360Works Messenger/Documentation
360Works Messenger User Guide
The 360Works Messenger plugin enables instant messaging and SMS functionality over AOL's AIM and ICQ services in FileMaker, including:
- Getting a buddy list
- Getting buddies' status and icon
- Sending notification messages and SMSs to buddies
Most plugin functions that interact with the messaging services require the service type, login name, and password to be passed in. The plugin connects as needed and manages the connection in the background. This eliminated the need for an explicit connect call, allowing you to start using plugin functions without worrying about the connection state. Multiple accounts can be used at the same time, since the plugin tracks the desired account using a combination of the service and login fields.</p>
Once you're connected, the plugin maintains the session without reconnecting for every function call.</p>
Example Usage
This shows an example of getting a buddy list, getting a buddy's status, and sending them a message.</p>
Step #1: Get a buddy list. The plugin will connect and retrieve the return-separated list, maintaining the connection for other functions.</p>
Set Field[ example::buddyList; IM_GetBuddyList( "AIM"; "myLogin"; "myPassword" ) ] If[ example::buddyList = "ERROR" ] ...show/handle error using IM_LastError...
Step #2: Get a buddy's status message</p>
Set Field[ example::buddyStatus; IM_GetBuddyStatusMessage( "AIM"; "myLogin";
"myPassword"; "myBuddy" ) ] If[ example::buddyStatus = "ERROR" ] ...show/handle error using IM_LastError...
Step #3: Send a buddy a message</p>
If[ IM_SendMessage( "AIM"; "myLogin"; "myPassword"; "myBuddy"; "Hello buddy!" )
= "ERROR" ] ...show/handle error using IM_LastError...
Step #4: Disconnect. This is optional and will typically only be done on some final operation, such as closing the FileMaker file.</p>
If[ IM_Disconnect = "ERROR" ]
...Display error message to user, but we don't need to do anything else...
360Works Plugin Setup Guides
See Plugins_101 for Error reporting, installation, registration, and more.
Function Summary
- IM_Disconnect ( { service ; login } ) — Disconnects user from all connected services.
- IM_GetBuddyIcon ( service ; login ; password ; buddy ) — Returns a buddy's icon.
- IM_GetBuddyList ( service ; login ; password ) — Connects to the messaging service (if necessary) and retrieves the user's buddy list.
- IM_GetBuddyStatusMessage ( service ; login ; password ; buddy ) — Returns a buddy's status.
- IM_GetBuddyStatusType ( service ; login ; password ; buddy ) — Returns a buddy's status type as one of the following: "online", "idle", "away", "mobile", or "offline".
- IM_LastError — Returns detailed information about the last error generated by this plugin.
- IM_LicenseInfo —
- IM_Register ( licenseKey ; registeredTo ) —
- IM_SendMessage ( service ; login ; password ; buddy ; message ) — Connects to the messaging service (if necessary) and sends a plain text message to the recipient buddy.
- IM_SetErrorCapture ( errorCapture ) —
- IM_Version ( ) — Returns the version number of the plugin.
- Twitter_UpdateStatus ( login ; password ; status ) —
Function Detail
IM_Disconnect ( { service ; login } )
Disconnects user from all connected services. If login information is passed it, only that specific account is disconnected. If only partial login info is passed it, all accounts are disconnected.
service
- optional parameter to disconnect from only the specific messaging service; currently only "AIM" is supported
login
- optional parameter to disconnect only the specific login/account name for the service
IM_GetBuddyIcon ( service ; login ; password ; buddy )
Returns a buddy's icon. If the buddy doesn't have an icon set, a default one will be returned corresponding to the buddy's messaging service. Note that if a connection is made shortly before the function is called, the returned icon be the default even if the buddy does have one set. A subsequent call will return the appropriate icon after it has been retrieved and cached by the plugin.
service
- the messaging service to use; currently only "AIM" is supported
login
- login/account name for the service
password
- the password for service account
buddy
- the buddy whose icon to get
IM_GetBuddyList ( service ; login ; password )
Connects to the messaging service (if necessary) and retrieves the user's buddy list. The list is return-separated
and can easily be parsed using FileMaker's built-in GetValue()
function.
service
- the messaging service to use; currently only "AIM" is supported
login
- login/account name for the service
password
- the password for service account
IM_GetBuddyStatusMessage ( service ; login ; password ; buddy )
Returns a buddy's status. If the buddy doesn't have a status set, an empty string is returned instead. Note that if a connection is made shortly before the function is called, the returned status may still be blank even if the buddy does have one set. A subsequent call will return the status after it has been retrieved and cached by the plugin.
service
- the messaging service to use; currently only "AIM" is supported
login
- login/account name for the service
password
- the password for service account
buddy
- the buddy whose status to get
IM_GetBuddyStatusType ( service ; login ; password ; buddy )
Returns a buddy's status type as one of the following: "online", "idle", "away", "mobile", or "offline". If the buddy doesn't have a status set, an empty string is returned instead. Note that if a connection is made shortly before the function is called, the returned status type may still be blank even if the buddy does have one set. A subsequent call will return the status type after it has been retrieved and cached by the plugin.
service
- the messaging service to use; currently only "AIM" is supported
login
- login/account name for the service
password
- the password for service account
buddy
- the buddy whose status type to get
IM_LastError
Returns detailed information about the last error generated by this plugin. If another plugin function returns the text "ERROR", call this function to get a user-presentable description of what went wrong. For example,
If[ IM_GetBuddyList( "AIM"; "myLogin"; "myPassword" ) = "ERROR" ] Show Custom Dialog[ "Could not get buddy list: " & IM_LastError ] Exit Script End If
null
if there was no error.
IM_LicenseInfo
IM_Register ( licenseKey ; registeredTo )
IM_SendMessage ( service ; login ; password ; buddy ; message )
Connects to the messaging service (if necessary) and sends a plain text message to the recipient buddy. This function can also send SMS messages if used with AIM as the service. The recipient buddy in this case would be a phone number, prefixed with "+1". For example, to send a SMS to 555-123-4567, enter "+15551234567" as the buddy.
service
- the messaging service to use; currently only "AIM" is supported
login
- login/account name for the service
password
- the password for service account
buddy
- the recipient of the message; can be phone number if sending SMS through AIM
message
- the message to send
IM_SetErrorCapture ( errorCapture )
IM_Version ( )
Returns the version number of the plugin. This is always a numeric value, with no letter characters.