messenger.js/api.md

Types

FileInfo

{"Path": string, "Size": long, "Progress": long, "Incoming": bool, "Status": Number(0-3)}

Path: A filesystem path to the file being sent.

Size: Size of the file.

Progress: Total number of bytes sent for the transfer.

Incoming: If this file is from the local client, false, otherwise true.

Status: The status of the transfer. [0: Not started, 1: In progress, 2: Cancelled, 3: Finished]

User

Blank values are returned for all values if the PassportSiteID and/or UserProperties permissions are not enabled.

All local client-only properties will be blank for the remote client's user.

{"EMail": string, "GlobalIP": string, "LocalIP": string, "Name": string, "PUID": string}

EMail: The contact email of the user.

GlobalIP: Requires EnableIP permission. The fully-resolvable IP of the local client's user.

LocalIP: Requires EnableIP permission. The IP given to us by the network of the local client's user.

Name: The display name of the user.

PUID: The Passport Unique ID of the local client's user.

Input functions

window.external

window.external.CloseApp()

Signals the local client to close the Activity, therefore, closing the WebSocket connection to the Channel.

window.external.Channel

window.external.Channel.Initialize()

Does nothing in messenger.js, otherwise executes Channel_OnRemoteAppLoaded() on the remote client's Activity window.

window.external.Channel.SendData(vDataValue: string)

Sends the data through the Channel to the remote client.

window.external.Channel.EnterIM(IM: string)

Requires SendIM permission.

Unimplemented. Sets the text input of the local client's chat-box to IM.

window.external.Channel.SendIM(myIM: string)

Requires SendIM permission.

Unimplemented. Append the myIM data in the local client's chat-box with the author set to the Activity's name.

window.external.Channel.SendIMAsUser(bstrIM: string)

Requires ReplaceIM permission.

Unimplemented. Send a message (bstrIM) as if written by the user through the channel.

window.external.Channel.SendFile(pdFileInfo: FileInfo*)

Requires SendFile and ActiveX permissions.

Returns the pdFileInfo object.

Unimplemented. Send a file from the local client's storage device through the Channel.

window.external.Channel.CancelSendFile(aFileInfo: FileInfo*)

Requires SendFile and ActiveX permissions.

Unimplemented. Cancel a file transfer operation.

Output functions

Channel_ events

Channel_OnAppClose

Triggered when the Activity window is destroyed.

Technical: Called by a beforeunload handler in messenger.js.

Channel_OnDataError

Accepts parameter pdispError: {"Type": long, "Data": string}.

Triggered if a window.external.Channel.SendData() were to fail on the local client.

The local client should handle the Error object in window.external.Error:

Type: long, Type of error thrown. Data: string, Data which failed to send.

Channel_OnDataReceived

Accepts parameter vData: string.

Triggered after the remote client calls window.external.Channel.SendData().

The local client should handle the data given in window.external.Channel.Data as a string.

Channel_OnFileProgress

Accepts parameter pdispFile: FileInfo.

Unimplemented. Only fired if Activity has SendFile permission.

Triggered after data has been sent over the channel to the remote client regarding a file transfer.

Channel_OnFileReceived

Accepts parameter pdispFile: FileInfo.

Unimplemented. Only fired if Activity has SendFile permission.

Triggered after a file transfer to the local client is received.

The local client should handle the data given in window.external.Channel.File as a FileInfo.

Channel_OnIMReceived

Unimplemented. Only fired if Activity has ReceiveIM permission.

Triggered by retriving a chat message to the local client.

The local client should handle the data given in window.external.Channel.IM as a string.

If the Activity was to have the ReplaceIM permission, window.external.Channel.IM is writable, for which the modified value will be the message sent to the chat-box.

Channel_OnRemoteAppClosed

Triggered when the remote client's Activity window has been destroyed.

The local client should be expected to clean up and display a "remote client has left" message.

Channel_OnRemoteAppLoaded

Triggered when the remote client's Activity window has fired window.external.Channel.Initialize().

Channel_OnSendFileCancelled

Accepts parameter pdispFile: FileInfo.

Unimplemented. Only fired if Activity has SendFile permission.

Triggered when a file transfer is cancelled by either client.

Channel_OnTypeChanged

Accepts parameter eConnectionType: number.

Triggered when the connection type changes.

The local client can see the new connection type by getting window.external.Channel.Type (or eConnectionType's value), which provides these values:

0: Direct connection, Switchboard connection exists, but the local client has a direct connection to the remote client.

1: Indirect connection, Clients can send data, but must go through Switchboard.

2: Disconnected, No connection to the remote client.

Channel_OnIMSent

Accepts parameter bstrIM: string.

Unimplemented. Triggered when the local client has sent an Instant Message. The bstrIM parameter contains the IM text.

Originally introduced in client version 6.2.

Other objects

window.external.Messenger

window.external.Messenger.Options(Page: int)

Unimplemented. Opens the indexed options page (specified by Page, default of 0) of the local client.

window.external.Messenger.Phone(Phone: string)

Unimplemented. Opens the phone dialer with a pre-filled number on the local client. Doesn't initiate the call.

window.external.Users

window.external.Users.Item(lPos: long)

Returns the User object from the list of users in the Activity Channel.

window.external.Users[Symbol.iterator]

Get the User object from the list of users in the Activity Channel.

window.external.Users.Count

Get the number of total User objects in the list of users.

window.external.Users.Me

Get the local client's User object from the list of users.

window.external.Users.Inviter

Get the initiating client's User object from the list of users.

Permission Flags

• ActiveX: Allows unspeakable evils.
• EnableIP: Allows the local client to use the LocalIP and GlobalIP properties from it's own User object.
• PassportSiteID: Allows the local client to use the EMail and Name properties in any User object, and PUID from it's own User object. Authenticates.
• ReceiveIM: Allows the Activity to read Instant Messages sent from the remote client. Enables Channel_OnIMReceived event.
• ReplaceIM: Allows the Activity to read and overwrite Instant Messages from the remote client, and send messages as the local client. Enables Channel_OnIMReceived event and the Channel.SendIMAsUser method.
• SendFile: When combined with ActiveX, allows File operations to occur. Enables Channel_OnFileReceived, Channel_OnSendFileCancelled events, and Channel.SendFile and Channel.CancelSendFile methods.
• SendIM: Allows the Activity to send Instant Messages or enter text into the local client's chat-box text input. Enables Channel.EnterIM and Channel.SendIM methods.
• UserProperties: Allows the local client to use the EMail and Name properties in any User object, and PUID from it's own User object. Does not authenticate.