When in communication with a messaging service, events happen which a client application needs to be aware of, e.g. a remote user may have logged in to a session, or a remote user may have sent a message to the client. This section describes the event handlers which can be defined to take appropriate action when events occur.
When a connection is made to a messaging service (via the xmConnect function) a channel identifier is returned for subsequent communication with the service. This is referred to as the service handle. The channel has member functions (aka event callbacks) defining what action should be taken when events occur. These are already defined for you and you can choose to leave them as they are or you can define your own actions by redefining (aka overriding) them.
All callbacks use the following naming and parameter convention:
channel.on<event name>(<parameters ..>)
e.g.
channel.onUserLogIn(string user)
which is the event callback for when a remote user in the same group as you logs in to the service.
To override a callback you should redefine it in the following manner:
# Connect to a (fictional) service
channel svch = ~redline.xmConnect('Test Messaging Service')
if (svch) {
# Successful connection, redefine what happens when another user logs in
svch.onUserLogin = {
args svch=channel,user=string
message user & 'has logged in'
}
}
The default action for an event callback is to call a generic function with the same name as the channel callback, i.e.
~redline.onUserLogIn(channel svch,string user)
so you could if required call the default action before or after your action, e.g.
svch.onUserLogin = {
args svch=channel,user=string
# Call the default action
onUserLogIn(svch,user)
# Do something special if fred has logged in, in this case
# invite him to join an active session
if (user == 'fred') {
xmInvite(svch,'mygroup/mysession',user)
}
}
To ignore an event (a questionable requirement), just set the callback to null, e.g.
svch.onUserLogIn = null
The callbacks will be invoked (called) by the underlying API framework when necessary. User applications should not invoke these callbacks unless they know what they are doing.
The channel callbacks and the events which invoke them are as follows:
| Callback | Event |
| onInvite | When the current user has been invited to join a session. |
| onMessageReceipt | When a message has been received from a remote user. |
| onSessionClose | When a remote user has closed a session. |
| onSessionOpen | When a remote user has opened a session. |
| onShowError | When an error has occurred and the text needs to be displayed. |
| onShowMessage | When an event message needs to be displayed. |
| onShowStatus | When a status message needs to be displayed. |
| onUserDeclined | When a remote user has declined an invitation to join a session. |
| onUserJoined | When a remote user has joined a session. |
| onUserLeft | When a remote user has left a session. |
| onUserLogIn | When a remote user has logged in. |
| onUserLogOut | When a remote user has logged out. |
Invoked when an error has occurred in one of the API functions. The default action is to issue a bell signal and display the error text in the error log window.
procedure onShowError = {
args svch=channel
args text=string
# add user code here
}
where:
svch (input) the open channel to the service (as returned by xmConnect).
text (input) the text of the error, also available via xmGetError.
Invoked when an information message has been generated by one of the default event callbacks. Such messages include notification when remote users have logged in/out, joined/left a session etc. The default action is to pop up a message window displaying the relevant text.
procedure onShowMessage= {
args svch=channel
args text=string
# add user code here
}
where:
svch (input) the open channel to the service (as returned by xmConnect).
text (input) the text of the message.
Invoked when a status message has been generated by one of the API functions. Such messages include confirmation of successful execution, e.g. when the current user logs in, joins/leaves a session etc.The default action is to display the message in the monitor window.
procedure onShowStatus= {
args svch=channel
args text=string
# add user code here
}
where:
svch (input) the open channel to the service (as returned by xmConnect).
text (input) the text of the message.
Invoked when a remote user, in the same group as the current user, has logged in to the messaging service. The default action is to issue an appropriate message (via onShowMessage).
procedure onUserLogIn = {
args svch=channel
args user=string
# add user code here
}
where:
svch (input) the open channel to the service (as returned by xmConnect).
user (input) the login name of the remote user who has logged in.
Invoked when a remote user, in the same group as the current user, has logged out from the messaging service. The default action is to issue an appropriate message (via onShowMessage).
procedure onUserLogOut = {
args svch=channel
args user=string
# add user code here
}
where:
svch (input) the open channel to the service (as returned by xmConnect).
user (input) the login name of the remote user who has logged out.
Invoked when a remote user has joined a session in which the current user is participating. The default action is to issue an appropriate message (via onShowMessage).
procedure onUserJoined = {
args svch=channel
args user=string
args session=string
# add user code here
}
where:
svch (input) the open channel to the service (as returned by xmConnect).
user (input) the login name of the remote user who has joined the session.
session (input) the name of the session, in the form group/name.
Invoked when a remote user has left a session in which the current user is participating. The default action is to issue an appropriate message (via onShowMessage).
procedure onUserLeft = {
args svch=channel
args user=string
args session=string
# add user code here
}
where:
svch (input) the open channel to the service (as returned by xmConnect).
user (input) the login name of the remote user who has left the session.
session (input) the name of the session, in the form group/name.
Invoked when a remote user has declined an invitation from the current user to join a session. The invitation will have been sent via a previous call to xmInvite. The default action is to issue an appropriate message (via onShowMessage).
procedure onUserDeclined = {
args svch=channel
args user=string
args session=string
# add user code here
}
where:
svch (input) the open channel to the service (as returned by xmConnect).
user (input) the login name of the remote user who has declined the invitation.
session (input) the name of the session, in the form group/name.
Invoked when a remote user opens a session in which the current user is entitled to participate because of group membership. The default action is to issue an appropriate message (via onShowMessage).
procedure onSessionOpen = {
args svch=channel
args user=string
args session=string
args sesstype=numeric
# add user code here
}
where:
svch (input) the open channel to the service (as returned by xmConnect).
user (input) the login name of the remote user who has opened the session.
session (input) the name of the session, in the form group/name.
sesstype (input) the session type (service-dependent).
Invoked when a remote user closes a session in which the current user is already participating, or is entitiled to participate because of group membership. The default action is to issue an appropriate message (via onShowMessage).
procedure onSessionClose = {
args svch=channel
args user=string
args session=string
args sesstype=numeric
# add user code here
}
where:
svch (input) the open channel to the service (as returned by xmConnect).
user (input) the login name of the remote user who has closed the session.
session (input) the name of the session, in the form group/name.
sesstype (input) the session type (service-dependent).
Invoked when a remote user invites the current user to join a session. The default action is to display a Yes/No dialog to accept the invitation or not. An internal call is then made to xmReplyToInvite with the appropriate answer.
If you override this callback, you must decide whether to accept the invitation, then make an appropriate call to xmReplyToInvite so that the messaging service knows whether or not the invitation has been accepted.
procedure onInvite = {
args svch=channel
args user=string
args session=string
args sesstype=numeric
# add user code here
}
where:
svch (input) the open channel to the service (as returned by xmConnect).
user (input) the login name of the remote user who issued the invitation.
session (input) the name of the session, in the form group/name.
sesstype (input) the session type (service-dependent).
Invoked when a remote user sends a message to the current user. The default action is to display a Yes/No dialog to accept the message or cancel (ignore) it. An internal call is then made to xmAcceptMessage or xmCancelMessage. Acceptance of a message will pull down the meat of the message from the messaging service, then execute it. Cancelling a message will tell the messaging service to remove it from the user's input queue.
If you override this callback, you must decide whether to accept the message, then make a call to xmAcceptMessage or xmCancelMessage accordingly so that the messaging service knows what to do with the message.
procedure onMessageReceipt = {
args svch=channel
args user=string
args session=string
args sesstype=numeric
args msgid=numeric
args immediate=numeric
args msgname=string
args msgtype=numeric
args desc=string
# add user code here
}
where:
svch (input) the open channel to the service (as returned by xmConnect).
user (input) the login name of the remote user who sent the message.
session (input) the name of the session, in the form group/name.
sesstype (input) the session type (service-dependent).
msgid (input) an id which should be passed to xmAcceptMessage or xmCancelMessage specifying which message is being accepted or cancelled.
msgname (input) a name to identify the message for future reference. This may be an empty string.
immediate (input) whether or not the sender indicated that the message be executed immediately (i.e. without getting confirmation from the user). This advisory can be obeyed or ignored. The default action obeys this setting and does not give the user the option to accept or cancel if its value is non-zero but accepts it immediately.
msgtype (input) a numeric value indicating the type of message. This is a client field to be used for application purposes and is set by the sender.
desc (input) 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.