Webifi.me

Javascript Library Documentation

 

Index

1. Introduction
2. Control
3. Property Functions
4. Functions
5. Callbacks
6. Discovery message
7. Version History

1. Introduction

This document describes all the variables and functions for the Webifi Javascript Library. The Javascript library is used by adding the following line to your HTML file:
<script type=”text/javascript” src=”https://www.webifi.me/Webifi-min-1.0.js”></script>
The second important thing is to create the Webifi object in your page load function.

webifi = WebifiCreate();  //remember to create a global variable: var webifi;

We have a tutorial for using the Javascript library here, the source code can be downloaded at https://github.com/webifi-me/WebifiJavascriptTutorial. We also have a full featured example available at https://github.com/webifi-me/WebifiJavascriptExample.

2. Control

For the user’s convenience the library can create a control for entering the user’s information and starting the service. It is not necessary for the user to create this control, you can create your own controls and use the API calls to have the same functionality as this control. This control is very convenient to get started quickly. In your HTML file you need an empty div where you would like the control to be:

<div id="webifiControl"></div>

Next we need to create the control in your page load function. We use jQuery in our examples. At this point our page load function will look like this:

var webifi;  //this will reference the Webifi library
$(function () {
  webifi = WebifiCreate();
  webifi.WebifiControl("webifiControl");
});

The control that was created should look like this:
Javascript control
The look of the control can be changed using CSS and Javascript. Multiple instances of the control can be created. For the first control the following IDs have been assigned:

id Description
webifiControlDiv0 The div that encapsulated the entire control
textWebifiConnectName0 Connect name text box
textWebifiConnectPassword0 Connect password text box
textWebifiNetworkNames0 Network names text area
buttonSetNetworkNames0 Button for setting the network names
buttonWebifiStart0 Button used for starting or stopping the service

Have a look at our Test Page to see how this is implemented.

3. Property Functions and Variables

Function Description
SetConnectName Set the connect name before starting the connection. Returns 0 if successful or 10 if connect name could not be set. The connect name cannot be changed after the service is started.
GetConnectName Returns the connect name.
SetConnectPassword Set the connect password before starting the connection. Returns 0 if successful or 10 if password could not be set. The password cannot be changed after the service is started.
GetConnectPassword Returns the connect password.
SetNetworkNames Takes an array of network names as an input parameter. These will be the default networks that this instance will belong to. For more details about how this works please check our How it works page. The network names can be changed after the service has started.
GetNetworkNames Returns an array with all the network names that this instance belongs to.
SetDiscoverable The input parameter must be either true or false. If true then this instance will respond to any discovery requests from your other devices. The default value for this property is true.
GetDiscoverable Returns true if this instance is discoverable.
SetDownloadRequestTimeout Set the maximum amount of time a download request should wait if there is no data available. This setting is not used with WebSocket, only with Long Polling. A smaller number uses more bandwidth and a large number will take a long time to recover when something goes wrong with the connection. The default value is 2 minutes and the maximum value is 10 minutes. Normally the user does not need to change this value.
GetDownloadRequestTimeout Returns the current download request timeout duration.
SetUseEncryption When its input variable is true all the data will be exchanged using SSL/TLS. The default value of this property is false.
GetUseEncryption Returns the current encryption state.
GetSessionID Returns the address of this instance on the Webifi network. This property is important if you design more complex systems where you would like another device to only send data to this one.
GetCounters Returns the values of the upload and download counters. The upload counter is incremented each time data is sent. The download counter is incremented each time data is received or if the download request timed out and a new download request is started (The download counter is only used with Long Polling). This function can be used as follows:

var counters = webifi.GetCounters();
var downCnt = counters.download;
var upCnt = counters.upload;
SetUseWebSocket Takes true or false as an argument. If true then the connection will use HTML5 WebSocket. If false then the connection will be established using Long Polling. This function can be called after the connection has been established. The connection will be re-established using the selected technique. The default value for this setting is true.
GetUseWebSocket Returns true if HTML5 WebSocket is enabled.

In the example below we set all the credentials needed for a connection:

webifi = WebifiCreate();
webifi.SetConnectName("webifi");
webifi.SetConnectPassword("12345678");
var networkNames = [];
networkNames.push("network 1");
webifi.SetNetworkNames(networkNames);

There are two variables that are useful to the user:

Variable Description
connected If the value of this variable is true then this instance is connected to the Webifi server and data can be sent and received.
name The name of this instance. This value is returned when a responds to a discovery request is sent.

4. Functions

Method Description
Start This function will start the service and create a connection to the Webifi server.
CreateSendData This function creates an empty sendData object. Because all the correct fields are initialised only the needed fields needs to be set by the user. This function creates and initialises the sendData object as follows:

webifi.CreateSendData = function ()
{
  var sendData = {};
  sendData.data = "";
  sendData.dataType = "";
  sendData.toSessionIDs = [];
  sendData.toNetworks = [];
  return sendData;
}
SendData This function will send data to your other connected devices. The input parameter, the sendData object, needs to be populated as shown in the CreateSendData function above.
CloseConnection Call this function when you want to disconnect from our service.
ConvertErrorCodeToString This is a handy function for converting an error code to a description of the error.
GetBufferedAmount This function returns the number of send packets (not the number of bytes) that is currently in the queue for sending.
SendDiscovery Call this function to discover the names and session IDs of your other devices currently connected. If this function is called without any input parameters then the discovery message will be sent to the default networks this device is part of. If an array of network names are passed into this function then the discovery message will be sent to those networks. Discovery messages are explained in more detail later in this document.

5. Callbacks

The following functions are used to set the callbacks for the Javacript Library:

Set Callback Description
SetConnectionStatusCallback This callback is called each time the connection status changes, in other words when your device connects or disconnects from our service.
SetDataReceivedCallback When data is received from another device this callback is called. There are three variables passed to this callback:

  • data: The data that was received
  • dataType: This optional field is a string that the sending device can use. This can be useful for implementing basic protocols.
  • from: The session ID of the device that sent the message. This can be used to only reply to the device that sent this message.
SetErrorCallback When something goes wrong then the error callback is called. The error code is passed to the callback.

Below is an example of how the callbacks are used (This page uses a jQuery function for it’s page load event):

var webifi;

//this function runs when the page is finished loading
$(function () {
  webifi = WebifiCreate();

  //set callbacks
  webifi.SetDataReceivedCallback(RecDataCallback);
  webifi.SetConnectionStatusCallback(ConnectionMessageCallback);
  webifi.SetErrorCallback(ErrorCallback);

  //generate the Webifi control
  //there needs to be a div with an id set to "webifiControl" for this to work
  webifi.WebifiControl("webifiControl"); 
  webifi.SetConnectName("webifi");
  webifi.SetConnectPassword("12345678");
  var networkNames = [];
  networkNames.push("network 1");
  networkNames.push("network 2");
  webifi.SetNetworkNames(networkNames);
});

//callback functions
function RecDataCallback(data, dataType, from, sender) {
  //process received data
}

function ErrorCallback(errorCode, sender) {
  var errorMessage = webifi.ConvertErrorCodeToString(errorCode);
  //code to display error message
}

function ConnectionMessageCallback(connected, sender) {
  var message;
  if (connected) {
    message = "Connection successful";
    //user code if connection successful
  } else {
    //there was an error, get the error message
    message = "Connection error: " + webifi.ConvertErrorCodeToString(error);
    //process connection failed
  }
}

6. Discovery message

The session IDs are dynamically assigned to devices connecting to the Webifi server. If you need to send data to a specific device or devices then you need to know their session IDs. The discovery message is an easy way to find the session IDs of all your connected devices. When you call the Send Discovery function the following message will be sent:

  • Data type: Discovery
  • Data: ? (A question mark character needs to be sent)
  • To networks: When empty then the discovery message will be sent to the default networks the sending device is listening to. If an array of networks are specified then all the discoverable devices on these networks will respond.

There isn’t a special event handler for the discovery response, the responses will be received by the data received event. This gives the most flexibility for the user to process the discovery responses any way the user needs. The discovery response looks as follows:

  • Data type: Discovery Response
  • Data: User defined name on the responding device
  • From session ID: The session ID that was discovered. This needs to be stored by the device doing the discovery.

Below is an example of how the discovery can be implemented by the user:

function RecDataCallback(data, dataType, from, sender) {
  //check if a discovery response was received
  if (dataType == "Discovery Response") {
    //device discovered, name will be in data and the session ID will be in the from variable
  }
  else {
    //data was received, process...
  }
}

7. Version History

Version Description
Webifi-min-1.0.js First release