FMA Scripts SDK

Introduction:
FMA is an opensource software application which supports external scripts to be executed on various events. Detailed information about these follows, which can be used in your own scripts. If you're quite a good script programmer you will be able to do amazing things with Fma :-)

Supported objects as of FMA 2.1.4 R229: Script Events, Mobile Agent, Accessories Menu, Volume Control, Mouse Control, Winamp.

New changes are marked in red color. Required are FMA 2.1.4 R229 and MediaControl 1.4a releases.

This page was last modified on


Script Events

Events are special occasions, when Fma allows a script to do some additional action. The following examples demonstrate some common event handlers in VBscript:

Sub HandlerName[(Param1[, ...])]
  'Some action to do here.
End Sub

There are a variety of events which can be used in place of HandlerName. The following list contains names of events which can occur during Fma execution.

and special cases of events:

They can be handled by a script, if their handlers exist. If there is no such handler implemented, don't worry about it. No handler is mandatory and they can be safely omitted.

OnInit

This event arises in these cases:

  1. During Fma startup.
  2. When script file path is changed in options.
  3. After a change in script editor.
Therefore the OnInit event handler is the right place for initialization of script global variables, such as static script menu, creation of COM objects used during script execution, etc.

Example:

Dim Shell 'Global variable declaration

Sub OnInit
  Set Shell = CreateObject("WScript.Shell") 'Shell variable initialization.
  fma.AddCmd "Fma Home Page", "Shell.Run ""IExplore.exe http://fma.sourceforge.com/""" 'Adds new command under Fma tools menu.
End Sub

See also: Mobile Agent

OnConnected

Event is called when Fma is successfully connected to the phone. This is a good time to initialize phone related stuff such as the accessories menu.

Example:

Sub OnConnected
  am.Init 'Initialization of accesories menu.
  am.DlgMsgBox "Connected to floAt's Mobile Agent", 1  'Shows dialog box with message on phone screen for one second.
End Sub

See also: Accessories Menu

OnConnectionLost

Appears when phone goes out of range, but Fma was not disconnected first.

Example:

Sub OnConnectionLost
  MsgBox "Connection was lost!"
End Sub

OnDisconnected

Appears when phone is disconnected by user.

Example:

Sub OnDisconnected
  MsgBox "Phone was disconnected!"
End Sub

OnNewSMS

Event notifies script about new incoming SMS. There can be two parameters used:

Example:

'Shut down computer when specific message was received.
'MyNumber constant should contain number of user who is allowed to shut down computer.
Sub OnNewSMS(Sender, Text)
  If (Sender = MyNumber) and (LCase(Text) = "shutdown") Then
    Shell.Run "shutdown -f -s -t 30"
    fma.Disconnect
  End If
End Sub

See also: Mobile Agent

OnCall

Event notifies script about calls and their state. The following parameters can be used:

Example:

Sub OnCall(State, Name, Number)
  MsgBox "Incoming call from number " & Number
End Sub

OnAMRoot

Event is called when phone accessories menu should be displayed. It can be built only by scripts. Fma doesn't build any default menu itself. See Accessories Menu for additional information about phone menus.

Example:

Sub OnAMRoot
  am.Clear
  am.Title = "My menu"

  am.AddItem "Settings", "onSettings" 'Adds menu item SETTINGS. Response will be handled by onSettings function
  am.AddItem "About", "onAbout" 'Adds menu item ABOUT. Response will be handled by onAbout function

  am.Update
End Sub

Sub onSettings
  'Settings menu item was chosen.
End Sub

Sub onAbout
  'About menu item was chosen.
End Sub

See also: Accessories Menu

OnProximity

When Auto Connect option is enabled, the proximity function becomes available. Each time the phone goes out of range or is getting in range, the OnProximity event can be operated. One parameter is available:

Example:

Sub OnProximity(State)
  If State = 1 Then
    MsgBox "Phone is away"
  Else 
    MsgBox "Phone is near"
  End If
End Sub

OnMusicMute

Serves as handler for disabling sound. Usually appears when a call is incoming, but it can also arise when new e-mail is received and on many other phone events (phone specific, doesn't seem to work on K750+ phones). One parameter can be used:

Example:

'Pause winamp when phone starts to ring and continue playing after call.
'WinampCtrl has to be initialized first
Sub OnMusicMute(State)
  If State = 1 Then
    WinampState = WinampCtrl.GetSongState
    If WinampState = "playing" Then
      WinampCtrl.Pause
    End If
  Else
    If WinampState = "playing" Then
      WinampCtrl.Pause
    End If
  End If
End Sub

See also: Winamp

OnKeyPress

When Key Monitor is enabled, each phone key press is reported to the Fma and generates this event. One key press consists of two steps:

  1. Key is pressed.
  2. Key is released.
For each step, one event is generated with proper parameters:

Example:

Sub OnKeyPress(Key, Press)
  If State = 0 Then
    MsgBox "Button " & " was released"
  Else 
    MsgBox "Button " & " was pressed"
  End If
End Sub

Menu and dialog events

See also: Accessories Menu


Mobile Agent (fma)

Methods and properties definitions:

  protected
    // adds menu item to FMA's Tools > My Script Menu
    procedure AddCmd(const label_, event: WideString); safecall;
    procedure Connect; safecall;
    procedure Disconnect; safecall;
    procedure Exit; safecall;
    function Get_KeyPress: WideString; safecall;
    function Get_PopKey: WideString; safecall;
    // display debug string in FMA's Event log
    procedure Debug(const str: WideString); safecall;
    procedure ClearKey; safecall;
    procedure Status(const Str: WideString); safecall;
    procedure Minimize; safecall;
    procedure Restore; safecall;
    procedure Set_KeyInActivityTimeout(Value: Integer); safecall;
    // sends AT command to phone
    procedure Transmit(const Cmd: WideString); safecall;
    // returns 0 if phone is NOT connected
    function Get_Connected: Integer; safecall;
    // searches for contact name for the specified number
    function Get_LookupByNumber(const Number: WideString): WideString; safecall;
    function Get_Received: WideString; safecall;
    // sends SMS to number specified by DestNo
    procedure SentMessage(const Msg, DestNo: WideString; ReqReply, Flash, StatusReq: Smallint); safecall;
    procedure VoiceAnswer; safecall;
    procedure VoiceCall(const Number: WideString); safecall;
    procedure VoiceHangUp; safecall;
    // OBEX SyncIRMC support:
    // here objecturl is like '/telecom/pb/info.log'
    function ObexGetObj(const filename, objecturl: WideString): HResult; safecall;
    function ObexPutObj(const filename, objecturl: WideString): HResult; safecall;
    // OBEX Folder Browseing support:
    // here objectname is like '/Pictures/Image(1).jpg'
    function ObexGet(const filename, objectname: WideString): HResult; safecall;
    procedure ObexDelete(const objectname: WideString); safecall;
    // Cut is actualy Get then Delete
    function ObexCut(const filename, objectname: WideString): HResult; safecall;
    // upload file to phone
    procedure ObexPut(const filename: WideString); safecall;
    // call function 'event' on every 'msec' miliseconds
    procedure AddTimer(msec: Integer; const event: WideString); safecall;
    // remove timer trigger for function 'event'
    procedure DeleteTimer(const event: WideString); safecall;
    procedure EnableKeyMonitor; safecall;
    procedure DisableKeyMonitor; safecall;
    procedure ScriptCall(const Code: WideString); safecall;
    procedure Sleep(msec: Integer); safecall;
    // get phone number type specified by parameter Number (Home, Cell...)
    function Get_PhoneType(const Number: WideString): WideString; safecall;
    procedure DisconnectTemporary; safecall;
    // localization functions
    function dGetText(const Domain, szMsgId: WideString): WideString; safecall;
    function dnGetText(const Domain, Singular, Plural: WideString; Number: Integer): WideString; safecall;
    function GetCurrentLocale: WideString; safecall;
    // this function returns phone model; usage: phoneUsed = fma.PhoneModel 'phoneUsed="Sony Ericsson K700"
    function Get_PhoneModel: WideString; safecall;
    // adds Tip to FMA's Welcome tips; if ashownow is 1 tip is immediatelly displayed
    procedure AddTip(const atip: WideString; atimeoutsecs: Integer; ashownow: Smallint); safecall;
    procedure ClearTips; safecall;
    // shows baloon message in system tray
    procedure AddBaloon(const atext: WideString; atimeoutsecs: Integer); safecall;
    procedure HideBaloon; safecall;
    // returns path to FMA executable
    function Get_MobileAgentFolder: WideString; safecall;
    // returns path to folder where script is located
    function Get_ScriptFolder: WideString; safecall;
    // UTF-8 encode/decode functions
    function PhoneDecode(aText: OleVariant): WideString; safecall;
    function PhoneEncode(const aText: WideString): OleVariant; safecall;
    // returns true if phone model is one of: K750, D750, W600, W800, W900, Z520 (deprecated)
    function Get_isK750clone: WordBool; safecall;
    // returns true if phone model is one of: T610, T630, Z600, Z610, K700, S700 (deprecated)
    function Get_isT610clone: WordBool; safecall;
    // use this instead of deprecated isK750clone and isT610clone
    function Get_isK750orBetter: WordBool; safecall;
  public
    procedure Initialize; override;
    destructor Destroy; override;
    procedure MenuClicked(Sender: TObject);
    procedure TimerEvent(Sender: TObject);

Example script code:

Sub OnInit
  fma.AddCmd "Test AT Command", "OnTestATCommand"
  'Add menu separator here
  fma.AddCmd "-", ""
  fma.AddCmd "FMA Home", "OnFMAHome"
  'call this function every 2 seconds
  fma.AddTimer 2000, "OnCameraClick"
End Sub

Sub OnDisconnected
  'Removes 2-secs calls for this function
  fma.DeleteTimer "OnCameraClick"
End Sub

See also: OnInit, OnDisconnected


Accessories menu (am)

Methods and properties definitions:

  protected
    procedure Init; safecall;
    procedure Clear; safecall;
    procedure AddItem(const Caption, Event: WideString); safecall;
    // support for improved menu item handling on K750+ phones
    procedure AddItemEx(const Caption: WideString; Disabled, Selected, CanDelete: WordBool; ImgIndex: Integer; const Event: WideString); safecall;
    // can be changed for building various menus, K750+ only (10 = standard menu <default>, 11 = list with one option, 12 = list with multiple options)
    procedure Set_MenuType(Value: Integer); safecall;
    procedure Set_Title(const Value: WideString); safecall;
    procedure Set_Selected(Value: Integer); safecall;
    procedure Update; safecall;
    procedure Set_Back(const Value: WideString); safecall;
    procedure ClearMenu; safecall;
    procedure Set_NextState(Value: Integer); safecall;
    procedure DlgOption; safecall;
    procedure DlgMsgBox(const Msg: WideString; TimeoutS: Integer); safecall;
    procedure DlgYesNo(const Msg, Event: WideString; TimeoutS: Integer); safecall;
    procedure DlgOnOff(const Title, Event: WideString; Default: Integer); safecall;
    procedure DlgPercent(const Title, Event: WideString; Steps, Pos: Integer); safecall;
    procedure DlgInputStr(const Title, Prompt: WideString; MaxLen: Integer; const DefaultStr: WideString; const Event: WideString); safecall;
    procedure DlgInputInt(const Title, Prompt: WideString; MinVal, MaxVal, DefaultVal: Integer; const event: WideString); safecall;
    procedure DlgInformation(const Title, Msg: WideString); safecall;
    procedure DlgFeedback(const Title, event: WideString); safecall;

Example script code:

Sub OnConnected
  'Initialize the Accessories Menu, this will put FMA submenu
  'under Accessories phone menu...
  am.Init
  'Show information message on your phone's display...
  am.DlgMsgBox "Connected to floAt's Mobile Agent", 1
  fma.Sleep 5000
  SimpleMenu
End Sub

Sub SimpleMenu
  'create a menu with 3 items
  am.Clear
  am.AddItem "First item", "firstAction"
  am.AddItem "Second item", "secondAction"
  am.AddItem "Search for item", "DisplayPrompt"

  am.Title = "Example menu"
  am.Back = "otherMenu" 'will call otherMenu sub if back button is pressed
  am.NextState = 2
  am.Update
End Sub

Sub DisplayPrompt
  'Prompts for search string
  am.DlgInputStr "Search", "Search for:", 30, "","mySearch" 'mySearch sub will be called when user finishes editing
End Sub

Sub mySearch(what)
  am.DlgFeedback "Searching...", "searchCancel"
 am.Update Dim i i = searchForItem(what) DisplayItem i End Sub

See also: OnConnected, Sleep


Volume Control (floAtMediaCtrl.VolumeCtrl)

Methods and properties definitions:

  interface(IDispatch)
    function  Get_Mute: Integer; safecall;
    procedure Set_Mute(Value: Integer); safecall;
    function  Get_Volume: Integer; safecall;
    procedure Set_Volume(Value: Integer); safecall;
    procedure Set_DestinationID(Param1: Integer); safecall;
    procedure Set_ConnectionID(Param1: Integer); safecall;
    procedure Set_ShowDurationMS(Param1: Integer); safecall;
    procedure Show; safecall;

Example script code:

Sub OnInit
  Set VolumeCtrl = CreateObject("floAtMediaCtrl.VolumeCtrl")
End Sub

Sub onVolMute
  If VolumeCtrl.Mute = 1 Then 
    VolumeCtrl.Mute = 0
  Else 
    VolumeCtrl.Mute = 1
  End If
End Sub

See also: onVolMute


Mouse Control (floAtMediaCtrl.MouseCtrl)

Methods and properties definitions:

  interface(IDispatch)
    procedure MouseMove(const Direction: WideString); safecall;
    procedure MouseStop; safecall;
    procedure MouseWhlUp; safecall;
    procedure MouseWhlDown; safecall;
    procedure MouseRightClick; safecall;
    procedure MouseLeftClick; safecall;

Example script code:

Sub OnInit
  Set MouseCtrl = CreateObject("floAtMediaCtrl.MouseCtrl")
  'Enable Key Press monitoring
  fma.EnableKeyMonitor
End Sub

' MouseMove Directions:
'    NW  N  NE
'        |
'    W --+-- E
'        |
'    SW  S  SE

Sub OnKeyPress(Key, State)
  'SE T610 only
  Select Case Key
    'Left and right click
    Case "["    MouseCtrl.MouseLeftClick
    Case "]"    MouseCtrl.MouseRightClick
    'Move mouse with phone keypad
    Case "1"    MouseCtrl.MouseMove("NW")
    Case "2"    MouseCtrl.MouseMove("N")
    Case "3"    MouseCtrl.MouseMove("NE")
    Case "4"    MouseCtrl.MouseMove("W")
    Case "6"    MouseCtrl.MouseMove("E")
    Case "7"    MouseCtrl.MouseMove("SW")
    Case "8"    MouseCtrl.MouseMove("S")
    Case "9"    MouseCtrl.MouseMove("SE")
    'Exit Mouse move mode
    Case ":R"   MouseControlFinish
  End Select
End Sub

Sub MouseControlFinish
  MouseCtrl.MouseStop
  'Disable Key Press monitoring
  fma.DisableKeyMonitor
End Sub

See also: OnKeyPress, EnableKeyMonitor, DisableKeyMonitor


Winamp Control (WinampCOMLib.WinampCOMObj)

Methods and properties definitions:

  interface(IDispatch)
    function Get_PathExe: WideString; safecall;
    procedure Set_PathExe(const Value: WideString); safecall;
    procedure Play; safecall;
    procedure Stop; safecall;
    procedure Pause; safecall;
    procedure NextTrack; safecall;
    procedure PreviousTrack; safecall;
    procedure Forward5sec; safecall;
    procedure Back5sec; safecall;
    procedure StartOfPlayList; safecall;
    procedure VolumeUp; safecall;
    procedure VolumeDown; safecall;
    procedure FadeOutStop; safecall;
    function Get_GetTitlePlaying: WideString; safecall;
    function Get_GetSongState: WideString; safecall;
    function Get_GetSongLength: WideString; safecall;
    function Get_GetSongSampleRate: WideString; safecall;
    function Get_GetSongBitRate: WideString; safecall;
    function Get_GetSongChanel: WideString; safecall;
    function Get_GetPlayListPosition: WideString; safecall;
    function Get_GetPlayListLength: WideString; safecall;
    procedure GetPlayList; safecall;
    function Get_GetSongTitlebyPosition(Position: Integer): WideString; safecall;
    function Get_GetFileNamebyPosition(Position: Integer): WideString; safecall;
    procedure PlaySongByPosition(Position: Integer); safecall;
    function Get_SetLengthParseTime: WordBool; safecall;
    procedure Set_SetLengthParseTime(Value: WordBool); safecall;
    function Get_SongPosParseTime: WordBool; safecall;
    procedure Set_SongPosParseTime(Value: WordBool); safecall;
    function Get_GetArtistByPosition(Position: Integer): WideString; safecall;
    function Get_GetSongPosition: WideString; safecall;
    function Get_Shuffle: WordBool; safecall;
    procedure Set_Shuffle(Value: WordBool); safecall;
    function Get_Repeat_: WordBool; safecall;
    procedure Set_Repeat_(Value: WordBool); safecall;
    procedure Set_SetVolume(Param1: Integer); safecall;
    function Get_JumpToTime(ms: Integer): Integer; safecall;
    function Get_GetUniqueArtist(Index: Integer): WideString; safecall;

Example script code:

Sub OnInit
  Set WinampCtrl = CreateObject("WinampCOMLib.WinampCOMObj")
End Sub

Sub OnMusicMute(Start)
  If Start = 1 Then
    WinampState = WinampCtrl.GetSongState
    If WinampState = "playing" Then
      WinampCtrl.Pause
    End If
  Else
    If WinampState = "playing" Then
      WinampCtrl.Pause
    End If
  End If 
End Sub

See also: OnMusicMute