clipsar

chat room for your home.

CLIPSAR DEVELOPER AREA

Any webpage or smart device can be turned into a clipsar-enabled (ce) entity to communicate with people or other smart devices in the same clipsar network. This page describes the main steps to turn a webpage to a ce-entity.

Importing the ce.js

In order to add clipsar support to a webpage the following script tag has to be added in the head section of the page html file:

script(src="https://clipsar.azurewebsites.net/ce-1.00.js", id="clipsar", classId="12345678abcdefgh", classDisplayName="My Website", type="text/javascript")

The following attributes has to be provided in the above mentioned tag:

  • src: Pointing to the correct version of the ce.js file.
  • id: Must be "clipsar".
  • classId: A 16 character unique id (composed of numbers and lowercase characters) assigned to the class of all webpage instances opened from this page.
  • classDisplayName: A display named assigned to the class of all webpages instances opened from this page.
  • type: Must be "text/javascript".

Overriding the abstract functions

In order to receive events from the network the following functions can be provided in the javascript file of the webpage:

clipsar_MessageHandler

This function is called whenever a message is sent to this entity.

Parameters:

  1. senderClassId: The class id of the entity who has sent the message.
  2. senderEntityId: The entity id of the entity who has sent the message.
  3. message: The message sent to this entity.
  4. parameters: Additional parameters sent to this entity as text string.

Return value:

A boolean value true, if the message is known and successfully processed, otherwise false.

Example:

clipsar_MessageHandler = function (senderClassId, senderEntityId, message, parameters) { return true; };

clipsar_ConnectionStatusChanged

This function is called whenever the connection status of the entity is changed.

Parameters:

  1. connectionStatus: The current connection status which can be "connecting", "connected" or "disconnected".

Return value:

None

Example:

clipsar_ConnectionStatusChanged = function (connectionStatus) { };

clipsar_NetworkStatusChanged

This function is called whenever a member joins or leaves the network.

Parameters:

Arguments are passed as a JSON object including the following information:

  1. ip: The gateway ip of the ce-entities attached to this network.
  2. networkDisplayName: The display name assigned to this network.
  3. invitationSession: The current invitation session id for connected guests.
  4. invitationCode: The invitation code for new guests who need to attach.
  5. loggingEnabled: Boolean flag showing if the logging is enabled in network.
  6. classes: A JSON object with properties each specifying a classId connected in network including the following information:
    1. classDisplayName: The display name assigned to the class.
    2. entities: A JSON object with properties each specifying an entityId connected in network with the given class type, including the following information:
      1. entityDisplayName: The display name assigned to this entity.
      2. socketId: The id of the socket for the given entity.
      3. isGuest: A flag specifying if the entity is a guest in network.

Return value:

None

Example:

clipsar_NetworkStatusChanged = function (network) { }

clipsar_InvitationCodeReceived

This function is called whenever an invitation code is requested by this entity.

Parameters:

  1. invitationCode: An invitation code valid for 60 seconds.

Return value:

None

Example:

clipsar_InvitationCodeReceived = function (invitationCode) { };

Using the clipsar functionalities

The following fuctions are provided to ce-entities to interact with the clipsar server and other ce-entities in the network:

clipsar_SendMessage

This function can be used to send a message to other entities in the network providing its classId and entityId. The following combination of sender class id and entity id is accepted by this function:

  • When both receiver classId and entityId is available the message will be sent to the given entity.
  • When the receiver classId is "clipsar" and the entityId is "server" the message will be sent to clipsar server.
  • When the receiver entityId is null but the classId is provided, the message will be broadcasted to all entities in the network with the given classId including the sender.
  • When the entityId is "0" but the classId is provided, the message will be broadcasted to all entities in the network with the given classId excluding the sender.
  • When the receiver classId and entityId are both null the message will be broadcasted to all entities in the network including the sender.
  • When the classId is null but the entityId is "0" the message will be broadcasted to all entities in the network excluding the sender.

Parameters:

  1. receiverClassId: The class id of the entity who shall receive the message.
  2. receiverEntityId: The entity id of the entity who shall receive the message.
  3. message: The message to be sent.
  4. parameters: Additional parameters to be sent with the message.

Return value:

A boolean value true, if the message is successfully sent, otherwise false.

Example:

clipsar_SendMessage(receiverClassId, receiverEntityId, message, parameters);

clipsar_SendServerMessage

This function can be used to send a message to clipsar server.

Parameters:

  1. message: The message to be sent.
  2. parameters: Additional parameters to be sent with the message.

Return value:

A boolean value true, if the message is successfully sent, otherwise false.

Example:

clipsar_SendServerMessage(message, parameters);

clipsar_GetClassDisplayName

This function returns the display name of a entity class.

Parameters:

  1. classId: The classId to retrieve its display name.

Return value:

Display name of the given class or, "invalid" if the provided classId is not valid or, "Unknown" if no display name is assigned to the classId.

Example:

clipsar_GetEntityDisplayName(classId, entityId);

clipsar_GetEntityDisplayName

This function returns the display name of a entity in the network.

Parameters:

  1. classId: The classId of the entity to retrieve its display name.
  2. entityId: The entityId of the entity to retrieve its display name.

Return value:

Display name of the given entity or, "invalid" if the provided entity is not valid or, "Unknown:Unknown" if no display name is assigned to the entity.

Example:

clipsar_GetEntityDisplayName(classId, entityId);

clipsar_GetClassId

This function returns the class id of this entity.

Parameters:

None

Return value:

The class id of this entity.

Example:

clipsar_GetClassId();

clipsar_GetEntityId

This function returns the entity id of this entity.

Parameters:

None

Return value:

The entity id of this entity.

Example:

clipsar_GetEntityId();

clipsar_GetNetwork

This function returns information about the network.

Parameters:

None

Return value:

The return value is a JSON object including the following information:

  1. ip: The gateway ip of the ce-entities attached to this network.
  2. networkDisplayName: The display name assigned to this network.
  3. invitationSession: The current invitation session id for connected guests.
  4. invitationCode: The invitation code for new guests who need to attach.
  5. loggingEnabled: Boolean flag showing if the logging is enabled in network.
  6. classes: A JSON object with properties each specifying a classId connected in network including the following information:
    1. classDisplayName: The display name assigned to the class.
    2. entities: A JSON object with properties each specifying an entityId connected in network with the given class type, including the following information:
      1. entityDisplayName: The display name assigned to this entity.
      2. socketId: The id of the socket for the given entity.
      3. isGuest: A flag specifying if the entity is a guest in network.

Example:

clipsar_GetNetwork();

clipsar_DropHost

This function disconnects the entity if it is connected as guest to a network and reconnect it back to its own network.

Parameters:

None

Return value:

A boolean true value when the call is successful, otherwise false when the entity is not connected as guest to any network.

Example:

clipsar_DropHost();