360Works Messenger/Documentation

From 360Works Product Documentation Wiki
Jump to: navigation, search

Contents

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.

Parameters:

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

Returns: @return 1 on success, ERROR on failure

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.

Parameters:

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

Returns: the buddy's icon as a container

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.

Parameters:

service
the messaging service to use; currently only "AIM" is supported
login
login/account name for the service
password
the password for service account

Returns: return-separated list of buddies

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.

Parameters:

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

Returns: the buddy's current status; if no status is set, an empty string is returned

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.

Parameters:

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

Returns: the buddy's current status type

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


Returns: Error text, or null if there was no error.

IM_LicenseInfo

IM_Register ( licenseKey ; registeredTo )

Parameters:


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.

Parameters:

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

Returns: 1 on success, ERROR on failure

IM_SetErrorCapture ( errorCapture )

Parameters:


IM_Version ( )

Returns the version number of the plugin. This is always a numeric value, with no letter characters.

Returns: the version number of the plugin

Twitter_UpdateStatus ( login ; password ; status )

Parameters:
Personal tools
Namespaces

Variants
Actions
Plug-in Products
Other Products
Navigation
Toolbox