Packet32包中的函数说明

Packet32包中的函数说明:

No.1.  PacketGetAdapterNames(从注册表中读取网卡名)
得到现有的网络适配器的列表和它们的描述。
BOOLEAN PacketGetAdapterNames(
PTSTR pStr,
PULONG  BufferSize
)；

Parameters：
pStr:
[in , out] 一块用户负责分配的缓冲区，将把适配器的名字填充进去。
BufferSize:
[in] pStr这块缓冲区的大小。
Return Values：
如果查询成功，返回一个非零值。

Usage:
[C/C++]
C/C++ Usage Sample
char        AdapterNamea[8192];
ULONG   AdapterLength;
PacketGetAdapterNames(AdapterName,&AdapterLength);

Remarks:

通常，这都是与网卡通信时要调用的第一个函数。它返回系统上安装了的网卡的名字。在每个网卡的名字后面，pStr中还有一个与之相应的描述。

由于结果都是通过查询注册表得到的，所以WindowsNTx和Windows9X/Me下得到的字符串编码是不同的。Windows9X下用ASCII编码存储，而WindowsNTx则是Unicode。

如果是在Windows9X下，调用完PacketGetAdapterNames后，得到的pStr将是这样的：

-          一串用"/0"分隔的ASCII字符串，每一个都是一个网卡的名字；

-          两个"/0"；

-          一串用"/0"分隔的ASCII字符串，每一个都是一个网卡的描述；顺序是和网卡名字一样的；

-          两个"/0"；

 

如果是在WindowsNTx下，调用完PacketGetAdapterNames后，得到的pStr将是这样的：

-          一串用一个Unicode的"/0"分隔的Unicode字符串，每一个都是一个网卡的名字；

-          两个Unicode的"/0"；

-          一串用ASCII的"/0"分隔的ASCII字符串，每一个都是一个网卡的描述；顺序是和网卡名字一样的；

-          两个ASCII的"/0"；

 

这个函数的操作大致为：

网卡的注册表项是：

HKEY_LOCAL_MACHINE/

SYSTEM/

CurrentControlSet/

Control/

Class/

{4D36E972-E325-11CE-BFC1-08002BE10318}

     先打开这个键值；

      再枚举下面的每一项，依次读取参数：

      对子项/Linkage/UpperBind参数，核对是否等于” NdisWan”，如果不是，就跳过去；

      如果是” NdisWan”，则读取子项/Linkage/Export，这就是网卡的名字。

 

      如果前面的查询有网卡记录，那么执行下面这个循环：

      将调用PacketOpenAdapter打开每个网卡；

其中将调用PacketRequest(adapter,FALSE,OidData)来得到网卡的描述；

具体方法是这样，OidData是一个PACKET_OID_DATA结构，我们事先设置它的Oid成员为OID_GEN_VENDOR_DESCRIPTION，然后调用PacketRequest把这个OID发送给网卡driver，就可以从OidData->Data中拿到网卡的描述了。

      最后调用PacketCloseAdapter关闭适配器。

     

      如果前面没有查询到网卡记录，那么执行我们将根据TCP/IP Binding来查找网卡：

      先打开这个键值；

HKEY_LOCAL_MACHINE/

SYSTEM/

CurrentControlSet/

Services/

Tcpip/

Linkage

它的Bind参数设置的就是现在系统上绑定的网卡的名字。

得到名字之后，同上调用PacketOpenAdapter和PacketRequest方法向网卡查询它的描述。

No.2.  PacketOpenAdapter (打开网卡)

根据传入的设备名，打开它。

LPADAPTER PacketOpenAdapter(

LPTSTR AdapterName

)；

Parameters：

AdapterName:

[in] 要打开的设备的名字。

Return Values：

如果打开成功，返回一个指针，它指向一个正确初始化了的ADAPTER Object。

否则，返回NULL。

Usage:

[C/C++]

C/C++ Usage Sample

LPADAPTER  adapter;

adapter = PacketOpenAdapter(pStr+rewind);

 

Remarks:

这个函数尝试加载并启动packet driver，这样，管理driver对于应用程序来说就十分的透明了。

           

            Windows9X版本的NPF driver用的是ASCII编码，而WindowsNTx用的是Unicode编码。所以提请注意这个输入参数AdapterName，在Windows9X下，必须是正确的编码格式！在WindowsNTx下，这个函数能够监测到ASCII编码，并在送给driver 之前先转换为Unicode编码。

 

这个函数的操作大致为：

            首先调用OpenSCManager，以Administrators的身份连接Service Control Manager，权限是SC_MANAGER_ALL_ACCESS。这也说明，使用Packet.dll你必须是本机管理员组成员。

            如果可以连接SCM，检查NPF注册表项是否存在。如果存在，说明driver已经安装了，就不需要我们调用PacketInstallDriver了。

            NPF注册表项：

HKEY_LOCAL_MACHINE/

SYSTEM/

CurrentControlSet/

Services/

  NPF

如果不存在此键，则调用PacketInstallDriver安装当前路径下的driver：npf.sys。

如果这次PacketInstallDriver安装也失败了，就到系统路径下查找并安装这个驱动。

           

            如果以上操作都成功的话，调用OpenService打开NPF服务。如果服务存在的话，就调用QueryServiceStatus查询当前服务状态。这就是我们的driver的状态。

            如果这个服务没有启动，就调用StartService启动之。

           

            确认服务启动之后，检查AdapterName是否是ASCII编码，是的话，就转换为Unicode。

 

            由于一般输入参数AdapterNAme类似于这样：

/Device/NPF_{A67CEC3B-C099-47E0-B096-480B01FAF348}

所以，我们会重新组织一个设备名SymbolicLink：

“Packet_”的前缀 + AdapterName[8]

也就是：

//./Packet_NPF_{A67CEC3B-C099-47E0-B096-480B01FAF348}

 

先尝试着CreateFile函数能不能马上用这个SymbolicLink名字打开设备。

如果可以，就调用PacketSetReadEvt函数打开一个open事件等。

否则，调用DefineDosDevice定义一个新的MS-DOS设备：

名字类似于” Packet_NPF_{A67CEC3B-C099-47E0-B096-480B01FAF348}”。

通过这个DOS设备名，我们的应用层程序才能向驱动发出请求。

接着，调用CreateFile函数来建立并打开一个联系设备的文件句柄(GENERIC_WRITE| GENERIC_READ，OPEN_EXISTING)。

之后，调用PacketSetReadEvt函数打开一个open事件等。

Packet32包中的数据结构:

第一个重要的数据结构：_ADAPTER(关于Network Adapter的)

typedef struct _ADAPTER 

{

    // 一个打开的NPF driver实例的句柄:

    HANDLE hFile;                   

    // 当前打开的网卡的名字:

    CHAR  SymbolicLink[MAX_LINK_NAME_LENGTH];

    // 在这块Adapter上，一个数据包被写的次数:

    int NumWrites;

// 这块Adapter上的read操作的通知事件。它可以被传递给标准Win32函数(如WaitForSingleObject或者WaitForMultipleObjects)，这样可以等待到driver的缓冲区内有数据到来。在同时等待几个事件的GUI程序中，它特别有用。在Windows2000/XP中，函数PacketSetMinToCopy()可以用来设置内核缓冲区中激发本事件的最小数据大小:

    HANDLE ReadEvent;

    // 设置一个时间，到时候，即使没有捕获任何包，read操作也会被释放，ReadEvent也会被触发:

    UINT ReadTimeOut;

}  ADAPTER, *LPADAPTER;

 

第二个重要的数据结构：_PACKET(关于Packet的)

typedef struct _PACKET

{

    // 向后兼容用的:

    HANDLE       hEvent;

    // 向后兼容用的:

    OVERLAPPED   OverLapped;

    // 存放Packets的缓冲区:

    PVOID        Buffer;

// 缓冲区的大小:

    UINT         Length;

    // 当前缓冲区中有效的字节数，如，上一次调用PacketReceivePacket()函数接收到的字节数:

    DWORD        ulBytesReceived;

    // 向后兼容用的:

    BOOLEAN      bIoComplete

}  PACKET, *LPPACKET;

第三个重要的数据结构：_PACKET_OID_DATA (关于OID请求的)

typedef struct _PACKET_OID_DATA

{

    // OID的code，有效的OID code的定义参见ntddndis.h；比如：

// OID_GEN_SUPPORTED_LIST，OID_GEN_VENDOR_DESCRIPTION等:

    ULONG Oid;

    // 成员Data的长度:

    ULONG Length;

    // 存放发送给网卡或者从网卡接收的数据的缓冲区:

    UCHAR Data[1];

}

typedef struct _PACKET_OID_DATA  PACKET_OID_DATA, *PPACKET_OID_DATA;

其他数据结构：

npf_if_addr(网卡的地址)：

typedef struct npf_if_addr {

    struct sockaddr IPAddress;      //  IP address.

    struct sockaddr SubnetMask;    //  Netmask for that address.

    struct sockaddr Broadcast;      //  Broadcast address.

}npf_if_addr;

 

bpf_hdr(Packet Header)：

struct bpf_hdr {

    // 捕获到的packet的timestamp:

    struct timeval bh_tstamp;

    // 捕获到的packet的长度:

    UINT   bh_caplen;

    // 原始packet的长度:

    UINT   bh_datalen;

    // bpf header的长度(this struct plus alignment padding):

    USHORT        bh_hdrlen;

};

 

bpf_insn(一个简单的BPF伪指令):

bpf_insn中包含了一个BPF注册机的简单指令，它被用来发送一个filter程序给driver。

struct bpf_insn {

    // 指令的类型和寻址模式:

    USHORT  code;

    // Jump if true:

    UCHAR   jt;

    // Jump if false:

    UCHAR   jf;

// 通用的一个字段，有多种目的:

    int k;

};

 

bpf_program(一个BPF伪汇编程序):

这段程序将被PacketSetBPF()注射入内核，并被应用到每一个进来的Packet。

struct bpf_program {

    // 程序指令数目，如，后面的bpf_insn结构的数目:

    UINT bf_len;

    // 指向第一个bpf_insn结构的指针:

    struct bpf_insn *bf_insns;

};

 

bpf_stat (本次捕获的统计数据):

这个结构将被Packet.dll用来返回捕获过程中的统计数据。

struct bpf_stat {

    // 从开始捕获起，这个driver从网卡上接收的Packet的数量(包括driver丢失的Packet):

    UINT bs_recv;

    //从开始捕获起，这个driver丢失的Packet的数量，一般地，包丢失，是因为driver的缓冲区满了，这时driver将扔掉这个包:

    UINT bs_drop;

    UINT ps_ifdrop;

    // 通过filter的包的数量:

UINT bs_capt;

};

 

dump_bpf_hdr(Dump Packet Header):

struct dump_bpf_hdr{

    // Packet的timestamp:

    struct timeval  ts;

    // 捕获到的packet的长度:

    UINT                caplen;

    // 原始Packet的长度:

    UINT                len;

};

 

NetType (网络类型):

NetType用于PacketGetNetType()，返回当前网卡的类型和速度。

struct NetType{

    //当前网卡的MAC:

    UINT LinkType;

    // 网络的速度(bits/s):

    UINT LinkSpeed;

};

No.3.  PacketSetHwFilter (设置过滤器)

设置一个hardware filter。比如，Filter参数传递NDIS_PACKET_TYPE_PROMISCUOUS，就可以设置网卡为混杂模式。

BOOLEAN PacketSetHwFilter(

LPADAPTER  AdapterObject,

ULONG Filter

);

Parameters：

AdapterObject:

[in] 指向一个_ADAPTER结构的指针。

Filter:

[in] 过滤器的id。

Return Values：

如果执行成功，返回一个非零值。

Usage:

C/C++ Usage Sample

lpAdapter =   PacketOpenAdapter(AdapterList[Open-1]);

PacketSetHwFilter(lpAdapter,NDIS_PACKET_TYPE_PROMISCUOUS);

Remarks:

过滤器定义在ntddndis.h中。下面是一些最常用的：

NDIS_PACKET_TYPE_PROMISCUOUS：设置混杂模式。网卡接收每一个Packet；

NDIS_PACKET_TYPE_DIRECTED；

NDIS_PACKET_TYPE_BROADCAST：只接收broadcast packets；

NDIS_PACKET_TYPE_MULTICAST：只接收multicast packets，而且本机网卡是接收组的一个成员；

NDIS_PACKET_TYPE_ALL_MULTICAST：所有multicast packets都接收；

NDIS_PACKET_TYPE_ALL_LOCAL：所有local packets。

 

这个函数的实现是非常简单的：

首先填充PACKET_OID_DATA结构的Oid成员为OID_GEN_CURRENT_PACKET_FILTER，填充Data成员为既定的Filter，调用PacketRequest向网卡发送OID请求即可。

No.4.  PacketSetBuff (设置缓冲区的大小)

设置捕获的内核级缓冲区的大小。

BOOLEAN PacketSetBuff(

LPADAPTER AdapterObject,

int dim

);

Parameters：

AdapterObject:

[in] 指向一个_ADAPTER结构的指针。

dim:

[in] 缓冲区的大小(单位：字节)。

Return Values：

如果执行成功，返回一个TRUE。如果没有足够的内存分配，返回FALSE。

Usage:

C/C++ Usage Sample

lpAdapter =   PacketOpenAdapter(AdapterList[Open-1]);

PacketSetBuff(lpAdapter,512000) ; // 设置driver有512KB字节的缓冲区

Remarks:

一旦设定了一个新缓冲区大小，在原来的那块缓冲区中的数据就会被丢弃，包括存在里面的Packets。

注意：内核缓冲区的大小会严重影响到捕获进程的性能。一个适当的缓冲区可以在应用忙时保有数据，从而补偿应用的响应延迟，并在网络活动频繁时做到不丢失Packets。当driver的一个实例被打开时，这个缓冲区的大小被重设为0：开发者应该记得把它设为一个合适的值，比如设为1MB。

 

本函数调用了DeviceIoControl，给AdapterObject参数的hFile成员指向的NPF driver设备发送pBIOCSETBUFFERSIZE控制码。pBIOCSETBUFFERSIZE是在Packet32.h中定义的：

//< IOCTL code: set kernel buffer size：

#define   pBIOCSETBUFFERSIZE 9592

No.5.  PacketSetReadTimeout (设置读操作的超时时间)

设置一次读操作返回的超时时间。

BOOLEAN PacketSetReadTimeout(

LPADAPTER AdapterObject,

int timeout

);

Parameters：

AdapterObject:

[in] 指向一个_ADAPTER结构的指针。

timeout:

[in] 超时时间(单位：毫秒)。

Return Values：

如果执行成功，返回非零值。

Usage:

C/C++ Usage Sample

lpAdapter =   PacketOpenAdapter(AdapterList[Open-1]);

PacketSetReadTimeout(lpAdapter,1000) ; // 设置读操作超时时间1秒

Remarks:

在AdapterObject指向的网卡上调用PacketReceivePacket()，到了设定的超时时间，这次调用就会释放，即使没有Packet被捕获到。

设置超时时间为0，说明没有超时。这样，如果没有Packet到来的话，PacketReceivePacket()方法永不会返回。

设置超时时间为-1，PacketReceivePacket()会立即返回。

   这个函数也工作在网卡的统计模式下。所以可以用来设置两次统计报告之间的时间间隔。

   这个函数也是通过DeviceIoControl发送控制码来实现的。

No.6.  PacketAllocatePacket

为_PACKET结构分配内存。

LPPACKET PacketAllocatePacket(void);

Parameters：

无

Return Values：

如果执行成功，返回指向_PACKET结构的指针。否则，返回NULL。

Usage:

C/C++ Usage Sample

LPPACKET   lpPacket;

lpPacket = PacketAllocatePacket() ;

Remarks:

这个函数并不负责为_PACKET结构的Buffer成员分配空间。这块缓冲区必须由应用程序分配，而且必须调用PacketInitPacket来将这缓冲区和_PACKET结构关联到一起。

No.7.  PacketInitPacket

初始化一个_PACKET结构，即将packet结构中的buffer设置为传递的buffer指针。

VOID PacketInitPacket(

LPPACKET lpPacket,

PVOID Buffer,

UINT Length

);

Parameters：

lpPacket

[in] 指向一个_PACKET结构的指针。

Buffer

[in] 一个指向一块用户分配的缓冲区的指针。捕获的数据将放置于此。

Length

[in] 缓冲区的大小。这是一个读操作从driver传递到应用的最大数据量。

Return Values：

无。

Usage:

C/C++ Usage Sample

char buffer[256000];

LPPACKET   lpPacket;

PacketInitPacket(lpPacket,(char*)buffer,256000);;

Remarks:

Driver能够用一个读操作返回几个Packets，那么一次调用传递给应用程序的packet的数量，就只取决于传递给PacketReceivePacket()的_PACKET结构的buffer的大小了。因此用PacketInitPacket()初始化一块大缓冲区，能够显著地减少系统调用，减少捕获进程在处理器上的影响。

 

No.8.  PacketReceivePacket (读取数据)

从NPF driver上读取数据（Packets或者统计信息）。

BOOLEAN PacketReceivePacket(

LPADAPTER AdapterObject,

LPPACKET lpPacket,

BOOLEAN Sync

);

Parameters：

AdapterObject:

[in] 指向一个_ADAPTER结构的指针。

lpPacket:

[in , out] 放数据的_PACKET结构缓冲区。

Sync:

[in] 一个可以忽略的参数，保留它是为了向后兼容。

Return Values：

如果执行成功，返回一个非零值。

Usage:

C/C++ Usage Sample

LPADAPTER  lpAdapter = 0;

LPPACKET   lpPacket;

lpAdapter =   PacketOpenAdapter(AdapterList[Open-1]);

lpPacket = PacketAllocatePacket();

PacketInitPacket(lpPacket,(char*)buffer,256000);

PacketReceivePacket(lpAdapter,lpPacket,TRUE);

Remarks:

这个函数所接收的数据可以是一组Packets，也可以是网络流量的一个统计数据，依赖于网卡的工作模式。

接收到的Packet的数量是可变的。它依赖于几个因素：当前存储在driver缓冲区中的Packet的数目，这些Packet的大小，分配给lpPacket参数的缓冲区的大小。

Packet存储在lpPacket结构的buffer缓冲区内，lpPacket->Length指示着复制到缓冲区的数据的大小。

它的实现也很简单：

先看看AdapterObject->ReadTimeOut是否是-1：

如果不是-1，则调用WaitForSingleObject等候AdapterObject->ReadEvent读事件触发，超时时间为AdapterObject->ReadTimeOut的数值。如果AdapterObject->ReadTimeOut为0，则永不超时。

如果是-1，就表明读完立即返回。

之后，调用ReadFile读取数据。

No.9.  PacketGetStats (得到本次捕获的统计数据)

得到当前捕获进程的统计信息。

BOOLEAN PacketGetStats(

LPADAPTER AdapterObject,

struct bpf_stat *s

);

Parameters：

AdapterObject:

[in] 指向一个_ADAPTER结构的指针。

s:

[in, out] bpf_stat结构，通过它，我们可以知道接收到的包数，丢失的包数等。

Return Values：

如果执行成功，返回非零值。

Usage:

C/C++ Usage Sample

struct bpf_stat stat;

PacketGetStats(lpAdapter,&stat) ;

通过这个函数，我们可以知道：
从开始捕获起，这个driver从网卡上接收的Packet的数量(包括driver丢失的Packet)；
从开始捕获起，这个driver丢失的Packet的数量，一般地，包丢失，是因为driver的缓冲区满了，这时driver将扔掉这个包。
具体实现也是调用DeviceIoControl函数向设备发送pBIOCGSTATS控制码，得到一个bpf_stat结构，然后只把这个结构的bs_recv和bs_drop成员返回。