windows wdf 驱动开发总结(2)--usb驱动
2010-10-07 09:50
225 查看
武安河：Usbsample
(14) WDF_REQUEST_SEND_OPTIONS_INIT
函数功能：initializes a driver's
WDF_REQUEST_SEND_OPTIONS structure
VOID
WDF_REQUEST_SEND_OPTIONS_INIT(
OUT PWDF_REQUEST_SEND_OPTIONS Options,
IN ULONG Flags
);
Options
A pointer to a caller-supplied
WDF_REQUEST_SEND_OPTIONS structure.
Flags
A bitwise OR of
WDF_REQUEST_SEND_OPTIONS_FLAGS-typed flags.
（15）WDF_REQUEST_SEND_OPTIONS_SET_TIMEOUT
函数功能：sets a time-out value in a driver's
WDF_REQUEST_SEND_OPTIONS structure.
VOID WDF_REQUEST_SEND_OPTIONS_SET_TIMEOUT(
__out
PWDF_REQUEST_SEND_OPTIONS Options,
__in
LONGLONG Timeout
);
Timeout
如果为负数，那么是相对于系统时间而言的，如果timeout为正数，那么是一个绝对的时间，为0就表示没有超时。
Options [out]
A pointer to the driver's
WDF_REQUEST_SEND_OPTIONS structure.
Timeout [in]
An absolute or relative time-out value. For more information, see the
Timeout member of the
WDF_REQUEST_SEND_OPTIONS structure.
typedef struct _WDF_REQUEST_SEND_OPTIONS {
ULONG
Size;
ULONG
Flags;
LONGLONG Timeout;
} WDF_REQUEST_SEND_OPTIONS, *PWDF_REQUEST_SEND_OPTIONS;
Members
Size
The size, in bytes, of this structure.
Flags
A bitwise OR of
WDF_REQUEST_SEND_OPTIONS_FLAGS-typed flags.
Timeout
A time-out value, in system time units (100-nanosecond intervals). If the driver has set the WDF_REQUEST_SEND_OPTION_TIMEOUT flag, the framework cancels the associated I/O request if
it is not completed within the specified time-out period. The time-out value can be negative, positive, or zero, as follows:
·
If the value is negative, the expiration time is relative to the current system time.
·
If the value is positive, the expiration time is specified as an absolute time (which is actually relative to January 1, 1601).
·
If the value is zero, the framework does not time out the request.
Relative expiration times are not affected by any changes to the system time that might occur within the specified time-out period. Absolute expiration times do reflect system time changes.
The framework provides
time conversion functions that convert time values into system time units.
If the framework cancels an I/O request because the specified time-out period has elapsed, the framework provides a completion status of STATUS_IO_TIMEOUT for the I/O request. However,
after the time-out period elapses, the I/O target might complete the I/O request before the framework is able to cancel it. In that case, the I/O request's completion status will not be STATUS_IO_TIMEOUT.
评论：
The
WDF_REQUEST_SEND_OPTIONS structure is passed to object methods that send an I/O request to an I/O target, such as the
WdfRequestSend method. The structure must be initialized by calling the
WDF_REQUEST_SEND_OPTIONS_INIT and
WDF_REQUEST_SEND_OPTIONS_SET_TIMEOUT functions.
(16) WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR
//vendor,class等
函数功能：初始化控制传输包，设置要传递的批量传输字节数
WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR(
&controlSetupPacket,
BmRequestHostToDevice,
BmRequestToDevice,
0,
dwBytes,
0
);
VOID WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR(
__out
PWDF_USB_CONTROL_SETUP_PACKET Packet, //setup_packet
__in
WDF_USB_BMREQUEST_DIRECTION Direction, //主机to设备或者设备to主机
__in
WDF_USB_BMREQUEST_RECIPIENT Recipient,//请求to设备，请求to接口，请求to端点
__in
BYTE Request, //请求类型F1
__in
USHORT Value,
__in
USHORT Index
);
(17)WdfUsbTargetDeviceSendControlTransferSynchronously
函数功能：builds a USB control transfer request and sends it synchronously
to an I/O target.
NTSTATUS WdfUsbTargetDeviceSendControlTransferSynchronously(
[in]
WDFUSBDEVICE UsbDevice,
[in, optional]
WDFREQUEST Request,
[in, optional]
PWDF_REQUEST_SEND_OPTIONS RequestOptions,
[in]
PWDF_USB_CONTROL_SETUP_PACKET SetupPacket,
[in, optional]
PWDF_MEMORY_DESCRIPTOR MemoryDescriptor,
[out, optional]
PULONG BytesTransferred
);
UsbDevice [in]
A handle to a USB device object that was obtained from a previous call to
WdfUsbTargetDeviceCreate.
Request [in,
optional]
A handle to a framework request object. This parameter is optional and can be NULL. For more information, see the following Remarks section.
RequestOptions
[in, optional]
A pointer to a caller-allocated
WDF_REQUEST_SEND_OPTIONS structure that specifies options for the request. This pointer is optional and can be NULL. For more information, see the following Remarks
section.
SetupPacket [in]
A pointer to a caller-allocated
WDF_USB_CONTROL_SETUP_PACKET structure that describes the control transfer.
MemoryDescriptor
[in, optional]
A pointer to a caller-allocated
WDF_MEMORY_DESCRIPTOR structure that describes either an input or an output buffer, depending on the device-specific command. This pointer is optional and can be NULL.
For more information, see the following Remarks section.
BytesTransferred
[out, optional]
A pointer to a location that receives the number of bytes that are transferred. This parameter is optional and can be NULL.
Return Value
：STATUS_IO_TIMEOUT STATUS_INVALID_PARAMETER
STATUS_INSUFFICIENT_RESOURCES,
STATUS_INVALID_DEVICE_REQUEST
成功返回
//控制传输VENDOR命令
status = WdfUsbTargetDeviceSendControlTransferSynchronously(
pDeviceContext->UsbDevice,
WDF_NO_HANDLE,
&syncReqOptions,
&controlSetupPacket,
NULL,
NULL
);
Msdn:例子
WDF_USB_CONTROL_SETUP_PACKET controlSetupPacket;
WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR(
&controlSetupPacket,
BmRequestHostToDevice,
BmRequestToDevice,
USBFX2LK_REENUMERATE,
0,
0
);
status = WdfUsbTargetDeviceSendControlTransferSynchronously(
UsbDevice,
WDF_NO_HANDLE,
NULL,
&controlSetupPacket,
NULL,
NULL
);
return status;
(18) WdfUsbTargetDeviceResetPortSynchronously
函数功能：resets the USB port that is associated with the specified USB
device.
NTSTATUS WdfUsbTargetDeviceResetPortSynchronously(
[in] WDFUSBDEVICE UsbDevice
);
参数：UsbDevice:usb设备对象句柄
在设置I/O target’s usb port以前，取消保持在I/O
target’s queue里面的所有I/O请求，驱动程序不能发送其他的I/O请求，直到WdfUsbTargetDeviceResetPortSynchronously返回。
在发送WdfUsbTargetDeviceResetPortSynchronously函数之前，必须调用WdfIoTargetStop，在调用该函数后，驱动can
call WdfIoTargetStart函数。
Msdn
例子：
NTSTATUS status;
status = WdfUsbTargetDeviceResetPortSynchronously(UsbDevice);
(19) WDF_MEMORY_DESCRIPTOR_INIT_BUFFER
函数功能：initializes a
WDF_MEMORY_DESCRIPTOR structure so that it describes a specified buffer.
VOID WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
__out
PWDF_MEMORY_DESCRIPTOR Descriptor,
__in
PVOID Buffer,
__in
ULONG BufferLength
);
Descriptor [out]
A pointer to a
WDF_MEMORY_DESCRIPTOR structure.
Buffer [in]
A pointer to a memory buffer.
BufferLength
[in]
The size, in bytes, of the memory buffer that
Buffer points to.
typedef struct _WDF_MEMORY_DESCRIPTOR {
WDF_MEMORY_DESCRIPTOR_TYPE Type;
union {
struct {
PVOID Buffer;
ULONG Length;
} BufferType;
struct {
PMDL
Mdl;
ULONG BufferLength;
} MdlType;
struct {
WDFMEMORY
Memory;
PWDFMEMORY_OFFSET Offsets;
} HandleType;
} u;
} WDF_MEMORY_DESCRIPTOR, *PWDF_MEMORY_DESCRIPTOR;
//批量传输数据块初始化
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&bufDesc,buffer,bufSize);
WDF_REQUEST_SEND_OPTIONS_INIT(&syncReqOptions, 0);
WDF_REQUEST_SEND_OPTIONS_SET_TIMEOUT(&syncReqOptions, -1000000);
(20) WdfUsbTargetPipeWriteSynchronously
函数功能：builds a write request and sends it synchronously to a specified
USB output pipe.
NTSTATUS WdfUsbTargetPipeWriteSynchronously(
[in]
WDFUSBPIPE Pipe,
[in, optional]
WDFREQUEST Request,
[in, optional]
PWDF_REQUEST_SEND_OPTIONS RequestOptions,
[in, optional]
PWDF_MEMORY_DESCRIPTOR MemoryDescriptor,
[out, optional]
PULONG BytesWritten
);
Pipe [in]
A handle to a framework pipe object that was obtained by calling
WdfUsbInterfaceGetConfiguredPipe.
Request [in,
optional]
A handle to a framework request object. This parameter is optional and can be NULL. For more information, see the following Remarks section.
RequestOptions
[in, optional]
A pointer to a caller-allocated
WDF_REQUEST_SEND_OPTIONS structure that specifies options for the request. This pointer is optional and can be NULL. For more information, see the following Remarks
section.
MemoryDescriptor
[in, optional]
A pointer to a caller-allocated
WDF_MEMORY_DESCRIPTOR structure that describes the buffer that contains data that will be written to the device. For more information about this buffer, see the following
Remarks section.
BytesWritten
[out, optional] :
A pointer to a location that receives the number of bytes written, if the operation succeeds. This parameter is optional and can be NULL.
Supply a local buffer:
Because handles I/O requests synchronously, the driver can create request buffers that are local to the calling routine, as the following code example shows.
Copy Code
WDF_MEMORY_DESCRIPTOR memoryDescriptor;
MY_BUFFER_TYPE myBuffer;
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&memoryDescriptor,
(PVOID) &myBuffer,
sizeof(myBuffer));
·
WDF_MEMORY_DESCRIPTOR
memoryDescriptor;
·
WDFMEMORY
memoryHandle = NULL;
·
status = WdfMemoryCreate(NULL,
·
NonPagedPool,
·
POOL_TAG,
·
MY_BUFFER_SIZE,
·
&memoryHandle,
·
NULL);
·
WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(&memoryDescriptor,
·
memoryHandle,
·
NULL);
WDF_MEMORY_DESCRIPTOR writeBufDesc;
WDFMEMORY wdfMemory;
ULONG writeSize, bytesWritten;
size_t bufferSize;
NTSTATUS status;
writeSize = SMALL_BUF_LEN;
status = WdfMemoryCreate(
WDF_NO_OBJECT_ATTRIBUTES,
NonPagedPool,
0,
writeSize,
&wdfMemory,
NULL
);
if (!NT_SUCCESS(status)){
return status;
}
writeBuffer = WdfMemoryGetBuffer(
wdfMemory,
&bufferSize
);
FillMyBuffer(
writeBuffer,
writeSize
);
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
&writeBufDesc,
writeBuffer,
writeSize
);
status = WdfUsbTargetPipeWriteSynchronously(
pipeHandle,
NULL,
NULL,
&writeBufDesc,
&bytesWritten
);
(21) WdfUsbTargetPipeReadSynchronously
函数功能：builds a read request and sends it synchronously to a specified
USB input pipe.
NTSTATUS WdfUsbTargetPipeReadSynchronously(
[in]
WDFUSBPIPE Pipe, //input 端点
[in, optional]
WDFREQUEST Request, //Request
[in, optional]
PWDF_REQUEST_SEND_OPTIONS RequestOptions,
[in, optional]
PWDF_MEMORY_DESCRIPTOR MemoryDescriptor,
[out, optional]
PULONG BytesRead //指向接收数据的指针
);
Pipe [in]
A handle to a framework pipe object that was obtained by calling
WdfUsbInterfaceGetConfiguredPipe.
Request [in,
optional]
A handle to a framework request object. This parameter is optional and can be NULL. For more information, see the following Remarks section.
RequestOptions
[in, optional]
A pointer to a caller-allocated
WDF_REQUEST_SEND_OPTIONS structure that specifies options for the request. This pointer is optional and can be NULL. For more information, see
the following Remarks section.
MemoryDescriptor
[in, optional]
A pointer to a caller-allocated
WDF_MEMORY_DESCRIPTOR structure that describes the buffer that will receive data from the device. The buffer size must be a multiple of the pipe's
maximum packet size unless the driver has called
WdfUsbTargetPipeSetNoMaximumPacketSizeCheck. For more information about this buffer, see the following Remarks section.
BytesRead
[out, optional]
A pointer to a location that receives the number of bytes that were read, if the operation succeeds. This parameter is optional and can be NULL
Msdn example
WDFMEMORY wdfMemory;
WDF_MEMORY_DESCRIPTOR readBufDesc;
ULONG BytesRead;
status = WdfMemoryCreate(
WDF_NO_OBJECT_ATTRIBUTES,
NonPagedPool,
0,
readSize,
&wdfMemory,
NULL
);
if (!NT_SUCCESS(status)){
return ;
}
buffer = WdfMemoryGetBuffer(
wdfMemory,
NULL
);
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
&readBufDesc,
buffer,
readSize
);
status = WdfUsbTargetPipeReadSynchronously(
Pipe, //input端点号，端点6
NULL,
NULL,
&readBufDesc, //缓冲区，缓冲区的大小必须是maxpacketsize的整数倍
&BytesRead
);
(22)WdfUsbTargetPipeFormatRequestForWrite
函数功能：builds a write request for a USB output pipe, but it does not send
the request （用来完成写管道的准备工作）。
NTSTATUS WdfUsbTargetPipeFormatRequestForWrite(
[in] WDFUSBPIPE Pipe,
// 管道句柄
[in] WDFREQUEST Request,
//Request对象句柄，可以是新建的，也可以是老对象的重用
[in, optional] WDFMEMORY WriteMemory,//Memory句柄，内部含有一块含有写内容的缓冲区
[in, optional] PWDFMEMORY_OFFSET WriteOffset //缓冲偏移，如果为NULL，表示从缓冲区的头部开始写。
);
将一个Request句柄和一个Memory句柄，关联到这个管道上，使用Request句柄用来跟踪写操作的各个阶段（开始，完成等），Memory
句柄用来存储需要写到管道的数据。
（23）WdfUsbTargetPipeFormatRequestForRead
函数功能：用来完成读管道的准备工作，参数和写操作一样，作用也很相近。
NTSTATUS WdfUsbTargetPipeFormatRequestForRead(
[in] WDFUSBPIPE Pipe,
[in] WDFREQUEST Request,
[in, optional] WDFMEMORY ReadMemory,
[in, optional] PWDFMEMORY_OFFSET ReadOffset
);
(24) UsbBuildInterruptOrBulkTransferRequest
函数功能：macro formats an
URB to send or receive data on a bulk pipe, or to receive data from an interrupt pipe.
void UsbBuildInterruptOrBulkTransferRequest(
__inout
PURB Urb,
__in
USHORT Length,
__in
USBD_PIPE_HANDLE PipeHandle,
__in_opt
PVOID TransferBuffer,
__in_opt
PMDL TransferBufferMDL,
__in
ULONG TransferBufferLength,
__in
ULONG TransferFlags,
__in
PURB Link
);
Urb [in, out]
Pointer to an
URB to be formatted as an interrupt or bulk transfer request.
Length [in]
Specifies the size, in bytes, of the
URB.
PipeHandle [in]
Specifies the handle for this pipe returned by the HCD when a configuration was selected.
TransferBuffer
[in, optional]
Pointer to a resident buffer for the transfer or is NULL if an MDL is supplied in
TransferBufferMDL. The contents of this buffer depend on the value of
TransferFlags. If USBD_TRANSFER_DIRECTION_IN is specified, this buffer will contain data read from the device on return from the HCD. Otherwise, this buffer contains driver-supplied data to be transferred to the device.
TransferBufferMDL
[in, optional]
Pointer to an MDL that describes a resident buffer or is NULL if a buffer is supplied in
TransferBuffer. The contents of the buffer depend on the value of TransferFlags. If USBD_TRANSFER_DIRECTION_IN is specified, the described buffer will contain data read from the device on return from the HCD. Otherwise, the buffer contains
driver-supplied data to be transferred to the device. The MDL must be allocated from nonpaged pool.
TransferBufferLength
[in]
Specifies the length, in bytes, of the buffer specified in
TransferBuffer or described in TransferBufferMDL.
TransferFlags
[in]
Specifies zero, one, or a combination of the following flags:
USBD_TRANSFER_DIRECTION_IN
Is set to request data from a device. To transfer data to a device, this flag must be clear.
USBD_SHORT_TRANSFER_OK
Can be used if USBD_TRANSFER_DIRECTION_IN is set. If set, directs the HCD not to return an error if a packet is received from the device that is shorter than the maximum packet size
for the endpoint. Otherwise, a short request returns an error condition.
Link [in]
Reserved. Must be set to NULL.
(25) WdfUsbTargetPipeFormatRequestForUrb
函数功能：builds an USB request for a specified USB pipe, using request
parameters that a specified URB describes, but it does not send the
request.
NTSTATUS WdfUsbTargetPipeFormatRequestForUrb(
[in] WDFUSBPIPE Pipe,
//usb管道
[in] WDFREQUEST Request,
[in] WDFMEMORY UrbMemory,
[in, optional] PWDFMEMORY_OFFSET UrbMemoryOffset
);
Parameters
Pipe [in]
A handle to a framework pipe object that was obtained by calling
WdfUsbInterfaceGetConfiguredPipe.
Request [in]
A handle to a framework request object. For more information, see the following Remarks section.
UrbMemory
[in]
A handle to a framework memory object that contains a
URB structure.
UrbMemoryOffset
[in, optional]
A pointer to a caller-allocated
WDFMEMORY_OFFSET structure that supplies optional byte offset and length values. The framework uses these values to determine the beginning address
of the URB within the memory that UrbMemory specifies. If this pointer is NULL,
the URB is located at the beginning of the UrbMemory memory.
(26) WdfRequestSend
函数功能：sends a specified I/O request to a specified I/O target.
BOOLEAN
WdfRequestSend(
[in]
WDFREQUEST Request,
[in]
WDFIOTARGET Target,
[in, optional]
PWDF_REQUEST_SEND_OPTIONS RequestOptions
);
参数：
Request [in]
A handle to a framework request object.
Target [in]
A handle to a framework I/O target object. For more information about how to obtain this handle, see the following Remarks section.
RequestOptions
[in, optional]
A pointer to a
WDF_REQUEST_SEND_OPTIONS structure that contains caller-supplied request options. This parameter is optional and can be NULL if you do not want
to enable any request options.
Target
可以通过WdfUsbTargetDeviceGetIoTarget
or WdfUsbTargetPipeGetIoTarget获取。
返回值：
returns TRUE if the request was sent to the target. Otherwise, this method returns FALSE.
A bug check occurs if the driver supplies an invalid object handle.
(27)直接I/O和Buffer
I/O的区别
Direct I/O
：window
锁住用户缓冲的内存，然后传给驱动一个MDL(Memory descriptor list)，用户内存和系统内存映射到同一段物理内存，这样，无论应用程序线程怎么切换，都没有影响。
Buffer I/O: I/O管理器create
和用户缓冲区大小一样的系统缓冲区，将用户缓冲区的数据copy到系统缓冲区中，然后在Irp中将传递系统缓冲区的指针，驱动程序读写系统缓冲区，然后将数据传递给用户缓冲区。这种方法的优点是，简单，缺点是需要在用户缓冲和系统缓冲之间不断切换，耗资源。
(28)
WDF_PNPPOWER_EVENT_CALLBACKS_INIT
//初始化即插即用和电源管理例程配置结构
WDF_PNPPOWER_EVENT_CALLBACKS_INIT(&pnpPowerCallbacks);
pnpPowerCallbacks.EvtDevicePrepareHardware =
USBSample_EvtDevicePrepareHardware;
pnpPowerCallbacks.EvtDeviceReleaseHardware
= USBSample_EvtDeviceReleaseHardware;
//设置即插即用基本例程
函数功能：
initializes a driver's
WDF_PNPPOWER_EVENT_CALLBACKS structure
参数：
Callbacks
[out]
A pointer to a driver-allocated
WDF_PNPPOWER_EVENT_CALLBACKS structure.
评论：
The
WDF_PNPPOWER_EVENT_CALLBACKS_INIT function zeros the
specified
WDF_PNPPOWER_EVENT_CALLBACKS structure and sets the structure's
Size member.
typedef struct _WDF_PNPPOWER_EVENT_CALLBACKS {
ULONG Size;
PFN_WDF_DEVICE_D0_ENTRY EvtDeviceD0Entry;
PFN_WDF_DEVICE_D0_ENTRY_POST_INTERRUPTS_ENABLED EvtDeviceD0EntryPostInterruptsEnabled;
PFN_WDF_DEVICE_D0_EXIT EvtDeviceD0Exit;
PFN_WDF_DEVICE_D0_EXIT_PRE_INTERRUPTS_DISABLED EvtDeviceD0ExitPreInterruptsDisabled;
PFN_WDF_DEVICE_PREPARE_HARDWARE EvtDevicePrepareHardware;
PFN_WDF_DEVICE_RELEASE_HARDWARE EvtDeviceReleaseHardware;
PFN_WDF_DEVICE_SELF_MANAGED_IO_CLEANUP EvtDeviceSelfManagedIoCleanup;
PFN_WDF_DEVICE_SELF_MANAGED_IO_FLUSH EvtDeviceSelfManagedIoFlush;
PFN_WDF_DEVICE_SELF_MANAGED_IO_INIT EvtDeviceSelfManagedIoInit;
PFN_WDF_DEVICE_SELF_MANAGED_IO_SUSPEND EvtDeviceSelfManagedIoSuspend;
PFN_WDF_DEVICE_SELF_MANAGED_IO_RESTART EvtDeviceSelfManagedIoRestart;
PFN_WDF_DEVICE_SURPRISE_REMOVAL EvtDeviceSurpriseRemoval;
PFN_WDF_DEVICE_QUERY_REMOVE EvtDeviceQueryRemove;
PFN_WDF_DEVICE_QUERY_STOP EvtDeviceQueryStop;
PFN_WDF_DEVICE_USAGE_NOTIFICATION EvtDeviceUsageNotification;
PFN_WDF_DEVICE_RELATIONS_QUERY EvtDeviceRelationsQuery;
} WDF_PNPPOWER_EVENT_CALLBACKS, *PWDF_PNPPOWER_EVENT_CALLBACKS;
WdfDeviceInitSetPnpPowerEventCallbacks
函数功能：registers a driver's Plug and Play and power management event callback functions.
VOID WdfDeviceInitSetPnpPowerEventCallbacks(
[in] PWDFDEVICE_INIT DeviceInit,
[in] PWDF_PNPPOWER_EVENT_CALLBACKS PnpPowerEventCallbacks
);
WDFDEVICE_INIT
是一个不透明的结构，is defined and allocated by the framework。
参数：
DeviceInit
[in]
A caller-supplied pointer to a
WDFDEVICE_INIT structure.
PnpPowerEventCallbacks
[in]
A pointer to a caller-initialized
WDF_PNPPOWER_EVENT_CALLBACKS structure.
评论：
If your driver calls
WdfDeviceInitSetPnpPowerEventCallbacks, it must do so before it calls
WdfDeviceCreate.
WDF_PNPPOWER_EVENT_CALLBACKS
pnpPowerCallbacks;
WDF_PNPPOWER_EVENT_CALLBACKS_INIT(&pnpPowerCallbacks);
pnpPowerCallbacks.EvtDevicePrepareHardware = SerialEvtPrepareHardware;
pnpPowerCallbacks.EvtDeviceReleaseHardware = SerialEvtReleaseHardware;
pnpPowerCallbacks.EvtDeviceD0Entry = SerialEvtDeviceD0Entry;
pnpPowerCallbacks.EvtDeviceD0Exit = SerialEvtDeviceD0Exit;
WdfDeviceInitSetPnpPowerEventCallbacks(
DeviceInit,
&pnpPowerCallbacks
);
(29)
ObReferenceObjectByHandle
函数功能：provides access validation on the object handle, and, if access
can be granted, returns the corresponding pointer to the object's body.
NTSTATUS
ObReferenceObjectByHandle(
IN HANDLE Handle,
//
IN ACCESS_MASK DesiredAccess,
IN POBJECT_TYPE ObjectType OPTIONAL,
IN KPROCESSOR_MODE AccessMode,
OUT PVOID *Object,
OUT POBJECT_HANDLE_INFORMATION HandleInformation OPTIONAL
);
参数：
Handle: Specifies an open handle for an object
DesiredAccess: Specifies the requested types of access
to the object. The interpretation of this field is dependent on the object type. Do not use any generic access rights.
ObjectType
Pointer to the object type. ObjectType can be *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsProcessType, *PsThreadType, *SeTokenObjectType, *TmEnlistmentObjectType,
*TmResourceManagerObjectType, *TmTransactionManagerObjectType, or *TmTransactionObjectType.
Note The SeTokenObjectType object type is supported in Windows XP and later versions of Windows.
If ObjectType is not NULL, the operating system verifies that the supplied object type matches the object type of the object that Handle specifies.
AccessMode
Specifies the access mode to use for the access check. It must be either
UserMode or KernelMode. Lower-level drivers should specify
KernelMode.
Object
Pointer to a variable that receives a pointer to the object's body. The following table contains the pointer types.
HandleInformation
Drivers set this to NULL.
返回值：
STATUS_SUCCESS
STATUS_OBJECT_TYPE_MISMATCH
STATUS_ACCESS_DENIED
STATUS_INVALID_HANDLE
调用示例：
//构造内核事件
status =
ObReferenceObjectByHandle(hEvent,
SYNCHRONIZE,
*ExEventObjectType,
UserMode,
&pQueueContext->Event,
NULL
);
PQUEUE_CONTEXT pQueueContext;
(30)
WdfObjectContextGetObject
函数功能：The WdfObjectContextGetObject method returns a handle to
the framework object that a specified context space belongs to。
WDFOBJECT
WdfObjectContextGetObject(
IN PVOID ContextPointer
);
ContextPointer
A pointer to object context space. The driver can obtain this pointer by calling
WdfObjectGetTypedContext.
The following code example obtains a handle to the framework object that a specified context space belongs to.
WDFDEVICE device;
device = WdfObjectContextGetObject(DeviceContext);
(31)
WDF_USB_CONTINUOUS_READER_CONFIG_INIT(宏)
函数功能：function initializes a
WDF_USB_CONTINUOUS_READER_CONFIG structure.
VOID
WDF_USB_CONTINUOUS_READER_CONFIG_INIT(
PWDF_USB_CONTINUOUS_READER_CONFIG Config,
PFN_WDF_USB_READER_COMPLETION_ROUTINE EvtUsbTargetPipeReadComplete,
WDFCONTEXT EvtUsbTargetPipeReadCompleteContext,
size_t TransferLength
);
参数说明：
Config
A pointer to a
WDF_USB_CONTINUOUS_READER_CONFIG structure.
EvtUsbTargetPipeReadComplete
A pointer to the driver's
EvtUsbTargetPipeReadComplete callback function.
EvtUsbTargetPipeReadCompleteContext
An untyped pointer to driver-defined context information that the framework passes to the driver's EvtUsbTargetPipeReadComplete
callback function.
TransferLength
The maximum length, in bytes, of data that can be received from the device.
评论：
The
WDF_USB_CONTINUOUS_READER_CONFIG_INIT function zeros the specified
WDF_USB_CONTINUOUS_READER_CONFIG structure and sets the structure's
Size member. It also sets the structure's EvtUsbTargetPipeReadComplete,
EvtUsbTargetPipeReadCompleteContext, and TransferLength members to the specified values.
WDF_USB_CONTINUOUS_READER_CONFIG结构：
typedef struct _WDF_USB_CONTINUOUS_READER_CONFIG {
ULONG Size; //结构的长度
size_t TransferLength;// The maximum length,
in bytes, of data that can be received from the device.
size_t HeaderLength;//an offset,in bytes
size_t TrailerLength;
//
UCHAR NumPendingReads;
PWDF_OBJECT_ATTRIBUTES BufferAttributes;
PFN_WDF_USB_READER_COMPLETION_ROUTINE EvtUsbTargetPipeReadComplete;
WDFCONTEXT EvtUsbTargetPipeReadCompleteContext;
PFN_WDF_USB_READERS_FAILED EvtUsbTargetPipeReadersFailed;
} WDF_USB_CONTINUOUS_READER_CONFIG, *PWDF_USB_CONTINUOUS_READER_CONFIG;
NumPendingReads
The number of read requests that the framework will queue to receive data from the I/O target. If this value is zero, the framework uses a default number of read requests. If the specified
value is greater than the permitted maximum, the framework uses the permitted maximum. For more information about the
NumPendingReads member, see the following Comments section.
BufferAttributes
A
WDF_OBJECT_ATTRIBUTES structure that specifies object attributes for the framework memory object that the framework creates for each read request. This member can be NULL. You cannot set the
ParentObject member of the WDF_OBJECT_ATTRIBUTES structure.
EvtUsbTargetPipeReadComplete
A pointer to the driver's
EvtUsbTargetPipeReadComplete callback function.
EvtUsbTargetPipeReadCompleteContext
An untyped pointer to driver-defined context information that the framework passes to the driver's
EvtUsbTargetPipeReadComplete callback function.
EvtUsbTargetPipeReadersFailed
A pointer to the driver's
EvtUsbTargetPipeReadersFailed callback function.
(32)
WdfUsbTargetPipeConfigContinuousReader
函数功能：configures the framework to continuously read from a specified
USB pipe.
NTSTATUS
WdfUsbTargetPipeConfigContinuousReader(
IN WDFUSBPIPE Pipe,
IN PWDF_USB_CONTINUOUS_READER_CONFIG Config
);
Pipe
A handle to a framework pipe object that was obtained by calling
WdfUsbInterfaceGetConfiguredPipe.
Config
A pointer to a caller-allocated
WDF_USB_CONTINUOUS_READER_CONFIG structure.
返回值：如果操作成功，返回STATUS,否则返回：
STATUS_INFO_LENGTH_MISMATCH
STATUS_INVALID_PARAMETER
STATUS_INSUFFICIENT_RESOURCES
STATUS_INVALID_DEVICE_REQUEST
STATUS_INVALID_BUFFER_SIZE
(14) WDF_REQUEST_SEND_OPTIONS_INIT
函数功能：initializes a driver's
WDF_REQUEST_SEND_OPTIONS structure
VOID
WDF_REQUEST_SEND_OPTIONS_INIT(
OUT PWDF_REQUEST_SEND_OPTIONS Options,
IN ULONG Flags
);
Options
A pointer to a caller-supplied
WDF_REQUEST_SEND_OPTIONS structure.
Flags
A bitwise OR of
WDF_REQUEST_SEND_OPTIONS_FLAGS-typed flags.
（15）WDF_REQUEST_SEND_OPTIONS_SET_TIMEOUT
函数功能：sets a time-out value in a driver's
WDF_REQUEST_SEND_OPTIONS structure.
VOID WDF_REQUEST_SEND_OPTIONS_SET_TIMEOUT(
__out
PWDF_REQUEST_SEND_OPTIONS Options,
__in
LONGLONG Timeout
);
Timeout
如果为负数，那么是相对于系统时间而言的，如果timeout为正数，那么是一个绝对的时间，为0就表示没有超时。
Options [out]
A pointer to the driver's
WDF_REQUEST_SEND_OPTIONS structure.
Timeout [in]
An absolute or relative time-out value. For more information, see the
Timeout member of the
WDF_REQUEST_SEND_OPTIONS structure.
typedef struct _WDF_REQUEST_SEND_OPTIONS {
ULONG
Size;
ULONG
Flags;
LONGLONG Timeout;
} WDF_REQUEST_SEND_OPTIONS, *PWDF_REQUEST_SEND_OPTIONS;
Members
Size
The size, in bytes, of this structure.
Flags
A bitwise OR of
WDF_REQUEST_SEND_OPTIONS_FLAGS-typed flags.
Timeout
A time-out value, in system time units (100-nanosecond intervals). If the driver has set the WDF_REQUEST_SEND_OPTION_TIMEOUT flag, the framework cancels the associated I/O request if
it is not completed within the specified time-out period. The time-out value can be negative, positive, or zero, as follows:
·
If the value is negative, the expiration time is relative to the current system time.
·
If the value is positive, the expiration time is specified as an absolute time (which is actually relative to January 1, 1601).
·
If the value is zero, the framework does not time out the request.
Relative expiration times are not affected by any changes to the system time that might occur within the specified time-out period. Absolute expiration times do reflect system time changes.
The framework provides
time conversion functions that convert time values into system time units.
If the framework cancels an I/O request because the specified time-out period has elapsed, the framework provides a completion status of STATUS_IO_TIMEOUT for the I/O request. However,
after the time-out period elapses, the I/O target might complete the I/O request before the framework is able to cancel it. In that case, the I/O request's completion status will not be STATUS_IO_TIMEOUT.
评论：
The
WDF_REQUEST_SEND_OPTIONS structure is passed to object methods that send an I/O request to an I/O target, such as the
WdfRequestSend method. The structure must be initialized by calling the
WDF_REQUEST_SEND_OPTIONS_INIT and
WDF_REQUEST_SEND_OPTIONS_SET_TIMEOUT functions.
(16) WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR
//vendor,class等
函数功能：初始化控制传输包，设置要传递的批量传输字节数
WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR(
&controlSetupPacket,
BmRequestHostToDevice,
BmRequestToDevice,
0,
dwBytes,
0
);
VOID WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR(
__out
PWDF_USB_CONTROL_SETUP_PACKET Packet, //setup_packet
__in
WDF_USB_BMREQUEST_DIRECTION Direction, //主机to设备或者设备to主机
__in
WDF_USB_BMREQUEST_RECIPIENT Recipient,//请求to设备，请求to接口，请求to端点
__in
BYTE Request, //请求类型F1
__in
USHORT Value,
__in
USHORT Index
);
(17)WdfUsbTargetDeviceSendControlTransferSynchronously
函数功能：builds a USB control transfer request and sends it synchronously
to an I/O target.
NTSTATUS WdfUsbTargetDeviceSendControlTransferSynchronously(
[in]
WDFUSBDEVICE UsbDevice,
[in, optional]
WDFREQUEST Request,
[in, optional]
PWDF_REQUEST_SEND_OPTIONS RequestOptions,
[in]
PWDF_USB_CONTROL_SETUP_PACKET SetupPacket,
[in, optional]
PWDF_MEMORY_DESCRIPTOR MemoryDescriptor,
[out, optional]
PULONG BytesTransferred
);
UsbDevice [in]
A handle to a USB device object that was obtained from a previous call to
WdfUsbTargetDeviceCreate.
Request [in,
optional]
A handle to a framework request object. This parameter is optional and can be NULL. For more information, see the following Remarks section.
RequestOptions
[in, optional]
A pointer to a caller-allocated
WDF_REQUEST_SEND_OPTIONS structure that specifies options for the request. This pointer is optional and can be NULL. For more information, see the following Remarks
section.
SetupPacket [in]
A pointer to a caller-allocated
WDF_USB_CONTROL_SETUP_PACKET structure that describes the control transfer.
MemoryDescriptor
[in, optional]
A pointer to a caller-allocated
WDF_MEMORY_DESCRIPTOR structure that describes either an input or an output buffer, depending on the device-specific command. This pointer is optional and can be NULL.
For more information, see the following Remarks section.
BytesTransferred
[out, optional]
A pointer to a location that receives the number of bytes that are transferred. This parameter is optional and can be NULL.
Return Value
：STATUS_IO_TIMEOUT STATUS_INVALID_PARAMETER
STATUS_INSUFFICIENT_RESOURCES,
STATUS_INVALID_DEVICE_REQUEST
成功返回
//控制传输VENDOR命令
status = WdfUsbTargetDeviceSendControlTransferSynchronously(
pDeviceContext->UsbDevice,
WDF_NO_HANDLE,
&syncReqOptions,
&controlSetupPacket,
NULL,
NULL
);
Msdn:例子
WDF_USB_CONTROL_SETUP_PACKET controlSetupPacket;
WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR(
&controlSetupPacket,
BmRequestHostToDevice,
BmRequestToDevice,
USBFX2LK_REENUMERATE,
0,
0
);
status = WdfUsbTargetDeviceSendControlTransferSynchronously(
UsbDevice,
WDF_NO_HANDLE,
NULL,
&controlSetupPacket,
NULL,
NULL
);
return status;
(18) WdfUsbTargetDeviceResetPortSynchronously
函数功能：resets the USB port that is associated with the specified USB
device.
NTSTATUS WdfUsbTargetDeviceResetPortSynchronously(
[in] WDFUSBDEVICE UsbDevice
);
参数：UsbDevice:usb设备对象句柄
在设置I/O target’s usb port以前，取消保持在I/O
target’s queue里面的所有I/O请求，驱动程序不能发送其他的I/O请求，直到WdfUsbTargetDeviceResetPortSynchronously返回。
在发送WdfUsbTargetDeviceResetPortSynchronously函数之前，必须调用WdfIoTargetStop，在调用该函数后，驱动can
call WdfIoTargetStart函数。
Msdn
例子：
NTSTATUS status;
status = WdfUsbTargetDeviceResetPortSynchronously(UsbDevice);
(19) WDF_MEMORY_DESCRIPTOR_INIT_BUFFER
函数功能：initializes a
WDF_MEMORY_DESCRIPTOR structure so that it describes a specified buffer.
VOID WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
__out
PWDF_MEMORY_DESCRIPTOR Descriptor,
__in
PVOID Buffer,
__in
ULONG BufferLength
);
Descriptor [out]
A pointer to a
WDF_MEMORY_DESCRIPTOR structure.
Buffer [in]
A pointer to a memory buffer.
BufferLength
[in]
The size, in bytes, of the memory buffer that
Buffer points to.
typedef struct _WDF_MEMORY_DESCRIPTOR {
WDF_MEMORY_DESCRIPTOR_TYPE Type;
union {
struct {
PVOID Buffer;
ULONG Length;
} BufferType;
struct {
PMDL
Mdl;
ULONG BufferLength;
} MdlType;
struct {
WDFMEMORY
Memory;
PWDFMEMORY_OFFSET Offsets;
} HandleType;
} u;
} WDF_MEMORY_DESCRIPTOR, *PWDF_MEMORY_DESCRIPTOR;
//批量传输数据块初始化
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&bufDesc,buffer,bufSize);
WDF_REQUEST_SEND_OPTIONS_INIT(&syncReqOptions, 0);
WDF_REQUEST_SEND_OPTIONS_SET_TIMEOUT(&syncReqOptions, -1000000);
(20) WdfUsbTargetPipeWriteSynchronously
函数功能：builds a write request and sends it synchronously to a specified
USB output pipe.
NTSTATUS WdfUsbTargetPipeWriteSynchronously(
[in]
WDFUSBPIPE Pipe,
[in, optional]
WDFREQUEST Request,
[in, optional]
PWDF_REQUEST_SEND_OPTIONS RequestOptions,
[in, optional]
PWDF_MEMORY_DESCRIPTOR MemoryDescriptor,
[out, optional]
PULONG BytesWritten
);
Pipe [in]
A handle to a framework pipe object that was obtained by calling
WdfUsbInterfaceGetConfiguredPipe.
Request [in,
optional]
A handle to a framework request object. This parameter is optional and can be NULL. For more information, see the following Remarks section.
RequestOptions
[in, optional]
A pointer to a caller-allocated
WDF_REQUEST_SEND_OPTIONS structure that specifies options for the request. This pointer is optional and can be NULL. For more information, see the following Remarks
section.
MemoryDescriptor
[in, optional]
A pointer to a caller-allocated
WDF_MEMORY_DESCRIPTOR structure that describes the buffer that contains data that will be written to the device. For more information about this buffer, see the following
Remarks section.
BytesWritten
[out, optional] :
A pointer to a location that receives the number of bytes written, if the operation succeeds. This parameter is optional and can be NULL.
Supply a local buffer:
Because handles I/O requests synchronously, the driver can create request buffers that are local to the calling routine, as the following code example shows.
Copy Code
WDF_MEMORY_DESCRIPTOR memoryDescriptor;
MY_BUFFER_TYPE myBuffer;
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&memoryDescriptor,
(PVOID) &myBuffer,
sizeof(myBuffer));
·
WDF_MEMORY_DESCRIPTOR
memoryDescriptor;
·
WDFMEMORY
memoryHandle = NULL;
·
status = WdfMemoryCreate(NULL,
·
NonPagedPool,
·
POOL_TAG,
·
MY_BUFFER_SIZE,
·
&memoryHandle,
·
NULL);
·
WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(&memoryDescriptor,
·
memoryHandle,
·
NULL);
WDF_MEMORY_DESCRIPTOR writeBufDesc;
WDFMEMORY wdfMemory;
ULONG writeSize, bytesWritten;
size_t bufferSize;
NTSTATUS status;
writeSize = SMALL_BUF_LEN;
status = WdfMemoryCreate(
WDF_NO_OBJECT_ATTRIBUTES,
NonPagedPool,
0,
writeSize,
&wdfMemory,
NULL
);
if (!NT_SUCCESS(status)){
return status;
}
writeBuffer = WdfMemoryGetBuffer(
wdfMemory,
&bufferSize
);
FillMyBuffer(
writeBuffer,
writeSize
);
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
&writeBufDesc,
writeBuffer,
writeSize
);
status = WdfUsbTargetPipeWriteSynchronously(
pipeHandle,
NULL,
NULL,
&writeBufDesc,
&bytesWritten
);
(21) WdfUsbTargetPipeReadSynchronously
函数功能：builds a read request and sends it synchronously to a specified
USB input pipe.
NTSTATUS WdfUsbTargetPipeReadSynchronously(
[in]
WDFUSBPIPE Pipe, //input 端点
[in, optional]
WDFREQUEST Request, //Request
[in, optional]
PWDF_REQUEST_SEND_OPTIONS RequestOptions,
[in, optional]
PWDF_MEMORY_DESCRIPTOR MemoryDescriptor,
[out, optional]
PULONG BytesRead //指向接收数据的指针
);
Pipe [in]
A handle to a framework pipe object that was obtained by calling
WdfUsbInterfaceGetConfiguredPipe.
Request [in,
optional]
A handle to a framework request object. This parameter is optional and can be NULL. For more information, see the following Remarks section.
RequestOptions
[in, optional]
A pointer to a caller-allocated
WDF_REQUEST_SEND_OPTIONS structure that specifies options for the request. This pointer is optional and can be NULL. For more information, see
the following Remarks section.
MemoryDescriptor
[in, optional]
A pointer to a caller-allocated
WDF_MEMORY_DESCRIPTOR structure that describes the buffer that will receive data from the device. The buffer size must be a multiple of the pipe's
maximum packet size unless the driver has called
WdfUsbTargetPipeSetNoMaximumPacketSizeCheck. For more information about this buffer, see the following Remarks section.
BytesRead
[out, optional]
A pointer to a location that receives the number of bytes that were read, if the operation succeeds. This parameter is optional and can be NULL
Msdn example
WDFMEMORY wdfMemory;
WDF_MEMORY_DESCRIPTOR readBufDesc;
ULONG BytesRead;
status = WdfMemoryCreate(
WDF_NO_OBJECT_ATTRIBUTES,
NonPagedPool,
0,
readSize,
&wdfMemory,
NULL
);
if (!NT_SUCCESS(status)){
return ;
}
buffer = WdfMemoryGetBuffer(
wdfMemory,
NULL
);
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
&readBufDesc,
buffer,
readSize
);
status = WdfUsbTargetPipeReadSynchronously(
Pipe, //input端点号，端点6
NULL,
NULL,
&readBufDesc, //缓冲区，缓冲区的大小必须是maxpacketsize的整数倍
&BytesRead
);
(22)WdfUsbTargetPipeFormatRequestForWrite
函数功能：builds a write request for a USB output pipe, but it does not send
the request （用来完成写管道的准备工作）。
NTSTATUS WdfUsbTargetPipeFormatRequestForWrite(
[in] WDFUSBPIPE Pipe,
// 管道句柄
[in] WDFREQUEST Request,
//Request对象句柄，可以是新建的，也可以是老对象的重用
[in, optional] WDFMEMORY WriteMemory,//Memory句柄，内部含有一块含有写内容的缓冲区
[in, optional] PWDFMEMORY_OFFSET WriteOffset //缓冲偏移，如果为NULL，表示从缓冲区的头部开始写。
);
将一个Request句柄和一个Memory句柄，关联到这个管道上，使用Request句柄用来跟踪写操作的各个阶段（开始，完成等），Memory
句柄用来存储需要写到管道的数据。
（23）WdfUsbTargetPipeFormatRequestForRead
函数功能：用来完成读管道的准备工作，参数和写操作一样，作用也很相近。
NTSTATUS WdfUsbTargetPipeFormatRequestForRead(
[in] WDFUSBPIPE Pipe,
[in] WDFREQUEST Request,
[in, optional] WDFMEMORY ReadMemory,
[in, optional] PWDFMEMORY_OFFSET ReadOffset
);
(24) UsbBuildInterruptOrBulkTransferRequest
函数功能：macro formats an
URB to send or receive data on a bulk pipe, or to receive data from an interrupt pipe.
void UsbBuildInterruptOrBulkTransferRequest(
__inout
PURB Urb,
__in
USHORT Length,
__in
USBD_PIPE_HANDLE PipeHandle,
__in_opt
PVOID TransferBuffer,
__in_opt
PMDL TransferBufferMDL,
__in
ULONG TransferBufferLength,
__in
ULONG TransferFlags,
__in
PURB Link
);
Urb [in, out]
Pointer to an
URB to be formatted as an interrupt or bulk transfer request.
Length [in]
Specifies the size, in bytes, of the
URB.
PipeHandle [in]
Specifies the handle for this pipe returned by the HCD when a configuration was selected.
TransferBuffer
[in, optional]
Pointer to a resident buffer for the transfer or is NULL if an MDL is supplied in
TransferBufferMDL. The contents of this buffer depend on the value of
TransferFlags. If USBD_TRANSFER_DIRECTION_IN is specified, this buffer will contain data read from the device on return from the HCD. Otherwise, this buffer contains driver-supplied data to be transferred to the device.
TransferBufferMDL
[in, optional]
Pointer to an MDL that describes a resident buffer or is NULL if a buffer is supplied in
TransferBuffer. The contents of the buffer depend on the value of TransferFlags. If USBD_TRANSFER_DIRECTION_IN is specified, the described buffer will contain data read from the device on return from the HCD. Otherwise, the buffer contains
driver-supplied data to be transferred to the device. The MDL must be allocated from nonpaged pool.
TransferBufferLength
[in]
Specifies the length, in bytes, of the buffer specified in
TransferBuffer or described in TransferBufferMDL.
TransferFlags
[in]
Specifies zero, one, or a combination of the following flags:
USBD_TRANSFER_DIRECTION_IN
Is set to request data from a device. To transfer data to a device, this flag must be clear.
USBD_SHORT_TRANSFER_OK
Can be used if USBD_TRANSFER_DIRECTION_IN is set. If set, directs the HCD not to return an error if a packet is received from the device that is shorter than the maximum packet size
for the endpoint. Otherwise, a short request returns an error condition.
Link [in]
Reserved. Must be set to NULL.
(25) WdfUsbTargetPipeFormatRequestForUrb
函数功能：builds an USB request for a specified USB pipe, using request
parameters that a specified URB describes, but it does not send the
request.
NTSTATUS WdfUsbTargetPipeFormatRequestForUrb(
[in] WDFUSBPIPE Pipe,
//usb管道
[in] WDFREQUEST Request,
[in] WDFMEMORY UrbMemory,
[in, optional] PWDFMEMORY_OFFSET UrbMemoryOffset
);
Parameters
Pipe [in]
A handle to a framework pipe object that was obtained by calling
WdfUsbInterfaceGetConfiguredPipe.
Request [in]
A handle to a framework request object. For more information, see the following Remarks section.
UrbMemory
[in]
A handle to a framework memory object that contains a
URB structure.
UrbMemoryOffset
[in, optional]
A pointer to a caller-allocated
WDFMEMORY_OFFSET structure that supplies optional byte offset and length values. The framework uses these values to determine the beginning address
of the URB within the memory that UrbMemory specifies. If this pointer is NULL,
the URB is located at the beginning of the UrbMemory memory.
(26) WdfRequestSend
函数功能：sends a specified I/O request to a specified I/O target.
BOOLEAN
WdfRequestSend(
[in]
WDFREQUEST Request,
[in]
WDFIOTARGET Target,
[in, optional]
PWDF_REQUEST_SEND_OPTIONS RequestOptions
);
参数：
Request [in]
A handle to a framework request object.
Target [in]
A handle to a framework I/O target object. For more information about how to obtain this handle, see the following Remarks section.
RequestOptions
[in, optional]
A pointer to a
WDF_REQUEST_SEND_OPTIONS structure that contains caller-supplied request options. This parameter is optional and can be NULL if you do not want
to enable any request options.
Target
可以通过WdfUsbTargetDeviceGetIoTarget
or WdfUsbTargetPipeGetIoTarget获取。
返回值：
returns TRUE if the request was sent to the target. Otherwise, this method returns FALSE.
A bug check occurs if the driver supplies an invalid object handle.
(27)直接I/O和Buffer
I/O的区别
Direct I/O
：window
锁住用户缓冲的内存，然后传给驱动一个MDL(Memory descriptor list)，用户内存和系统内存映射到同一段物理内存，这样，无论应用程序线程怎么切换，都没有影响。
Buffer I/O: I/O管理器create
和用户缓冲区大小一样的系统缓冲区，将用户缓冲区的数据copy到系统缓冲区中，然后在Irp中将传递系统缓冲区的指针，驱动程序读写系统缓冲区，然后将数据传递给用户缓冲区。这种方法的优点是，简单，缺点是需要在用户缓冲和系统缓冲之间不断切换，耗资源。
(28)
WDF_PNPPOWER_EVENT_CALLBACKS_INIT
//初始化即插即用和电源管理例程配置结构
WDF_PNPPOWER_EVENT_CALLBACKS_INIT(&pnpPowerCallbacks);
pnpPowerCallbacks.EvtDevicePrepareHardware =
USBSample_EvtDevicePrepareHardware;
pnpPowerCallbacks.EvtDeviceReleaseHardware
= USBSample_EvtDeviceReleaseHardware;
//设置即插即用基本例程
函数功能：
initializes a driver's
WDF_PNPPOWER_EVENT_CALLBACKS structure
参数：
Callbacks
[out]
A pointer to a driver-allocated
WDF_PNPPOWER_EVENT_CALLBACKS structure.
评论：
The
WDF_PNPPOWER_EVENT_CALLBACKS_INIT function zeros the
specified
WDF_PNPPOWER_EVENT_CALLBACKS structure and sets the structure's
Size member.
typedef struct _WDF_PNPPOWER_EVENT_CALLBACKS {
ULONG Size;
PFN_WDF_DEVICE_D0_ENTRY EvtDeviceD0Entry;
PFN_WDF_DEVICE_D0_ENTRY_POST_INTERRUPTS_ENABLED EvtDeviceD0EntryPostInterruptsEnabled;
PFN_WDF_DEVICE_D0_EXIT EvtDeviceD0Exit;
PFN_WDF_DEVICE_D0_EXIT_PRE_INTERRUPTS_DISABLED EvtDeviceD0ExitPreInterruptsDisabled;
PFN_WDF_DEVICE_PREPARE_HARDWARE EvtDevicePrepareHardware;
PFN_WDF_DEVICE_RELEASE_HARDWARE EvtDeviceReleaseHardware;
PFN_WDF_DEVICE_SELF_MANAGED_IO_CLEANUP EvtDeviceSelfManagedIoCleanup;
PFN_WDF_DEVICE_SELF_MANAGED_IO_FLUSH EvtDeviceSelfManagedIoFlush;
PFN_WDF_DEVICE_SELF_MANAGED_IO_INIT EvtDeviceSelfManagedIoInit;
PFN_WDF_DEVICE_SELF_MANAGED_IO_SUSPEND EvtDeviceSelfManagedIoSuspend;
PFN_WDF_DEVICE_SELF_MANAGED_IO_RESTART EvtDeviceSelfManagedIoRestart;
PFN_WDF_DEVICE_SURPRISE_REMOVAL EvtDeviceSurpriseRemoval;
PFN_WDF_DEVICE_QUERY_REMOVE EvtDeviceQueryRemove;
PFN_WDF_DEVICE_QUERY_STOP EvtDeviceQueryStop;
PFN_WDF_DEVICE_USAGE_NOTIFICATION EvtDeviceUsageNotification;
PFN_WDF_DEVICE_RELATIONS_QUERY EvtDeviceRelationsQuery;
} WDF_PNPPOWER_EVENT_CALLBACKS, *PWDF_PNPPOWER_EVENT_CALLBACKS;
WdfDeviceInitSetPnpPowerEventCallbacks
函数功能：registers a driver's Plug and Play and power management event callback functions.
VOID WdfDeviceInitSetPnpPowerEventCallbacks(
[in] PWDFDEVICE_INIT DeviceInit,
[in] PWDF_PNPPOWER_EVENT_CALLBACKS PnpPowerEventCallbacks
);
WDFDEVICE_INIT
是一个不透明的结构，is defined and allocated by the framework。
参数：
DeviceInit
[in]
A caller-supplied pointer to a
WDFDEVICE_INIT structure.
PnpPowerEventCallbacks
[in]
A pointer to a caller-initialized
WDF_PNPPOWER_EVENT_CALLBACKS structure.
评论：
If your driver calls
WdfDeviceInitSetPnpPowerEventCallbacks, it must do so before it calls
WdfDeviceCreate.
WDF_PNPPOWER_EVENT_CALLBACKS
pnpPowerCallbacks;
WDF_PNPPOWER_EVENT_CALLBACKS_INIT(&pnpPowerCallbacks);
pnpPowerCallbacks.EvtDevicePrepareHardware = SerialEvtPrepareHardware;
pnpPowerCallbacks.EvtDeviceReleaseHardware = SerialEvtReleaseHardware;
pnpPowerCallbacks.EvtDeviceD0Entry = SerialEvtDeviceD0Entry;
pnpPowerCallbacks.EvtDeviceD0Exit = SerialEvtDeviceD0Exit;
WdfDeviceInitSetPnpPowerEventCallbacks(
DeviceInit,
&pnpPowerCallbacks
);
(29)
ObReferenceObjectByHandle
函数功能：provides access validation on the object handle, and, if access
can be granted, returns the corresponding pointer to the object's body.
NTSTATUS
ObReferenceObjectByHandle(
IN HANDLE Handle,
//
IN ACCESS_MASK DesiredAccess,
IN POBJECT_TYPE ObjectType OPTIONAL,
IN KPROCESSOR_MODE AccessMode,
OUT PVOID *Object,
OUT POBJECT_HANDLE_INFORMATION HandleInformation OPTIONAL
);
参数：
Handle: Specifies an open handle for an object
DesiredAccess: Specifies the requested types of access
to the object. The interpretation of this field is dependent on the object type. Do not use any generic access rights.
ObjectType
Pointer to the object type. ObjectType can be *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsProcessType, *PsThreadType, *SeTokenObjectType, *TmEnlistmentObjectType,
*TmResourceManagerObjectType, *TmTransactionManagerObjectType, or *TmTransactionObjectType.
Note The SeTokenObjectType object type is supported in Windows XP and later versions of Windows.
If ObjectType is not NULL, the operating system verifies that the supplied object type matches the object type of the object that Handle specifies.
AccessMode
Specifies the access mode to use for the access check. It must be either
UserMode or KernelMode. Lower-level drivers should specify
KernelMode.
Object
Pointer to a variable that receives a pointer to the object's body. The following table contains the pointer types.
HandleInformation
Drivers set this to NULL.
返回值：
STATUS_SUCCESS
STATUS_OBJECT_TYPE_MISMATCH
STATUS_ACCESS_DENIED
STATUS_INVALID_HANDLE
调用示例：
//构造内核事件
status =
ObReferenceObjectByHandle(hEvent,
SYNCHRONIZE,
*ExEventObjectType,
UserMode,
&pQueueContext->Event,
NULL
);
PQUEUE_CONTEXT pQueueContext;
(30)
WdfObjectContextGetObject
函数功能：The WdfObjectContextGetObject method returns a handle to
the framework object that a specified context space belongs to。
WDFOBJECT
WdfObjectContextGetObject(
IN PVOID ContextPointer
);
ContextPointer
A pointer to object context space. The driver can obtain this pointer by calling
WdfObjectGetTypedContext.
The following code example obtains a handle to the framework object that a specified context space belongs to.
WDFDEVICE device;
device = WdfObjectContextGetObject(DeviceContext);
(31)
WDF_USB_CONTINUOUS_READER_CONFIG_INIT(宏)
函数功能：function initializes a
WDF_USB_CONTINUOUS_READER_CONFIG structure.
VOID
WDF_USB_CONTINUOUS_READER_CONFIG_INIT(
PWDF_USB_CONTINUOUS_READER_CONFIG Config,
PFN_WDF_USB_READER_COMPLETION_ROUTINE EvtUsbTargetPipeReadComplete,
WDFCONTEXT EvtUsbTargetPipeReadCompleteContext,
size_t TransferLength
);
参数说明：
Config
A pointer to a
WDF_USB_CONTINUOUS_READER_CONFIG structure.
EvtUsbTargetPipeReadComplete
A pointer to the driver's
EvtUsbTargetPipeReadComplete callback function.
EvtUsbTargetPipeReadCompleteContext
An untyped pointer to driver-defined context information that the framework passes to the driver's EvtUsbTargetPipeReadComplete
callback function.
TransferLength
The maximum length, in bytes, of data that can be received from the device.
评论：
The
WDF_USB_CONTINUOUS_READER_CONFIG_INIT function zeros the specified
WDF_USB_CONTINUOUS_READER_CONFIG structure and sets the structure's
Size member. It also sets the structure's EvtUsbTargetPipeReadComplete,
EvtUsbTargetPipeReadCompleteContext, and TransferLength members to the specified values.
WDF_USB_CONTINUOUS_READER_CONFIG结构：
typedef struct _WDF_USB_CONTINUOUS_READER_CONFIG {
ULONG Size; //结构的长度
size_t TransferLength;// The maximum length,
in bytes, of data that can be received from the device.
size_t HeaderLength;//an offset,in bytes
size_t TrailerLength;
//
UCHAR NumPendingReads;
PWDF_OBJECT_ATTRIBUTES BufferAttributes;
PFN_WDF_USB_READER_COMPLETION_ROUTINE EvtUsbTargetPipeReadComplete;
WDFCONTEXT EvtUsbTargetPipeReadCompleteContext;
PFN_WDF_USB_READERS_FAILED EvtUsbTargetPipeReadersFailed;
} WDF_USB_CONTINUOUS_READER_CONFIG, *PWDF_USB_CONTINUOUS_READER_CONFIG;
NumPendingReads
The number of read requests that the framework will queue to receive data from the I/O target. If this value is zero, the framework uses a default number of read requests. If the specified
value is greater than the permitted maximum, the framework uses the permitted maximum. For more information about the
NumPendingReads member, see the following Comments section.
BufferAttributes
A
WDF_OBJECT_ATTRIBUTES structure that specifies object attributes for the framework memory object that the framework creates for each read request. This member can be NULL. You cannot set the
ParentObject member of the WDF_OBJECT_ATTRIBUTES structure.
EvtUsbTargetPipeReadComplete
A pointer to the driver's
EvtUsbTargetPipeReadComplete callback function.
EvtUsbTargetPipeReadCompleteContext
An untyped pointer to driver-defined context information that the framework passes to the driver's
EvtUsbTargetPipeReadComplete callback function.
EvtUsbTargetPipeReadersFailed
A pointer to the driver's
EvtUsbTargetPipeReadersFailed callback function.
(32)
WdfUsbTargetPipeConfigContinuousReader
函数功能：configures the framework to continuously read from a specified
USB pipe.
NTSTATUS
WdfUsbTargetPipeConfigContinuousReader(
IN WDFUSBPIPE Pipe,
IN PWDF_USB_CONTINUOUS_READER_CONFIG Config
);
Pipe
A handle to a framework pipe object that was obtained by calling
WdfUsbInterfaceGetConfiguredPipe.
Config
A pointer to a caller-allocated
WDF_USB_CONTINUOUS_READER_CONFIG structure.
返回值：如果操作成功，返回STATUS,否则返回：
STATUS_INFO_LENGTH_MISMATCH
STATUS_INVALID_PARAMETER
STATUS_INSUFFICIENT_RESOURCES
STATUS_INVALID_DEVICE_REQUEST
STATUS_INVALID_BUFFER_SIZE
内容来自用户分享和网络整理，不保证内容的准确性，如有侵权内容，可联系管理员处理 
相关文章推荐
- windows wdf 驱动开发总结(1)--usb驱动
- windows wdf 驱动开发总结(3)-usb驱动
- windows wdf 驱动开发总结(9)--网络驱动开发(NDIS)
- windows wdf 驱动开发总结(4)--usb驱动
- windows wdf 驱动开发总结(8)--网络驱动开发(NDIS)
- 开发wince下的usb音频设备驱动总结
- Linux USB 驱动开发（五）—— USB驱动程序开发过程简单总结
- Linux USB 驱动开发（五）—— USB驱动程序开发过程简单总结
- windows wdf 驱动开发总结(5)--PCI 驱动
- 开发wince下的usb音频设备驱动总结
- Windows USB功能驱动开发总结
- Windows USB功能驱动开发总结
- Linux USB 驱动开发（五）—— USB驱动程序开发过程简单总结
- Linux USB 驱动开发（五）—— USB驱动程序开发过程简单总结
- windows WDF 驱动开发总结（6）----PCI驱动开发
- 开发wince下的usb音频设备驱动总结
- windows WDF驱动开发总结（7）--网络驱动开发（NDIS）
- windows xp 驱动开发(十八) USB驱动程序开发用到的工具总结
- 开发wince下的usb音频设备驱动总结
- Linux USB 驱动开发（二）—— USB 驱动几个重要数据结构