To enable applications to get and set an endpoint pipe's default policy parameters, libusbK.dll exposes the UsbK_GetPipePolicy function to retrieve the pipe's default policy. The UsbK_SetPipePolicy function allows an application to set the policy parameter to a new value.

libusbK allows you to modify its default behavior by applying policies to an endpoint's pipe. By using these policies, you can configure libusbK to best match your device to its capabilities. The following table provides a list of the pipe policies that are supported by libusbK.

Pipe Policies

Note: The policies described in the table are valid only for the specified endpoints. Setting the policy on other endpoints has no effect on libusbK's behavior for read or write requests.

Policy number	Policy name	Description	Endpoint (direction)	Default
0x01	SHORT_PACKET_TERMINATE	Terminates every write request with a zero-length packet.	Bulk (OUT) Interrupt (OUT)	Off
0x02	AUTO_CLEAR_STALL	Automatically clears a stalled pipe without stopping the data flow.	Bulk (IN) Interrupt (IN)	Off
0x03	PIPE_TRANSFER_TIMEOUT	Waits for a time-out interval before canceling the request.	Bulk (IN) Bulk (OUT) Interrupt (IN) Interrupt (OUT)	5 seconds for control; 0 for others
0x04	IGNORE_SHORT_PACKETS	Completes a read request based on the number of bytes read.	Bulk (IN) Interrupt (IN)	Off
0x05	ALLOW_PARTIAL_READS	Allows read requests from a device that returns more data than requested by the caller.	Bulk (IN) Interrupt (IN)	On
0x06	AUTO_FLUSH	Saves the excess data from the read request and adds it to the next read request or discards the excess data.	Bulk (IN) Interrupt (IN)	Off
0x07	RAW_IO	Bypasses queuing and error handling to boost performance for multiple read requests.	Bulk (IN) Interrupt (IN)	Off
0x08	MAXIMUM_TRANSFER_SIZE	Gets the maximum size of a USB transfer supported by libusbK. This is a read-only policy that can be retrieved by calling WinUsb_GetPipePolicy.	Bulk (IN) Bulk (OUT) Interrupt (IN) Interrupt (OUT)
0x09	RESET_PIPE_ON_RESUME	Resets the endpoint's pipe after resuming from suspend before accepting new requests.	Bulk (IN) Bulk (OUT) Interrupt (IN) Interrupt (OUT)	Off
0x30	SIMUL_PARALLEL_REQUESTS	Maximum number of transfers that can be asynchronously delivered at a time. Available in version 1.9 and later versions of KMDF. Requires \b RAW_IO. http://msdn.microsoft.com/en-us/library/windows/hardware/ff552359%28v=vs.85%29.aspx.	Bulk (IN) Bulk (OUT) Interrupt (IN) Interrupt (OUT) ISO (IN) ISO (OUT)	Unlimited
0x20	ISO_START_LATENCY	TODO:	ISO (IN) ISO (OUT)	8 for full speed, 32 for high speed
0x21	ISO_ALWAYS_START_ASAP	TODO:	ISO (IN) ISO (OUT)	On for OUT endpoints, Off for IN endpoints
0x22	ISO_NUM_FIXED_PACKETS	TODO:	ISO (OUT)	0 (disabled)

Behavior and Best Practices

Note: The following table identifies best practices for how to use each of the pipe policies and describes the resulting behavior when the policy is enabled.

Policy	Enable if...	Behavior
SHORT_PACKET_TERMINATE	The device requires the OUT transfers to be terminated with a zero-length packet. Most devices do not have this requirement.	If enabled (policy parameter value is TRUE or nonzero), every write request is followed by a zero-length packet to the endpoint's pipe. After sending all of the requested data to the host controller, libusbK sends a write request with a zero-length packet and then completes the request that was created by UsbK_WritePipe.
AUTO_CLEAR_STALL	You do not want the failed transfers to leave the endpoint in a stalled state. This policy is useful only when you have multiple pending read requests to the endpoint when RAW_IO is disabled.	If enabled (policy parameter value is TRUE or nonzero), a stall condition is cleared automatically. This policy parameter does not affect control pipes. When a read request fails and the host controller returns a status other than STATUS_CANCELLED or STATUS_DEVICE_NOT_CONNECTED, libusbK resets the pipe before completing the failed request. Resetting the pipe clears the stall condition without interrupting the data flow. Data continues to flow in the endpoints as long as new transfers keep arriving from the device. A new transfer can include one that was in the queue when the stall occurred. Enabling this policy does not significantly impact performance. If disabled (policy parameter value is FALSE or zero), all transfers that arrive to the endpoint after the stalled transfer fail until the caller manually resets the endpoint's pipe by calling UsbK_ResetPipe.
PIPE_TRANSFER_TIMEOUT	You expect transfers to an endpoint to complete within a specific time.	If set to zero (default), transfers will not time out because the host controller will not cancel the transfer. In this case, the transfer waits indefinitely until it is manually canceled or the transfer completes normally. If set to a nonzero value (time-out interval), the host controller starts a timer when it receives the transfer request. When the timer exceeds the set time-out interval, the request is canceled. A minor performance penalty will occur due to timer management. Requests do not time out while waiting in a libusbK queue. In Windows Vista, for all transfers (except transfers with RAW_IO enabled), libusbK queues the request until all previous transfers on the destination endpoint have been completed. The host controller does not include the queuing time in the calculation of the time-out interval. With RAW_IO enabled, libusbK does not queue the request. Instead, it passes the request directly to the USB stack, whether or not the USB stack is busy processing previous transfers. If the USB stack is busy, it can delay processing the new request. Note that this can cause a time-out.
IGNORE_SHORT_PACKETS	RAW_IO is disabled and you do not want short packets to complete the read requests.	If enabled (policy parameter value is TRUE or nonzero), the host controller will not complete a read operation immediately after it receives a short packet. Instead, it completes the operation only if: An error occurs. The request is canceled. All the requested bytes have been received. If disabled (policy parameter value is FALSE or zero), the host controller completes a read operation after it has read the specified number of bytes or has received a short packet.
ALLOW_PARTIAL_READS	The device can send more data than requested. This is possible if the size of your request buffer is a multiple of the maximum endpoint packet size. Use if your application wants to read a few bytes to determine how many total bytes to read.	If disabled (policy parameter value is FALSE or zero) and the device returns more data than was requested, libusbK completes the request with an error. If enabled (policy parameter value is TRUE or nonzero) and the device returns more data than was requested, libusbK can (depending on AUTO_FLUSH settings) add the excess data from the read request to the beginning of the next read request or discard the excess data. If enabled, libusbK immediately completes read requests for zero bytes successfully and will not send the requests down the stack.
AUTO_FLUSH	ALLOW_PARTIAL _READS policy is enabled. The device can send more data than was requested, and your application does not require any additional data. This is possible if the size of your request buffer is a multiple of the maximum endpoint packet size.	AUTO_FLUSH defines libusbK's behavior when ALLOW_PARTIAL_READS is enabled. If ALLOW_PARTIAL_READS is disabled, the AUTO_FLUSH value is ignored by libusbK. libusbK can either discard the remaining data or send it with the caller's next read request. If enabled (policy parameter value is TRUE or nonzero), libusbK discards the extra bytes without any error code. If disabled (policy parameter value is FALSE or zero), libusbK saves the extra bytes, adds them to the beginning of the caller's next read request, and then sends the data to the caller in the next read operation.
RAW_IO	Performance is a priority and the application submits simultaneous read requests to the same endpoint. RAW_IO imposes certain restrictions on the buffer that is passed by the caller in UsbK_ReadPipe: The buffer length must be a multiple of the maximum endpoint packet size. The length must be less than or equal to the value of MAXIMUM_TRANSFER_SIZE retrieved by UsbK_GetPipePolicy.	If enabled, transfers bypass queuing and error handling to boost performance for multiple read requests. libusbK handles read requests as follows: A request that is not a multiple of the maximum endpoint packet size fails. A request that is greater than the maximum transfer size supported by libusbK fails. All well-formed requests are immediately sent down to the USB core stack to be scheduled in the host controller. Enabling this setting significantly improves the performance of multiple read requests by reducing the delay between the last packet of one transfer and the first packet of the next transfer.
RESET_PIPE_ON_RESUME	The device does not preserve its data toggle state across suspend.	On resume from suspend, libusbK resets the endpoint before it allows the caller to send new requests to the endpoint.
SIMUL_PARALLEL_REQUESTS	TODO:	TODO:
ISO_START_LATENCY	TODO:	TODO:
ISO_ALWAYS_START_ASAP	TODO:	TODO:
ISO_NUM_FIXED_PACKETS	TODO:	TODO: