WinUsb_WritePipe function (winusb.h)
The WinUsb_WritePipe function writes data to a pipe.
Syntax
BOOL WinUsb_WritePipe(
[in] WINUSB_INTERFACE_HANDLE InterfaceHandle,
[in] UCHAR PipeID,
[in] PUCHAR Buffer,
[in] ULONG BufferLength,
[out, optional] PULONG LengthTransferred,
[in, optional] LPOVERLAPPED Overlapped
);
Parameters
[in] InterfaceHandle
An opaque handle to the interface that contains the endpoint with which the pipe is associated.
To write to a pipe that is associated with an endpoint in the first interface, use the handle returned by WinUsb_Initialize. For all other interfaces, use the handle to the target interface, retrieved by WinUsb_GetAssociatedInterface.
[in] PipeID
PipeID corresponds to the bEndpointAddress field in the endpoint descriptor. For information about the layout of this field, see Table 9-13 in "Universal Serial Bus Specification Revision 2.0" at USB Technology. In the bEndpointAddress field, Bit 7 indicates the direction of the endpoint: 0 for OUT; 1 for IN.
[in] Buffer
A caller-allocated buffer that contains the data to write.
[in] BufferLength
The number of bytes to write. This number must be less than or equal to the size, in bytes, of Buffer.
[out, optional] LengthTransferred
A pointer to a ULONG variable that receives the actual number of bytes that were written to the pipe. For more information, see Remarks.
[in, optional] Overlapped
An optional pointer to an OVERLAPPED structure, which is used for asynchronous operations. If this parameter is specified, WinUsb_WritePipe immediately returns, and the event is signaled when the operation is complete.
Return value
WinUsb_WritePipe returns TRUE if the operation succeeds. Otherwise, this function returns FALSE, and the caller can retrieve the logged error by calling GetLastError.
GetLastError can return the following error code.
Return code | Description |
---|---|
|
The caller passed NULL in the InterfaceHandle parameter. |
|
Indicates that an overlapped I/O operation is in progress but has not completed. If the overlapped operation cannot be completed immediately, the function returns FALSE and the GetLastError function returns ERROR_IO_PENDING, indicating that the operation is executing in the background. Call WinUsb_GetOverlappedResult to check the success or failure of the operation. |
|
Indicates that there is insufficient memory to perform the operation. |
|
The write operation initiated by WinUsb_WritePipe in the USB stack timed out before the operation could be completed. |
Remarks
To create a write request, your the application must allocate a buffer, fill it with the data that you want to write to the device, and send the buffer to the host controller by calling WinUsb_WritePipe.
The following restrictions apply to the size of the buffer if RAW_IO is set:
- 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 WinUsb_GetPipePolicy.
A write request that contains zero-length data is forwarded down the USB stack.
If an application passes NULL in the Overlapped parameter (synchronous operation), it must ensure that LengthTransferred is not NULL, even when an operation produces no output data.
If Overlapped is not NULL (asynchronous operation), LengthTransferred can be set to NULL. For an overlapped operation (and if LengthTransferred is a non-NULL value), the value received in LengthTransferred after WinUsb_WritePipe returns is meaningless until the overlapped operation has completed. To retrieve the actual number of bytes returned, call WinUsb_GetOverlappedResult.
Requirements
Requirement | Value |
---|---|
Target Platform | Universal |
Header | winusb.h (include Winusb.h) |
Library | Winusb.lib |
DLL | Winusb.dll |