Short API Documentation

Mario Schreiner edited this page Jan 14, 2015 · 9 revisions

TOC

Global

Most of Connichiwa's functions reside in a global Connichiwa object.

TOC:

Events

Connichiwa.onLoad(callback)

Attaches the given callback to Connichiwa's load event. This is equivalent to jQuery's load() except it also fires when the page is already loaded when the callback is attached. This is particularly useful on remote devices, where we often load JavaScript files asynchronously.

Arguments:

  • callback: The callback to execute when the load event fires

Example:

Connichiwa.onLoad(function() {
    /* Do something with Connichiwa and the DOM */
});
Connichiwa.on(event, callback) (master only)

Attaches a callback to an event. Connichiwa sends a number of events to your application, mostly related to nearby devices.

Possible Events:

  • deviceDetected: Sent when a new device was detected nearby. Receives the detected CWDevice as its only argument.
  • deviceDistanceChanged: Sent when the distance of a nearby device changes. Receives the moved CWDevice as its only argument.
  • deviceLost: Sent when a previously detected device was lost. Receives the lost CWDevice as its only argument.
  • deviceConnected: Sent when a remote device was connected. The device can now be used as a remote device. Receives the connected CWDevice as its only argument.
  • connectFailed: Sent when the connection to a remote device failed. Receives the failed CWDevice as its only argument.
  • deviceDisconnected: Sent when a connected remote device was disconnected. Receives the disconnected CWDevice as its only argument.

Arguments:

  • event: The name of the event to handle
  • callback: The callback to execute when the given event is triggered

Example:

Connichiwa.on("deviceDetected", function(device) {
    device.connect();
});

Sending & Receiving Messages

Your application can send messages to other devices and set up event handlers to react to incoming messages. This is the main way of communication between devices.

Connichiwa.send(device, name, message)

Sends the given message (a JSON object) with the given name to the given device.

Arguments:

  • device: A device identifier, a CWDevice or the string "master". The message target.
  • name: The name of the message.
  • message: A valid JSON object that can contain arbitrary key-value pairs which will be sent to the target device. Keys starting with an underscore _ are reserved by Connichiwa and should not be used.

Example:

var message = { "newvalue" : 90 };
Connichiwa.send(device, "rotate", message);

//... on another device (or the same device), the message can be handled...

Connichiwa.onMessage("rotate", function(message) {
   infoPanel.css("-webkit-transform", "rotate("+message.newvalue+"deg)");
});
Connichiwa.broadcast(name, message, sendToSelf)

Broadcasts the given message with the given name to all devices. If sendToSelf is set to true, the message will also be broadcasted to the device where the call originated from.

Arguments:

  • name: The name of the message.
  • message: A valid JSON object that can contain arbitrary key-value pairs which will be sent to the devices. Keys starting with an underscore _ are reserved by Connichiwa and should not be used.
  • sendToSelf: If set to true, the message will also be sent to the device that calls broadcast(), otherwise it won't. Default: false

Example:

var message = { "newvalue" : 90 };
Connichiwa.broadcast("rotate", message, true);
Connichiwa.respond(originalMessage, responseName, response)

Convenience method that will respond to a message. The given message will be sent back to the device where originalMessage was sent from.

Arguments:

  • originalMessage: The message to respond to. The response will be sent to the device this message came from.
  • responseName: The name of the response message.
  • response: A valid JSON object that can contain arbitrary key-value pairs which will be sent. Keys starting with an underscore _ are reserved by Connichiwa and should not be used.

Example:

Connichwa.onMessage("rotate", function(message) {
    infoPanel.css("-webkit-transform", "rotate("+message.newvalue+")");
    var response = { "success": true };
    Connichiwa.respond(message, "didrotate", response);
});
Connichiwa.onMessage(name, callback)

Sets up a handler for messages of the given name. Every time a message with name is received from another device, the callback will be executed. The callback will receive a single argument, which is the message that has been passed to Connichiwa.send(), Connichiwa.broadcast() or Connichiwa.respond().

Additional message properties:

Connichiwa adds a number of properties to a message when sending it:

  • _source: The identifier of the sending device
  • _target: The identifier of the receiving device (the current device), but can also be the strings "master" or "broadcast"
  • _id: A unique ID that identifies each message
  • _name: The message name

Arguments:

  • name: The name of the messages that callback should be attached to
  • callback: The callback function to execute when messages with the given name are received

Example:

var message = { "newvalue" : 90 };
Connichiwa.send(device, "rotate", message);

//... on another device (or the same device), the message can be handled...

Connichiwa.onMessage("rotate", function(message) {
   infoPanel.css("-webkit-transform", "rotate("+message.newvalue+"deg)");
});

Working with remote devices

Connichiwa.insert(device, targetElement, html)

Will insert the given piece of html (or a copy of a given DOM or jQuery object) into the targetElement on the device.

Arguments:

  • device: The target device where html should be inserted. Can be a CWDevice object, a device identifier or the string "master".
  • targetElement: A CSS selector that represents an existing DOM-element on device. html will be added to that element using jQuery's .append(). This can also be a DOM or jQuery object, in which case a CSS selector with the id of the object will be created.
  • html: Can be either a string representing HTML code, a DOM object or a jQuery object. The latter two will be cloned and converted to HTML. The HTML code represented by this will be inserted.

Example:

Insert a piece of HTML code to a device's <body> tag:

Connichiwa.insert(device, "body", "<b>Some HTML code</b>");

Insert a copy of an jQuery object to a device's <body> tag:

Connichiwa.insert(device, "body", $(infoPanel));

Insert a piece of HTML code to an HTML element with ID "container" on a device. If no such HTML element exists on the remote device, this call will have no effect.

var container;
Connichiwa.onLoad(function() {
    container = $("<div></div>");
    container.attr("id", "container");
    container.html("<b>Welcome to Connichiwa!</b>");
    $("body").append(container);
});

Connichiwa.on("deviceConnected", function(device) {
    Connichiwa.insert(device, container, "<b>Some HTML code</b>");
});
Connichiwa.replaceContent(device, targetElement, html)

Will replace the contents of the targetElement with html on the device.

Arguments:

  • device: The target device. Can be a CWDevice object, a device identifier or the string "master".
  • targetElement: A CSS selector that represents an existing DOM-element on device. html will replace the content of that element using jQuery's .html(). This can also be a DOM or jQuery object, in which case a CSS selector with the id of the object will be created.
  • html: Can be either a string representing HTML code, a DOM object or a jQuery object. The latter two will be cloned and converted to HTML. The HTML code represented by this will be the new content of targetElement.

Example:

Replace the content of all <p> elements on a device:

Connichiwa.replaceContent(device, "p", "<b>Some HTML code</b>");

Replace the content of all <p> elements with class remote:

Connichiwa.replaceContent(device, "p.remote", "<b>Some HTML code</b>");

Replace the entire <body> tag on a device:

Connichiwa.replaceContent(device, "body", "<b>Some HTML code</b>");

Replace the HTML element with ID "container" on a device. If no such HTML element exists on the remote device, this call will have no effect.

var container;
Connichiwa.onLoad(function() {
    container = $("<div></div>");
    container.attr("id", "container");
    container.html("<b>Welcome to Connichiwa!</b>");
    $("body").append(container);
});

Connichiwa.on("deviceConnected", function(device) {
    Connichiwa.replaceContent(device, container, "<b>Some HTML code</b>");
});
Connichiwa.replace(device, targetElement, html)

Will replace the targetElement with html on the device. The difference between this method and replaceContent() is that this method will replace the entire element (including its content), while replaceContent() only replaces the content but leaves the element intact.

Arguments:

  • device: The target device. Can be a CWDevice object, a device identifier or the string "master".
  • targetElement: A CSS selector that represents an existing DOM-element on device. html will replace this element using jQuery's .replaceWith(). This can also be a DOM or jQuery object, in which case a CSS selector with the id of the object will be created.
  • html: Can be either a string representing HTML code, a DOM object or a jQuery object. The latter two will be cloned and converted to HTML. The HTML code represented by this will be the new content of targetElement.

Example:

Replace a <div> elements with ID first with a <div> element with class second. The content of the element (if it has any) will be lost:

Connichiwa.replace(device, "div#first", "<div class='second'></div>");
Connichiwa.loadScript(device, url, callback)

Loads the JavaScript file at url on device. The optional callback is executed after the script has been loaded.

Arguments:

  • device: The target device where the JavaScript file will be executed. Can be a CWDevice object, a device identifier or the string "master".
  • url: A valid URL to a JavaScript file that should be loaded on device.
  • callback (optional): Will be called after url has been loaded

Examples:

Connichiwa.on("deviceConnected", function(device) {
    Connichiwa.loadScript(device, "/remoteScript.js", function() {
        //remoteScript.js has loaded, which contained our Connichiwa code for the other device
        //Now that our remote device installed its event handlers, it will respond to our messages
        var message = { "newvalue": 90 };
        device.send("rotate", message);
    });
});

Misc

Connichiwa.isMaster()

true if the current device is the master device (where your application is running). false if the device is a remotely connected device

Connichiwa.getIdentifier()

A string representing a 128-bit UUID, in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. This is the unique identifier of the current device

Connichiwa.autoConnect (master only)

Setting this to true will make Connichiwa automatically connect any device in range.

Connichiwa.autoLoadScripts (master only)

An array of paths. Each path should point to a JavaScript file that will be automatically loaded on each connected device.


CWDevice

A CWDevice object represents a device in Connichiwa. This can be any device - the master or a remotely connected device. Each device in Connichiwa is represented by a unique identifier string. CWDevice objects are created by Connichiwa when it detects a nearby device, and passed to your application in all device-related events, such as deviceDetected, deviceConnected and so on (also see Connichiwa.on()). Your application needs to remember either the CWDevice or the device's unique identifier in order to send messages to a device or update another device's content.

getIdentifier()

Returns the unique identifier of the device, which is a string representing a 128-bit UUID, in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Each device in Connichiwa has a identifier that uniquely identifies the device. Oftentimes, the identifier can be used as a substitute for a CWDevice, for example when using Connichiwa.send(). When another device disconnects and reconnects later, its identifier is not guaranteed to stay the same.

getLaunchDate()

Returns the startup time of Connichiwa in the device's local time

getName()

Returns the name of the device if present. If the device has no name, the string unknown is returned.

getPPI()

Returns the pixels per inch (pixel density) of the device's display. This might be an approximation.

isLocal()

Returns true if the CWDevice represents the device where the current code is running, otherwise false

isNearby()

Returns true if the device is in Bluetooth range and detected and false if the device has been lost

canBeConnected()

Returns true if a call to connect() will have an effect on this device. This returns false if the device is not nearby or already connected.

isConnected()

Returns true if the device is connected and can be used by the application. Calls such as insert() or loadScript() will have no effect as long as the device is not connected.

connect() (master only)

The master device can connect a device by calling this method. If the device is already connected this method will have no effect.

insert(targetElement, html)

Shortcut for Connichiwa.insert(device, targetElement, html) with this CWDevice as the first argument. Will insert HTML code to an element on the device.

loadScript(url, callback)

Shortcut for Connichiwa.loadScript(device, url, callback) with this CWDevice as the first argument. Will load a JavaScript file on the device.

send(name, message)

Shortcut for Connichiwa.send(device, name, message) with this CWDevice as the first argument. Will send a message to the device. A shortcut for Connichiwa.send(device, name, message) with the CWDevice as the first parameter.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.