This section details the general Fire API for messaging applications.
| Error Functions | Description |
| xmGetError | Get the text of the last error |
| Service Functions | Description |
| xmConnect | Connect to a service |
| xmDisconnect | Disconnect from a service |
| xmFindService | Find a service by name |
| xmFindServiceByURL | Find a service by web address |
| Log In/Out Functions | Description |
| xmLogIn | Log in to a service |
| xmLogOut | Log out from a service |
| xmSetCallbackMode | Set the callback connection mode |
| Session Functions | Description |
| xmCloseSession | Close a session |
| xmInvite | Invite other users to join a session |
| xmJoinSession | Join a session |
| xmLeaveSession | Leave a session |
| xmOpenSession | Open a session |
| xmReplyToInvite | Reply to a session invitation |
| Message Functions | Description |
| xmAcceptMessage | Accept a message |
| xmCancelMessage | Cancel (reject) a message |
| xmSendMessage | Send a message to other users |
| Message Structure | Description |
| packet_t | Message data sstructure |
| Query Functions | Description |
| xmGetGroups | Get all groups for a user |
| xmGetGroupUsers | Get all users in a group |
| xmGetGroupUsersInfo | Get all users (login names and display names) in a group |
| xmGetServiceTitle | Get a service title |
| xmGetServiceURL | Get a service web address |
| xmGetServiceVersion | Get a service version |
| xmGetSessions | Get all open sessions |
| xmGetSessionsInfo | Get all open sessions and types |
| xmGetSessionMessages | Get message history for a session |
| xmGetSessionUsers | Get all users in a session |
| xmGetSessionUsersInfo | Get all users (login names and display names) in a session |
| xmGetVersion | Get the version number |
Note: All functions are part of the redline atable, so to call them you should prefix their names with ~redline., or add the redline atable to your atable search path, e.g.
myatable.search_path := redline
The messaging application (redline.mxa) resides in $MXSYS/app and is loaded by the following Fire command:
start $MXSYS/app/redline.mxa
Once loaded, all the above methods become available. It can be unloaded by the following:
stop @redline
Gets the text of the last error. Whenever one of the messaging functions in this API fails, the error message explaining the reason for the failure is not displayed immediately but is remembered. The caller can then display the message appropriately after calling this function.
In addition, where there is a valid service channel, the event callback onShowError is called.
string_function ~redline.xmGetError()
Gets the version number of the redline application (redline.mxa) . The higher the return value, the later the version.
numeric_function ~redline.xmGetVersion()
Determines whether a messaging service has been registered on the client machine. Whenever a successful connection is made to a service, its details (title and web address) are recorded for future reference in the registry.
numeric_function ~redline.xmFindService(string name)
where:
name (input) the title of the service.
This function returns non-zero if successful, or 0 if the service is uknown, i.e. has not been registered.
Determines whether a messaging service has been registered on the client machine. Whenever a successful connection is made to a service, its details (title and web address) are recorded for future reference in the registry.
numeric_function ~redline.xmFindServiceByURL(string url)
where:
url (input) the web address of the service.
This function returns non-zero if successful, or 0 if the service is uknown, i.e. has not been registered.
Opens a connection to a messaging service. The service may be indicated by title or web address. This function does not log you in to a service, but merely establishes a connection.
channel_function ~redline.xmConnect(string text)
where:
text (input) the title or web address (URL) of the service. If text begins with "http" then an attempt will be made to connect to that web address, otherwise the name will be looked up in the list of registered services and if found a connection made to its web address.
If a successful connection is established a channel is returned, through which all subsequent communication with the service should be made. In addition, service details are recorded in the registry. On failure to connect, null is returned.
Closes a connection to a messaging service.This function will log you off if necessary.
procedure ~redline.xmDisconnect(channel svch)
where:
svch (input) the open channel to the service (as returned by xmConnect).
Returns the title of a messaging service.
string_function ~redline.xmGetServiceTitle(channel svch)
where:
svch (input) the open channel to the service (as returned by xmConnect).
This function returns the title of the service, or an empty string if the connection is invalid.
Returns the web address of a messaging service.
string_function ~redline.xmGetServiceURL(channel svch)
where:
svch (input) the open channel to the service (as returned by xmConnect).
This function returns the web address (URL) of the service, or an empty string if the connection is invalid.
Returns the version number associated with a messaging service.
numeric_function ~redline.xmGetServiceVersion(channel svch)
where:
svch (input) the open channel to the service (as returned by xmConnect).
This function returns the version number of the service, or zero if the connection is invalid.
Sets how the messaging service communicates events to the next user who logs in. There are 2 methods:
switchboard - where the client cannot be contacted by the service, typically because the client machine is behind a firewall, and therefore the service has no way of addressing the client machine. This is the default method.
client-port - where the client can be contacted by the service, typically because the client machine is on the same internal network as the service, is therefore behind the same firewall, and can be addressed directly (by machine name or IP address). This is the more efficient method and should be used where possible.
If a client-port connection is required, this function must be called before the next call to xmLogIn. The method will be remembered, so if a user logs in and out multiple times, it need only be called before the first log in.
procedure ~redline.xmSetCallbackMode(channel svch {,string host})
where:
svch (input) the open channel to the service (as returned by xmConnect).
host (input) if this string value is supplied and is not an empty string, the callback method is set to client-port and the value is the machine name or IP address by which the messaging service will identify the client (there are 2 system strings available: host_name and host_ip if required). If this value is omitted, the callback method is set to switchboard..
Log in to a messaging service. At any time, only one user may be logged in to a connection. A suitable callback mode should be set before logging in (see xmSetCallbackMode)
numeric_function ~redline.xmLogIn(channel svch {,string user,string pwd})
where:
svch (input) the open channel to the service (as returned by xmConnect).
user (input) the name of the user logging in. This must be a name known to the messaging service. If the user is the same as the user who last logged out from the connection this parameter can be omitted.
pwd (input) the user's password, known to the messaging service, for verification purposes. If the user is the same as the user who last logged out from the connection this parameter can be omitted.
This function returns 1 on a successful log in, or 0 on failure.
Log out from a messaging service. The connection to the service will remain open to enable subsequent log-in's as the same or a different user. If the user is currently participating in any group sessions, the user will automatically be removed from the sessions.
procedure ~redline.xmLogOut(channel svch)
where:
svch (input) the open channel to the service (as returned by xmConnect).
Gets the names of all groups for which the current logged-in user is a member.
string_function ~redline.xmGetGroups(channel svch)
where:
svch (input) the open channel to the service (as returned by xmConnect).
This function returns an array of group names on success, or an empty array if an error occurred.
Gets the log-in names for all users in a group for which the current logged-in user is a member.
string_function ~redline.xmGetGroupUsers(channel svch,string grpname,numeric active)
where:
svch (input) the open channel to the service (as returned by xmConnect).
grpname (input) the group being queried.
active (input) a value to filter the returned list:
1 - only users currently logged in to the service
0 - all users, logged in or otherwise
This function returns an array of user names on success, or an empty array if there are no suitable users or some other error occurred.
Gets the log-in names and display names for all users in a group for which the current logged-in user is a member.
numeric_function ~redline.xmGetGroupUsersInfo(channel svch,string grpname,numeric active,
string &names,string &displaynames)
where:
svch (input) the open channel to the service (as returned by xmConnect).
grpname (input) the group being queried.
active (input) a value to filter the returned list:
1 - only users currently logged in to the service
0 - all users, logged in or otherwise
names (output) a string array to receive the user log-in names.
displaynames (output) a string array to receive the user display names.
This function returns the number of elements written to each output array, or 0 if there are no suitable users or some other error occurred.
Gets the names of all open sessions in which the logged-in user is entitled to participate.
string_function ~redline.xmGetSessions(channel svch)
where:
svch (input) the open channel to the service (as returned by xmConnect).
This function returns an array of session names on success, or an empty array if there are no suitable sessions or some other error occurred. Note: the returned array will not include any private sessions unless the logged-in user has received an invitation to participate.
Gets the names and types of all open sessions in which the logged-in user is entitled to participate. Session types are service-dependent.
numeric_function ~redline.xmGetSessionsInfo(channel svch,string &names,numeric &types)
where:
svch (input) the open channel to the service (as returned by xmConnect).
names (output) a string array to receive the session names.
types (output) a numeric array to receive the session types.
This function returns the number of elements written to names and types, or 0 if there are no suitable sessions or some other error occurred. Note: the names array will not include any private sessions unless the logged-in user has received an invitation to participate.
Gets the log-in names for all users entitled to participate in a session. The current logged-in user must have control or participate rights to be allowed to do this, and the session must not be a private session, unless the logged-in user has been invited to participate.
string_function ~redline.xmGetSessionUsers(channel svch,string session,numeric active)
where:
svch (input) the open channel to the service (as returned by xmConnect).
session (input) the session being queried.
active (input) a value to filter the returned list:
0 all users, logged-in or otherwise
1 only logged-in users, session participants or otherwise
2 only current session participants
This function returns an array of user names on success, or an empty array if there are no suitable users or some other error occurred.
Gets the log-in names and display names for all users entitled to participate in a session. The current logged-in user must have control or participate rights to be allowed to do this, and the session must not be a private session, unless the logged-in user has been invited to participate.
numeric_function ~redline.xmGetSessionUsersInfo(channel svch,string session,numeric active,
string &names,string &displaynames)
where:
svch (input) the open channel to the service (as returned by xmConnect).
session (input) the session being queried.
active (input) a value to filter the returned list:
0 all users, logged-in or otherwise
1 only logged-in users, session participants or otherwise
2 only current session participants
names (output) a string array to receive the user log-in names.
displaynames (output) a string array to receive the user display names.
This function returns the number of elements written to each output array, or 0 if there are no suitable users or some other error occurred.
Starts a multi-user session with the messaging service between members of a group. Session names are of the form group/name. The current logged-in user must have control privileges within a group to be able to open a session. Once a user has opened a sesson, the user is also deemed to have joined the session providing the user has participate rights within the group.
numeric_function ~redline.xmOpenSession(channel svch,string session,numeric type,
numeric resume {,numeric record {,numeric keep_open
{,numeric private }}})
where:
svch (input) the open channel to the service (as returned by xmConnect).
session (input) the name of the session, in the form group/name. If this is a new session (resume is 0), then group must be a group for which the current logged-in user is a member , and the group/name combination must be unique. If this is re-opening a previously paused session (resume is 1), then the session must be a known and previously-closed session.
type (input) the session type (used by new sessions only). This is a service-dependent value. Use zero when unsure.
resume (input) whether or not a previously-closed session is being re-opened.
record (input) whether or not all message activity is to be recorded in the messaging service datbase. The default behavior is for activity not to be recorded.
keep_open (input) whether or not the session is to be kept open when the service detects that all participants have left the session. The default behavior is for the session to be closed.
private (input) whether or not the session is to be prrivate. Users can only join private sessions after receiving an invitation. The default value (0) is for the session not to be private.
This function returns 1 if successful, or 0 on failure.
Closes a multi-user session. The session may have been opened by the current logged-in user (via xmOpenSession), or may have been opened by a remote user. The current logged-in user must have control privileges within a group to be able to close a session.
numeric_function ~redline.xmCloseSession(channel svch,string session)
where:
svch (input) the open channel to the service (as returned by xmConnect).
session (input) the name of the session to be closed, in the form group/name.
This function returns 1 if successful, or 0 on failure.
Joins a multi-user session. Typically this call will be made in response to an invitation to join the session from a remote user. However, as long as the current logged-in user has participate rights in the relevant group, the user can join the session uninvited.
numeric_function ~redline.xmJoinSession(channel svch,string session)
where:
svch (input) the open channel to the service (as returned by xmConnect).
session (input) the name of the session to be joined, in the form group/name.
This function returns 1 if successful, or 0 on failure.
Leaves a multi-user session. For sessions which are not marked keep-open when the last participant has left the session the messaging service will close the session. Sometimes a session will be closed by a remote user and the user will be forced to leave automatically.
numeric_function ~redline.xmLeaveSession(channel svch,string session)
where:
svch (input) the open channel to the service (as returned by xmConnect).
session (input) the name of the session to be left, in the form group/name.
This function returns 1 if successful, or 0 on failure.
Invites one or all remote users to join a multi-user session.
numeric_function ~redline.xmInvite(channel svch,string session,string user)
where:
svch (input) the open channel to the service (as returned by xmConnect).
session (input) the name of the session for which the invitation applies, in the form group/name.
user (input) the name of the user to be invited, or the value all to send an invitation to all remote users who are entitled to join the session, i.e. who have participate rights.
This function returns 1 if successful, or 0 on failure.
Reply to an invitation from a remote user to join a multi-user session. This function should only be called from within an onInvite event callback.
numeric_function ~redline.xmReplyToInvite(channel svch,string user,string session,numeric answer)
where:
svch (input) the open channel to the service (as returned by xmConnect).
user (input) the name of the user who issued the invitation.
session (input) the name of the session for which the invitation applies, in the form group/name.
answer (input) whether or not the invitation is being accepted. A value 1 will tell the messaging service to add you as a session participant . A value 0 will decline the invitation.
This function returns 1 if successful, or 0 on failure, e.g. on a communication error.
Accept a message sent from a remote user. This function should only be called in response to a receive message event from within an onMessageReceipt callback. Typically within the callback you would check whether you were prepared to accept the message, then call this function. If you did not want to accept it you would call xmCancelMessage
procedure ~redline.xmAcceptMessage(channel svch,string session,numeric msgid)
where:
svch (input) the open channel to the service (as returned by xmConnect).
session (input) the name of the session in which the message has originated, in the form group/name.
msgid (input) an id which is passed to the messaging service to identify which message is being accepted.
As a result of this function, the messaging service will dispatch the message to you and the underlying message handler will process it all within the execution of this function.
Cancel (refuse to accept) a message sent from a remote user. This function should only be called in response to a receive message event from within an onMessageReceipt callback. Typically within the callback you would check whether you were prepared to accept the message. If you were not, then call this function. If you did want to accept it you would call xmAcceptMessage
procedure ~redline.xmCancelMessage(channel svch,string session,numeric msgid)
where:
svch (input) the open channel to the service (as returned by xmConnect).
session (input) the name of the session in which the message has originated, in the form group/name.
msgid (input) an id which is passed to the messaging service to identify which message is being rejected.
As a result of this function, the messaging service will dispose of the message which was destined for you.
Send a message sent to one or all remote user in a multi-user session.
numeric_function ~redline.xmSendMessage(channel svch,string session,string user
string msgname,numeric msgtype,string desc,numeric replace,
blob meat[],string func,numeric immediate)
where:
svch (input) the open channel to the service (as returned by xmConnect).
session (input) the name of the session, in the form group/name.
user (input) the name of the user to receive the message, or the value all to send the message to all remote users currenty participating in the session.
msgname (input) a name to identify the message for future reference. This can be an empty string if this is a one-off message.
msgtype (input) a numeric value indicating the type of message. This is a client field to be used for application purposes.
desc (input) a description of the message to convey the purpose or contents of the message to the recipient. This can be displayed by the recipient to help them decide whether or not to accept it.
replace (input) whether or not this message replaces a previous message of the same name (msgname).
meat (input) an array of blobs containing the meat of the message. Basically this will be one or more sets of file contents.
func (input) the name of an application function to be used by the recipient to process the message. If this is an empty string then the meat blobs are to be processed automatically by file association. If this is not an empty string it must be the name of a macro or procedure already resident in the recipient's execution environment. Such a custom macro/procedure should take one parameter: an object of type ~redline.packet_t.
immediate (input) whether or not the recipient should execute the message immediately without prompting the user for acceptance or rejection. This is advisory and the client might decide to reject the message anyway.
This function returns 1 if the message was sent successfully, not necessarily that it was received. A 0 value is returned on error.
This is the class of object passed to a custom message-handling macro. Such an object contains everything about a message received from a messaging service during execution of the xmAcceptMessage function. Many of the member values are those passed to the onMessageReceipt callback which first alerts a client to an incoming message.
The structure itself has the following members:
structure ~redline.packet_t {
numeric m_msgid
string m_msgname
numeric m_msgtype
string m_user
string m_session
numeric m_session_type
string m_desc
string m_ticks
string m_func
blob m_data[]
}
where:
m_msgid: an id uniquely identifying the message within the messaging service. This id is generated by the service.
m_msgname: a name to identify the message for future reference. This is a value generated by the sender of the message. It might be an empty string, a unique name, or a name shared by many messages of the same type where reference to the name always refers to the most recent one.
m_msgtype: a numeric value indicating the type of message. This is a client field generated by the sender and has no meaning for remote the messaging service.
m_user: the login name of the remote user who sent the message.
m_session: the name of the session, in the form group/name.
m_sesstype: the session type, whose value will have a service-dependent meaning.
m_desc: a description of the message contents. This was set by the sender and would typically be used in a dialog for the user to decide whether to accept or cancel.
m_ticks: a message timestamp, measured in seconds since the epoch (1-1-1970).
m_func: the name of the custom macro/procedure. When the message gets process (within the execution of xmAcceptMessage), the macro/procedure gets invoked as follows:
# Macro exec ^(obj.m_func)(obj)# Procedure ^(obj.m_func)(obj)where obj is the packet_t being processed. Thus the application macro/procedure must take one parameter, here is an example of a macro.
# @myapp/mymacro.cmd args obj=~redline.packet_t # add user code here to process the meat of the messageIn this example, the value of m_func would be '@myapp/mymacro' (the .cmd extension is the default and can therefore be omitted from the macro name).
m_data: the meat of the message, a series of blobs to be processed in an application-specific way, for example as files, raw data or whatever.
Get the message history for a session. This is only recommended for advanced users and enables all, or a selected set of, messages to be retrieved from the messaging service, e.g. to inspect messages which may have been lost or missed. Only sessions created in record mode (see xmOpenSession) have their messages retained by the server and thus available for retrieval. The requesting user must have participate privileges in the group associated with the session.
This method should not be used during general message acceptance and processing (see xmAcceptMessage and xmCancelMessage), but should only be used by an application wishing to examine unprocessed messages from a session's history.
There are various parameters to this method to restrict message selection by message id, message name, message type, message sender, client function or timestamp.
numeric_function ~redline.xmGetSessionMessages(channel svch,string session,numeric msgids[],string names[],
numeric types[],string senders[],string funcs[],numeric ticks[],
~redline.packet_t recv[])
where:
svch (input) the open channel to the service (as returned by xmConnect).
session (input) the session being queried. It must be a recordable session but does not have to be currently open.
msgids (input) a numeric array restricting the search to messages with particular id's. To indicate no restriction, use a single numeric value of -1.
names (input) a string array restricting the search to messages with particular names. To indicate no restriction, use a single empty string value.
types (input) a numeric array restricting the search to messages of particular types. To indicate no restriction, use a single numeric value of -1.
senders (input) a string array restricting the search to messages sent by particular users. To indicate no restriction, use a single empty string value.
funcs (input) a string array restricting the search to messages with particular custom macros/procedures. To indicate no restriction, use a single empty string value.
ticks (input) a numeric array restricting the search to messages sent within a particular timestamp period. To indicate a period within which messages were sent, use a 2-element array. To indicate all messages sent after a particular timestamp use one value. To indicate no restriction, use one zero value.
recv (output) an array of type ~redline.packet_t to receive the details of the fetched messages. They will be sorted in ascending timestamp order.
This function returns the number of messages retrieved by the search, or -1 on error.