# appwebsocket

## innovaphone.appwebsocket.Connection(url, app)

Creates a WebSocket connection to 'url' for an app entity named 'app'. It uses the JavaScript function opener.GetLogin(app,challenge,onlogin(app, user, key)) to obtain login credentials from the web page which opened the app.

Optional parameters 'password' and 'domain' can be used to perform a password based login. This is useful when connection is established from a plain website, without myApps client (e.g. AP Manager UI uses this option for password login).

It provides a send function to send messages. The messages are provided to the send function as JavaScript object, which are JSON coded by the library. For receiving messages a onmessage handler is provided.

To route messages to multiple objects inside the App a mechanism is provided with the this.src constructor function. The idea is, that each object, which independtly sends and receives messages using the same WebSocket connection allocates an object with this constructor function. Each object is identifies itself by a name, which has to be unique within the App. Then the send and onmessage functions of this 'src' object are used to send and receive messages. This mechanism uses the 'src' member inside the JSON messages.

this.onconnected = function(domain, user, dn, appdomain) { }
  To be overwritten by the app. Is called, when the connection is established.
  domain
    Domain of the looged in user
  user
    username of the logged in user
  dn
    Display name of the logged in user
  appdomain
    Domain of the App Instance to which the user is logged in
this.onmessage = function (message) { }
  To be overwritten by the app. Is called when a message is received. The argument 'message' is a JavaScript object constructed from the received json message.
this.onerror = function (error) { }
this.onclosed = function () { }
this.send = function (message) { }
  Send a message via the WebSocket connection.
  message
    A JavaScript object representing a message.
this.sendSrc = function (message, onresult, obj) { }
  Send a message via the WebSocket connection. Creates a separate src object instance for this request (see this.src function). The src instance is closed on a first response with the same src.
  message
    A JavaScript object representing a message.
  result
    A callback function (message, obj) that is called when a message for this src is received.
  obj (optional)
    An optional JavaScript object reference that is returned as the second parameter of the callback function. Can be used to pass a reference to an entity that is relevant to the callback processing (e.g. a UI element that should be updated on callback).
this.sendSrcMore = function (message, onresult, obj) { }
  Send a message via the WebSocket connection. Creates a separate src object instance for this request (see this.src function). The src instance will persist as long as responses with a 'more' property are received. On each response with a 'more' property set to a Number or a String, the src instance will resend the original message, adding the received 'more' property to it. If received messages contain a Boolean 'more' property set to 'true', no initial message is resent, but the src instance persists until a response without a 'more' property set is received.
  message
    A JavaScript object representing a message.
  result
    A callback function (message, obj) that is called when a message for this src is received.
  obj (optional)
    An optional JavaScript object reference that is returned as the second parameter of the callback function. Can be used to pass a reference to an entity that is relevant to the callback processing (e.g. a UI element that should be updated on callback).
this.src = function (src)
  Constructor function to create an object, which routes received messages based on the 'src' property in the message. This can be used, if the app contains different objects, which independently send requests and receive responses or indications. Each object may allocate a src object and set the onmessage member of this object to receive messages. If the send function of this src object is used, a property 'src' is added to each sent JSON message.
this.checkBuild
  Boolean. If set to true, the CheckBuild mechanism will be used.
this.setKeepAlive = function (on)
  Turns KeepAlive on or off. If on, a "KeepAlive" message will be sent to the server from time to time in order to detect if the connection is still up.
this.encrypt = function (seed, data)
  Returns ecrypted data based on a certain seed. RC4 is used in combination with a session key which is calculated during the login handshake.
this.decrypt = function (seed, data)
  Returns decrypted data based on a certain seed. RC4 is used in combination with a session key which is calculated during the login handshake.

## Messages

See the protocol definition here: AppWebsocket.