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.