libusbK/WinUsb ISO

Module for isochronous transfers. (libusbK & WinUSB) More...

Functions
KUSB_EXP BOOL KUSB_API	IsochK_Init (_out KISOCH_HANDLE *IsochHandle, _in KUSB_HANDLE InterfaceHandle, _in UCHAR PipeId, _in UINT MaxNumberOfPackets, _in PUCHAR TransferBuffer, _in UINT TransferBufferSize)
	Creates a new isochronous transfer handle for libusbK or WinUSB. More...
KUSB_EXP BOOL KUSB_API	IsochK_Free (_in KISOCH_HANDLE IsochHandle)
	Destroys an isochronous transfer handle. More...
KUSB_EXP BOOL KUSB_API	IsochK_SetPacketOffsets (_in KISOCH_HANDLE IsochHandle, _in UINT PacketSize)
	Convenience function for setting the offsets and lengths of all ISO packets of an isochronous transfer handle. More...
KUSB_EXP BOOL KUSB_API	IsochK_SetPacket (_in KISOCH_HANDLE IsochHandle, _in UINT PacketIndex, _in UINT Offset, _in UINT Length, _in UINT Status)
	Convenience function for setting all fields in an isochronous transfer packet. More...
KUSB_EXP BOOL KUSB_API	IsochK_GetPacket (_in KISOCH_HANDLE IsochHandle, _in UINT PacketIndex, _outopt PUINT Offset, _outopt PUINT Length, _outopt PUINT Status)
	Convenience function for getting all fields in an isochronous transfer packet. More...
KUSB_EXP BOOL KUSB_API	IsochK_EnumPackets (_in KISOCH_HANDLE IsochHandle, _in KISOCH_ENUM_PACKETS_CB *EnumPackets, _inopt UINT StartPacketIndex, _inopt PVOID UserState)
	Convenience function for enumerating ISO packets of an isochronous transfer context. More...
KUSB_EXP BOOL KUSB_API	IsochK_CalcPacketInformation (_in BOOL IsHighSpeed, _in PWINUSB_PIPE_INFORMATION_EX PipeInformationEx, _out PKISOCH_PACKET_INFORMATION PacketInformation)
	Helper function for isochronous packet/transfer calculations. More...
KUSB_EXP BOOL KUSB_API	IsochK_GetNumberOfPackets (_in KISOCH_HANDLE IsochHandle, _out PUINT NumberOfPackets)
	Gets the number of iso packets that will be used. More...
KUSB_EXP BOOL KUSB_API	IsochK_SetNumberOfPackets (_in KISOCH_HANDLE IsochHandle, _in UINT NumberOfPackets)
	Sets the number of iso packets that will be used. More...

Detailed Description

Module for isochronous transfers. (libusbK & WinUSB)

Function Documentation

KUSB_EXP BOOL KUSB_API IsochK_Init	(	_out KISOCH_HANDLE *	IsochHandle,
		_in KUSB_HANDLE	InterfaceHandle,
		_in UCHAR	PipeId,
		_in UINT	MaxNumberOfPackets,
		_in PUCHAR	TransferBuffer,
		_in UINT	TransferBufferSize
	)

Creates a new isochronous transfer handle for libusbK or WinUSB.

Parameters

[in]	InterfaceHandle	An initialized usb handle, see UsbK_Init.
[out]	IsochHandle	Receives a new isochronous transfer handle.
[in]	PipeId	The USB pipe ID that this transfer handle will be used with.

Note

The interface containing this pipe must be selected before calling this function.

See /ref UsbK_SelectInterface and /ref UsbK_SetAltInterface.

Parameters

[in]	MaxNumberOfPackets	The number of ISO packet structures allocated to this IsochHandle.
[in]	TransferBuffer	The buffer to use for reading/writing.
[in]	TransferBufferSize	The size (in bytes) of /c TransferBuffer. This is also the number of bytes that will be written/read from the pipe on every call to /ref UsbK_IsochReadPipe and /ref UsbK_IsochWritePipe

Returns

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

IsochK_Init is performs the following tasks in order:

1. Allocates the IsochHandle and the required ISO packet structures.

2. See Also

   IsochK_SetPacketOffsets

Examples:

xfer-iso-asap.c, and xfer-iso.c.

KUSB_EXP BOOL KUSB_API IsochK_Free

(

_in KISOCH_HANDLE

IsochHandle

)

Destroys an isochronous transfer handle.

Parameters

[in]

IsochHandle

A pointer to an isochronous transfer handle created with IsochK_Init.

Returns

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

Examples:

xfer-iso-asap.c, and xfer-iso.c.

KUSB_EXP BOOL KUSB_API IsochK_SetPacketOffsets	(	_in KISOCH_HANDLE	IsochHandle,
		_in UINT	PacketSize
	)

Convenience function for setting the offsets and lengths of all ISO packets of an isochronous transfer handle.

Parameters

[in]	IsochHandle	A pointer to an isochronous transfer handle.
[in]	PacketSize	The packet size used to calculate and assign the absolute data offset for each ISO packet

Returns

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

IsoK_SetPackets updates iso packet offsets so all offset are PacketSize apart. For example:

• The offset of the first (0-index) packet is 0.
• The offset of the second (1-index) packet is PacketSize.
• The offset of the third (2-index) packet is PacketSize*2.

Examples:

xfer-iso-asap.c, and xfer-iso.c.

KUSB_EXP BOOL KUSB_API IsochK_SetPacket	(	_in KISOCH_HANDLE	IsochHandle,
		_in UINT	PacketIndex,
		_in UINT	Offset,
		_in UINT	Length,
		_in UINT	Status
	)

Convenience function for setting all fields in an isochronous transfer packet.

Parameters

[in]	IsochHandle	A pointer to an isochronous transfer handle.
[in]	PacketIndex	The packet index to set.
[out]	Offset	The offset in the transfer buffer that this packet starts at.
[out]	Length	The Length in bytes of this packet.
[out]	Status	The transfer status of this packet. This is set by the driver when the transfer completes.

Remarks

• For Read operations, the length and status are updated by the driver on transfer completion
• For Write operations, WinUSB does not use the ISO packet structures.
• For Write operations, libusbK will update the status field only.

Returns

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

KUSB_EXP BOOL KUSB_API IsochK_GetPacket	(	_in KISOCH_HANDLE	IsochHandle,
		_in UINT	PacketIndex,
		_outopt PUINT	Offset,
		_outopt PUINT	Length,
		_outopt PUINT	Status
	)

Convenience function for getting all fields in an isochronous transfer packet.

Parameters

[in]	IsochHandle	A pointer to an isochronous transfer handle.
[in]	PacketIndex	The packet index to get.
[out]	Offset	The offset in the transfer buffer that this packet starts at.
[out]	Length	The Length in bytes of this packet.
[out]	Status	The transfer status of this packet. This is set by the driver when the transfer completes.

Remarks

• For Read operations, the length and status are updated by the driver on transfer completion
• For Write operations, WinUSB does not use the ISO packet structures.
• For Write operations, libusbK will update the status field only.

Returns

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

Examples:

xfer-iso-asap.c, and xfer-iso.c.

KUSB_EXP BOOL KUSB_API IsochK_EnumPackets	(	_in KISOCH_HANDLE	IsochHandle,
		_in KISOCH_ENUM_PACKETS_CB *	EnumPackets,
		_inopt UINT	StartPacketIndex,
		_inopt PVOID	UserState
	)

Convenience function for enumerating ISO packets of an isochronous transfer context.

Parameters

[in]	IsochHandle	A pointer to an isochronous transfer context.
[in]	EnumPackets	Pointer to a user supplied callback function which is executed for all ISO packets allocated in the isochronous transfer handle or until the user supplied callback function returns FALSE.
[in]	StartPacketIndex	The zero-based ISO packet index to begin enumeration at.
[in]	UserState	A user defined value which is passed as a parameter to the user supplied callback function.

Returns

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

KUSB_EXP BOOL KUSB_API IsochK_CalcPacketInformation	(	_in BOOL	IsHighSpeed,
		_in PWINUSB_PIPE_INFORMATION_EX	PipeInformationEx,
		_out PKISOCH_PACKET_INFORMATION	PacketInformation
	)

Helper function for isochronous packet/transfer calculations.

Parameters

[in]	IsHighSpeed	False if the calculations are for a FullSpeed device. True for HighSpeed and SuperSpeed.
[in]	PipeInformationEx	A pointer to a WINUSB_PIPE_INFORMATION_EX structure the was obtained from UsbK_QueryPipeEx.
[out]	PacketInformation	Pointer to a /ref KISOCH_PACKET_INFORMATION structure that receives the information

Returns

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

Examples:

xfer-iso-asap.c, and xfer-iso.c.

KUSB_EXP BOOL KUSB_API IsochK_GetNumberOfPackets	(	_in KISOCH_HANDLE	IsochHandle,
		_out PUINT	NumberOfPackets
	)

Gets the number of iso packets that will be used.

Parameters

[in]	IsochHandle	A pointer to an isochronous transfer context.
[out]	NumberOfPackets	A pointer to variable that will receive the number of ISO packets.

Returns

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

KUSB_EXP BOOL KUSB_API IsochK_SetNumberOfPackets	(	_in KISOCH_HANDLE	IsochHandle,
		_in UINT	NumberOfPackets
	)

Sets the number of iso packets that will be used.

Parameters

[in]	IsochHandle	A pointer to an isochronous transfer context.
[in]	NumberOfPackets	The number of ISO packets. This value must be less than or equal to the MaxNumberOfIsoPackets that this transfer handle was initialized with. See IsochK_Init

Returns

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