Webinos Logo

App2App Messaging API

Webinos API Specifications

3 Sep 2012

Authors


Abstract

Interface for exchanging messages between applications, locally and/or remotely.

Table of Contents

  1. Introduction
  2. Interfaces and Dictionaries
    1. Webinos
    2. App2AppMessaging
    3. App2AppMessage
    4. App2AppChannel
    5. App2AppChannelProperties
    6. App2AppChannelRequest
    7. PendingOperation
  3. Callbacks
    1. App2AppMessageCB
    2. App2AppChannelRequestCB
    3. App2AppSuccessCB
    4. App2AppErrorCB
    5. App2AppChannelSearchCB
  4. Enums
    1. ChannelMode
  5. Features
  6. Full WebIDL

Summary of Methods

Interface Method
Webinos
App2AppMessaging App2AppChannel createChannel(DOMString namespace, App2AppChannelProperties properties, App2AppChannelRequestCB requestCB)
App2AppMessage createMessage(DOMString type, DOMString? payload)
PendingOperation searchForChannels(DOMString namespace, DOMString[] zoneIds, App2AppChannelSearchCB searchCB, App2AppErrorCB errorCB)
App2AppChannel void connect(App2AppChannelRequest request, App2AppMessageCB messageCB, App2AppSuccessCB successCB, App2AppErrorCB errorCB)
void send(App2AppMessage message, App2AppErrorCB errorCB)
void close()
PendingOperation void cancel()

Introduction

The Webinos App2App Messaging specification defines interfaces to create, send and receive messages between applications in the Webinos system. It provides generic messaging primitives which can be applied in different application scenarios. The messaging is indirect, meaning that applications do not directly address each other but use a channel to route the messages to connected applications. An unique namespace (within a personal zone) is used as a key to find and connect to channels.

This API can be used by third-party application developers to implement custom message-based protocols by taking advantage of the features offered by the Webinos message handling system and overlay networking model.

Interfaces and Dictionaries

Interface Webinos (partial interface)

The App2AppMessaging interface describes the part of the App2App Messaging API accessible through the webinos object.

WebIDL
partial interface Webinos {

  readonly attribute App2AppMessaging app2app;
};

Attributes

readonly App2AppMessaging app2app

webinos.app2app object.

This attribute is readonly.

Interface App2AppMessaging

Access to the App2App Messaging functions.

WebIDL
interface App2AppMessaging {


  App2AppChannel createChannel(
    DOMString namespace,
    App2AppChannelProperties properties,
    App2AppChannelRequestCB requestCB);


  App2AppMessage createMessage(
    DOMString type,
    [TreatUndefinedAs=Null] 
      optional DOMString? payload);


  PendingOperation searchForChannels(
    DOMString namespace, 
    DOMString[] zoneIds,
    App2AppChannelSearchCB searchCB,
    optional App2AppErrorCB errorCB);

};

An application can create and configure a channel using a namespace. Other applications are able to connect to that channel using the namespace as a key (with a possible wildcard). A channel sits between (two or more) applications such that applications do not address each other directly.

The application which created the channel (i.e. the channel owner) can authorize connect requests of other application instances that want to use the channel using the App2AppChannelRequestCB callback.

Methods

createChannel

Create a new channel.

Signature
App2AppChannel createChannel(DOMString namespace, App2AppChannelProperties properties, App2AppChannelRequestCB requestCB);
Code example
   // create channel and ask user to accept connections
   var channel = webinos.app2app.createChannel("urn:webinos:org:example", { channelOwner: "exampleApp", mode: "send-receive" },
                                               requestHandler(request) { return confirm("Accept connect request from " + request.source) });
   
Parameters
  • namespace
    • Optional: No.
    • Nullable: No
    • Type: DOMString
    • Description: The namespace of the channel (must be unique within the personal zone).
  • properties
  • requestCB
    • Optional: No.
    • Nullable: No
    • Type: App2AppChannelRequestCB
    • Description: The callback called when an application wants to connect to the channel. If the callback returns true the application is allowed to connect, otherwise the connect attempt is rejected.
createMessage

Create a new message.

Signature
App2AppMessage createMessage(DOMString type, optional DOMString? payload);
Code example
   var channel; // previously created channel
   var message = webinos.app2app.createMessage("status", '{"status": "ok"}');
   channel.send(message, errorHandler(error) { alert("Oops, something went wrong.") });
   
Parameters
  • type
    • Optional: No.
    • Nullable: No
    • Type: DOMString
    • Description: The type of the message.
  • payload
    • Optional: Yes.
    • Nullable: Yes
    • Type: DOMString
    • Description: The payload of the message.
searchForChannels

Search for channels.

Signature
PendingOperation searchForChannels(DOMString namespace, DOMString[] zoneIds, App2AppChannelSearchCB searchCB, optional App2AppErrorCB errorCB);

The key used for finding channels is the channel namespace. It is possible to use a trailing wildcard for the namespace-specific string of the URN to match all channels with the provided namespace identifier prefix. This is useful when multiple application instances of the same application run in the personal zone, share the same namespace identifier and use a generated namespace-specific string to avoid clashes.

Code example
   webinos.app2app.searchForChannels("urn:webinos:org:*", [],
                                     resultHandler(channel) { alert("Found a channel.") });
   
Parameters
  • namespace
    • Optional: No.
    • Nullable: No
    • Type: DOMString
    • Description: The namespace of the channels to search for. A wildcard is allowed for the namespace-specific string.
  • zoneIds
    • Optional: No.
    • Nullable: No
    • Type: array
    • Description: The identifiers of the personal zones to search for channels in addition the local personal zone.
  • searchCB
    • Optional: No.
    • Nullable: No
    • Type: App2AppChannelSearchCB
    • Description: The callback called when a channel is found. Can be called multiple times if multiple channels are found.
  • errorCB
Return value
PendingOperation interface to cancel the asynchronous call.

Dictionary App2AppMessage

The App2AppMessage interface.

WebIDL
dictionary App2AppMessage {


  DOMString id;


  DOMString type;


  DOMTimeStamp timeStamp;


  DOMString? payload;
};

Dictionary Members

DOMString id

The identifier of the message.

The message identifier is generated by the Webinos system.

DOMString type

The message type.

DOMTimeStamp timeStamp

The timestamp of the message.

The message timestamp is generated by the Webinos system.

DOMString? payload

The payload of the message.

Interface App2AppChannel

The App2AppChannel interface.

WebIDL
interface App2AppChannel {


  readonly attribute DOMString namespace;


  readonly attribute App2AppChannelProperties properties;


  void connect(
    App2AppChannelRequest request,
    App2AppMessageCB messageCB,
    optional App2AppSuccessCB successCB,
    optional App2AppErrorCB errorCB);


  void send(
    App2AppMessage message,
    optional App2AppErrorCB errorCB);


  void close();
};

A channel is the primary entity used for App2App Messaging. The namespace of a channel is specified as an URN and must be unique within a personal zone. If an application attempts to create a channel with an already existing namespace (i.e. there is already an active channel with the same namespace within the personal zone) an error is returned.

An application can create multiple channels, if needed. Each channel requires its own namespace.

Attributes

readonly DOMString namespace

The namespace of the channel.

This attribute is readonly.
readonly App2AppChannelProperties properties

The properties of the channel.

This attribute is readonly.

Methods

connect

Connects to the channel.

Signature
void connect(App2AppChannelRequest request, App2AppMessageCB messageCB, optional App2AppSuccessCB successCB, optional App2AppErrorCB errorCB);
Code example
   var channels; // previously (non-empty) array of found channels
   channels[0].connect( { source: "exampleApp" },
                        messageHandler(message) { alert("Got message with type: " + message.type) },
                        successHandler() { alert("Successfully connected to channel.") },
                        errorHandler() { alert("Oops, something went wrong.") });
   
Parameters
  • request
    • Optional: No.
    • Nullable: No
    • Type: App2AppChannelRequest
    • Description: Request object to include in the request.
  • messageCB
    • Optional: No.
    • Nullable: No
    • Type: App2AppMessageCB
    • Description: Callback called when receiving a message.
  • successCB
    • Optional: Yes.
    • Nullable: No
    • Type: App2AppSuccessCB
    • Description: Callback called when the connect was successful.
  • errorCB
    • Optional: Yes.
    • Nullable: No
    • Type: App2AppErrorCB
    • Description: Callback called when an error occurred during connecting.
send

Send a message on the channel.

Signature
void send(App2AppMessage message, optional App2AppErrorCB errorCB);
Code example
   var channel; // previously obtained and successfully connected channel
   var message = webinos.app2app.createMessage("status", '{"status": "ok"}');
   channel.send(message, errorHandler(error) { alert("Oops, something went wrong.") });
   
Parameters
  • message
    • Optional: No.
    • Nullable: No
    • Type: App2AppMessage
    • Description: The message to send.
  • errorCB
    • Optional: Yes.
    • Nullable: No
    • Type: App2AppErrorCB
    • Description: Callback called when an error occurred during sending.
close

Close the channel.

Signature
void close();

There is no corresponding open function as this is implicit in the creation of the channel.

Dictionary App2AppChannelProperties

The channel properties.

WebIDL
dictionary App2AppChannelProperties {


  DOMString channelOwner;


  ChannelMode mode;
};

At channel creation time the application instance can specify channel properties. The properties contains mandatory fields but can be extended with application-specific fields.

Dictionary Members

DOMString channelOwner

The owner of the channel.

ChannelMode mode

The mode of the channel.

Dictionary App2AppChannelRequest

Interface for channel connect requests.

WebIDL
dictionary App2AppChannelRequest {


  DOMString source;
};

Dictionary Members

DOMString source

The source of the channel request.

Interface PendingOperation

Pending operation interface for cancelling asynchronous calls.

WebIDL
[NoInterfaceObject] interface PendingOperation {


  void cancel();
};

Methods

cancel

Cancel method for cancelling asynchronous find channel operation.

Signature
void cancel();

Cancel the pending channel search operation. When this method is called, the user agent must immediately bring the operation to stop and return. Allocated resources should be released and any ongoing related network operations should be terminated. An error callback is issued with the DOMError name "AbortError".

Callbacks

App2AppMessageCB

The message callback for receiving messages on the channel.

WebIDL
callback App2AppMessageCB = void (App2AppMessage message);
Signature
void App2AppMessageCB(App2AppMessage message);
Parameters
  • message

App2AppChannelRequestCB

The request callback for authorizing channel connection attempts.

WebIDL
callback App2AppChannelRequestCB = boolean (App2AppChannelRequest request);
Signature
boolean App2AppChannelRequestCB(App2AppChannelRequest request);
Parameters

App2AppSuccessCB

Success callback for when an operation successfully terminated.

WebIDL
callback App2AppSuccessCB = void ();
Signature
void App2AppSuccessCB();

App2AppErrorCB

Error callback for errors when interacting with a channel.

WebIDL
callback App2AppErrorCB = void (DOMError error);
Signature
void App2AppErrorCB(DOMError error);
Parameters
  • error
    • Optional: No.
    • Nullable: No
    • Type: DOMError
    • Description:

App2AppChannelSearchCB

The channel search callback.

WebIDL
callback App2AppChannelSearchCB = void (App2AppChannel channel);
Signature
void App2AppChannelSearchCB(App2AppChannel channel);
Parameters
  • channel

Enums

ChannelMode

The available channel modes.

WebIDL
enum ChannelMode { "send-receive", "receive-only" };
  • send-receive: connected applications can both send and receive on the channel. This is effectively a many-to-many communication scheme.
  • receive-only: connected applications can only receive on the channel (the channel owner can both send and receive). This is effectively a one-to-many communication scheme.

Values

send-receive
receive-only

Features

This is the list of URIs used to declare this API's features, for use in the widget config.xml and as identifier for service type in service discovery functionality. For each URI, the list of functions covered is provided.

http://webinos.org/api/app2app

Full WebIDL

WebIDL
partial interface Webinos {

  readonly attribute App2AppMessaging app2app;
};


interface App2AppMessaging {


  App2AppChannel createChannel(
    DOMString namespace,
    App2AppChannelProperties properties,
    App2AppChannelRequestCB requestCB);


  App2AppMessage createMessage(
    DOMString type,
    [TreatUndefinedAs=Null] 
      optional DOMString? payload);


  PendingOperation searchForChannels(
    DOMString namespace, 
    DOMString[] zoneIds,
    App2AppChannelSearchCB searchCB,
    optional App2AppErrorCB errorCB);

};


dictionary App2AppMessage {


  DOMString id;


  DOMString type;


  DOMTimeStamp timeStamp;


  DOMString? payload;
};


interface App2AppChannel {


  readonly attribute DOMString namespace;


  readonly attribute App2AppChannelProperties properties;


  void connect(
    App2AppChannelRequest request,
    App2AppMessageCB messageCB,
    optional App2AppSuccessCB successCB,
    optional App2AppErrorCB errorCB);


  void send(
    App2AppMessage message,
    optional App2AppErrorCB errorCB);


  void close();
};


dictionary App2AppChannelProperties {


  DOMString channelOwner;


  ChannelMode mode;
};


enum ChannelMode { "send-receive", "receive-only" };


dictionary App2AppChannelRequest {


  DOMString source;
};


callback App2AppMessageCB = void (App2AppMessage message);


callback App2AppChannelRequestCB = boolean (App2AppChannelRequest request);


[NoInterfaceObject] interface PendingOperation {


  void cancel();
};


callback App2AppSuccessCB = void ();


callback App2AppErrorCB = void (DOMError error);


callback App2AppChannelSearchCB = void (App2AppChannel channel);