libusbK 
3.0
Library Documentation
© 2011-2021 Travis Lee Robinson. All rights reserved.
libusbK Advanced ISO

Module for advanced isochronous transfers. (libusbK only) More...

Data Structures

struct  KISO_PACKET
 Structure describing an isochronous transfer packet for libusbK. More...
 
struct  KISO_WUSB_PACKET
 Structure describing an isochronous transfer packet for winusb. More...
 
struct  KISO_CONTEXT
 Structure describing a user defined isochronous transfer. More...
 
struct  KISOCH_PACKET_INFORMATION
 Structure describing additional information about how an isochronous pipe transfers data. More...
 

Typedefs

typedef BOOL KUSB_API KISO_ENUM_PACKETS_CB (_in UINT PacketIndex, _in PKISO_PACKET IsoPacket, _in PVOID UserState)
 Callback function typedef for IsoK_EnumPackets.
 
typedef BOOL KUSB_API KISOCH_ENUM_PACKETS_CB (_in UINT PacketIndex, _ref PUINT Offset, _ref PUINT Length, _ref PUINT Status, _in PVOID UserState)
 Callback function typedef for IsochK_EnumPackets.
 
typedef KISO_PACKETPKISO_PACKET
 pointer to a KISO_PACKET structure
 
typedef KISO_WUSB_PACKETPKISO_WUSB_PACKET
 pointer to a KISO_PACKET structure
 
typedef KISO_CONTEXTPKISO_CONTEXT
 pointer to a KISO_CONTEXT structure
 
typedef KISOCH_PACKET_INFORMATIONPKISOCH_PACKET_INFORMATION
 pointer to a KISOCH_PACKET_INFORMATION structure
 

Enumerations

enum  KISO_FLAG { , KISO_FLAG_SET_START_FRAME = 0x00000001 }
 Additional ISO transfer flags. More...
 

Functions

KUSB_EXP BOOL KUSB_API IsoK_Init (_out PKISO_CONTEXT *IsoContext, _in INT NumberOfPackets, _inopt INT StartFrame)
 Creates a new isochronous transfer context for libusbK only. More...
 
KUSB_EXP BOOL KUSB_API IsoK_Free (_in PKISO_CONTEXT IsoContext)
 Destroys an isochronous transfer context. More...
 
KUSB_EXP BOOL KUSB_API IsoK_SetPackets (_in PKISO_CONTEXT IsoContext, _in INT PacketSize)
 Convenience function for setting the offset of all ISO packets of an isochronous transfer context. More...
 
KUSB_EXP BOOL KUSB_API IsoK_SetPacket (_in PKISO_CONTEXT IsoContext, _in INT PacketIndex, _in PKISO_PACKET IsoPacket)
 Convenience function for setting all fields of a KISO_PACKET. More...
 
KUSB_EXP BOOL KUSB_API IsoK_GetPacket (_in PKISO_CONTEXT IsoContext, _in INT PacketIndex, _out PKISO_PACKET IsoPacket)
 Convenience function for getting all fields of a KISO_PACKET. More...
 
KUSB_EXP BOOL KUSB_API IsoK_EnumPackets (_in PKISO_CONTEXT IsoContext, _in KISO_ENUM_PACKETS_CB *EnumPackets, _inopt INT StartPacketIndex, _inopt PVOID UserState)
 Convenience function for enumerating ISO packets of an isochronous transfer context. More...
 
KUSB_EXP BOOL KUSB_API IsoK_ReUse (_ref PKISO_CONTEXT IsoContext)
 Convenience function for re-using an isochronous transfer context in a subsequent request. More...
 

Detailed Description

Module for advanced isochronous transfers. (libusbK only)

Enumeration Type Documentation

enum KISO_FLAG

Additional ISO transfer flags.

Enumerator
KISO_FLAG_SET_START_FRAME 

Do not start the transfer immediately, instead use KISO_CONTEXT::StartFrame.

By default, isochronous transfers start on the next frame and KISO_CONTEXT::StartFrame is ignored. If this flag is specified, the transfer is postponed until the current usb frame number equals that specified by KISO_CONTEXT::StartFrame.

Under certain circumstances, the driver can specify 0 for KISO_CONTEXT::StartFrame, and the bus driver will begin the transaction in the next available frame.

Specifing 0 for KISO_CONTEXT::StartFrame (start transfer ASAP) is restricted to the first transaction on a newly opened or reset pipe. Furthermore, the USB stack contains a bug in Microsoft Windows Server 2003 and Windows XP that limits the use of this to an isochronous context with 255 or fewer packets.

For more information about resetting pipes, see UsbK_ResetPipe.

Function Documentation

KUSB_EXP BOOL KUSB_API IsoK_Init ( _out PKISO_CONTEXT IsoContext,
_in INT  NumberOfPackets,
_inopt INT  StartFrame 
)

Creates a new isochronous transfer context for libusbK only.

Parameters
[out]IsoContextReceives a new isochronous transfer context.
[in]NumberOfPacketsThe number of KISO_PACKET structures allocated to IsoContext. Assigned to KISO_CONTEXT::NumberOfPackets. The KISO_CONTEXT::NumberOfPackets field is assignable by IsoK_Init only and must not be changed by the user.
[in]StartFrameThe USB frame number this request must start on (or 0 for ASAP) and assigned to KISO_CONTEXT::StartFrame. The KISO_CONTEXT::StartFrame may be chamged by the user in subsequent request. For more information, see KISO_CONTEXT::StartFrame.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

IsoK_Init is performs the following tasks in order:

  1. Allocates the IsoContext and the required KISO_PACKET structures.
  2. Zero-initializes all ISO context memory.
  3. Assigns NumberOfPackets, PipeID, and StartFrame to IsoContext.
KUSB_EXP BOOL KUSB_API IsoK_Free ( _in PKISO_CONTEXT  IsoContext)

Destroys an isochronous transfer context.

Parameters
[in]IsoContextA pointer to an isochronous transfer context created with IsoK_Init.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.
KUSB_EXP BOOL KUSB_API IsoK_SetPackets ( _in PKISO_CONTEXT  IsoContext,
_in INT  PacketSize 
)

Convenience function for setting the offset of all ISO packets of an isochronous transfer context.

Parameters
[in]IsoContextA pointer to an isochronous transfer context.
[in]PacketSizeThe packet size used to calculate and assign the absolute data offset for each KISO_PACKET in IsoContext.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

IsoK_SetPackets updates all KISO_PACKET::Offset fields in a KISO_CONTEXT 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.
for (packetIndex = 0; packetIndex < IsoContext->NumberOfPackets; packetIndex++)
IsoContext->IsoPackets[packetIndex].Offset = packetIndex * PacketSize;
KUSB_EXP BOOL KUSB_API IsoK_SetPacket ( _in PKISO_CONTEXT  IsoContext,
_in INT  PacketIndex,
_in PKISO_PACKET  IsoPacket 
)

Convenience function for setting all fields of a KISO_PACKET.

Parameters
[in]IsoContextA pointer to an isochronous transfer context.
[in]PacketIndexThe packet index to set.
[in]IsoPacketPointer to a user allocated KISO_PACKET which is copied into the PKISO_CONTEXT::IsoPackets array at the specified index.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.
KUSB_EXP BOOL KUSB_API IsoK_GetPacket ( _in PKISO_CONTEXT  IsoContext,
_in INT  PacketIndex,
_out PKISO_PACKET  IsoPacket 
)

Convenience function for getting all fields of a KISO_PACKET.

Parameters
[in]IsoContextA pointer to an isochronous transfer context.
[in]PacketIndexThe packet index to get.
[out]IsoPacketPointer to a user allocated KISO_PACKET which receives a copy of the ISO packet in the PKISO_CONTEXT::IsoPackets array at the specified index.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.
KUSB_EXP BOOL KUSB_API IsoK_EnumPackets ( _in PKISO_CONTEXT  IsoContext,
_in KISO_ENUM_PACKETS_CB EnumPackets,
_inopt INT  StartPacketIndex,
_inopt PVOID  UserState 
)

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

Parameters
[in]IsoContextA pointer to an isochronous transfer context.
[in]EnumPacketsPointer to a user supplied callback function which is executed for all ISO packets in IsoContext or until the user supplied callback function returns FALSE.
[in]StartPacketIndexThe zero-based ISO packet index to begin enumeration at.
[in]UserStateA 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 IsoK_ReUse ( _ref PKISO_CONTEXT  IsoContext)

Convenience function for re-using an isochronous transfer context in a subsequent request.

Parameters
[in,out]IsoContextA pointer to an isochronous transfer context.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

IsoK_ReUse does the following:

  1. Zero-initializes the Length and Status fields of all KISO_PACKET structures.
  2. Zero-initializes the StartFrame and ErrorCount of the KISO_CONTEXT.