Skip to content

Latest commit

 

History

History
224 lines (175 loc) · 8.37 KB

Reference.md

File metadata and controls

224 lines (175 loc) · 8.37 KB
Raw

1.0.x API Reference

The jingle-session module is intended to be used in conjunction with Jingle.js.

Session

The Session class is intended to be a common base for covering the general requirements of a Jingle session. Subclasses of Session are needed to actually do interesting things, such as media or file transfer.

new Session(opts)

  • opts - An object summarizing the information in the session initiate request, suitable for passing directly to a session class constructor:
    • sid - The ID for the session, as provided by the initiating peer.
    • peer - The JID for the initiating peer (may be either a {String} or {JID}).
    • peerID - An alternative to peer, which MUST be a {String} (derived from peer).
    • initiator - This will always be false, as we are the one receiving the initiation request.
    • descriptionTypes - An array of content description names.
    • transportTypes - An array of content transport names.

Session Properties

  • sid - A unique ID for the session.
  • peer - The JID for the initiating peer (may be either a {String} or {JID}).
  • peerID - An alternative to peer, which MUST be a {String} (derived from peer).
  • state - Always one of:
    • starting
    • pending
    • active
    • ended
  • connectionState - Always one of:
    • starting
    • connecting
    • connected
    • disconnected
    • interrupted
  • pendingAction - The name of the action that has just been sent to the peer, so we can check for tie-breaking if the same action is requested from both parties at the same time.
  • pendingDescriptionTypes - The list of content types gathered from a session initiate request, so that we can perform tie-breaking if another session initiation request is received for the same content types.
  • isInitiator - This flag is true if the initiator field is true when creating the session.
  • starting - This flag is true when .state equals 'starting'.
  • pending - This flag is true when .state equals 'pending'.
  • active - This flag is true when .state equals 'active'.
  • ended - This flag is true when .state equals 'ended'.
  • connecting - This flag is true when .connectionState equals 'connecting'.
  • connected - This flag is true when .connectionState equals 'connected'.
  • disconnected - This flag is true when .connectionState equals 'disconnected'.
  • interrupted - This flag is true when .connectionState equals 'interrupted'.

Session Methods

session.process(action, data, cb)

  • action - The session action to apply to the session.
  • data - The contents of the jingle field of a Jingle packet.
  • cb([err]) - callback for returning potential errors, and triggering processing for the next queued action.
    • err - An error object if the action could not be performed
      • condition - The general error condition
      • jingleCondition - A Jingle specific error condition, if applicable

Calling this method places the action and its associated data and callback into the session's processing queue.

Each action is processed sequentially, calling cb() to trigger sending an ack result to the peer, and then process the next action. If cb() is given an error object, an error response will be sent to the peer.

This method is not intended to be called directly by the user, but is a required method for any Session instance to be able to work with the session jingle.

session.send(action, data)

  • action - The session action the peer should perform based on this request.
  • data - Information to insert into the jingle section of the packet. The sid and action fields will be automatically set.

Emits a send event for a new Jingle packet:

// Send a session terminate message directly:
session.send('session-terminate', {
    reason: {
        condition: 'gone'
    }
});

// emitted send event: {
//    to: '[email protected]',
//    type: 'set',
//    jingle: {
//        sid: 'sid123',
//
//        // the provided action:
//        action: 'session-terminate',
//
//        // the provided data:
//        reason: {
//            condition: 'gone'
//        }
//    }
//}

session.start()

Initiate a the session request to the peer. Calling this method will move the session from the starting state to pending, and will trigger an outgoing event on the session jingle.

The session should have been added to the session jingle with .addSession() before calling .start().

var session = new MyCustomSession({
    peer: '[email protected]',
    initiator: true
});

jingle.addSession(session);
jingle.on('outgoing', function (sess) {
    console.log('Outgoing session:', sess.sid === session.sid);
});

session.start();
// -> Outgoing session: true

session.accept()

Moves the session to the active state, and sends a session-accept action.

For a Session instance, this actually calls .end('unsupported-applications').

jingle.on('incoming', function (session) {
    // Auto-accept an incoming session
    session.accept();
});

session.cancel()

This is a shortcut for calling session.end('cancel').

Calling session.cancel() should only be done after initiating the session and before it is accepted by the peer. After that point, calling session.end() is more appropriate.

session.decline()

This is a shortcut for calling session.end('decline').

Calling session.decline() should only be done after receiving a session initiation request and before (or rather, instead of) accepting the session.

session.end([reason], [silent])

  • reason - Why the session is being ended. This may be either a {String} or an object:
    • condition - The name of the reason
    • text - A freeform description of the reason
    • alternativeSession - If the condition is alternative-session, this is the sid value for that session.
  • silent - If true, the session terminate message will not be generated to be sent to the peer.

Once .end() is called, the session moves to the ended state.

The list of valid reason (or reason.condition) values:

  • alternative-session
  • busy
  • cancel
  • connectivity-error
  • decline
  • expired
  • failed-application
  • failed-transport
  • general-error
  • gone
  • incompatible-parameters
  • media-error
  • security-error
  • success
  • timeout
  • unsupported-applications
  • unsupported-transports

See XEP-0166: Jingle Section 7.4 for more information on when each reason condition should be used.

// We succesfully used the session, and are now ending it:
session.end('success');

// Declining a session in favor of an existing one:
session.end({
    condition: 'alternative-session',
    alternativeSession: 'othersessionsid'
});

session.on<SessionAction>(data, cb)

  • data - The jingle payload of a Jingle packet
  • cb - Callback for sending an ack or error to the peer, and allow processing of the next action.

Each session action has a corresponding onX(data, cb) method, where X is the action name in CamelCase without dashes.

The full list of standard session actions:

  • content-accept
  • content-add
  • content-modify
  • content-reject
  • content-remove
  • description-info
  • security-info
  • session-accept
  • session-info
  • session-initiate
  • session-terminate
  • transport-accept
  • transport-info
  • transport-reject
  • transport-replace

See XEP-0166: Jingle Section 7.2 for more information on when each action is used.