diff --git a/api.md b/api.md new file mode 100644 index 0000000..e6915d0 --- /dev/null +++ b/api.md @@ -0,0 +1,202 @@ +# 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. + +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 + +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 + +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 + +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 + +Unimplemented. Only fired if Activity has `SendFile` permission. + +Triggered after a file transfer to the local client is received. + +### 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 + +Unimplemented. Only fired if Activity has `SendFile` permission. + +Triggered when a file transfer is cancelled by either client. + +### Channel_OnTypeChanged + +Triggered when the connection type changes. + +The local client can see the new connection type by getting `window.external.Channel.Type`, 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. + + +# 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. \ No newline at end of file diff --git a/client.js b/client.js index ff74311..1940761 100644 --- a/client.js +++ b/client.js @@ -1,4 +1,4 @@ -const channelSocket = new WebSocket("ws://localhost:9091/connect"); +const channelSocket = new WebSocket("ws://localhost:19180/connect"); const __messengerjs__ = { "sessionID": null, "imTheChannelOwner": false, @@ -243,7 +243,7 @@ channelSocket.onerror = function(ev) { window.external.Channel.Error.Data = "WebSocket generic error"; __messengerjs__.fade.textContent = "encountered a WebSocket error" __messengerjs__.fade.style.display = "block"; - Channel_OnDataError(); + __messengerjs__.callIfExists("Channel_OnDataError"); } channelSocket.onclose = function() { __messengerjs__.callIfExists("Channel_OnTypeChanged"); diff --git a/server.js b/server.js index 76a0ea2..54951f9 100644 --- a/server.js +++ b/server.js @@ -1,4 +1,4 @@ -const config = {"__proto__": null, port: 9091}; +const config = {"__proto__": null, port: 19180}; var uidcounter = 0; Object.freeze(config); // Config should not be modified after initialization!