Skip to content

Latest commit

 

History

History
257 lines (199 loc) · 10 KB

Reference.md

File metadata and controls

257 lines (199 loc) · 10 KB
Raw

1.7.x API Reference

Jingle.Jingle

new Jingle(config)

Creates a new Jingle session jingle with the following configuration options:

var Jingle = require('jingle');
var BaseSession = require('jingle-session');

var jingle = new Jingle({
    jid: '[email protected]',
    iceServers: [
        {url: 'stun:stun.mydomain.example'}
    ],
    prepareSession: function (opts) {
        return new Session(opts);
    }
});

prepareSession(opts, [req])

  • 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.
    • applicationTypes - An array of content application names.
    • transportTypes - An array of content transport names.
  • req - The original session initiation request, in case you need more information than provided in opts for selecting a session type.

Returns a Session instance of your choosing or a falsy value if you wish to fallback to a BaseSession instance (the jingle-session module).

The prepareSession() function allows you to control what type of session is created for a given incoming session request. If prepareSession() is not included when creating the session jingle, or if your prepareSession() function does not return a session, a BaseSession will be created for you.

new Jingle.Jingle({
    ...,
    prepareSession: function (opts) {
        // Check if the session request includes "stub" content, and if so
        // create a custom StubSession.
        if (opts.applicationTypes.indexOf('stub') >= 0) {
            return new StubSession(opts);
        }
    }
});

performTieBreak(existingSession, req)

  • existingSession - A Session object.
  • req - The incoming session initiation request that triggered the tie break check.

A tie break check is performed when receiving a session-initiate if:

  • A session in the pending state already exists for the peer.
  • The existing pending session ID is greater than the one used by the incoming session request

The performTieBreak() method allows you to control whether or not the session request is declined to resolve the tie. In some applications, you may wish to allow two simultaneous sessions (e.g., multiple uni-directional video sessions). In others you may wish to allow the tie break to force the use of a single session (e.g., a bidirectional video session).

Returning true will trigger the tie break and deny the request; returning false will allow the session request to proceed.

Jingle Methods

jingle.addICEServer(info)

  • info - Either a {String} of the URI of the ICE server, or an object:
    • url - The URI of the ICE server
    • username - The username for accessing the ICE server
    • credential - The password or other shared secret to authenticate the username with the ICE server

Saves the URI and any required credentials for an ICE STUN/TURN server for use by future sessions.

jingle.addICEServer('stun:stun.l.google.com:19302');
jingle.addICEServer({
    url: 'stun:stun.mydomain.example',
    username: 'ad24lwra',
    credential: '234lamvnerl13k40au35oahfadad'
});

jingle.addSession(session)

  • session - A {BaseSession} (or ideally, a subclass of BaseSession) instance

Calling this method allows the Jingle instance to begin tracking the session and route actions to it.

For incoming sessions, this step is already handled for you. Using this method is only necessary for when you are initiating a session yourself.

Relevant events generated by session will now be proxied through the Jingle instance.

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

jingle.addSession(session);

jingle.endAllSessions([reason], [silent])

  • reason - Why the sessions are being ended (see session.end() for the list of available reasons).
  • silent - If true, then session terminating messages will not be generated to be sent to the peers. This is only intended for cases where you've lost network connection and would not be able to send those messages anyway.
// End all sessions because we're about to go offline
jingle.endAllSessions('gone');

jingle.endPeerSessions(peer, [reason], [silent])

  • peer - Either the {JID} or {String} value of the peer's ID.
  • reason - Why the session is being ended (see session.end() for the list of available reasons).
  • 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.
// End sessions with a peer because we've successfully finished them.
jingle.endPeerSessions('[email protected]', 'success');

jingle.process(packet)

  • packet - An object representing an action to process & apply to a session.
    • from - The ID for the peer which sent the packet
    • to - Optional, this should be the ID for the session jingle
    • id - ID of the packet
    • type - One of: set, result, or error
    • jingle - This is the data that will be forwarded to the matching session
      • sid - The session ID
      • action - The action for the session to perform, using the data in jingle
    • error - Optional error object with a condition:
      • condition - The type of error
      • jingleCondition - A Jingle specific error condition, if applicable

The .process() method is the heart of how the Jingle module works. It verifies that the incoming packet is valid (e.g. preventing session hijacking or handling tie-breaking conditions), and then routes the packet to the matching session for further, session-type specific processing.

jingle.process({
    to: '[email protected]',
    from: '[email protected]',
    id: '123',
    type: 'set',
    jingle: {
        sid: 'sidABC',
        action: 'session-initiate',
        contents: [
            {
                application: {applicationType: 'stub'},
                transport: {transportType: 'stub'}
            }
        ]
    }
});

Jingle Events

incoming

The incoming event is triggered when a session initiation request is received from a peer.

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

outgoing

The outgoing event is triggered when a tracked session has its .start() method called.

jingle.on('outgoing', function (session) {
    renderOutgoingSessionUI(session);
});

send

The send event provides a Jingle packet suitable for sending to the peer. Each packet includes some routing information, an optional Jingle payload, and an optional error payload.

jingle.on('send', function (data) {
    realtimeConnection.send(data, function (err, result) {
        // We want to process both successful acks, and errors
        var resp = err || result;

        // Ensure that we have the sid included in the ack so
        // that it routes properly to the correct session.
        resp.jingle = resp.jingle || {};
        resp.jingle.sid = data.jingle.sid;

        // Process the ack response
        jingle.process(resp);
    });
});

terminated

The terminated event is triggered when a session has been ended, either locally via the session's .end() method, or from a session terminate action from the peer.

jingle.on('terminated', function (session) {
    closeSessionUI();
});

log:[error|debug|info]

Log messages can be listened for with the log:error, log:debug, and log:info events.

jingle.on('log:*', function (logLevel, msg) {
    console.log(logLevel, msg);
});