IOCTL_STREAM_ATTACH_BUFFER

  • Article

This IOCTL attaches one or more buffers to a particular session.

Parameters

  • hDevice
    [in] Handle to the target object. To get a device handle, call the CreateFile function with a name dynamically obtained from the SetupDiEnumDeviceInterfaces function.
  • dwIoControlCode
    [in] IOCTL for the operation. This value identifies the target operation and the type of device on which to perform the operation. For this operation, use IOCTL_STREAM_ATTACH_BUFFER.
  • lpInBuffer
    [in] Must be filled in with a properly initialized STREAM_AttachBuffers_Request structure. The sab_Session, sab_NumberOfBuffers, and sab_Buffers members must be pre-initialized.
  • nInBufferSize
    [in] Set to the size of the STREAM_AttachBuffers_Request structure. The last entry of the structure, sab_Buffers, is an array that can extend infinitely, so this field should represent the full size of the structure used rather than merely sizeof(STREAM_AttachBuffers_Request).
  • lpOutBuffer
    [out] This field should be set to point to a STREAM_AttachBuffers_Response structure, which will be filled in by the device driver. The sab_NumberOfIds and sab_BufferIds members in the structure will be filled in.
  • nOutBufferSize
    [in] This field should be pre-initialized with the maximum size of the lpOutBuffer. This buffer should have a STREAM_AttachBuffers_Response structure at its head, but also must have space after the structure for all of the desired extra entries of the sab_BufferIds array.
  • lpBytesReturned
    [out] Pointer to a DWORD variable that receives the actual count of bytes returned by the function in the output buffer.
  • lpOverlapped
    [out] If not used, set to NULL. Otherwise, this should point to a completely filled out OVERLAPPED structure that contains a valid event. The event will be signaled when the I/O operation is complete.

Return Values

If the operation succeeds, the DeviceIoControl function returns a non-zero value. If the operation fails, DeviceIoControl returns zero. To obtain extended error information, call the GetLastError function.

Remarks

Because Windows CE does not support overlapped I/O in DeviceIoControl, and therefore does not support asynchronous I/O, some mechanism of generating asynchronous streaming is required. IOCTL_STREAM_ATTACH_BUFFER permits an application to attach one or more buffers to a session, where they will eventually complete. Once completed, they need to be detached using IOCTL_STREAM_DETACH_BUFFER. The application can determine whether buffers have completed using IOCTL_STREAM_QUERY_BUFFER_STATE.

If the session is a transmit session, the attachment of buffers is perceived as an attempt to transmit the enclosed data. If the session is a receive session, the attachment of buffers is perceived as an attempt to receive arriving data into those buffers.

If any buffers are currently attached when the device is closed, they will be automatically detached as part of the typical resource cleanup for the streaming filter driver.

The buffer size is dependent on the type of media being transferred. IOCTL_STREAM_GET_MEDIA_SIZE should be used to determine the correct size buffer to use.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Avc_stream.h.

See Also

IOCTL_STREAM_START_RECV_SESSION | IOCTL_STREAM_START_XMIT_SESSION | IOCTL_STREAM_QUERY_BUFFER_STATE | IOCTL_STREAM_ATTACH_BUFFER | IOCTL_STREAM_DETACH_BUFFER | DeviceIoControl | CreateFile | STREAM_AttachBuffers_Request | STREAM_AttachBuffers_Response | IOCTL_STREAM_GET_MEDIA_SIZE

 Last updated on Tuesday, May 18, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.