windows wdf 驱动开发总结(4)--usb驱动
(73) WdfIoTargetStart
函数功能：starts sending queued requests to a local or remote I/O target.
NTSTATUS WdfIoTargetStart(
[in] WDFIOTARGET IoTarget
);
参数：IoTarget [in]
A handle to a local or remote I/O target object that was obtained from a previous call to WdfDeviceGetIoTarget or WdfIoTargetCreate, or from a method that a specialized I/O target provides.
（74）WdfDeviceGetIoTarget
函数功能：returns a handle to a function or filter driver's local I/O target, for a specified device
WDFIOTARGET WdfDeviceGetIoTarget(
[in] WDFDEVICE Device
);
参数：A handle to a framework device object.
(75) WdfIoTargetCreate
函数功能：creates a remote I/O target for a specified device.
NTSTATUS WdfIoTargetCreate(
[in] WDFDEVICE Device,
[in, optional] PWDF_OBJECT_ATTRIBUTES IoTargetAttributes,
[out] WDFIOTARGET *IoTarget
);
参数：
Device [in]
A handle to a framework device object.
IoTargetAttributes [in, optional]
A pointer to a caller-allocated WDF_OBJECT_ATTRIBUTES structure that specifies object attributes for the I/O target object. This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES.
IoTarget [out]
A pointer to a location that receives a handle to an I/O target object.
评论：
WdfIoTargetCreate returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method might return one of the following values:
（76）WdfUsbTargetPipeGetIoTarget
函数功能：a handle to the I/O target object that is associated with a specified USB pipe.
WDFIOTARGET WdfUsbTargetPipeGetIoTarget(
[in] WDFUSBPIPE Pipe
);
参数：
Pipe [in]
A handle to a framework pipe object that was obtained by calling WdfUsbInterfaceGetConfiguredPipe.
返回值：
returns a handle to the I/O target object that is associated with the specified pipe object.
(77) WdfIoTargetStop
函数功能：sending queued requests to a local or remote I/O target.
VOID WdfIoTargetStop(
[in] WDFIOTARGET IoTarget,
[in] WDF_IO_TARGET_SENT_IO_ACTION Action
);
参数：
IoTarget [in]
A handle to a local or remote I/O target object that was obtained from a previous call to WdfDeviceGetIoTarget or WdfIoTargetCreate, or from a method that a specialized I/O target supplies.
Action [in]
A WDF_IO_TARGET_SENT_IO_ACTION-typed value that specifies how the framework should handle I/O requests that the driver has sent to the I/O target, if the target has not completed the requests.
评论：
If your driver can detect recoverable device errors, you might want your driver to call to temporarily stop sending requests, then later call WdfIoTargetStart to resume sending requests.
typedef enum _WDF_IO_TARGET_SENT_IO_ACTION {
WdfIoTargetSentIoUndefined = 0,
WdfIoTargetCancelSentIo = 1,
WdfIoTargetWaitForSentIoToComplete = 2,
WdfIoTargetLeaveSentIoPending = 3
} WDF_IO_TARGET_SENT_IO_ACTION;
参数：
WdfIoTargetSentIoUndefined
Reserved for system use.
WdfIoTargetCancelSentIo
Before the framework stops the I/O target, it will attempt to cancel I/O requests that are in the I/O target's queue. The framework cancels all of the target queue's I/O requests, and waits for all I/O requests to complete, before WdfIoTargetStop returns.
WdfIoTargetWaitForSentIoToComplete
Before the framework stops the I/O target, it will wait for I/O requests that are in the I/O target's queue to be completed. The framework completes all of the target queue's I/O requests, and calls each request's CompletionRoutine callback function, before WdfIoTargetStop returns.
WdfIoTargetLeaveSentIoPending
The framework will leave I/O requests in the I/O target's queue. The requests remain in the target's queue until the driver calls WdfIoTargetStart or the device is removed.
（78）WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_SINGLE_INTERFACE
函数功能：initializes a WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure so that a driver can configure a device to use a single, specified interface
VOID WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_SINGLE_INTERFACE(
__out PWDF_USB_DEVICE_SELECT_CONFIG_PARAMS Params
);
参数：
Params [out]
A pointer to a driver-allocated WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure.
评论：
The WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure specifies USB device configuration parameters.
typedef struct _WDF_USB_DEVICE_SELECT_CONFIG_PARAMS {
ULONG Size;
WdfUsbTargetDeviceSelectConfigType Type;
union {
struct {
PUSB_CONFIGURATION_DESCRIPTOR ConfigurationDescriptor;
PUSB_INTERFACE_DESCRIPTOR *InterfaceDescriptors;
ULONG NumInterfaceDescriptors;
} Descriptor;
struct {
PURB Urb;
} Urb;
struct {
UCHAR NumberConfiguredPipes;
WDFUSBINTERFACE ConfiguredUsbInterface;
} SingleInterface;
struct {
UCHAR NumberInterfaces;
PWDF_USB_INTERFACE_SETTING_PAIR Pairs;
UCHAR NumberOfConfiguredInterfaces;
} MultiInterface;
} Types;
} WDF_USB_DEVICE_SELECT_CONFIG_PARAMS, *PWDF_USB_DEVICE_SELECT_CONFIG_PARAMS;
(79) WdfUsbTargetDeviceSelectConfig
函数功能：selects a USB configuration for a device, or it deconfigures the device.
NTSTATUS WdfUsbTargetDeviceSelectConfig(
[in] WDFUSBDEVICE UsbDevice,
[in, optional] PWDF_OBJECT_ATTRIBUTES PipeAttributes,
[in, out] PWDF_USB_DEVICE_SELECT_CONFIG_PARAMS Params
);
参数：
UsbDevice [in]
A handle to a USB device object that was obtained from a previous call to WdfUsbTargetDeviceCreate.
PipeAttributes [in, optional]
A pointer to a caller-allocated WDF_OBJECT_ATTRIBUTES structure that contains attributes for new framework USB pipe objects that the framework creates for the device's interfaces. This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES.
Params [in, out]
A pointer to a caller-allocated WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure that the caller and the framework use to specify configuration parameters.
(80) WdfUsbTargetPipeSetNoMaximumPacketSizeCheck(检查是否buffer是maximum packet size的整数倍)
函数功能：disables the framework's test of whether the size of a driver's read buffer is a multiple of a USB pipe's maximum packet size.
VOID WdfUsbTargetPipeSetNoMaximumPacketSizeCheck(
[in] WDFUSBPIPE Pipe
);
Pipe [in]
A handle to a framework pipe object that was obtained by calling WdfUsbInterfaceGetConfiguredPipe.
评论：
To avoid receiving extra data from unexpected bus activity, which is sometimes called babble, drivers usually specify read buffers that are a multiple of the pipe's maximum packet size. (Drivers receive a USB pipe's maximum packet size in a WDF_USB_PIPE_INFORMATION structure.) By default, the framework reports an error if a driver specifies a read buffer that is not a multiple of the pipe's maximum packet size. If the driver calls, the framework does not report an error if a read buffer is not a multiple of the maximum packet size.For more information about the method and USB I/O targets, see USB I/O Targets.
(81) WDF_USB_CONTINUOUS_READER_CONFIG_INIT
函数功能：initializes a WDF_USB_CONTINUOUS_READER_CONFIG structure.
VOID WDF_USB_CONTINUOUS_READER_CONFIG_INIT(
__out PWDF_USB_CONTINUOUS_READER_CONFIG Config,
__in PFN_WDF_USB_READER_COMPLETION_ROUTINE EvtUsbTargetPipeReadComplete,
__in WDFCONTEXT EvtUsbTargetPipeReadCompleteContext,
__in size_t TransferLength
);
参数：
Config [out]
A pointer to a WDF_USB_CONTINUOUS_READER_CONFIG structure.
EvtUsbTargetPipeReadComplete [in]
A pointer to the driver's EvtUsbTargetPipeReadComplete callback function.
EvtUsbTargetPipeReadCompleteContext [in]
An untyped pointer to driver-defined context information that the framework passes to the driver's EvtUsbTargetPipeReadComplete callback function.
TransferLength [in]
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_READ_CONFIG 结构：
typedef struct _WDF_USB_CONTINUOUS_READER_CONFIG {
ULONG Size;
size_t TransferLength;
size_t HeaderLength;
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;
参数：
Size
The size, in bytes, of this structure.
TransferLength
The maximum length, in bytes, of data that can be received from the device.
HeaderLength
An offset, in bytes, into the buffer that receives data from the device. The framework will store data from the device in a read buffer, beginning at the offset value. In other words, this space precedes the TransferLength-sized space in which the framework stores data from the device.
TrailerLength
The length, in bytes, of a trailing buffer space. This space follows the TransferLength-sized space in which the framework stores data from the device.
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 Remarks 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.
评论：
The WDF_USB_CONTINUOUS_READER_CONFIG structure is used as input to the WdfUsbTargetPipeConfigContinuousReader method.
To initialize a WDF_USB_CONTINUOUS_READER_CONFIG structure, the driver must call WDF_USB_CONTINUOUS_READER_CONFIG_INIT.
(82) 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 [in]
A handle to a framework pipe object that was obtained by calling WdfUsbInterfaceGetConfiguredPipe.
Config [in]
A pointer to a caller-allocated WDF_USB_CONTINUOUS_READER_CONFIG structure.
返回值： returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method can return one of the following values:STATUS_INFO_LENGTH_MISMATCH,STATUS_INVALID_PARAMETER,
STATUS_INSUFFICIENT_RESOURCES,STATUS_INVALID_DEVICE_REQUEST, STATUS_INTEGER_OVERFLOW , STATUS_INVALID_BUFFER_SIZE
评论：
可以配置continuous reader ,对bulk或interrupt 传输，管道必须有一个输入端点,在使用WdfusbTargetPipeConfigContinuousReader配置continuous reader,驱动必须调用WdfIoTargetStart开始读请求，调用WdfIoTargetStop停止读请求。一般，驱动在EvtDevicePrepareHardware的回调函数中调用WdfusbTargetPipeConfigContinuousReader，在EvtDeviceD0Entry回调函数中调用WdfIoTargetStart,在EvtDeviceD0Exit回调函数中调用WdfIoTargetStop.
每次管道 I/O target 成功完成一个read request，framework调用驱动的EVtUsbTargetPipeREadComplete 回调函数。如果I/O target 报告失败，framework调用EvtUsbTargetPipeReadersFailed回调函数（在所有的read requests 都完成以后）。(Therefore, the EvtUsbTargetPipeReadComplete callback function will not be called while the EvtUsbTargetPipeReadersFailed callback function is executing.)
After a driver has called WdfusbTargetPipeConfigContinuousReader, the driver cannot use WdfUsbTargetPipeReadSynchronously or WdfRequestSend to send I/O requests to the pipe unless the driver's EvtUsbTargetPipeReadersFailed callback function is called and returns FALSE.
The framework sets the USBD_SHORT_TRANSFER_OK flag in its internal URB. Setting this flag allows the last packet of a data transfer to be less than the maximum packet size.
（83）WdfRequestRetrieveUnsafeUserInputBuffer
函数功能：retrieves an I/O request's input buffer, if the request's technique for accessing data buffers is neither buffered nor direct I/O.
NTSTATUS WdfRequestRetrieveUnsafeUserInputBuffer(
[in] WDFREQUEST Request,
[in] size_t MinimumRequiredLength,
[out] PVOID *InputBuffer,
[out, optional] size_t *Length
);
参数：
Request [in]
A handle to a framework request object.
MinimumRequiredLength [in]
The minimum buffer size, in bytes, that the driver needs to process the I/O request.
InputBuffer [out]
A pointer to a location that receives the buffer's address.
Length [out, optional]
A pointer to a location that receives the buffer's size, in bytes. This parameter is optional and can be NULL.
(84) WdfRequestRetrieveUnsafeUserOutputBuffer
函数功能：retrieves an I/O request's output buffer, if the request's technique for accessing data buffers is neither buffered nor direct I/O.
NTSTATUS WdfRequestRetrieveUnsafeUserOutputBuffer(
[in] WDFREQUEST Request,
[in] size_t MinimumRequiredLength,
[out] PVOID *OutputBuffer,
[out, optional] size_t *Length
);
参数：
Request [in]
A handle to a framework request object.
MinimumRequiredLength [in]
The minimum buffer size, in bytes, that the driver needs to process the I/O request.
OutputBuffer [out]
A pointer to a location that receives the buffer's address.
Length [out, optional]
A pointer to a location that receives the buffer's size, in bytes. This parameter is optional and can be NULL.
评论：
The WdfRequestRetrieveUnsafeUserOutputBuffer method must be called from an EvtIoInCallerContext callback function. After calling WdfRequestRetrieveUnsafeUserOutputBuffer, the driver must call WdfRequestProbeAndLockUserBufferForWrite.
(85) IoBuildDeviceIoControlRequest(WDM)
函数功能：allocates and sets up an IRP for a synchronously processed device control request.
函数主要用来构造一个用于设备i/o控制请求的irp包，该irp包将被同步处理。
PIRP IoBuildDeviceIoControlRequest(
__in ULONG IoControlCode,
__in PDEVICE_OBJECT DeviceObject,
__in_opt PVOID InputBuffer,
__in ULONG InputBufferLength,
__out_opt PVOID OutputBuffer,
__in ULONG OutputBufferLength,
__in BOOLEAN InternalDeviceIoControl,
__in PKEVENT Event,
__out PIO_STATUS_BLOCK IoStatusBlock
);
参数：
IoControlCode：
提供i/o控制请求所需的i/o控制码。这个i/o控制码可以在msdn中查询到。
DeviceObject：
指向下层驱动的设备对象的指针。这个就是构造的irp要被发向的目标对象。
InputBuffer：
指向输入缓冲区的指针，这个缓冲区中的内容是给下层驱动使用的。此指针可为NULL。
InputBufferLength [in]
输入缓冲区的长度，按字节计算。如果InputBuffer为NULL，则此参数必须为0。
OutputBuffer：
指向输出缓冲区的指针，这个缓冲区是用于给下层驱动返回数据用的。此指针可为NULL。
OutputBufferLength
输出缓冲区的长度，按字节计算。如果OutputBuffer为NULL，则此参数必须为0。
InternalDeviceIoControl：
如果此参数为TRUE，这个函数设置所构造的irp的主函数码（major function code）为IRP_MJ_INTERNAL_DEVICE_CONTROL，否则这个函数设置所构造的irp的主函数码（major function code）为IRP_MJ _DEVICE_CONTROL。
Event：
提供一个指向事件对象的指针，该事件对象由调用者分配并初始化。当下层驱动程序完成这个irp请求时i/o管理器将此事件对象设置为通知状态（signaled）。当调用IoCallDriver后，调用者可以等待这个事件对象成为通知状态。
IoStatusBlock：
调用者指定一个i/o状态块，当这个irp完成时，下层驱动会把相应信息填入这个i/o状态块。
返回值：
当这个函数调用成功时，将返回一个指向所构造的irp的指针并且下一层驱动的i/o堆栈会根据调用此函数提供的参数设置好，若调用失败，将返回NULL。
注意事项：
1、 此函数构造的irp包将被同步处理。当构造好irp包后，调用者调用IoCallDriver将这个irp发送给目标对象，如果IoCallDriver返回STATUS_PENDING，调用者必须调用KeWaitForSingleObject等待调用IoBuildDeviceIoControlRequest时所提供的那个Event。对于大多数的驱动程序我们不用给该irp设置完成函数。
2、 由IoBuildDeviceIoControlRequest构造的irp必须由某个驱动调用IoCompleteRequest来完成，并且注意调用IoBuildDeviceIoControlRequest的驱动程序不能调用IoFreeIrp来释放这些构造的irp，因为i/o管理器会在IoCompleteRequest被调用后自动释放这些irp。
3、 IoBuildDeviceIoControlRequest将把它构造的irp放在当前线程特有的一个irp队列上，如果当前线程退出，则i/o管理器将取消这些irp。
4、 InputBuffer和OutputBuffer这两个参数如何存放在所构造的irp中将取决于IoControlCode的TransferType，具体可查相关资料。
5、 IoBuildDeviceIoControlRequest的调用者必须运行在IRQL <= APC_LEVEL。
6、 这个函数并不初始化所构造irp中的FileObject指针，因此如果你在写和文件系统相关的驱动，你必须自己初始化这个指针。
7、 使用IoBuildDeviceIoControlRequest构造的irp其主函数代码只能是IRP_MJ_DEVICE_CONTROL 或IRP_MJ_INTERNAL_DEVICE_CONTROL。
(86)Windbg 的！devnode命令，可以列举系统中的设备树。
Bug：为什么驱动怎是返回 STATUS_PENDING,并且推迟完成这个控制操作。注意：ERROR_IO_PENDING 并不是一个真正的错误。
(1-2)HIDUSBFX2
The HIDUSBFX2 sample demonstrates how to write a HID minidriver by using the Microsoft Windows Driver Foundation (WDF). The sample also demonstrates how to map a non-HID USB device to a HID device. The minidriver is written for the OSR USB-FX2 Learning Kit. This device is not HID-compliant and the sample exposes the device as a HID device.
HID设备的缺点是只能使用中断或控制传输。由于对中断传输查询的时间间隔最小为1帧，因而HID设备速度受到了限制。对于一些数据量较少的场合(例如按键输入，LED显示，甚至一些小容量的芯片烧录器等)，使用用户自定义的HID设备是很合适的。
(87) WdfFdoInitSetFilter
函数功能：identifies the calling driver as an upper-level or lower-level filter driver, for a specified device.
VOID WdfFdoInitSetFilter(
[in] PWDFDEVICE_INIT DeviceInit
);
参数：
DeviceInit [in]
A pointer to a WDFDEVICE_INIT structure that the driver obtained from its EvtDriverDeviceAdd callback function.
Filter drivers typically process some I/O requests, but they simply pass most requests to the next driver in the driver stack.
(88) WDF_TIMER_CONFIG_INIT
函数功能：
initializes a WDF_TIMER_CONFIG structure for a timer that will use a single due time.
VOID
WDF_TIMER_CONFIG_INIT(
IN PWDF_TIMER_CONFIG Config,
IN PFN_WDF_TIMER EvtTimerFunc,
);
参数：
Config
A pointer to a WDF_TIMER_CONFIG structure.
EvtTimerFunc
A pointer to a driver-supplied EvtTimerFunc callback function.
评论：
The WDF_TIMER_CONFIG_INIT function zeros the specified WDF_TIMER_CONFIG structure. Then it sets the structure's Size member, stores the EvtTimerFunc pointer, sets the Period member and the TolerableDelay member to zero, and sets the AutomaticSerialization member to TRUE.
WDF_TIMER_CONFIG
The WDF_TIMER_CONFIG structure contains configuration information for a framework timer object.
typedef struct _WDF_TIMER_CONFIG {
ULONG Size;
PFN_WDF_TIMER EvtTimerFunc;
ULONG Period;
BOOLEAN AutomaticSerialization;
ULONG TolerableDelay;
} WDF_TIMER_CONFIG, *PWDF_TIMER_CONFIG;
参数：
Size
The size, in bytes, of this structure.
EvtTimerFunc
A pointer to a driver-supplied EvtTimerFunc callback function, or NULL.
Period
A time period, in milliseconds. The framework calls the driver's EvtTimerFunc callback function repeatedly, whenever the specified number of milliseconds elapses. If this value is zero, the framework does not call the driver's EvtTimerFunc callback function repeatedly. Instead, it calls the callback function once, after the WdfTimerStart method's "due time" has elapsed. (The time period must be zero if WdfTimerCreate sets the execution level to WdfExecutionLevelPassive.) The time period cannot be a negative value.
AutomaticSerialization
A Boolean value that, if TRUE, indicates that the framework will synchronize execution of the timer object's EvtTimerFunc callback function with callback functions from other objects that are underneath the timer's parent device object. For more information, see the following Comments section. If FALSE, the framework does not synchronize execution of the EvtTimerFunc callback function.
TolerableDelay
A time value, in milliseconds, that specifies the maximum amount of additional time that the driver can tolerate after the Period time elapses. The time value cannot be negative. For more information about this member, see the following Comments section. The TolerableDelay member is available in version 1.9 and later versions of KMDF.
（89）WdfTimerCreate
函数功能：creates a framework timer object
NTSTATUS
WdfTimerCreate(
IN PWDF_TIMER_CONFIG Config,
IN PWDF_OBJECT_ATTRIBUTES Attributes,
OUT WDFTIMER* Timer
);
参数：
Config
A pointer to a WDF_TIMER_CONFIG structure.
Attributes
A pointer to a WDF_OBJECT_ATTRIBUTES structure that contains object attributes for the new timer object.
Timer
A pointer to a location that receives a handle to the new framework timer object.
评论：
When your driver calls WdfTimerCreate, it must supply a WDF_OBJECT_ATTRIBUTES structure and must specify a parent object in the structure's ParentObject member. The parent object can be a framework device object or any object whose chain of parents leads to a framework device object. The framework will delete the timer object when it deletes the device object.
After creating a timer object, the driver calls WdfTimerStart to start the timer's clock.
If your driver provides EvtCleanupCallback or EvtDestroyCallback callback functions for the framework timer object, note that the framework calls these callback functions at IRQL = PASSIVE_LEVEL.
调用示例：
WDF_TIMER_CONFIG timerConfig;
WDF_OBJECT_ATTRIBUTES timerAttributes;
WDFTIMER timerHandle;
NTSTATUS status;
WDF_TIMER_CONFIG_INIT(
&timerConfig,
MyEvtTimerFunc
);
timerConfig.AutomaticSerialization = TRUE;
WDF_OBJECT_ATTRIBUTES_INIT(&timerAttributes);
timerAttributes.ParentObject = DeviceHandle;
status = WdfTimerCreate(
&timerConfig,
&timerAttributes,
&timerHandle
);
if (!NT_SUCCESS(status)) {
return status;
}
(90) WPP_CLEANUP
宏定义：deactivates software tracing in a driver.
VOID
WPP_CLEANUP(
IN PDRIVER_OBJECT DriverObject
);
参数：
DriverObject
Pointer to the driver object that represents the driver.
评论：
WPP_CLEANUP deactivates software tracing in a driver. A driver should deactivate software tracing before it unloads.
(91) WdfUsbTargetDeviceGetDeviceDescriptor 获取usb设备描述符
函数功能：retrieves the USB device descriptor for the USB device that is associated with a specified framework USB device object.
VOID
WdfUsbTargetDeviceGetDeviceDescriptor(
IN WDFUSBDEVICE UsbDevice,
OUT PUSB_DEVICE_DESCRIPTOR UsbDeviceDescriptor
);
Parameters
UsbDevice
A handle to a USB device object that was obtained from a previous call to WdfUsbTargetDeviceCreate.
UsbDeviceDescriptor
A pointer to a caller-allocated USB_DEVICE_DESCRIPTOR structure that receives the USB device descriptor.
(92) WdfUsbInterfaceGetConfiguredPipe
函数功能：returns a handle to the framework pipe object that is associated with a specified USB device interface and pipe index. Optionally, the method also returns information about the pipe.
WDFUSBPIPE
WdfUsbInterfaceGetConfiguredPipe(
IN WDFUSBINTERFACE UsbInterface,
IN UCHAR PipeIndex,
OUT OPTIONAL PWDF_USB_PIPE_INFORMATION PipeInfo
);
UsbInterface
A handle to a USB interface object that was obtained by calling WdfUsbTargetDeviceGetInterface.
PipeIndex
A zero-based index into the set of framework pipe objects that are associated with the specified interface object.
PipeInfo
A pointer to a caller-allocated WDF_USB_PIPE_INFORMATION structure that the framework fills in. This parameter is optional and can be NULL.
返回值：
If the operation succeeds, WdfUsbInterfaceGetConfiguredPipe returns a handle to the framework pipe object that is associated with the specified interface object and pipe index. The method returns NULL if the WDF_USB_PIPE_INFORMATION structure's size is incorrect or if the pipe index value is too large.
A bug check occurs if a driver-supplied object handle is invalid.
(93) WdfTimerStart
函数功能：starts a timer's clock.
BOOLEAN
WdfTimerStart(
IN WDFTIMER Timer,
IN LONGLONG DueTime
);
参数：
Timer
A handle to a framework timer object that was obtained by calling WdfTimerCreate.
DueTime
A time period, in system time units (100-nanosecond intervals). The framework calls the driver's EvtTimerFunc callback function when the specified time period elapses. The time period value can be negative or positive as follows:
· If the value is negative, the time period is relative to the current system time.
· If the value is positive, the time period specifies an absolute time (which is actually relative to January 1, 1601).
Relative times are not affected by any changes to the system time that might occur within the specified time period. Absolute times do reflect system time changes.
返回值：
WdfTimerStart returns TRUE if the timer object was in the system's timer queue. Otherwise, this method returns FALSE.
(94) WdfTimerGetParentObject
函数功能：returns a handle to the parent object of a specified framework timer object.
WDFOBJECT
WdfTimerGetParentObject(
IN WDFTIMER Timer
);
Parameters
Timer
A handle to a framework timer object that was obtained by calling WdfTimerCreate.
Return Value
WdfTimerGetParentObject returns a handle to the framework object that is the specified timer object's parent object.
A bug check occurs if the driver supplies an invalid object handle.
调用示例：
The following code example shows now an EvtTimerFunc callback function can obtain a timer object's parent. In this example, the driver previously specified that the timer object's parent is a queue object.
VOID
MyEvtTimerFunc(
IN WDFTIMER Timer
)
{
WDFQUEUE queue;
queue = WdfTimerGetParentObject(Timer);
…
}
(95) 如何建立一个厂商请求
NTSTATUS
SendVendorCommand(
IN WDFDEVICE Device,
IN UCHAR VendorCommand,
IN PUCHAR CommandData
)
/*++
Routine Description
This routine sets the state of the Feature: in this
case Segment Display on the USB FX2 board.
Arguments:
Request - Wdf Request
Return Value:
NT status value
--*/
{
NTSTATUS status = STATUS_SUCCESS;
ULONG bytesTransferred =0;
PDEVICE_EXTENSION pDevContext = NULL;
WDF_MEMORY_DESCRIPTOR memDesc;
WDF_USB_CONTROL_SETUP_PACKET controlSetupPacket;
WDF_REQUEST_SEND_OPTIONS sendOptions;
PAGED_CODE();
TraceEvents(TRACE_LEVEL_VERBOSE, DBG_IOCTL, "SendVendorCommand Enter/n");
pDevContext = GetDeviceContext(Device);
TraceEvents(TRACE_LEVEL_INFORMATION, DBG_IOCTL,
"SendVendorCommand: Command:0x%x, data: 0x%x/n",
VendorCommand, *CommandData);
//
// set the segment state on the USB device
//
// Send the I/O with a timeout. We do that because we send the
// I/O in the context of the user thread and if it gets stuck, it would
// prevent the user process from existing.
//
WDF_REQUEST_SEND_OPTIONS_INIT(&sendOptions,
WDF_REQUEST_SEND_OPTION_TIMEOUT);
WDF_REQUEST_SEND_OPTIONS_SET_TIMEOUT(&sendOptions,
WDF_REL_TIMEOUT_IN_SEC(5)); //5秒
WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR(&controlSetupPacket,
BmRequestHostToDevice,
BmRequestToDevice,
VendorCommand, // Request
0, // Value
0); // Index
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&memDesc,
CommandData,
sizeof(UCHAR));
status = WdfUsbTargetDeviceSendControlTransferSynchronously(
pDevContext->UsbDevice,
WDF_NO_HANDLE, // Optional WDFREQUEST
&sendOptions, // PWDF_REQUEST_SEND_OPTIONS
&controlSetupPacket,
&memDesc,
&bytesTransferred
);
if(!NT_SUCCESS(status)) {
TraceEvents(TRACE_LEVEL_ERROR, DBG_IOCTL,
"SendtVendorCommand: Failed to set Segment Display state - 0x%x /n",
status);
}
TraceEvents(TRACE_LEVEL_VERBOSE, DBG_IOCTL, "SendVendorCommand Exit/n");
return status;
}
(96) WdfMemoryCopyFromBuffer
函数功能：copies the contents of a specified source buffer into a specified memory object's buffer.
NTSTATUS
WdfMemoryCopyFromBuffer(
IN WDFMEMORY DestinationMemory,
IN size_t DestinationOffset,
IN PVOID Buffer,
IN size_t NumBytesToCopyFrom
);
Parameters
DestinationMemory
A handle to a framework memory object that represents the destination buffer.
DestinationOffset
An offset, in bytes, from the beginning of the destination buffer. The copy operation begins at the specified offset in the destination buffer.
Buffer
A pointer to a source buffer.
NumBytesToCopyFrom
The number of bytes to copy from the source buffer to the destination buffer. This value must not be greater than the size of the source buffer.
调用示例：
status = WdfMemoryCopyFromBuffer(memory,
0, // Offset
(PVOID) &G_DefaultHidDescriptor,
bytesToCopy);