DriverStudio的USB编程类函数

DriverStudioUSB编程类函数

DriverWorks提供了三个类:KUsbLowerDeviceKUsbInterfaceKUsbPipe类,用于实现USB设备操作。KUsbLowerDevice类用于逻辑设备的编程,KUsbInterface类用于借口的编程,KUsbPipe类用于管道的编程。

1KUsbLowerDevice

       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中断级别上访问该数据。应先调用PreConfigurePreconfigureInterface之后,在调用该函数。

         NTSTATUS Unconfigure (

PIO_COMPLETION_ROUTINE CompletionRoutine = NULL,

PVOID Context = NULL);

    调用系统USB总线驱动程序使设备处于未配置状态。若完成例程为NULL,必须在PASSIVE_LEVEL中断级别上调用该函数。

    CompletionRoutine为完成例程,默认为NULL

    Contex为传递给完成例程的环境变量参数,默认为NULL

    注意:线面六个成员函数,KUsbInterfaceKUsbPipe类也有,后面不再详述。

         FORM1PURB 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);

    FORM2PURB 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

bInTURE表示输入,数据从设备到主机;FALSE表示输出,数据从主机到设备。

bShortOkTRUE标示设备传输的字节数可以少于指定的字节数。

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

         FORM1NTSTATUS SubmitUrb (

PURB pUrb,

PIO_COMPLETION_ROUTINE CompletionRoutine = NULL,

PVOD CompletionCOntext = NULL,

ULONG mSecTimeOut = 0);

       FORM2NTSTATUS 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_REQUIREDFORM2由调用者提供一个IRP,用于PnP目的。

    I是由调用者提供的IRP

    pUrb是创建的URBan

    CopletionRoutine为完成例程,默认为NULL

    CompletionContext为传递给完成例程的环境参数,默认为NULL

    mSecTimeOut为对同步调用的定时参数,以毫秒为单位。当超过定时参数后,返回STATUS_TIMEOUT0标示无限期等待。

         NTSTATUS ClearFeature (

USHORT Feature,

PIO_COMPLETION_ROUTINE CompletionRoutine = NULL,

PVOID Context = NULL);

    清除一个特征标志。这个函数分配一个URB,并发送给系统USB总线驱动程序。若完成例程为NULL,则必须在PASSIVE_LEVEL中断级别上调用该函数。若有完成例程,则完成例程负责删除URBURBKIrp::Urb函数获得。

    Feature为特征值。

    CompletionRoutine为完成例程,默认为NULL

Context为传递给完成例程的环境变量参数,默认为NULL

         NTSTATUS SetFeature (

USHORT Feature,

PIO_COMPLETION_ROUTINE CompletionRoutine = NULL,

PVOID Context = NULL);

    设置一个特征标志。这个函数分配一个URB,并发送给系统USB总线驱动程序。若完成例程为NULL,则必须在PASSIVE_LEVEL中断级别上调用该函数。若有完成例程,则完成例程负责删除URBURBKIrp::Urb函数获得。

    Features为特征值。

    CompletionRoutine为完成例程,默认为NULL

    Context为传递给完成例程的环境变量参数,默认为NULL

         NTSTATUS GetStatus (

PUSHORT pStatus,

PIO_COMPLETION_ROUTINE CompletionRoutine = NULL,

PVOID Context = NULL);

    获取状态信息。这个函数分配一个URB,并发送给系统USB总线驱动程序。若完成例程为NULL,则必须在PASSIVE_LEVEL中断级别上调用该函数。若有完成例程,则完成例程负责删除URBURBKIrp::Urb函数获得。

    pStatus为状态值。

    CompletionRoutine为完成例程,默认为NULL

    Context为传递给完成例程的环境变来那个参数,默认为NULL

2KUsbInterface

    KUsbInterface类的作用更多的是结构上的而非功能上的,其成员函数几乎不与实际物理设备交互。驱动程序用这个类可获得接口和管道的信息。

    成员函数如下:

         NTSTATUS Initialize (

KUsbInterfaceDevice& Device,

UCHAR InterfaceNumber,

UCHAR ConfigurationValue,

UCHAR InitialAlternateSetting);

    初始化一个用默认构造函数定义的KUsbInterface类实例,在IRQL<=DISPATCH_LEVEL中断级别上调用该函数。

    DeviceKUsbInterfaceDevice类实例。

    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中断级别上调用该函数。

    DeviceKUsbLowerDevice类实例。

    EndpointAddress为端点地址。

    MaxTransferSize为管道最大传输字节数。

         NTSTATUS Reset (void);

复位管道,必须在PASSIVE_LEVEL中断级别上调用该函数。

         NTSTATUS Abort (void);

放弃管道上未完成的请求,必须在PASSIVE_LEVEL中断级别上调用该函数。

         UCHAR PollInterval (void);

返回中断传输的中断巡检间隔,以毫秒为单位。

         FORM1PURB BuildInterruptTransfer (

KMemory& Mdl,

ULONG Length,

BOOLEAN bShortOk = TRUE,

PURB Link = NULL,

PURB pUrb = NULL);

       FORM2PURB BuildInterruptTransfer (

                     PVOID Buffer,

                     ULONG Length,

                     BOOLEAN bShortOk = TRUE,

                     PURB Link = NULL,

                     PURB pUrb = NULL);

    分配并一个用于中断传输的URB

    Mdl为应用程序存放传输数据的内存。

    Buffer为驱动程序存放传输数据的内存区。

    Length为传输的字节数。

    bShortOkTRUE表示设备传输的字节数可以少于指定的字节数。

    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为驱动程序存放传输数据的内存区。

    bInTRUE表示输入,数据从设备到主机;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

       bShortOkTRUE表示设备传输的字节数可以少于指定的字节数。

       bInTRUE表示输入,数据从设备到主机;为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为包的字节数。

       bInTRUE表示输入,数据从设备到主机;为FALSE表示输出,数据从主机到设备。

       bASAPTRUE表示传输应尽可能快的开始;为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);

设置管道最大传输字节数,应在ConfigureActivateConfiguration之前调用,否则无效果。

         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 ();

获取状态信息。

你可能感兴趣的:(DriverStudio的USB编程类函数)