1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
|
<!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>BASE64 encoded bytes that were read from the stream.
<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 <code><b>data</b></code> must match the size.
<li><dt><code><b>data</b></code> <dd>BASE64 encoded bytes that will be written to the stream.
</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>
|
