Module for thread assisted USB pipe streaming transfers. More...

Data Structures
struct	KSTM_XFER_CONTEXT
	Stream transfer context structure. More...

struct	KSTM_INFO
	Stream information structure. More...

struct	KSTM_CALLBACK
	Stream callback structure. More...

Typedefs
typedef KSTM_XFER_CONTEXT *	PKSTM_XFER_CONTEXT
	Pointer to a KSTM_XFER_CONTEXT structure.

typedef KSTM_INFO *	PKSTM_INFO
	Pointer to a KSTM_INFO structure.

typedef KSTM_CALLBACK *	PKSTM_CALLBACK
	Pointer to a KSTM_CALLBACK structure.

Enumerations
enum	KSTM_FLAG { KSTM_FLAG_NONE = 0L }
	Stream config flags. More...

enum	KSTM_COMPLETE_RESULT { KSTM_COMPLETE_RESULT_VALID = 0L, KSTM_COMPLETE_RESULT_INVALID }
	Stream config flags. More...

Functions
KUSB_EXP BOOL KUSB_API	StmK_Init (_out KSTM_HANDLE *StreamHandle, _in KUSB_HANDLE UsbHandle, _in UCHAR PipeID, _in INT MaxTransferSize, _in INT MaxPendingTransfers, _in INT MaxPendingIO, _inopt PKSTM_CALLBACK Callbacks, _inopt KSTM_FLAG Flags)
	Initializes a new uni-directional pipe stream. More...

KUSB_EXP BOOL KUSB_API	StmK_Free (_in KSTM_HANDLE StreamHandle)
	Frees resources allocated by a stream handle. More...

KUSB_EXP BOOL KUSB_API	StmK_Start (_in KSTM_HANDLE StreamHandle)
	Starts the internal stream thread. More...

KUSB_EXP BOOL KUSB_API	StmK_Stop (_in KSTM_HANDLE StreamHandle, _in INT TimeoutCancelMS)
	Stops the internal stream thread. More...

KUSB_EXP BOOL KUSB_API	StmK_Read (_in KSTM_HANDLE StreamHandle, _out PUCHAR Buffer, _in INT Offset, _in INT Length, _out PUINT TransferredLength)
	Reads data from the stream buffer. More...

KUSB_EXP BOOL KUSB_API	StmK_Write (_in KSTM_HANDLE StreamHandle, _in PUCHAR Buffer, _in INT Offset, _in INT Length, _out PUINT TransferredLength)
	Writes data to the stream buffer. More...

INT KUSB_API	KSTM_ERROR_CB (_in PKSTM_INFO StreamInfo, _in PKSTM_XFER_CONTEXT XferContext, _in INT XferContextIndex, _in INT ErrorCode)
	Function definition for an optional user-defined callback; executed when a transfer error occurs.

INT KUSB_API	KSTM_SUBMIT_CB (_in PKSTM_INFO StreamInfo, _in PKSTM_XFER_CONTEXT XferContext, _in INT XferContextIndex, _in LPOVERLAPPED Overlapped)
	Function definition for an optional user-defined callback; executed to submit a transfer.

INT KUSB_API	KSTM_STARTED_CB (_in PKSTM_INFO StreamInfo, _in PKSTM_XFER_CONTEXT XferContext, _in INT XferContextIndex)
	Function definition for an optional user-defined callback; executed for each transfer context when the stream is started with StmK_Start.

INT KUSB_API	KSTM_STOPPED_CB (_in PKSTM_INFO StreamInfo, _in PKSTM_XFER_CONTEXT XferContext, _in INT XferContextIndex)
	Function definition for an optional user-defined callback; executed for each transfer context when the stream is stopped with StmK_Stop.

INT KUSB_API	KSTM_COMPLETE_CB (_in PKSTM_INFO StreamInfo, _in PKSTM_XFER_CONTEXT XferContext, _in INT XferContextIndex, _in INT ErrorCode)
	Function definition for an optional user-defined callback; executed when a valid transfer completes.

KSTM_COMPLETE_RESULT KUSB_API	KSTM_BEFORE_COMPLETE_CB (_in PKSTM_INFO StreamInfo, _in PKSTM_XFER_CONTEXT XferContext, _in INT XferContextIndex, _ref PINT ErrorCode)
	Function definition for an optional user-defined callback; executed immediately after a transfer completes. More...

Detailed Description

Module for thread assisted USB pipe streaming transfers.

Enumeration Type Documentation

enum KSTM_FLAG

Stream config flags.

Attention: Currently not used.

Enumerator
KSTM_FLAG_NONE	None.

enum KSTM_COMPLETE_RESULT

Stream config flags.

Attention: Currently not used.

Enumerator
KSTM_COMPLETE_RESULT_VALID	Valid.
KSTM_COMPLETE_RESULT_INVALID	Invalid.

Function Documentation

KUSB_EXP BOOL KUSB_API StmK_Init	(	_out KSTM_HANDLE *	StreamHandle,
		_in KUSB_HANDLE	UsbHandle,
		_in UCHAR	PipeID,
		_in INT	MaxTransferSize,
		_in INT	MaxPendingTransfers,
		_in INT	MaxPendingIO,
		_inopt PKSTM_CALLBACK	Callbacks,
		_inopt KSTM_FLAG	Flags
	)

Initializes a new uni-directional pipe stream.

Parameters

[out]	StreamHandle	On success, receives the new stream handle.
[in]	UsbHandle	Usb handle to associate with this stream.
[in]	PipeID	Endpoint address of USB pipe to associate with this stream.
[in]	MaxTransferSize	Maximum number of bytes transferred at once. Larger transfers committed with the stream read/write functions are automatically split into multiple smaller chunks.
[in]	MaxPendingTransfers	Maximum number of transfers allowed to be outstanding and the total number of transfer contexts that are allocated to the stream.
[in]	MaxPendingIO	Maximum number of I/O requests the internal stream thread is allowed to have submit at any given time. (Pending I/O)
[in]	Callbacks	Optional user callback functions. If specified, these callback functions will be executed in real time (from within the context of the internal stream thread) as transfers go through the various states.
[in]	Flags	Additional stream flags.

Returns: On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

: When a stream is initialized, it validates input parameters and allocates the required memory for the transfer context array and transfer lists from a private memory heap. The stream is not started and no I/O requests are sent to the device until StmK_Start is executed.

Examples:: xfer-stream.c.

KUSB_EXP BOOL KUSB_API StmK_Free ( _in KSTM_HANDLE StreamHandle )

Frees resources allocated by a stream handle.

Parameters

[in] StreamHandle The stream handle to free.

Returns: TRUE.

If the stream is currently started it is automatically stopped before its resources are freed.

Examples:: xfer-stream.c.

KUSB_EXP BOOL KUSB_API StmK_Start ( _in KSTM_HANDLE StreamHandle )

Starts the internal stream thread.

Parameters

[in] StreamHandle The stream to start. A stream handle is created with StmK_Init.

Returns: On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

: When a stream is started, an internal thread is created for managing pipe I/O operations. If a KSTM_CALLBACK::Started callback function is assgined, it is executed for each transfer context. (MaxPendingTransfers) See StmK_Init.

Examples:: xfer-stream.c.

KUSB_EXP BOOL KUSB_API StmK_Stop	(	_in KSTM_HANDLE	StreamHandle,
		_in INT	TimeoutCancelMS
	)

Stops the internal stream thread.

Parameters

[in]	StreamHandle	The stream to stop.
[in]	TimeoutCancelMS	Number of milliseconds the internal stream thread should wait for pending I/O to complete before cancelling all pending requests.

Returns: On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

Examples:: xfer-stream.c.

KUSB_EXP BOOL KUSB_API StmK_Read	(	_in KSTM_HANDLE	StreamHandle,
		_out PUCHAR	Buffer,
		_in INT	Offset,
		_in INT	Length,
		_out PUINT	TransferredLength
	)

Reads data from the stream buffer.

Parameters

[in]	StreamHandle	The stream to read.
[out]	Buffer	A caller-allocated buffer that receives the data that is read.
[in]	Offset	Read start offset of `Buffer`.
[in]	Length	Size of `Buffer`.
[out]	TransferredLength	On success, receives the actual number of bytes that were copied into `Buffer`.

Returns: On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

Read Stream Operations:
1. The internal stream thread will always try and keep reads pending as specified by MaxPendingIO in StmK_Init.
2. As the stream submits transfers, it increments the PendingIO and PendingTransfer counts. As it completes transfers, it decrements the PendingIO count. As the user processes transfers with StmK_Read, it decrements the PendingTransfer count and release control of the transfer context back to the stream where it is re-used.
3. When the pending I/O count reaches MaxPendingIO, the stream completes the oldest PendingTransfer and moves it into a FIFO complete where it awaits user processing via the StmK_Read function.
4. If the stream has not exhausted its MaxPendingTransfers count, another read request is submitted immediately to satisfy MaxPendingIO.

Examples:: xfer-stream.c.

KUSB_EXP BOOL KUSB_API StmK_Write	(	_in KSTM_HANDLE	StreamHandle,
		_in PUCHAR	Buffer,
		_in INT	Offset,
		_in INT	Length,
		_out PUINT	TransferredLength
	)

Writes data to the stream buffer.

Parameters

[in]	StreamHandle	The stream to write.
[in]	Buffer	A caller-allocated buffer the data is written from.
[in]	Offset	Write start offset of `Buffer`.
[in]	Length	Number of bytes to copy into the stream buffer.
[out]	TransferredLength	On success, receives the actual number of bytes that were copied into the stream buffer.

Returns: On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

Write Stream Operations:
1. The internal stream thread will always try and exhaust all pending transfers submitted by the user via StmK_Write.
2. As the user submits transfers via StmK_Write, the PendingTransfer count is inceremented and transfers are added to a queued FIFO list where they await processing by the internal stream thread.
3. While the queued FIFO list is not empty and PendingIO count is less than MaxPendingIO, The PendingIO count increments and the request is sent to the device.
4. When a transfer completes, the internal pending I/O count is decremented and the transfers is moved back into the idle list where it can be reused again by subsequent StmK_Write requests.

Examples:: xfer-stream.c.

KSTM_COMPLETE_RESULT KUSB_API KSTM_BEFORE_COMPLETE_CB	(	_in PKSTM_INFO	StreamInfo,
		_in PKSTM_XFER_CONTEXT	XferContext,
		_in INT	XferContextIndex,
		_ref PINT	ErrorCode
	)

Function definition for an optional user-defined callback; executed immediately after a transfer completes.

This callback function allows the user to accept or reject the transfer:

IN (Read, DeviceToHost) endpoints.
- KSTM_COMPLETE_RESULT_VALID Continue normal processing; add the transfer to the internal complete list and make it available to StmK_Read.
- KSTM_COMPLETE_RESULT_INVALID Ignore this transfer.
OUT (Write, HostToDevice) endpoints.
- KSTM_COMPLETE_RESULT_VALID Continue normal processing; add the transfer to the internal complete list and make it available subsequent StmK_Write requests.
- KSTM_COMPLETE_RESULT_INVALID Return this transfer to the internal queued list for automatic resubmission to the device.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation