PFNUSBCAMD_WaitOnDeviceEvent callback function (usbcamdi.h)

Article
03/13/2023

The USBCAMD_WaitOnDeviceEvent service is used to perform a read from the interrupt pipe if the camera has an interrupt pipe for external event notifications.

Syntax

PFNUSBCAMD_WaitOnDeviceEvent PfnusbcamdWaitondeviceevent;

NTSTATUS PfnusbcamdWaitondeviceevent(
  [in] PVOID DeviceContext,
  [in] ULONG PipeIndex,
  [in] PVOID Buffer,
  [in] ULONG BufferLength,
  [in] PCOMMAND_COMPLETE_FUNCTION EventComplete,
  [in] PVOID EventContext,
  [in] BOOLEAN LoopBack
)
{...}

Parameters

[in] DeviceContext

A pointer to device-specific context.

[in] PipeIndex

Specifies the index of the interrupt pipe.

[in] Buffer

A pointer to the read buffer.

[in] BufferLength

Length of the read buffer, in bytes.

[in] EventComplete

Pointer to a camera minidriver defined CommandCompleteFunction, which is called when the interrupt read is completed This value can be NULL.

[in] EventContext

Pointer to a block of memory, that is passed as an argument to the camera minidriver defined CommandCompleteFunction.

[in] LoopBack

Specifies if USBCAMD is to resubmit another read request to the interrupt pipe every time an interrupt read is completed. Set to TRUE

Return value

USBCAMD_WaitOnDeviceEvent returns STATUS_SUCCESS if the call was successful. Other possible error codes include:

Return code	Description
STATUS_FILE_CLOSED	The device has been removed.
STATUS_INVALID_PARAMETER	USBCAMD may return STATUS_INVALID_PARAMETER for a number of reasons, including: The value passed in the PipeIndex argument is invalid, the type of the pipe specified by the PipeIndex argument represents an invalid type of pipe, a bulk read/write request already exists, or the Buffer argument is NULL. The length specified in the BufferLength argument is smaller than the maximum packet size.
STATUS_PENDING	The event work item is deferred.
STATUS_INSUFFICIENT_RESOURCES	There are insufficient resources to allocate a work item to read from the pipe.

Remarks

The typical usage scenario for this function is a camera with a snapshot button and an interrupt pipe associated with the button. When a user presses the snapshot button, the read request on the interrupt pipe is satisfied and the camera minidriver is called back. If the camera minidriver sets USBCAMD_CamControlFlag_EnableDeviceEvents in the CamControlFlag argument during the USBCAMD_InitializeNewInterface call, the STI monitor also is notified of the snapshot event.

USBCAMD_WaitOnDeviceEvent is not available in USBCAMD version 1.0.

Requirements

Requirement	Value
Target Platform	Desktop
Header	usbcamdi.h (include Usbcamdi.h)