API.md

<title>RTWebSocket API Reference</title>

RTWebSocket API Reference

• RTWebSocket
• SendFlow
• RecvFlow
• WriteReceipt

RTWebSocket

<script src="rtws.js"></script>

[Constructor (DOMString uri)]
interface RTWebSocket {
    // constructor argument:
    //    uri: the WebSocket URI (ws://... or wss://...) to which to connect.

    typedef (ArrayBuffer or ArrayBufferView or DOMString or byte[]) Data_t;

    const unsigned long PRI_LOWEST  = 0;
    const unsigned long PRI_HIGHEST = 7;

    const unsigned long PRI_BACKGROUND     = PRI_LOWEST;
    const unsigned long PRI_BULK           = 1;
    const unsigned long PRI_DATA           = 2;
    const unsigned long PRI_ROUTINE        = 3;
    const unsigned long PRI_PRIORITY       = 4;
    const unsigned long PRI_IMMEDIATE      = 5;
    const unsigned long PRI_FLASH          = 6;
    const unsigned long PRI_FLASH_OVERRIDE = PRI_HIGHEST;

    SendFlow openFlow (Data_t metadata, optional unsigned long priority);
    // open a new sending flow with metadata having priority (default: PRI_ROUTINE).
    // throws a new Error if this is not open, otherwise answers the new flow.

    void close ();
    // close this RTWebSocket and the the underlying WebSocket. all open sending
    // flows will receive onexception. all open receiving flows will receive oncomplete.

    readonly attribute boolean isOpen;
    // true if this RTWebSocket is open, false otherwise.

    readonly attribute double rtt;
    // the smoothed round trip time of this connection.

    readonly attribute double baseRTT;
    // the minimum of all measured round trip times over the last 5 minutes.

    readonly attribute unsigned long bytesInflight;
    // the number of bytes currently transmitted to the other side
    // that have not yet been acknowledged.

    callback OnRecvFlowCallback = void (RecvFlow recvFlow);
    attribute OnRecvFlowCallback? onrecvflow;
    // if set, this callback is called when a new receiving flow (that is not an
    // associated return flow on a sending flow) is started. recvFlow must be accepted
    // during this callback or it will be rejected automatically.

    callback OnRTWSNotificationCallback = void (RTWebSocket rtws);

    attribute OnRTWSNotificationCallback? onopen;
    // if set, called when the underlying WebSocket connects to the far end.

    attribute OnRTWSNotificationCallback? onclose;
    // if set, called when this RTWebSocket is closed, either as a result of calling
    // the close() method, a protocol error, or the underlying WebSocket closing.

    static double getCurrentTime();
    // answer the current time used by all RTWebSockets, measured in seconds since
    // an arbitrary epoch. WriteReceipt deadlines are in this timescale.
};

SendFlow

interface SendFlow {
    WriteReceipt write (RTWebSocket.Data_t data, optional double startWithin, optional double endWithin, optional boolean capture);
    // queue data to send to the receiver. if data is a DOMString, it is encoded
    // to UTF-8, otherwise data is converted to a Uint8Array. if capture is true,
    // data is allowed to be captured to avoid a copy; otherwise a copy will be made.
    // in practice data will only be captured if it is a Uint8Array.
    // startWithin is the time in seconds after queuing by which transmission of this message
    // should start before the message is abandoned. default Infinity.
    // endWithin is the time in seconds after queuing by which transmission of this message,
    // if started, should complete before the message is abandoned. default Infinity.
    // answer a new WriteReceipt with which to track and control
    // delivery of this message.
    // throws a new Error if this flow is closed.

    void close ();
    // close this flow normally, completing it.

    void abandonQueuedMessages (optional double age, optional boolean onlyUnstarted);
    // abandon any queued messages at least as old as age seconds (default: 0).
    // if onlyUnstarted is true (default false), do not abandon a queued message
    // if it has started being sent.

    attribute unsigned long priority;
    // the priority of this flow. higher priority flows' data are sent before those of lower
    // priority flows, subject to the receivers' buffer advertisements. priority is clamped
    // between PRI_LOWEST and PRI_HIGHEST inclusive.

    attribute unsigned long sndbuf;
    // the advisory maximum bufferLength below which this flow is considered writable
    // (default 65536 bytes). data may still be written to the flow, memory permitting,
    // even if it is not writable.

    readonly attribute unsigned long bufferLength;
    // the count of the lengths, in bytes, of all queued messages that have not been
    // completely sent (or abandoned and removed from the queue).

    readonly attribute unsigned long rcvbuf;
    // the last received receive window advertisement.

    readonly attribute boolean writable;
    // true if this flow is open and bufferLength is less than sndbuf, false otherwise.

    readonly attribute boolean isOpen;
    // true if this flow is open, false otherwise.

    readonly attribute double unsentAge;
    // the age, in seconds, of the oldest unsent message in the transmission queue.

    void notifyWhenWritable ();
    // begin calling onwritable() when this flow is writable.

    callback OnWritableCallback boolean (SendFlow sendFlow);
    attribute OnWritableCallback? onwritable;
    // if set, called after notifyWritable() has been called when this
    // flow is writable, until this callback does not return true.

    callback OnExceptionCallback void (SendFlow sendFlow, (unsigned long or undefined) code, (DOMString or undefined) description);
    attribute OnExceptionCallback onexception;
    // called if this flow is still open and the receiver closed its end. if the
    // receiver sent a code and description, those are provided. callbacks should
    // be prepared for code or description to be undefined.
    
    callback OnRecvFlowCallback = void (RecvFlow recvFlow);
    attribute OnRecvFlowCallback? onrecvflow;
    // if set, this callback is called when a new receiving flow (that is an
    // associated return flow to this sending flow) is started. recvFlow must
    // be accepted during this callback or it will be rejected automatically.
};

RecvFlow

interface RecvFlow {
    void accept ();
    // accept this new receiving flow. a new incoming receiving flow that is not
    // accepted in the onrecvflow callback is automatically rejected.

    SendFlow openReturnFlow (RTWebSocket.Data_t metadata, optional unsigned long pri);
    // open a new sending flow with metadata having priority (default: PRI_ROUTINE) associated
    // in return to this receiving flow.
    // throws a new Error if this RecvFlow is not open, otherwise answers the new flow.

    void close (optional unsigned long code, optional DOMString description);
    // reject and close this receiving flow, sending an exception back to the
    // sender with code and description, if set.

    readonly attribute Uint8Array metadata;
    // this flow's metadata set by the sender.

    readonly attribute DOMString textMetadata;
    // convenience attribute, this flow's metadata set by the sender, decoded if possible from UTF-8.

    readonly attribute boolean isOpen;
    // true if this flow is open, false otherwise.

    attribute unsigned long rcvbuf;
    // the maximum amount of data, in bytes, that can be inflight (unacknowledged) from
    // the sender. if paused is true, also the maximum amount of data that can be held for
    // delivery in the receive queue.

    readonly attribute unsigned long advertisement;
    // the receive window that would be sent to the sender at this moment.

    readonly attribute unsigned long bufferLength;
    // the number of bytes of messages in the receive queue.

    attribute boolean paused;
    // if true, onmessage will not be called and complete messages will be held
    // in the receive queue.  if false (default), messages will be delivered
    // as soon as they are completely received.

    readonly attribute SendFlow associatedSendFlow;
    // if set, indicates the SendFlow on which this flow was accepted in its
    // onrecvflow callback.

    attribute DOMString mode;
    // either "binary" or "text" (default: "binary"), indicates the format
    // in which messages should be delivered to onmessage. if set to "text",
    // the message will be decoded as UTF-8 and delivered as a DOMString,
    // otherwise it will be delivered as a Uint8Array.

    callback OnMessageCallback void (RecvFlow recvFlow, (Uint8Array or DOMString) message, unsigned long messageNumber);
    attribute OnMessageCallback? onmessage;
    // if set, called when a message is received. recvFlow is the flow on which this
    // message was received. the type of message depends on mode. messageNumber is the
    // ordinal number of this message according to the sender, including any abandoned
    // messages that were not delivered. messageNumber can be used to detect abandoned
    // messages by paying attention to gaps in sequence.

    callback OnCompleteCallback void (RecvFlow recvFlow);
    attribute OnCompleteCallback oncomplete;
    // if set, called when this flow is complete.
};

WriteReceipt

interface WriteReceipt {
    void abandon ();
    // abandon this message if not sent already.

    attribute double startBy;
    attribute double endBy;
    // the deadlines for this message by which transmission must start or must
    // complete, respectively, in the timescale of RTWebSocket.getCurrentTime().
    // changing startBy has no effect if transmission has already started.

    attribute WriteReceipt? parent;
    // If set, this message will be abandoned if the parent is abandoned. Useful for
    // chaining depdendent messages together (such as a predictive-coded video frame that
    // can't be decoded if the previous one is not received).

    readonly attribute boolean abandoned;
    // true if this message is abandoned (either by timing out or by being manually
    // abandoned), false if it was or may still be sent.

    readonly attribute boolean sent;
    // true if this message was completely sent, false otherwise (for example,
    // it is still queued or was abandoned).

    readonly attribute boolean started;
    // true if any part of this message has been sent, otherwise false.

    readonly attribute double age;
    // the duration in seconds since this message was queued.

    readonly attribute unsigned long messageNumber;
    // the ordinal number of this message.

    callback WriteReceiptCallback void (WriteReceipt receipt);

    attribute WriteReceiptCallback? onsent;
    // if set, called when this message has been completely sent.

    attribute WriteReceiptCallback? onabandoned;
    // if set, called when this message is abandoned before being completely sent.
};