User's Manual

98 Voice API Programming Guide — June 2005
Recording and Playback
8.10.3 Implementing Streaming to Board
Perform the following steps to implement streaming to board in your application:
Note: These steps do not represent every task that must be performed to create a working application but
are intended as general guidelines for implementing streaming to board.
1. Decide on the size of the circular stream buffer. This value is used as input to the
dx_OpenStreamBuffer( ) function. To determine the circular stream buffer size, see
Section 8.10.4, “Streaming to Board Hints and Tips”, on page 98.
2. Based on the circular stream buffer and the bulk queue buffer size, decide on values for the
high and low water marks for the circular stream buffer. To determine high and low water mark
values, see Section 8.10.4, “Streaming to Board Hints and Tips”, on page 98.
3. Initialize and create a circular stream buffer using dx_OpenStreamBuffer( ).
4. Set the high and low water marks using dx_SetWaterMark( ).
5. Start the play using dx_playiottdata( ) or dx_play( ) in asynchronous mode with the io_type
field in DX_IOTT data structure set to IO_STREAM.
6. Put data in the circular stream buffer using dx_PutStreamData( ).
7. Wait for events.
The TDX_LOWWATER event is generated every time data in the buffer falls below the low
water mark. The TDX_HIGHWATER event is generated every time data in the buffer is above
the high water mark. The application receives TDX_LOWWATER and TDX_HIGHWATER
events regardless of whether or not dx_SetWaterMark( ) is used in your application. These
events are generated when there is a play operation with this buffer and are reported on the
device that is performing the play. If there is no active play, the application will not receive any
of these events.
TDX_PLAY indicates that play has completed.
8. When all files are played, issue dx_CloseStreamBuffer( ).
8.10.4 Streaming to Board Hints and Tips
Consider the following usage guidelines when implementing streaming to board in your
application:
• You can create as many circular stream buffers as needed on a channel; however, you are
limited by the amount of memory on the system. You can use more than one circular stream
buffer per play via the DX_IOTT structure. In this case, specify that the data ends in one buffer
using the STREAM_EOD flag so that the play can process the next DX_IOTT structure in the
chain.
• In general, the larger you define the circular stream buffer size, the better. Factors to take into
consideration include the average input file size, the amount of memory on your system, the
total number of channels in your system, and so on. Having an optimal circular stream buffer
size results in the high and low water marks being reached less often. In a well-tuned system,
the high and low water marks should rarely be reached.
• When adjusting circular stream buffer sizes, be aware that you must also adjust the high and
low water marks accordingly.