CaptureService

ULONG
CaptureService(
    PDEVICE_INFO pDevInfo,
    PUCHAR pBuffer,
    PULONG pTimeStamp,
    ULONG BufferLength
    );

The CaptureService function is a kernel-mode video capture driver’s deferred procedure call (DPC) function, used for copying captured video data from the frame buffer to client-supplied buffers. The function is driver-defined, and the CaptureService name is a placeholder for a driver-specified function name.

Parameters

pDevInfo

Pointer to the DEVICE_INFO structure returned by VC_Init.

pBuffer

Pointer to a page-locked buffer. Can be NULL (see the following Comments section).

pTimeStamp

Address of a ULONG location to return the time, in milliseconds, at which the frame was captured

BufferLength

Size, in bytes, of the buffer specified by pBuffer.

Return Value

If the driver has finished using the buffer pointed to by pBuffer, it should return the number of bytes written to the buffer. If the driver returns zero and pBuffer is not NULL, VCKernel.lib will return the same buffer the next time it calls CaptureService.

Comments

The VCKernel.lib library provides a generic DPC function that is called each time the driver’s InterruptAcknowledge function returns TRUE. This generic DPC function calls the driver’s CaptureService function, which is responsible for copying the current frame buffer contents into a client buffer. The function executes at an IRQL of DISPATCH_LEVEL.

The CaptureService function receives, in pBuffer, a pointer to the next available buffer, which has been page-locked. (This buffer usually is client-supplied, but if the system has limited memory resources, the buffer might be one that VCKernel.lib allocated from system space. This situation is irrelevant to the driver.)

If pBuffer is NULL, no buffers are available. In this case, the driver should drop the frame contents (typically by just returning zero), and VCKernel.lib will increment its count of dropped frames.

If pBuffer is not NULL, and if the driver does not completely fill the specified buffer with a single frame, it can return zero to indicate that VCKernel.lib should specify the same buffer the next time it calls CaptureService.

The driver returns a time stamp that is relative to the beginning of the stream and is reset by the driver’s StreamStartFunc function. The time stamp should be recorded by the driver’s InterruptAcknowledge function ¾ not its CaptureService function ¾ because there can be a time delay before the latter function is called.

If other code within the kernel-mode driver references the same objects that the CaptureService function references, the driver must use VC_SynchronizeDPC to synchronize access to the objects.

Support for a CaptureService function is required. The driver must place the address of its CaptureService function in the VC_CALLBACK structure supplied by VCKernel.lib.

For more information about deferred procedure calls (DPCs) see the Kernel Mode Drivers Design Guide.