再见绝望先生本子:WDM驱动程序设计之USB总线支持类：KUsbPipe类

WDM驱动程序设计之USB总线支持类：KUsbPipe类

KUsbPipe类
【Overview】
KUsbPipe类抽象了一个USB管道(pipe)，这种机制在USB规格说明书的第5章和第9章有描述。一个管道是一个主机和端点(endpoint)之间的连接。每个端点是互相独立的可寻址的数据使用者或数据提供者。因此一个管道为主机和设备之间的信息交换描绘了一个独特的逻辑上下文(a logically distinct context)。在设备给定的配置下，每个管道都和一个特定的接口联系在一起。
KUsbPipe对象的初始化发生在构造函数或Initialize函数里。初始化要求一个KUsbLowerDevice类实例的参数，这个实例将是把KUsbPipe对象注册到其上的实例。在KUsbLowerDevice被初始化之前，KUsbPipe实例不可能被驱动初始化。
USB规格说明书定义了四种类型的管道：Control,Bulk,Interrupt和Isochronous。每种管道的特征都在USB规格说明书中有详细的说明。KUsbPipe类包含有为每一种传输创建URBs(USB Request Blocks)的成员函数。对于一个给定的管道对象，只有为管道创建合适类型的URB的那个成员函数可以被调用。每当驱动程序为管道创建一个URB，它将调用基类的SubmitUrb函数，将请求传递给USB系统总线驱动程序。

【Member Functions】
1、KUsbPipe - Constructor构造函数(三种Forms)
调用中断级IRQL <= DISPATCH_LEVEL。

2、Type - Accessor to pipe type获取管道类型，返回m_Information->PipeType。
任何中断级上调用。

3、Open - Opens a KUsbPipe object打开一个KUsbPipe对象(这个对象建立对象和激活的USB管道之间的连接binding)。

4、IsOpen - Tests if the KUsbPipe object has been opened测试KUsbPipe对象是否被KUsbLowerDevice::ActivateConfiguration或KUsbInterface::SelectAlternate正确的初始化。

5、Close - Closes an open KUsbPipe object关闭一个KUsbPipe对象，删除对象和激活的USB管道之间的连接(biding)。

6、MaximumPacketSize - Accessor to maximum packet size获取管道有效负载的最大数据大小(B为单位)。返回m_Information->MaximumPacketSize。
任何中断级上调用。

7、EndpointAddress - Accessor to endpoint address获取管道的端点地址。返回m_Information->EndpointAddress。
任何中断级上调用。

8、PollInterval - Accessor to polling period获取轮询间隔时间(以ms为单位)。返回m_Information->Interval。
任何中断级上调用。

9、Handle - Accessor to handle assigned by bus driver获取管道句柄，返回m_Information->PipeHandle。
任何中断级上调用。

10、MaximumTransferSize - Accessor to maximum transfer size获取端点可以进行传输的最大数据量，返回m_Information->MaximumTransferSize。
任何中断级上调用。

11、SetMaximumTransferSize - Sets maximum transfer size of the pipe指定管道可以传输的最大数据量(以B为单位)。

12、Initialize - Initialization初始化，使用不带参数的构造函数时要用此函数进行初始化。
调用中断级IRQL <= DISPATCH_LEVEL。

13、Reset - Reset the pipe重置管道，返回从USB系统总线驱动返回的状态值。
任何中断级上调用。

14、Abort - Abort all outstanding requests强制取消所有未完成的请求。
任何中断级上调用。

15、BuildInterruptTransfer - Build an interrupt transfer URB构造一个interrupt类型的传输URB请求。

16、BuildControlTransfer - Build a control transfer URB构造一个control类型的传输URB请求。

17、BuildIsochronousTransfer - Build an isochronous transfer URB构造一个isochronous类型的传输URB请求。

18、BuildBulkTransfer - Build a bulk transfer URB构造一个bulk类型的传输URB请求。

19、GetStatus - Get status of pipe获取管道状态。
调用中断级必须在PASSIVE_LEVEL。

20、SetFeature - Set pipe feature设置管道特征值。如果无法分配URB的空间就返回STATUS_INSUFFICIENT_RESOURCES ，否则就返回对USB系统驱动调用所返回的状态值。
调用中断级必须在PASSIVE_LEVEL。

21、ClearFeature - Clear pipe feature清除管道特征值。
如果CompletionRoutine参数为NULL，调用中断级必须在PASSIVE_LEVEL。

22、BuildClassRequest - Build an URB for a class request为类请求构造一个URB，申请内存(非分页内存)，并/或 为逻辑设备初始化一个_URB_CONTROL_VENDOR_OR_CLASS_REQUEST结构。
调用者处于IRQL <= DISPATCH_LEVEL中断级别上。

23、BuildVendorRequest - Build an URB for a vendor request为供应商请求构造一个URB，申请内存(非分页内存)，并/或 为逻辑设备初始化一个_URB_CONTROL_VENDOR_OR_CLASS_REQUEST结构。
调用者处于IRQL <= DISPATCH_LEVEL中断级别上。

24、SubmitUrb - Submits an URB (USB Request Block) to the system USB bus driver for processing提交一个URB(USB Request Block)给系统USB总线驱动程序去处理。
如果驱动程序提供了一个非空(non-NULL)的完成例程，那么两种FORM之一的调用者处于IRQL <= DISPATCH_LEVEL中断级别上。否则中断级别必须在PASSIVE_LEVEL。 DISPATCH_LEVEL中断级别上。

                                            －－－－－－－－－－－－－－－－
                                            § 译自"DriverWorks帮助文件"  §
                                            §   李文凯 2008年05月02日    §
                                            －－－－－－－－－－－－－－－－