DriverStudio的USB编程类函数
DriverWorks提供了三个类：KUsbLowerDevice、KUsbInterface和KUsbPipe类，用于实现USB设备操作。KUsbLowerDevice类用于逻辑设备的编程，KUsbInterface类用于借口的编程，KUsbPipe类用于管道的编程。
1、KUsbLowerDevice类
KUsbLowerDevice类是KPnpLowerDevice类的继承，它继承类KPnpLowerDevice类的成员函数。
KUsbLowerDevice类实例代表端点0，允许USB驱动程序通过默认控制管道控制USB设备，如配置USB设备，传输各种控制和状态请求。
成员函数如下：
★ NTSTATUS Initialize (
KDevice* AttachingDevice,
PDEVICE_OBJECT PhysicalDeviceObject);
初始化一个用默认构造函数定义的KUsbLowerDevice类实例，必须在PASSIVE_LEVEL中断级别上调用该函数。如下所示：
KUsbLowerDevice m_Lower;
M_Lower.Initialize (this, Pdo);
★ AC_STATUS ActiveConfiguration (
UCHAR ConfigurationValue,
ULONG MaxConfigSize = 1024);
激活指定的USB设备配置，在PnP开始例程中使用。
ConfigurationValue为配置号，第1个配置号为1.
MaxConfigSize为声明存放设备配置描述符的最大存储空间字节数。
返回AC_SUCCESS表示成功，还有七种错误代码。
★ NTSTATUS DeActivateConfiguration (
PIO_COMPLETION_ROUTINE pfnCompletionRoutine = NULL,
PVOID pContext = NULL);
终止USB设备当前活动配置，在PnP停止例程中使用。若完成例程为NULL，应在passive_level中断级别上调用该函数。
pfnCompletionRoutine为完成例程，默认为NULL。
pContext为传递给完成例程的环境变量参数，默认为NULL。
★ void ReleaseResources (void);
释放动态分配的USB资源，在PnP删除例程中使用。
★ NTSTATUS GetDeviceDescriptor (PUSB_DEVICE_DESCRIPTOR pDevDesc);
获取设备描述符，必须在PASSIVE_LEVEL中断级别上调用该函数。
pDevDesc存放设备描述符变量的地址。
★ NTSTATUS GetStringDescroptor (
UCHAR Index,
PSTR pStr,
LONG MaxLen,
SHORT LangId);
获取字符串描述符，必须在PASSIVE_LEVEL中断级别上调用该函数。
Index为字符串索引号。
pStr为存放字符串地址。
MaxLen为字符串的最大字节数。
LangId为语言ID号，默认为English/American。
★ ULONG GetCurrentFrameNumber (void);
从系统USB总线驱动程序返回当前USB帧号，在同步传输中可以用作起始帧号。
★ PUSB_INTERFACE_DESCRIPTOR LocateInterface (
PVOID* pStart,
PUSB_ENDPOINT_DESCRIPTOR* ppEndpoints,
LONG InterfaceNumber = -1,
LONG AlternateSetting = -1,
LONG InterfaceClass = -1,
LONG InterfaceSubClass = -1,
LONG InterfaceProtocal = -1);
返回接口描述符，必须在PASSIVE_LEVEL中断级别上调用该函数。
pStart为地址指针。初次调用或重新开始搜索时，置为NULL。调用者不能改变指针数值，仅作为内部重复搜索接口的标志。
ppEndpoints为存放属于该接口的端点阵列。
InterfaceNumber为接口索引号，-1表示非标准值。
InterfaceSetting为要选择的接口设置值，-1表示非标准值。
InterfaceClass为接口类值，-1表示非标准值。
InterfaceSubClass为接口子类值，-1表示非标准值。
InterfaceProtocol为接口协议值，-1表示非标准值。
★ NTSTATUS PreconfigureInterface (
PUSB_INTERFACE_DESCRIPTOR pInterfaceDesc);
指定要配置的接口和相应的管道。
pInterfaceDesc为接口描述符变量地址，由LocateInterface返回。
★ NTSTATUS Preconfigure (
UCHAR ConfigIndex = 0,
ULONG MaxConfigSize = DEFAULT_CONFIG_SIZE);
获取设备配置描述符。若成功返回，其值返回到成员变量m_config中，只能在PASSIVE_LEVEL中断级别上访问该数值。
ConfigIndex为要获取的设备配置描述符的索引号。
MaxConfigSize为申请分配用于存放配置描述符的内存的字节数。
★ NTSTATUS Configure (void);
让系统USB总线驱动程序使设备处于配置状态，只能在PASSIVE_LEVEL中断级别上访问该数据。应先调用PreConfigure和PreconfigureInterface之后，在调用该函数。
★ NTSTATUS Unconfigure (
PIO_COMPLETION_ROUTINE CompletionRoutine = NULL,
PVOID Context = NULL);
调用系统USB总线驱动程序使设备处于未配置状态。若完成例程为NULL，必须在PASSIVE_LEVEL中断级别上调用该函数。
CompletionRoutine为完成例程，默认为NULL。
Contex为传递给完成例程的环境变量参数，默认为NULL。
注意：线面六个成员函数，KUsbInterface和KUsbPipe类也有，后面不再详述。
★ FORM1：PURB BuildVendorRequest (
PUCHAR TransferBuffer,
ULONG TransferBufferLength,
UCHAR RequestTypeReservedBits,
UCHAR Request,
USHORT Value,
BOOLEAN bIn = FALSE,
BOOLEAN bShortOk = FALSE,
PURB Link = NULL,
UCHAR Index = 0,
USHORT Function = URB_FUNCTION_VENDOR_DEVICE,
PURB pUrb = NULL);
FORM2：PURB BuildVendorRequest (
KMemory& TransferBufferMDL,
ULONG TransferBufferLength,
UCHAR RequestTypeReserveBits,
UCHAR Request,
USHORT Value,
BOOLEAN bIn = FALSE,
BOOLEAN bShortOk = FALSE,
PURB Link = NULL,
UCHAR Index = 0,
USHORT Function = URB_FUNCTION_VENDOR_DEVICE,
PURB pUrb = NULL);
分配初始化一个用于厂商请求的URB。
TransferBufferMdl为应用程序存放传输数据的内存，需先变为KMemory类实例。
TransferBuffer为驱动程序存放传输数据的内存区。
TransferBufferLength为传输的字节数，对应于wLength。
RequestTypeReservedBits为类别请求字节中的保留位。
Request为具体请求数值，对应于bRequest。
Value为数值，对应于wValue。
bIn为TURE表示输入，数据从设备到主机；FALSE表示输出，数据从主机到设备。
bShortOk为TRUE标示设备传输的字节数可以少于指定的字节数。
Link为连接下一个传输的URBan，若没有则置NULL。
Index为索引值，对应于wIndex。
Function为类别请求，默认值为URB_FUNCTION_VENDOR_DEVICE。
pUrb若指向一个已经存在的URBan，则初始化该URBan；若置NULL，则分配一个新的URB。
★ PURB BuildClassRequest (
PUCHAR TransferBuffer, //或KMemory & TransferBufferMDL
ULONG TransferBufferLength,
UCHAR RequestTypeReserveBits,
UCHAR Request,
USHORT Value,
BOOLEAN bIn = FALSE,
BOOLEAN bShortOk = FALSE,
PURB Link = NULL,
UCHAR Index = 0,
USHORT Function = URB_FUNCTION_CLASS_DEVICE,
PURB pUrb = NULL);
分配并初始化一个用于类请求的URB。
★ FORM1：NTSTATUS SubmitUrb (
PURB pUrb,
PIO_COMPLETION_ROUTINE CompletionRoutine = NULL,
PVOD CompletionCOntext = NULL,
ULONG mSecTimeOut = 0);
FORM2：NTSTATUS SubmitUrb (
KIrp I,
PURB pUrb,
PIO_COMPLETION_ROUTINE CompletionRoutine = NULL,
PVOID CompletionContext = NULL,
ULONG mSecTimeOut = 0);
将URB发送给系统USB总线驱动程序进行处理。若完成例程为NULL，则必须在PASSIVE_LEVEL中断级别上调用该函数。
FORM1将分配一个IRP，若又完成例程，则完成例程负责删除IRP，并且必须返回STATUS_MORE_PROCESSING_REQUIRED。FORM2由调用者提供一个IRP，用于PnP目的。
I是由调用者提供的IRP。
pUrb是创建的URBan。
CopletionRoutine为完成例程，默认为NULL。
CompletionContext为传递给完成例程的环境参数，默认为NULL。
mSecTimeOut为对同步调用的定时参数，以毫秒为单位。当超过定时参数后，返回STATUS_TIMEOUT。0标示无限期等待。
★ NTSTATUS ClearFeature (
USHORT Feature,
PIO_COMPLETION_ROUTINE CompletionRoutine = NULL,
PVOID Context = NULL);
清除一个特征标志。这个函数分配一个URB，并发送给系统USB总线驱动程序。若完成例程为NULL，则必须在PASSIVE_LEVEL中断级别上调用该函数。若有完成例程，则完成例程负责删除URB，URB由KIrp::Urb函数获得。
Feature为特征值。
CompletionRoutine为完成例程，默认为NULL。
Context为传递给完成例程的环境变量参数，默认为NULL。
★ NTSTATUS SetFeature (
USHORT Feature,
PIO_COMPLETION_ROUTINE CompletionRoutine = NULL,
PVOID Context = NULL);
设置一个特征标志。这个函数分配一个URB，并发送给系统USB总线驱动程序。若完成例程为NULL，则必须在PASSIVE_LEVEL中断级别上调用该函数。若有完成例程，则完成例程负责删除URB，URB由KIrp::Urb函数获得。
Features为特征值。
CompletionRoutine为完成例程，默认为NULL。
Context为传递给完成例程的环境变量参数，默认为NULL。
★ NTSTATUS GetStatus (
PUSHORT pStatus,
PIO_COMPLETION_ROUTINE CompletionRoutine = NULL,
PVOID Context = NULL);
获取状态信息。这个函数分配一个URB，并发送给系统USB总线驱动程序。若完成例程为NULL，则必须在PASSIVE_LEVEL中断级别上调用该函数。若有完成例程，则完成例程负责删除URB，URB由KIrp::Urb函数获得。
pStatus为状态值。
CompletionRoutine为完成例程，默认为NULL。
Context为传递给完成例程的环境变来那个参数，默认为NULL。
2、KUsbInterface类
KUsbInterface类的作用更多的是结构上的而非功能上的，其成员函数几乎不与实际物理设备交互。驱动程序用这个类可获得接口和管道的信息。
成员函数如下：
★ NTSTATUS Initialize (
KUsbInterfaceDevice& Device,
UCHAR InterfaceNumber,
UCHAR ConfigurationValue,
UCHAR InitialAlternateSetting);
初始化一个用默认构造函数定义的KUsbInterface类实例，在IRQL<=DISPATCH_LEVEL中断级别上调用该函数。
Device为KUsbInterfaceDevice类实例。
InterfaceNumber为接口号。
ConfigurationValue为配置号。
InitialAlternateSetting为初始化配置的接口号。
★ SA_STATUS SelectAlternate (UCHAR AlternateSetting);
按指定的接口号重新使能接口。返回SA_SUCCESS，表示成功。
AlternateSetting为所选的接口号。
★ UCHAR AlternateSetting (void);
返回当前的接口号。
★ ULONG NumberOfPipes (void);
返回当前使能接口的管道数量。
★ PUSBD_PIPE_INFORMATION Pipes (int Index = 0);
返回指定索引号的管道信息结构地址。
★ UCHAR Protocol (vod);
返回接口的协议值。
★ UCHAR Subclass (void);
返回借口的子类值。
★ UCHAR Class (void);
返回接口的类值。
★ BOOLEAN IsOpen (void);
测试接口是否打开。返回TRUE，表示已打开。
★ PURB BuildVendorRequest ();
分配并初始化一个用于类请求的URB。
★ NTSTATUS SubmitUrb ();
将URB发送给系统USB总线驱动程序进行处理。
★ NTSTATUS ClearFeature ();
清除一个特征标志。
★ NTSTATUS SetFeature ();
设置一个特征标志。
★ NTSTATUS GetStatus ();
获取状态信息。
KUsbPipe类
KUsbPipe类对应于管道，管道是主机和一个端点的信息链接。
成员函数如下：
★ NTSTATUS Initialize (
KUsbLowerDevice& Device,
UCHAR EndPointAddress,
ULONG MaxTransferSize = 0);
初始化一个用默认构造函数定义的KUsbPipe类实例，在IRQ<=DISPATCH_LEVEL中断级别上调用该函数。
Device为KUsbLowerDevice类实例。
EndpointAddress为端点地址。
MaxTransferSize为管道最大传输字节数。
★ NTSTATUS Reset (void);
复位管道，必须在PASSIVE_LEVEL中断级别上调用该函数。
★ NTSTATUS Abort (void);
放弃管道上未完成的请求，必须在PASSIVE_LEVEL中断级别上调用该函数。
★ UCHAR PollInterval (void);
返回中断传输的中断巡检间隔，以毫秒为单位。
★ FORM1：PURB BuildInterruptTransfer (
KMemory& Mdl,
ULONG Length,
BOOLEAN bShortOk = TRUE,
PURB Link = NULL,
PURB pUrb = NULL);
FORM2：PURB BuildInterruptTransfer (
PVOID Buffer,
ULONG Length,
BOOLEAN bShortOk = TRUE,
PURB Link = NULL,
PURB pUrb = NULL);
分配并一个用于中断传输的URB。
Mdl为应用程序存放传输数据的内存。
Buffer为驱动程序存放传输数据的内存区。
Length为传输的字节数。
bShortOk为TRUE表示设备传输的字节数可以少于指定的字节数。
Link为连接下一个传输的URB，若没有则置为NULL。
pUrb若指向一个已经存在的URB，则初始化该URB；若置为NULL，则分配一个新的URB。
★ PURB BuildControlTransfer (
KMemory& Mdl, //或PVOID Buffer
BOOLEAN bIn,
ULONG Length,
PURB Link = NULL,
PURB pUrb = NULL);
分配并初始化一个用于控制传输的URB。
Mdl为应用程序存放传输数据的内存，需先变为KMemory类实例。
Buffer为驱动程序存放传输数据的内存区。
bIn为TRUE表示输入，数据从设备到主机；FALSE表示输出，数据主机到设备。
Length为传输的字节数。
Link为连接下一个传输的URB，若没有则置为NULL。
pUrb若指向一个已经存在的URB，则初始化该URB，若置为NULL，则分配一个新的URB。
★ PURB NuildBulkTransfer (
KMemory& Mdl, //或PVOID Buffer
ULONG Length,
BOOLEAN bIn,
PURB Link = NULL,
BOOLEAN bShortOk = FALSE,
PURB pUrb = NULL);
分配并初始化一个用于批量传输的URB。
Mdl为应用程序存放传输数据的内存，需县编委KMemory类实例。
Buffer为驱动程序存放传输数据的内存区。
Length为传输的字节数。
Link为连接下一个传输的URB，如没有则置为NULL。
bShortOk为TRUE表示设备传输的字节数可以少于指定的字节数。
bIn为TRUE表示输入，数据从设备到主机；为FALSE表示输出，数据从主机到设备。
pUrb若指向一个已经存在的URBan，则初始化该URBan；若置为NULL，则分配一个新的URB。
★ PURB BuildIsochronousTransfer (
ULONG NumberOfPackets,
ULONG PacketSize,
BOOLEAN bIn,
BOOLEAN bASAP,
ULONG StartFrame,
PVOID Buffer,
ULONG ength,
PURB pUrb = nULL);
分配并初始化一个用于同步传输的URB。
NumberOfPackets为要传输的包的数量。
PacketSize为包的字节数。
bIn为TRUE表示输入，数据从设备到主机；为FALSE表示输出，数据从主机到设备。
bASAP为TRUE表示传输应尽可能快的开始；为FALSE表示设备在收到起始帧号后，传输才开始。
StartFrame为设备开始传输的起始帧号。
Buffer为驱动程序存放传输数据的内存区。
Length为传输的字节数。
pUrb若指向一个已经存在的URBan，则初始化该URBan；若置为NULL，则分配一个新的URB。
★ USBD_PIPE_TYPE Type (void);
返回管道传输类型。
★ UCHAR EndpointAddress (void);
返回管道的端点地址。
★ USHORT MaximumPacketSize (void);
返回最大帧字节数。
★ ULONG MaximumTransferSIze (void);
返回最大传输字节数。
★ void SetMaximumTransferSize (ULONG MaxSize);
设置管道最大传输字节数，应在Configure或ActivateConfiguration之前调用，否则无效果。
★ BOOLEAN IsOpen (void);
测试管道是否打开。返回TRUE，表示已经打开。
★ USBD_PIPE_HANDLE Handle (void);
返回管道句柄，用户驱动程序正常情况下不需要获取管道句柄。
★ PURB BuildVendorRequest ();
分配并初始化一个用于厂商请求的URB。
★ PURB BuildClassRequest ();
分配并初始化一个用于类请求的URB。
★ NTSTATUS SubmitUrb ();
将URB发送给系统USB总线驱动程序进行处理。
★ NTSTATUS ClearFeature ();
清楚一个特征标志。
★ NTSTATUS SetFeature ();
设置一个特征标志。
★ NTSTATUS GetStatus ();
获取状态信息。
