/*++
Copyright (c) 1997 Microsoft Corporation
Module Name:
USBCAMDI.H
Abstract:
interface definition for .
Environment:
Kernel & user mode
Revision History:
--*/
#ifndef __USBCAMDI_H__
#define __USBCAMDI_H__
// the purpose of this structure is to establish a connection between pipes discovered and
// streams to be declared (video,still). the following structure will be be passed along with
// USBD_PIPE_INFO structure in CamConfigEx to the cam driver. The Cam driver has to indicate
// pipe stream asscociation by oring all the relevant streams associated with this particular
// pipe. If there is more than one stream association, USBCAMD creates a virtual still pin,
// and assumes the first stream is video followed by still stream.
// The cam driver has to set the first field to USBCAMD_DONT_CARE_PIPE if a particular pipe should not be used by
// usbcamd. For example, if you have an iso audio pipe, iso video pipe in a camera device that
// supports stills and video .you should set the flag field in the first structure to
// USBCAMD_DONT_CARE_PIPE, The second structure should be set as foolows:
// {USBCAMD_VIDEO_STILL_STREAM,USBCAMD_MULTIPLEX_PIPE)}.
// the assumption here is that cam has one config descr, and all alt.interfcaes have the same
// number and types of pipes.
// also, notice that the flags are mutually exclusive.
//
typedef struct _pipe_config_descriptor {
CHAR StreamAssociation ; // video stream, still stream, or both
UCHAR PipeConfigFlags; // USBCAMD_PIPECONFIG_*
} USBCAMD_Pipe_Config_Descriptor, *PUSBCAMD_Pipe_Config_Descriptor;
#define USBCAMD_DATA_PIPE 0x0001 // video or still data pipe
#define USBCAMD_MULTIPLEX_PIPE 0x0002 // pipe used for both still & video
#define USBCAMD_SYNC_PIPE 0x0004 // out-of-band signalling pipe.
#define USBCAMD_DONT_CARE_PIPE 0x0008 // pipe is not to be used for streaming vidoe or still.
#define USBCAMD_VIDEO_STREAM 0x1
#define USBCAMD_STILL_STREAM 0x2
#define USBCAMD_VIDEO_STILL_STREAM (USBCAMD_VIDEO_STREAM | USBCAMD_STILL_STREAM)
// PacketFlag definitions for CamProcessUSBPacketEx
// *** Notice *** : these flags are mutually exclusive.
// current frame is unsalvageable, recycle the read IRP
#define USBCAMD_PROCESSPACKETEX_DropFrame 0x0002
// following frame is still.
#define USBCAMD_PROCESSPACKETEX_NextFrameIsStill 0x0004
// copy this frame to still pin. .
#define USBCAMD_PROCESSPACKETEX_CurrentFrameIsStill 0x0008
// these flags are used in PipeStateFlag in usbcamd_setpipestate function.
#define USBCAMD_STOP_STREAM 0x00000001
#define USBCAMD_START_STREAM 0x00000000
//
// the following flags are passed to usbcamd in USBCAMD_InitializeNewInterface.
// If Cam driver doesn't need to operate on the still image raw frame, then it should
// set the second flag in order to elminate on ebuffer copy. Likewise for the video frame.
// the associatedformat flag is set if the cam driver use the same format fro video and
// virtual still pin. Once, this flag is set, USBCAMD will not allow virtual still pin to be
// opened at different format than the video pin. USE this flag only when the virtual still
// pin produces frames that have exact format as video frames.
// EnableDeviceEvents will expose a deviceevents to stream class & DSHOW which will enable an STI
// Monitor to lunch a still image app if still button is pressed on the camera.
typedef enum {
USBCAMD_CamControlFlag_NoVideoRawProcessing = 0x0001,
USBCAMD_CamControlFlag_NoStillRawProcessing = 0x0002,
USBCAMD_CamControlFlag_AssociatedFormat = 0x0004,
USBCAMD_CamControlFlag_EnableDeviceEvents = 0x0008,
} USBCAMD_CamControlFlags;
// ------------------------------------------------------------------------
// The master list of all streams supported by this driver
// ------------------------------------------------------------------------
typedef
NTSTATUS
(*PCOMMAND_COMPLETE_FUNCTION)(
PVOID DeviceContext,
PVOID CommandContext,
NTSTATUS NtStatus
);
typedef
VOID
(*PSTREAM_RECEIVE_PACKET) (
IN PVOID Srb,
IN PVOID DeviceContext,
IN PBOOLEAN Completed
);
typedef
NTSTATUS
(*PCAM_INITIALIZE_ROUTINE)(
PDEVICE_OBJECT BusDeviceObject,
PVOID DeviceContext
);
typedef
NTSTATUS
(*PCAM_CONFIGURE_ROUTINE)(
PDEVICE_OBJECT BusDeviceObject,
PVOID DeviceContext,
PUSBD_INTERFACE_INFORMATION Interface,
PUSB_CONFIGURATION_DESCRIPTOR ConfigurationDescriptor,
PLONG DataPipeIndex,
PLONG SyncPipeIndex
);
typedef
NTSTATUS
(*PCAM_CONFIGURE_ROUTINE_EX)(
PDEVICE_OBJECT BusDeviceObject,
PVOID DeviceContext,
PUSBD_INTERFACE_INFORMATION Interface,
PUSB_CONFIGURATION_DESCRIPTOR ConfigurationDescriptor,
ULONG PipeConfigListSize,
PUSBCAMD_Pipe_Config_Descriptor PipeConfig,
PUSB_DEVICE_DESCRIPTOR DeviceDescriptor
);
typedef
NTSTATUS
(*PCAM_START_CAPTURE_ROUTINE)(
PDEVICE_OBJECT BusDeviceObject,
PVOID DeviceContext
);
typedef
NTSTATUS
(*PCAM_START_CAPTURE_ROUTINE_EX)(
PDEVICE_OBJECT BusDeviceObject,
PVOID DeviceContext,
ULONG StreamNumber
);
typedef
NTSTATUS
(*PCAM_ALLOCATE_BW_ROUTINE)(
PDEVICE_OBJECT BusDeviceObject,
PVOID DeviceContext,
PULONG RawFrameLength,
PVOID Format
);
typedef
NTSTATUS
(*PCAM_ALLOCATE_BW_ROUTINE_EX)(
PDEVICE_OBJECT BusDeviceObject,
PVOID DeviceContext,
PULONG RawFrameLength,
PVOID Format,
ULONG StreamNumber
);
typedef
NTSTATUS
(*PCAM_FREE_BW_ROUTINE)(
PDEVICE_OBJECT BusDeviceObject,
PVOID DeviceContext
);
typedef
NTSTATUS
(*PCAM_FREE_BW_ROUTINE_EX)(
PDEVICE_OBJECT BusDeviceObject,
PVOID DeviceContext,
ULONG STreamNumber
);
typedef
VOID
(*PADAPTER_RECEIVE_PACKET_ROUTINE)(
IN PHW_STREAM_REQUEST_BLOCK Srb
);
typedef
NTSTATUS
(*PCAM_STOP_CAPTURE_ROUTINE)(
PDEVICE_OBJECT BusDeviceObject,
PVOID DeviceContext
);
typedef
NTSTATUS
(*PCAM_STOP_CAPTURE_ROUTINE_EX)(
PDEVICE_OBJECT BusDeviceObject,
PVOID DeviceContext,
ULONG StreamNumber
);
typedef
ULONG
(*PCAM_PROCESS_PACKET_ROUTINE) (
PDEVICE_OBJECT BusDeviceObject,
PVOID DeviceContext,
PVOID CurrentFrameContext,
PUSBD_ISO_PACKET_DESCRIPTOR SyncPacket,
PVOID SyncBuffer,
PUSBD_ISO_PACKET_DESCRIPTOR DataPacket,
PVOID DataBuffer,
PBOOLEAN FrameComplete,
PBOOLEAN NextFrameIsStill
);
typedef
ULONG
(*PCAM_PROCESS_PACKET_ROUTINE_EX) (
PDEVICE_OBJECT BusDeviceObject,
PVOID DeviceContext,
PVOID CurrentFrameContext,
PUSBD_ISO_PACKET_DESCRIPTOR SyncPacket,
PVOID SyncBuffer,
PUSBD_ISO_PACKET_DESCRIPTOR DataPacket,
PVOID DataBuffer,
PBOOLEAN FrameComplete,
PULONG PacketFlag,
PULONG ValidDataOffset
);
typedef
VOID
(*PCAM_NEW_FRAME_ROUTINE) (
PVOID DeviceContext,
PVOID FrameContext
);
typedef
VOID
(*PCAM_NEW_FRAME_ROUTINE_EX) (
PVOID DeviceContext,
PVOID FrameContext,
ULONG StreamNumber,
PULONG FrameLength
);
typedef
NTSTATUS
(*PCAM_PROCESS_RAW_FRAME_ROUTINE) (
PDEVICE_OBJECT BusDeviceObject,
PVOID DeviceContext,
PVOID FrameContext,
PVOID FrameBuffer,
ULONG FrameLength,
PVOID RawFrameBuffer,
ULONG RawFrameLength,
ULONG NumberOfPackets,
PULONG BytesReturned
);
typedef
NTSTATUS
(*PCAM_PROCESS_RAW_FRAME_ROUTINE_EX) (
PDEVICE_OBJECT BusDeviceObject,
PVOID DeviceContext,
PVOID FrameContext,
PVOID FrameBuffer,
ULONG FrameLength,
PVOID RawFrameBuffer,
ULONG RawFrameLength,
ULONG NumberOfPackets,
PULONG BytesReturned,
ULONG ActualRawFrameLength,
ULONG StreamNumber
);
typedef
NTSTATUS
(*PCAM_STATE_ROUTINE) (
PDEVICE_OBJECT BusDeviceObject,
PVOID DeviceContext
);
#ifdef DEBUG_LOG
VOID
USBCAMD_Debug_LogEntry(
IN CHAR *Name,
IN ULONG Info1,
IN ULONG Info2,
IN ULONG Info3
);
#define ILOGENTRY(sig, info1, info2, info3) \
USBCAMD_Debug_LogEntry(sig, (ULONG)info1, (ULONG)info2, (ULONG)info3)
#else
#define ILOGENTRY(sig, info1, info2, info3)
#endif /* DEBUG_LOG */
typedef struct _USBCAMD_DEVICE_DATA {
ULONG Sig;
PCAM_INITIALIZE_ROUTINE CamInitialize;
PCAM_INITIALIZE_ROUTINE CamUnInitialize;
PCAM_PROCESS_PACKET_ROUTINE CamProcessUSBPacket;
PCAM_NEW_FRAME_ROUTINE CamNewVideoFrame;
PCAM_PROCESS_RAW_FRAME_ROUTINE CamProcessRawVideoFrame;
PCAM_START_CAPTURE_ROUTINE CamStartCapture;
PCAM_STOP_CAPTURE_ROUTINE CamStopCapture;
PCAM_CONFIGURE_ROUTINE CamConfigure;
PCAM_STATE_ROUTINE CamSaveState;
PCAM_STATE_ROUTINE CamRestoreState;
PCAM_ALLOCATE_BW_ROUTINE CamAllocateBandwidth;
PCAM_FREE_BW_ROUTINE CamFreeBandwidth;
} USBCAMD_DEVICE_DATA, *PUSBCAMD_DEVICE_DATA;
typedef struct _USBCAMD_DEVICE_DATA2 {
ULONG Sig;
PCAM_INITIALIZE_ROUTINE CamInitialize;
PCAM_INITIALIZE_ROUTINE CamUnInitialize;
PCAM_PROCESS_PACKET_ROUTINE_EX CamProcessUSBPacketEx;
PCAM_NEW_FRAME_ROUTINE_EX CamNewVideoFrameEx;
PCAM_PROCESS_RAW_FRAME_ROUTINE_EX CamProcessRawVideoFrameEx;
PCAM_START_CAPTURE_ROUTINE_EX CamStartCaptureEx;
PCAM_STOP_CAPTURE_ROUTINE_EX CamStopCaptureEx;
PCAM_CONFIGURE_ROUTINE_EX CamConfigureEx;
PCAM_STATE_ROUTINE CamSaveState;
PCAM_STATE_ROUTINE CamRestoreState;
PCAM_ALLOCATE_BW_ROUTINE_EX CamAllocateBandwidthEx;
PCAM_FREE_BW_ROUTINE_EX CamFreeBandwidthEx;
} USBCAMD_DEVICE_DATA2, *PUSBCAMD_DEVICE_DATA2;
//
// USBCAMD services
//
/*
This function is called from the "cam" driver DriverEntry routine to register
the driver with USBCAMD. This effectively binds the two drivers together.
Context1, Context2 - these are passed to the "cam" drivers DriverEntry and
should simply be passed on
DeviceContextSize - amount of memory needed for the "cam" driver's device
specific context.
FrameContextSize - size of an optional per video frame structure passed to
NewVideoFrame and ProcessRawVideoFrame.
*/
ULONG
USBCAMD_DriverEntry(
PVOID Context1,
PVOID Context2,
ULONG DeviceContextSize,
ULONG FrameContextSize,
PADAPTER_RECEIVE_PACKET_ROUTINE ReceivePacket
);
/*
This function is called by the "cam" driver from the AdapterReceivePacket
routine to allow USBCAMD to process an SRB.
Srb - The srb passed to the "cam" driver's AdapterReceievPacket Routine.
DeviceData - filled in USBCAMD_DEVICE_DATAx structure with entry points to the
"cam" driver for iso stream processing.
DeviceObject - this pointer will be filled in the device PDO, this is used by
the "cam" driver for calls to the USB stack through IoCallDriver.
NeedsCompletion - if this flag is true USBCAMD will process the SRB and
complete it, otherwise USBCAMD will ignore the SRB and just return the
DeveiceConext.
Returns:
Returns a pointer to the device specific context for this instance of the
camera "DeviceContext".
*/
PVOID
USBCAMD_AdapterReceivePacket(
IN PHW_STREAM_REQUEST_BLOCK Srb,
IN PUSBCAMD_DEVICE_DATA DeviceData,
IN PDEVICE_OBJECT *DeviceObject,
IN BOOLEAN NeedsCompletion
);
/*
This function is available to the "cam" driver to send vendor commands on the
control pipe. This function may be called at IRQL >= PASSIVE_LEVEL. If the
function is called at IRQL > PASSIVE_LEVEL the command will be deferred until
passive level, once completed the callers CommandComplete function is called
with a pointer to the CommandContext.
DeviceContext - device specific context.
Request - value for the bRequest field for the vendor command.
Value - value for the wValue field of the vendor command.
Index - value for the wIndex field of the vendor conmmand.
Buffer - data buffer if the command has data, may be NULL.
BufferLength - pointer length of Buffer in bytes, may be NULL if buffer is NULL
GetData - flag indicating data direction, "GetData" indicates data is send
device-to-host.
CommandComplete - function called when command is completed.
CommandContext - context passed to CommandComplete function
Returns:
Returns NTSTATUS code from command of STTAUS_PENDING if command is deferred.
*/
NTSTATUS
USBCAMD_ControlVendorCommand(
IN PVOID DeviceContext,
IN UCHAR Request,
IN USHORT Value,
IN USHORT Index,
IN PVOID Buffer,
IN OUT PULONG BufferLength,
IN BOOLEAN GetData,
IN PCOMMAND_COMPLETE_FUNCTION CommandComplete,
IN PVOID CommandContext
);
/*
This function is called by the "cam" driver to select an alternate interface,
The RequestInterface structure is filled in with the information from the
SELECT_INTERFACE request on successful completion. This function is
typically called from the "cam" driver in response to a request to allocate
or free bandwidth.
DeviceContext - device specific context.
RequestInterface - USBD_INTERFACE_INFORMATION structure for the appropriate
interface to select. The same rules apply to this structure as for the
SELECT_INTERFACE USBD request (see USBDI doc).
Returns:
Returns the status from the SELECT_INTERFACE request to USBD.
*/
NTSTATUS
USBCAMD_SelectAlternateInterface(
IN PVOID DeviceContext,
IN OUT PUSBD_INTERFACE_INFORMATION RequestInterface
);
/*
Handy function to get a device instance specific registry key value
*/
NTSTATUS
USBCAMD_GetRegistryKeyValue (
IN HANDLE Handle,
IN PWCHAR KeyNameString,
IN ULONG KeyNameStringLength,
IN PVOID Data,
IN ULONG DataLength
);
//
// These services are new.
//
/*
This function is called from the "cam" driver upon recieving SRB_INITIALIZE_DEVICE
to provid usbcamd with all the necessary info to configure the cam driver correctly with
stream class and USB Bus drivers.
DeviceContext - device specific context.
DeviceData - filled in USBCAMD_DEVICE_DATAx structure with entry points to the
"cam" driver .
Version - USBCAMD version
CamControlFlag - flags to control interaction with cam driver.
*/
ULONG
USBCAMD_InitializeNewInterface(
IN PVOID DeviceContext,
IN PVOID DeviceData,
IN ULONG Version,
IN ULONG CamControlFlag
);
// To access the new USBCAMD functionality in a CAM driver , the driver sends
// the following IRP to itself once it received SRB_INITIALIZATION_COMPLETE.
// MajorFunction = IRP_MJ_PNP;
// MinorFunction = IRP_MN_QUERY_INTERFACE;
// {2BCB75C0-B27F-11d1-BA41-00A0C90D2B05}
DEFINE_GUID( GUID_USBCAMD_INTERFACE ,
0x2bcb75c0, 0xb27f, 0x11d1, 0xba, 0x41, 0x0, 0xa0, 0xc9, 0xd, 0x2b, 0x5);
//The QUERY_INTERFACE Irp will return an interface (set of function pointers)
// of the type xxxxINTERFACE, defined below. This is essentially a table of
// function pointers.
typedef
NTSTATUS
(*PFNUSBCAMD_SetVideoFormat)(
IN PVOID DeviceContext,
IN IN PHW_STREAM_REQUEST_BLOCK pSrb
);
typedef
NTSTATUS
(*PFNUSBCAMD_WaitOnDeviceEvent)(
IN PVOID DeviceContext,
IN ULONG PipeIndex,
IN PVOID Buffer,
IN ULONG BufferLength,
IN PCOMMAND_COMPLETE_FUNCTION EventComplete,
IN PVOID EventContext,
IN BOOLEAN LoopBack
);
// this function is callable at PASSIVE_LEVEL Only.
typedef
NTSTATUS
(*PFNUSBCAMD_CancelBulkReadWrite)(
IN PVOID DeviceContext,
IN ULONG PipeIndex
);
typedef
NTSTATUS
(*PFNUSBCAMD_SetIsoPipeState)(
IN PVOID DeviceContext,
IN ULONG PipeStateFlags
);
typedef
NTSTATUS
(*PFNUSBCAMD_BulkReadWrite)(
IN PVOID DeviceContext,
IN USHORT PipeIndex,
IN PVOID Buffer,
IN ULONG BufferLength,
IN PCOMMAND_COMPLETE_FUNCTION CommandComplete,
IN PVOID CommandContext
);
#define USBCAMD_VERSION_200 0x200
typedef struct {
INTERFACE Interface;
PFNUSBCAMD_WaitOnDeviceEvent USBCAMD_WaitOnDeviceEvent;
PFNUSBCAMD_BulkReadWrite USBCAMD_BulkReadWrite;
PFNUSBCAMD_SetVideoFormat USBCAMD_SetVideoFormat;
PFNUSBCAMD_SetIsoPipeState USBCAMD_SetIsoPipeState;
PFNUSBCAMD_CancelBulkReadWrite USBCAMD_CancelBulkReadWrite;
} USBCAMD_INTERFACE, *PUSBCAMD_INTERFACE;
#endif /* __USBCAMDI_H__ */