| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <html> |
| <head> |
| <title>Target Communication Framework Services - Streams</title> |
| </head> |
| |
| <body lang='EN-US'> |
| |
| <h1>Target Communication Framework Services - Streams</h1> |
| |
| <ul> |
| <li><a href='#VersionHistory'>Version History</a> |
| <li><a href='#Overview'>Overview</a> |
| <li><a href='#Cmds'>Commands</a> |
| <ul> |
| <li><a href='#CmdSubscribe'>Subscribe</a> |
| <li><a href='#CmdUnsubscribe'>Unsubscribe</a> |
| <li><a href='#CmdRead'>Read</a> |
| <li><a href='#CmdWrite'>Write</a> |
| <li><a href='#CmdEOS'>End of Stream</a> |
| <li><a href='#CmdConnect'>Connect</a> |
| <li><a href='#CmdDisconnect'>Disconnect</a> |
| </ul> |
| <li><a href='#Events'>Events</a> |
| <li><a href='#API'>API</a> |
| </ul> |
| |
| <h1>Streams Service</h1> |
| |
| <h2><a name='VersionHistory'>Version History</a></h2> |
| |
| <table border=1 cellpadding=8> |
| <tr> |
| <th>Version |
| <th>Date |
| <th>Change |
| <tr> |
| <td>0.1 |
| <td>2009-03-17 |
| <td>Initial contribution |
| <tr> |
| <td>0.2 |
| <td>2009-05-18 |
| <td>Added connect command |
| <tr> |
| <td>0.3 |
| <td>2009-08-13 |
| <td>Added "context ID" argument in "created" event |
| </table> |
| |
| <h2><a name='Overview'>Overview</a></h2> |
| |
| <p>Streams service is a generic interface to support streaming of data between host and remote agents. |
| |
| <p>The service supports: |
| <ul> |
| <li> Asynchronous overlapped data streaming: multiple 'read' or 'write' command can be issued at same time, both peers |
| can continue data processing concurrently with data transmission. |
| <li> Multicast: multiple clients can receive data from same stream. |
| <li> Subscription model: clients are required to express interest in particular streams by subscribing for the service. |
| <li> Flow control: peers can throttle data flow of individual streams by delaying 'read' and 'write' commands. |
| </ul> |
| |
| <p> Command and event parameters are encoded as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</p> |
| |
| <p>The service uses standard format for error reports, |
| see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> |
| |
| <h2><a name='Cmds'>Commands</a></h2> |
| |
| <h3><a name='CmdSubscribe'>Subscribe</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • Streams • subscribe • <i><string: stream source type></i> • |
| </font></b></pre> |
| |
| <p>Clients must subscribe for one or more stream source types to be able to send or receive stream data. |
| Stream source type name are defined by other services that use streams to transfer data. |
| For example, <a href='TCF Service - Processes.html'>Processes Service</a> defines |
| "Processes" strem source that represents standard input/output streams. |
| Subscribers receive notifications when a stream of given type is created or disposed. |
| Subscribers are required to respond with 'read' or 'disconnect' commands as necessary.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • |
| </font></b></pre> |
| |
| <p>If no error is reported, the client becomes a subscriber of streams of the given type - until channel is closed or |
| the subscribtion is canceled by <b>unsubscribe</b> command. |
| When new stream is created, each subscriber must decide if it is interested in that particular stream instance. |
| If not interested, subscriber should send 'disconnect' command to allow remote peer to free resources and bandwidth allocated for the stream. |
| If not disconnected, subscriber is required to send 'read' commands as necessary to pump stream data and prevent stream buffer overflow. |
| </p> |
| |
| <h3><a name='CmdUnsubscribe'>Unsubscribe</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • Streams • unsubscribe • <i><string: stream source type></i> • |
| </font></b></pre> |
| |
| <p>Unsubscribe the client from given stream source type.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • |
| </font></b></pre> |
| |
| <h3><a name='CmdRead'>Read</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • Streams • read • <i><string: stream ID></i> • <i><int: size></i> • |
| </font></b></pre> |
| |
| <ul> |
| <li><dt><code><b>stream ID</b></code> <dd>ID of stream that will be read. |
| <li><dt><code><b>size</b></code> <dd>Maximum number of bytes to read. |
| </ul> |
| |
| <p>The command reads data from a stream. If stream buffer is empty, the command will wait until data is available. |
| Remote peer will continue to process other commands while 'read' command is pending. |
| Client can send more 'read' commands without waiting for the first command to complete. |
| Doing that improves communication channel bandwidth utilization. |
| Pending 'read' commands will be executed in same order as issued. |
| Client can delay sending of 'read' command if it is not ready to receive more data, |
| however, delaying for too long can cause stream buffer overflow and lost of data. |
| .</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><string: data></i> • <i><error report></i> • <i><int: lost size></i> • <i><boolean: EOS></i> • |
| </font></b></pre> |
| |
| <ul> |
| <li><dt><code><b>data</b></code> <dd>Data bytes that were read from the stream. By default, data is BASE64 encoded. |
| Peers can send unencoded binary data if both implement ZeroCopy service. |
| <li><dt><code><b>lost size</b></code> <dd>Number of bytes that were lost because of buffer overflow. |
| -1 means unknown number of bytes were lost. if both 'lost_size' and 'data.length' are non-zero then lost bytes are considered |
| located right before read bytes. |
| <li><dt><code><b>EOS</b></code> <dd>true if end of stream was reached. |
| </ul> |
| |
| <h3><a name='CmdWrite'>Write</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • Streams • write • <i><string: stream ID></i> • <i><int: size></i> • <i><string: data></i> • |
| </font></b></pre> |
| |
| <ul> |
| <li><dt><code><b>stream ID</b></code> <dd>ID of stream that will receive the data. |
| <li><dt><code><b>size</b></code> <dd>Number of bytes to write. Length of unencoded <code><b>data</b></code> must match the size. |
| <li><dt><code><b>data</b></code> <dd>Data bytes that will be written to the stream. By default, data is BASE64 encoded. |
| Peers can send unencoded binary data if both implement ZeroCopy service. |
| </ul> |
| |
| <p>The command writes data to a stream. If stream buffer is full, the command will wait until space is available. |
| Remote peer will continue to process other commands while 'write' command is pending. |
| Client can send more 'write' commands without waiting for the first command to complete. |
| Doing that improves communication channel bandwidth utilization. |
| Pending 'write' commands will be executed in same order as issued.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • |
| </font></b></pre> |
| |
| <h3><a name='CmdEOS'>End of Stream</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • Streams • eos • <i><string: stream ID></i> • |
| </font></b></pre> |
| |
| <p>The command sends End Of Stream marker to a stream. No more writing to the stream is allowed after that.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • |
| </font></b></pre> |
| |
| <h3><a name='CmdConnect'>Connect</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • Streams • connect • <i><string: stream ID></i> • |
| </font></b></pre> |
| |
| <p>The command connects client to a stream. Some data might be dropped from the stream by the time "connect" command is executed. |
| Client should be able to re-sync with stream data if it wants to read from such stream. |
| If a client wants to read a stream from the beginning it should use "subscribe" command instead of "connect"</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • |
| </font></b></pre> |
| |
| <h3><a name='CmdDisconnect'>Disconnect</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • Streams • disconnect • <i><string: stream ID></i> • |
| </font></b></pre> |
| |
| <p>The command disconnects client from a stream. Note that disconnect does not destroy the stream, client on other channels can |
| continue reading or writing the stream.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • |
| </font></b></pre> |
| |
| <h2><a name='Events'>Events</a></h2> |
| |
| <p>Streams service sends events when a stream is created or disposed. Only clients with active subscribtion will recceive the events. |
| Clients can change their subscription with <b>subscribe</b> and <b>unsubscribe</b> commands.</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| E • Streams • created • <i><string: stream type></i> • <i><string: stream ID></i> • <i><string: context ID></i> • |
| </font></b></pre> |
| <p> |
| Sent when a new stream is created. |
| "stream type" - source type of the stream. |
| "stream ID" - ID of the stream. |
| "context ID" - a context ID that is associated with the stream, or null. |
| </p> |
| <p> |
| Exact meaning of the context ID depends on stream type. |
| Stream types and context IDs are defined by services that use Streams service to transmit data. |
| </p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| E • Streams • disposed • <i><string: stream type></i> • <i><string: stream ID></i> • |
| </font></b></pre> |
| <p> |
| Sent when a stream is disposed. |
| "stream type" - source type of the stream. |
| "stream ID" - ID of the stream. |
| </p> |
| |
| <h2><a name='API'>API</a></h2> |
| |
| <pre> |
| <font color=#7F0055>public interface</font> IStreams extends IService { |
| |
| <font color=#3F5FBF>/** |
| * Service name. |
| */</font> |
| <font color=#7F0055>static final</font> String NAME = "Streams"; |
| |
| <font color=#3F5FBF>/** |
| * Clients can implement StreamsListener interface to be notified |
| * when a stream is created or disposed. The interface is registered with 'subscribe' command. |
| * |
| * When new stream is created, client must decide if it is interested in that particular stream instance. |
| * If not interested, client should send 'disconnect' command to allow remote peer to free resources and bandwidth. |
| * If not disconnected, client is required to send 'read' commands as necessary to prevent stream buffer overflow. |
| */</font> |
| <font color=#7F0055>interface</font> StreamsListener { |
| |
| <font color=#3F5FBF>/** |
| * Called when a new stream is created. |
| * <font color=#7F9FBF>@param</font> stream_type - source type of the stream. |
| * <font color=#7F9FBF>@param</font> stream_id - ID of the stream. |
| * <font color=#7F9FBF>@param</font> context_id - a context ID that is associated with the stream, or null. |
| * Exact meaning of the context ID depends on stream type. |
| * Stream types and context IDs are defined by services that use Streams service to transmit data. |
| */</font> |
| <font color=#7F0055>void</font> created(String stream_type, String stream_id, String context_id); |
| |
| <font color=#3F5FBF>/** |
| * Called when a stream is disposed. |
| * <font color=#7F9FBF>@param</font> stream_type - source type of the stream. |
| * <font color=#7F9FBF>@param</font> stream_id - ID of the stream. |
| */</font> |
| <font color=#7F0055>void</font> disposed(String stream_type, String stream_id); |
| } |
| |
| <font color=#3F5FBF>/** |
| * Clients must subscribe for one or more stream types to be able to send or receive stream data. |
| * Subscribers receive notifications when a stream of given type is created or disposed. |
| * Subscribers are required to respond with 'read' or 'disconnect' commands as necessary. |
| * <font color=#7F9FBF>@param</font> stream_type - the stream source type. |
| * <font color=#7F9FBF>@param</font> listener - client implementation of StreamsListener interface. |
| * <font color=#7F9FBF>@param</font> done - command result call back object. |
| * <font color=#7F9FBF>@return</font> - pending command handle. |
| */</font> |
| IToken subscribe(String stream_type, StreamsListener listener, DoneSubscribe done); |
| |
| <font color=#3F5FBF>/** |
| * Call back interface for 'subscribe' command. |
| */</font> |
| <font color=#7F0055>interface</font> DoneSubscribe { |
| <font color=#7F0055>void</font> doneSubscribe(IToken token, Exception error); |
| } |
| |
| <font color=#3F5FBF>/** |
| * Unsubscribe the client from given stream source type. |
| * <font color=#7F9FBF>@param</font> stream_type - the stream source type. |
| * <font color=#7F9FBF>@param</font> listener - client implementation of StreamsListener interface. |
| * <font color=#7F9FBF>@param</font> done - command result call back object. |
| * <font color=#7F9FBF>@return</font> - pending command handle. |
| */</font> |
| IToken unsubscribe(String stream_type, StreamsListener listener, DoneUnsubscribe done); |
| |
| <font color=#3F5FBF>/** |
| * Call back interface for 'unsubscribe' command. |
| */</font> |
| <font color=#7F0055>interface</font> DoneUnsubscribe { |
| <font color=#7F0055>void</font> doneUnsubscribe(IToken token, Exception error); |
| } |
| |
| <font color=#3F5FBF>/** |
| * Read data from a stream. If stream buffer is empty, the command will wait until data is available. |
| * Remote peer will continue to process other commands while 'read' command is pending. |
| * Client can send more 'read' commands without waiting for the first command to complete. |
| * Doing that improves communication channel bandwidth utilization. |
| * Pending 'read' commands will be executed in same order as issued. |
| * Client can delay sending of 'read' command if it is not ready to receive more data, |
| * however, delaying for too long can cause stream buffer overflow and lost of data. |
| * <font color=#7F9FBF>@param</font> stream_id - ID of the stream. |
| * <font color=#7F9FBF>@param</font> size - max number of bytes to read. |
| * <font color=#7F9FBF>@param</font> done - command result call back object. |
| * <font color=#7F9FBF>@return</font> - pending command handle. |
| */</font> |
| IToken read(String stream_id, <font color=#7F0055>int</font> size, DoneRead done); |
| |
| <font color=#3F5FBF>/** |
| * Call back interface for 'read' command. |
| */</font> |
| <font color=#7F0055>interface</font> DoneRead { |
| <font color=#3F5FBF>/** |
| * Called when 'read' command is done. |
| * <font color=#7F9FBF>@param</font> token - command handle. |
| * <font color=#7F9FBF>@param</font> error - error object or null. |
| * <font color=#7F9FBF>@param</font> lost_size - number of bytes that were lost because of buffer overflow. |
| * 'lost_size' -1 means unknown number of bytes were lost. |
| * if both 'lost_size' and 'data.length' are non-zero then lost bytes are considered |
| * located right before read bytes. |
| * <font color=#7F9FBF>@param</font> data - bytes read from the stream. |
| * <font color=#7F9FBF>@param</font> eos - true if end of stream was reached. |
| */</font> |
| <font color=#7F0055>void</font> doneRead(IToken token, Exception error, <font color=#7F0055>int</font> lost_size, <font color=#7F0055>byte</font>[] data, boolean eos); |
| } |
| |
| <font color=#3F5FBF>/** |
| * Write data to a stream. If stream buffer is full, the command will wait until space is available. |
| * Remote peer will continue to process other commands while 'write' command is pending. |
| * Client can send more 'write' commands without waiting for the first command to complete. |
| * Doing that improves communication channel bandwidth utilization. |
| * Pending 'write' commands will be executed in same order as issued. |
| * <font color=#7F9FBF>@param</font> stream_id - ID of the stream. |
| * <font color=#7F9FBF>@param</font> buf - buffer that contains stream data. |
| * <font color=#7F9FBF>@param</font> offset - byte offset in the buffer. |
| * <font color=#7F9FBF>@param</font> size - number of bytes to write. |
| * <font color=#7F9FBF>@param</font> done - command result call back object. |
| * <font color=#7F9FBF>@return</font> - pending command handle. |
| */</font> |
| IToken write(String stream_id, <font color=#7F0055>byte</font>[] buf, <font color=#7F0055>int</font> offset, <font color=#7F0055>int</font> size, DoneWrite done); |
| |
| <font color=#3F5FBF>/** |
| * Call back interface for 'write' command. |
| */</font> |
| <font color=#7F0055>interface</font> DoneWrite { |
| <font color=#3F5FBF>/** |
| * Called when 'write' command is done. |
| * <font color=#7F9FBF>@param</font> token - command handle. |
| * <font color=#7F9FBF>@param</font> error - error object or null. |
| */</font> |
| <font color=#7F0055>void</font> doneWrite(IToken token, Exception error); |
| } |
| |
| <font color=#3F5FBF>/** |
| * Send End Of Stream marker to a stream. No more writing to the stream is allowed after that. |
| * <font color=#7F9FBF>@param</font> stream_id - ID of the stream. |
| * <font color=#7F9FBF>@param</font> done - command result call back object. |
| * <font color=#7F9FBF>@return</font> - pending command handle. |
| */</font> |
| IToken eos(String stream_id, DoneEOS done); |
| |
| <font color=#3F5FBF>/** |
| * Call back interface for 'eos' command. |
| */</font> |
| <font color=#7F0055>interface</font> DoneEOS { |
| <font color=#3F5FBF>/** |
| * Called when 'eos' command is done. |
| * <font color=#7F9FBF>@param</font> token - command handle. |
| * <font color=#7F9FBF>@param</font> error - error object or null. |
| */</font> |
| <font color=#7F0055>void</font> doneEOS(IToken token, Exception error); |
| } |
| |
| <font color=#3F5FBF>/** |
| * Disconnect client from a stream. |
| * <font color=#7F9FBF>@param</font> stream_id - ID of the stream. |
| * <font color=#7F9FBF>@param</font> done - command result call back object. |
| * <font color=#7F9FBF>@return</font> - pending command handle. |
| */</font> |
| IToken disconnect(String stream_id, DoneDisconnect done); |
| |
| <font color=#3F5FBF>/** |
| * Call back interface for 'disconnect' command. |
| */</font> |
| <font color=#7F0055>interface</font> DoneDisconnect { |
| <font color=#3F5FBF>/** |
| * Called when 'disconnect' command is done. |
| * <font color=#7F9FBF>@param</font> token - command handle. |
| * <font color=#7F9FBF>@param</font> error - error object or null. |
| */</font> |
| <font color=#7F0055>void</font> doneDisconnect(IToken token, Exception error); |
| } |
| } |
| </pre> |
| |
| </body> |
| </html> |