Module for USB pipe specific async I/O. More...

Enumerations
enum	KOVL_WAIT_FLAG { KOVL_WAIT_FLAG_NONE = 0L, KOVL_WAIT_FLAG_RELEASE_ON_SUCCESS = 0x0001, KOVL_WAIT_FLAG_RELEASE_ON_FAIL = 0x0002, KOVL_WAIT_FLAG_RELEASE_ON_SUCCESS_FAIL = 0x0003, KOVL_WAIT_FLAG_CANCEL_ON_TIMEOUT = 0x0004, KOVL_WAIT_FLAG_RELEASE_ON_TIMEOUT = 0x000C, KOVL_WAIT_FLAG_RELEASE_ALWAYS = 0x000F, KOVL_WAIT_FLAG_ALERTABLE = 0x0010 }
	`WaitFlags` used by OvlK_Wait. More...

enum	KOVL_POOL_FLAG
	`Overlapped` pool config flags. More...

Functions
KUSB_EXP BOOL KUSB_API	OvlK_Acquire (_out KOVL_HANDLE *OverlappedK, _in KOVL_POOL_HANDLE PoolHandle)
	Gets a preallocated `OverlappedK` structure from the specified/default pool. More...

KUSB_EXP BOOL KUSB_API	OvlK_Release (_in KOVL_HANDLE OverlappedK)
	Returns an `OverlappedK` structure to it's pool. More...

KUSB_EXP BOOL KUSB_API	OvlK_Init (_out KOVL_POOL_HANDLE *PoolHandle, _in KUSB_HANDLE UsbHandle, _in INT MaxOverlappedCount, _inopt KOVL_POOL_FLAG Flags)
	Creates a new overlapped pool. More...

KUSB_EXP BOOL KUSB_API	OvlK_Free (_in KOVL_POOL_HANDLE PoolHandle)
	Destroys the specified pool and all resources it created. More...

KUSB_EXP HANDLE KUSB_API	OvlK_GetEventHandle (_in KOVL_HANDLE OverlappedK)
	Returns the internal event handle used to signal IO operations. More...

KUSB_EXP BOOL KUSB_API	OvlK_Wait (_in KOVL_HANDLE OverlappedK, _inopt INT TimeoutMS, _inopt KOVL_WAIT_FLAG WaitFlags, _out PUINT TransferredLength)
	Waits for overlapped I/O completion, and performs actions specified in `WaitFlags`. More...

KUSB_EXP BOOL KUSB_API	OvlK_WaitOldest (_in KOVL_POOL_HANDLE PoolHandle, _outopt KOVL_HANDLE *OverlappedK, _inopt INT TimeoutMS, _inopt KOVL_WAIT_FLAG WaitFlags, _out PUINT TransferredLength)
	Waits for overlapped I/O completion on the oldest acquired OverlappedK handle and performs actions specified in `WaitFlags`. More...

KUSB_EXP BOOL KUSB_API	OvlK_WaitOrCancel (_in KOVL_HANDLE OverlappedK, _inopt INT TimeoutMS, _out PUINT TransferredLength)
	Waits for overlapped I/O completion, cancels on a timeout error. More...

KUSB_EXP BOOL KUSB_API	OvlK_WaitAndRelease (_in KOVL_HANDLE OverlappedK, _inopt INT TimeoutMS, _out PUINT TransferredLength)
	Waits for overlapped I/O completion, cancels on a timeout error and always releases the OvlK handle back to its pool. More...

KUSB_EXP BOOL KUSB_API	OvlK_IsComplete (_in KOVL_HANDLE OverlappedK)
	Checks for i/o completion; returns immediately. (polling) More...

KUSB_EXP BOOL KUSB_API	OvlK_ReUse (_in KOVL_HANDLE OverlappedK)
	Initializes an overlappedK for re-use. The overlappedK is not return to its pool. More...

Detailed Description

Module for USB pipe specific async I/O.

Enumeration Type Documentation

enum KOVL_WAIT_FLAG

WaitFlags used by OvlK_Wait.

Enumerator
KOVL_WAIT_FLAG_NONE	Do not perform any additional actions upon exiting OvlK_Wait.
KOVL_WAIT_FLAG_RELEASE_ON_SUCCESS	If the i/o operation completes successfully, release the OverlappedK back to it's pool.
KOVL_WAIT_FLAG_RELEASE_ON_FAIL	If the i/o operation fails, release the OverlappedK back to it's pool.
KOVL_WAIT_FLAG_RELEASE_ON_SUCCESS_FAIL	If the i/o operation fails or completes successfully, release the OverlappedK back to its pool. Perform no actions if it times-out.
KOVL_WAIT_FLAG_CANCEL_ON_TIMEOUT	If the i/o operation times-out cancel it, but do not release the OverlappedK back to its pool.
KOVL_WAIT_FLAG_RELEASE_ON_TIMEOUT	If the i/o operation times-out, cancel it and release the OverlappedK back to its pool.
KOVL_WAIT_FLAG_RELEASE_ALWAYS	Always release the OverlappedK back to its pool. If the operation timed-out, cancel it before releasing back to its pool.
KOVL_WAIT_FLAG_ALERTABLE	Uses alterable wait functions. See http://msdn.microsoft.com/en-us/library/windows/desktop/ms687036%28v=vs.85%29.aspx.

enum KOVL_POOL_FLAG

Overlapped pool config flags.

Attention: Currently not used.

Function Documentation

KUSB_EXP BOOL KUSB_API OvlK_Acquire	(	_out KOVL_HANDLE *	OverlappedK,
		_in KOVL_POOL_HANDLE	PoolHandle
	)

Gets a preallocated OverlappedK structure from the specified/default pool.

Parameters

[out]	OverlappedK	On Success, receives the overlapped handle.
[in]	PoolHandle	The overlapped pool used to retrieve the next available `OverlappedK`.

Returns: On success, the next unused overlappedK available in the pool. Otherwise NULL. Use GetLastError() to get extended error information.

After calling OvlK_Acquire or OvlK_ReUse the OverlappedK is ready to be used in an I/O operation. See one of the UsbK core transfer functions such as UsbK_ReadPipe or UsbK_WritePipe for more information.

If the pools internal refurbished list (a re-usable list of OverlappedK structures) is not empty, the OvlK_Acquire function will choose an overlapped from the refurbished list.

Examples:: pipe-policy-timeout.c, xfer-async-loop.c, xfer-async.c, xfer-iso-asap.c, and xfer-iso.c.

KUSB_EXP BOOL KUSB_API OvlK_Release ( _in KOVL_HANDLE OverlappedK )

Returns an OverlappedK structure to it's pool.

Parameters

[in] OverlappedK The overlappedK to release.

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

When an overlapped is returned to pool, it resources are not freed. Instead, it is added to an internal refurbished list (a re-usable list of OverlappedK structures).

Warning: This function must not be called when the OverlappedK is in-use. If unsure, consider using OvlK_WaitAndRelease instead.

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

KUSB_EXP BOOL KUSB_API OvlK_Init	(	_out KOVL_POOL_HANDLE *	PoolHandle,
		_in KUSB_HANDLE	UsbHandle,
		_in INT	MaxOverlappedCount,
		_inopt KOVL_POOL_FLAG	Flags
	)

Creates a new overlapped pool.

Parameters

[out]	PoolHandle	On success, receives the new pool handle.
[in]	UsbHandle	USB handle to associate with the pool.
[in]	MaxOverlappedCount	Maximum number of overkappedK handles allowed in the pool.
[in]	Flags	Pool flags.

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

Examples:: pipe-policy-timeout.c, xfer-async-loop.c, xfer-async.c, xfer-iso-asap.c, and xfer-iso.c.

KUSB_EXP BOOL KUSB_API OvlK_Free ( _in KOVL_POOL_HANDLE PoolHandle )

Destroys the specified pool and all resources it created.

Parameters

[in] PoolHandle The overlapped pool to destroy. Once destroyed, the pool and all resources which belong to it can no longer be used.

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

Warning: A pool should not be destroyed until all OverlappedKs acquired from it are no longer in-use. For more information see OvlK_WaitAndRelease or OvlK_Release.

Examples:: xfer-async-loop.c, xfer-async.c, xfer-iso-asap.c, and xfer-iso.c.

KUSB_EXP HANDLE KUSB_API OvlK_GetEventHandle ( _in KOVL_HANDLE OverlappedK )

Returns the internal event handle used to signal IO operations.

Parameters

[in] OverlappedK The overlappedK used to return the internal event handle.

Returns: On success, The manual reset event handle being used by this overlappedK. Otherwise NULL. Use GetLastError() to get extended error information.

OvlK_GetEventHandle is useful for applications that must to their own event handling. It exposes the windows OVERLAPPED hEvent used for i/o completion signaling. This event handle can be used by the standard event wait functions; /c WaitForMultipleObjectsEx for example.

Warning: Use OvlK_GetEventHandle with caution. Event handles returned by this function should never be used unless the OverlappedK has been acquired by the application.

KUSB_EXP BOOL KUSB_API OvlK_Wait	(	_in KOVL_HANDLE	OverlappedK,
		_inopt INT	TimeoutMS,
		_inopt KOVL_WAIT_FLAG	WaitFlags,
		_out PUINT	TransferredLength
	)

Waits for overlapped I/O completion, and performs actions specified in WaitFlags.

Parameters

[in]	OverlappedK	The overlappedK to wait on.
[in]	TimeoutMS	Number of milliseconds to wait for overlapped completion.
[in]	WaitFlags	See /ref KOVL_WAIT_FLAG
[out]	TransferredLength	On success, returns the number of bytes transferred by this overlappedK.

Returns: On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information. See the remarks section below for details on relevant error codes.

OvlK_Wait waits the time interval specified in TimeoutMS for the overlapped I/O operation to complete. Different actions can then taken depending on the flags specified in WaitFlags.

Error codes relevant to this function

ERROR_CANCELLED
(1223)

The I/O was cancelled by the user. The transfer complete event was not signalled within the alotted transfer timeout time and the OvlK_Wait function issued a CancelIoEx/CancelIo request because the KOVL_WAIT_FLAG_CANCEL_ON_TIMEOUT flag bit was set.

ERROR_OPERATION_ABORTED
(995)

The transfer complete event is signalled but the overlapped result was allready cancelled. The overlapped I/O may have bee cancelled for one of the following reasons:
- Driver cancelled because of pipe timeout policy expiration.
- The device was disconnected.
- A UsbK_AbortPipe request was issued.

KUSB_EXP BOOL KUSB_API OvlK_WaitOldest	(	_in KOVL_POOL_HANDLE	PoolHandle,
		_outopt KOVL_HANDLE *	OverlappedK,
		_inopt INT	TimeoutMS,
		_inopt KOVL_WAIT_FLAG	WaitFlags,
		_out PUINT	TransferredLength
	)

Waits for overlapped I/O completion on the oldest acquired OverlappedK handle and performs actions specified in WaitFlags.

Parameters

[in]	PoolHandle	The pool handle containing one or more acuired OverlappedKs.
[out]	OverlappedK	On success, set to the oldest overlappedK in the acquired list.
[in]	TimeoutMS	See /ref OvlK_Wait
[in]	WaitFlags	See /ref KOVL_WAIT_FLAG
[out]	TransferredLength	See /ref OvlK_Wait

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

KUSB_EXP BOOL KUSB_API OvlK_WaitOrCancel	(	_in KOVL_HANDLE	OverlappedK,
		_inopt INT	TimeoutMS,
		_out PUINT	TransferredLength
	)

Waits for overlapped I/O completion, cancels on a timeout error.

Parameters

[in]	OverlappedK	The overlappedK to wait on.
[in]	TimeoutMS	Number of milliseconds to wait for overlapped completion.
[out]	TransferredLength	On success, returns the number of bytes transferred by this overlappedK.

Returns: On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information. See OvlK_Wait for details on relevant win32 error codes.

Note: This convenience function calls OvlK_Wait with KOVL_WAIT_FLAG_CANCEL_ON_TIMEOUT.

OvlK_WaitOrCancel waits the the time interval specified by TimeoutMS for an overlapped result. If the TimeoutMS interval expires the I/O operation is cancelled. The OverlappedK is not released back to its pool.

Examples:: xfer-async.c, xfer-iso-asap.c, and xfer-iso.c.

KUSB_EXP BOOL KUSB_API OvlK_WaitAndRelease	(	_in KOVL_HANDLE	OverlappedK,
		_inopt INT	TimeoutMS,
		_out PUINT	TransferredLength
	)

Waits for overlapped I/O completion, cancels on a timeout error and always releases the OvlK handle back to its pool.

Parameters

[in]	OverlappedK	The overlappedK to wait on.
[in]	TimeoutMS	Number of milliseconds to wait for overlapped completion.
[out]	TransferredLength	On success, returns the number of bytes transferred by this overlappedK.

Returns: On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information. See OvlK_Wait for details on relevant win32 error codes.

Note: This convenience function calls OvlK_Wait with KOVL_WAIT_FLAG_RELEASE_ALWAYS.

OvlK_WaitAndRelease waits the the time interval specified by TimeoutMS for an overlapped result. When OvlK_WaitOrCancel returns, the I/O operation has either been completed or cancelled. The OverlappedK is always released back to its pool where it can be re-acquired with OvlK_Acquire.

Examples:: pipe-policy-timeout.c, and xfer-async-loop.c.

KUSB_EXP BOOL KUSB_API OvlK_IsComplete ( _in KOVL_HANDLE OverlappedK )

Checks for i/o completion; returns immediately. (polling)

Parameters

[in] OverlappedK The overlappedK to check for completion.

Warning: OvlK_IsComplete does no validation on the OverlappedK. It's purpose is to check the event signal state as fast as possible.

Returns: TRUE if the OverlappedK has completed, otherwise FALSE.

OvlK_IsComplete quickly checks if the OverlappedK i/o operation has completed.

KUSB_EXP BOOL KUSB_API OvlK_ReUse ( _in KOVL_HANDLE OverlappedK )

Initializes an overlappedK for re-use. The overlappedK is not return to its pool.

Parameters

[in] OverlappedK The overlappedK to re-use.

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

This function performs the following actions:

Resets the overlapped event to non-signaled via ResetEvent().
Clears the internal overlapped information.
Clears the 'Internal' and 'InternalHigh' members of the windows overlapped structure.

Note: Re-using OverlappedKs is the most efficient means of OverlappedK management. When an OverlappedK is "re-used" it is not returned to the pool. Instead, the application retains ownership for use in another i/o operation.

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

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation