WinPcap下的主要结构体和主要函数.doc

WinPCap中的主要结构体：
1. struct pcap_if_t（称为网络设备结构，表示一个网络接口设备（如网卡））　结构体包含以下5个域（其结构体与pcap_if相同，可以用pcap_if_t代替pcap_if）：
struct pcap_if {
struct pcap_if *next;
char *name; /* name to hand to "pcap_open_live()" */
char *description; /* textual description of interface, or NULL */
struct pcap_addr *addresses;
bpf_u_int32 flags; /* PCAP_IF_ interface flags */
};

Struct pcap_addr : Representation of an interface address　 (表示接口地址)
Struct pcap_addr
{
struct pcap_addr * next：if not NULL, a pointer to the next element in the list;　 NULL for the last element of the list （指向下一个元素的指针）
struct sockaddr * addr  a pointer to a struct sockaddr containing an address
struct sockaddr * netmask  if not NULL, a pointer to a struct sockaddr that contains the netmask corresponding to the address pointed to by addr.
struct sockaddr * broadaddr  if not NULL, a pointer to a struct sockaddr that contains the broadcast address corre� sponding to the address pointed to by addr; may be null if the interface doesn't support broadcasts
struct sockaddr * dstaddr  if not NULL, a pointer to a struct sockaddr that contains the destination address corre� sponding to the address pointed to by addr; may be null if the interface isn't a point- to-point interface
}

２．pcap_if
Item in a list of interfaces, used by pcap_findalldevs().
（接口设备列表的一项（一个设备，比如一个网卡））
Definition at line 148 of file incs/pcap.h.　
Struct pcap_if
{
struct pcap_if * next
if not NULL, a pointer to the next element in the list; NULL for the last element of the list
char * name
a pointer to a string giving a name for the device to pass to pcap_open_live()
char * description
if not NULL, a pointer to a string giving a human-readable description of the device
struct pcap_addr * addresses
a pointer to the first element of a list of addresses for the interface
u_int flags
PCAP_IF_ interface flags. Currently the only possible flag is PCAP_IF_LOOPBACK, that is set if the interface is a loopback interface.
}

2. 结构体pcap_t
Descriptor of an open capture instance. This structure is opaque to the user, that handles its content through the functions provided by wpcap.dll. （该结构体描述一个捕获的实例（例如指向一个发现的网卡，称为网卡描述符），其结构体在.h文件中看不到）

3. 结构体pcap_pkthdr　// Header of a packet in the dump file.
Each packet in the dump file is prepended with this generic header.
（每一个分组都有不同的头部，分组的头部用该结构体表示）

struct pcap_pkthdr {
      struct timeval ts;
      bpf_u_int32 caplen;
      bpf_u_int32 len;
}
ts：时间戳
cpalen：当前分组的长度
len：数据包的长度

5. 结构体　sockaddr_in
一般编程中使用，它与sockaddr等价的数据结构
sockaddr_in（在Winsock2.h中定义）：

struct  sockaddr_in {
};

typedef struct in_addr {
union {
            struct{
                        unsigned char s_b1,
                        s_b2,
                        s_b3,
                        s_b4;
                        } S_un_b;
           struct {
                        unsigned short s_w1,
                        s_w2;
                        } S_un_w;
            unsigned long S_addr;
       } S_un;
} IN_ADDR;
sin_family指代协议族，在socket编程中只能是AF_INET
sin_port存储端口号（使用网络字节顺序）
sin_addr存储IP地址，使用in_addr这个数据结构
sin_zero是为了让sockaddr与sockaddr_in两个数据结构保持大小相同而保留的空字节。
s_addr按照网络字节顺序存储IP地址
sockaddr_in和sockaddr是并列的结构，指向sockaddr_in的结构体的指针也可以指向sockadd的结构体，并代替它。也就是说，你可以使用sockaddr_in建立你所需要的信息,
在最后用进行类型转换就可以了bzero((char*)&mysock,sizeof(mysock));//初始化
mysock结构体名
mysock.sa_family=AF_INET;
mysock.sin_addr.S_un.S_addr=inet_addr("192.168.0.1");
……
等到要做转换的时候用：
（struct sockaddr*）mysock

例子：获得子网掩码
pcap_if_t *d;
netmask = ( (sockaddr_in *) (d->addresses->netmask) )->sin_addr.S_un.S_addr;

例子２：
Socketaddr_in InternetAddr;
int nPortId = 5150;
InternetAddr.sin_family = AF_INET;
InternetAddr.sin_addr.s_addr = inet_addr("198.198.10.216");
InternetAddr.sin_port = htonl(nPortId);

WinPcap下的主要函数：
1. int pcap_findalldevs pcap_if_t ** alldevsp,
char * errbuf
) //获取设备列表，以供函数pcap_open_live()打开这些设备
Construct a list of network devices that can be opened with pcap_open_live().
Note:
that there may be network devices that cannot be opened with pcap_open_live() by the process calling pcap_findalldevs(), because, for example, that process might not have sufficient privileges to open them for capturing; if so, those devices will not appear on the list.
alldevsp is set to point to the first element of the list; each element of the list is of type pcap_if_t,
-1 is returned on failure, in which case errbuf is filled in with an appropriate error message; 0 is returned on success.

2. void pcap_freealldevs ( pcap_if_t * alldevsp )
释放由函数pcap_findalldevs()获取的设备列表
Free an interface list returned by pcap_findalldevs().
pcap_freealldevs() is used to free a list allocated by pcap_findalldevs().
See also:
pcap_findalldevs()

3. pcap_t* pcap_open_live (
const char * device, //要打开的网络设施，
int snaplen, //捕捉的分组最大长度，单位Byte
int promisc, //是否为混杂模式，1为混杂模式
int to_ms, //read time_out 给予阅读分组的最大时间,单位ms
char * ebuf
)

Device(Source)：为打开的网络设施，是包含要打开的源名称的以’\0’结尾的字符串。源名称得包含新的源规范语法(Source Specification Syntax)，并且它不能为NULL。为了方便的使用源语法，

snaplen：需要保留的数据包的长度。对每一个过滤器接收到的数据包，第一个‘snaplen’字节的内容将被保存到缓冲区，并且传递给用户程序。例如，snaplen等于100，那么仅仅每一个数据包的第一个100字节的内容被保存。简言之就是从每一个包的开头到snaplen的那段内容将被保存。
flags：保存一些由于抓包需要的标志。Winpcap定义了三种标志：
l         PCAP_OPENFLAG_PROMISCUOUS：1，它定义了适配器（网卡）是否进入混杂模式（promiscuous mode）。
l         PCAP_OPENFLAG_DATATX_UDP：2，它定义了数据传输（假如是远程抓包）是否用UDP协议来处理。
l         PCAP_OPENFLAG_NOCAPTURE_RPCAP：4，它定义了远程探测器是否捕获它自己产生的数据包。
read_timeout：以毫秒为单位。read timeout被用来设置在遇到一个数据包的时候读操作不必立即返回，而是等待一段时间，让更多的数据包到来后从OS内核一次读多个数据包。
auth：一个指向’struct pcap_rmtauth’的指针，保存当一个用户登录到某个远程机器上时的必要信息。假如不是远程抓包，该指针被设置为NULL。(本地抓包不需要该参数)
errbuf：一个指向用户申请的缓冲区的指针，存放当该函数出错时的错误信息。

函数的返回值：该函数正常情况下，返回值是一个’pcap_t’（网卡描述符），它可以作为下一步其他函数调用该网卡的参数（例如,ppcap_compile()等）的参数。

在遇到问题的情况下，该函数返回NULL并且’errbuf’变量保存了错误信息。

Open a live capture from the network.
pcap_open_live() is used to obtain a packet capture descriptor to look at packets on the network.
device is a string that specifies the network device to open; on Linux systems with 2.2 or later kernels, a device argument of "any" or NULL can be used to capture packets from all interfaces.
snaplen specifies the maximum number of bytes to capture. If this value is less than the size of a packet that is captured, only the first snaplen bytes of that packet will be captured and provided as packet data. A value of 65535 should be sufficient, on most if not all networks, to capture all the data available from the packet.
promisc specifies if the interface is to be put into promiscuous mode. (Note that even if this parameter is false, the interface could well be in promiscuous mode for some other reason.) For now, this doesn't work on the "any" device; if an argument of "any" or NULL is supplied, the promisc flag is ignored.
to_ms specifies the read timeout in milliseconds. The read timeout is used to arrange that the read not necessarily return immediately when a packet is seen, but that it wait for some amount of time to allow more packets to arrive and to read multiple packets from the OS kernel in one operation. Not all platforms support a read timeout; on platforms that don't, the read timeout is ignored. A zero value for to_ms, on platforms that support a read timeout, will cause a read to wait forever to allow enough packets to arrive, with no timeout.
errbuf is used to return error or warning text. It will be set to error text when pcap_open_live() fails and returns NULL. errbuf may also be set to warning text when pcap_open_live() succeds; to detect this case the caller should store a zero-length string in errbuf before calling pcap_open_live() and display the warning to the user if errbuf is no longer a zero-length string.
See also:
pcap_open_offline(), pcap_open_dead(), pcap_findalldevs(), pcap_close()
4. int pcap_datalink ( pcap_t * p )
返回链路层的类型，链路层的类型包括：
l         DLT_NULL： BSD回路封装；链路层协议头是一个4字节的域，以主机字节顺序（host byte order），包含一个从socket.h来的PF_value。主机字节顺序（host byte order）是捕获数据包的机器的字节顺序，而PF_value是捕获数据包的机器的OS。如果一个读取一个文件，字节顺序和PF_value不一定是抓取文件的那些机器。
l         DLT_EN10MB： 以太网（10Mb, 100Mb, 1000Mb, 或者更高）。
l         DLT_IEEE802： IEEE802.5令牌环网。
l         DLT_ARCNET：ARCNET。
l         DLT_SLIP：SLIP。
l         DLT_PPP：PPP；如果第一个字节是0xff或0x03，它是类HDLC帧上的PPP。
l         DLT_FDDI：FDDI
l         DLT_ATM_RFC1483：RFC1483LLC/SNAP ATM；数据包以IEEE802.2 LLC头开始。
l         DLT_RAW：原始IP（raw IP）；数据包以IP头开始。
l         DLT_PPP_SERIAL：按照RFC1662，基于类HDLC帧的PPP，或者按照RFC1547的4.3.1，基于HDLC帧的Cisco PPP；前者的第一个字节是0xFF，后者的第一个字节是0x0F或0x8F。
l         DLT_PPP_ETHER：按照RFC2516，PPPoE；数据包以PPPoE头开始。
l         DLT_C_HDLC：按照RFC1547的4.3.1，基于HDLC帧的Cisco PPP。
l         DLT_IEEE802_11：IEEE 802.11无线局域网。
l         DLT_FRELAY：帧中继（Frame Relay）。
l         DLT_LOOP：OpenBSD回路封装。
l         DLT_LINUX_SLL：Linux抓包封装。
l         DLT_LTALK：苹果的LocalTalk，数据包以AppleTalk LLAP头开始。
l         DLT_PFLOG：OpenBSD pflog。
l         DLT_PRISM_HEADER：后接802.11头的棱镜监视器模式（Prism monitor mode）信息。
l         DLT_IP_OVER_FC：RFC2625 IP-over-Fiber 频道，以RFC2625中定义的Network_Header开始。
l         DLT_SUNATM：SunATM设备。
l         DLT_IEEE802_11_RADIO：后接802.11头的链路层信息。
l         DLT_ARCNET_LINUX：没有异常帧的ARCNET。
l         DLT_LINUX_IRDA：Linux-IrDA数据包，DLT_LINUX_SLL头后接IrLAP头

5. int pcap_compile (pcap_t * p,
struct bpf_program * fp,
char * str,
int optimize,
bpf_u_int32 netmask
) //翻译分组过滤器
简单的说： pcap_complie()将程序中的字符串str集成到（翻译到）数据包驱动中的低级字节码fp。　Str -> fp(内核认识的格式)

编译一个数据包过滤器，将一个能被核心态（kernel-level）过滤器引擎解释的程序中的高层过滤表达式（filtering expression）进行转化。
pcap_compile()被用来将字符串str编译进 过滤器程序（fp），程序（fp）是一个指向bpf_program结构体并被pcap_compile()赋值的指针。
optimize控制是否对目标代码（resulting code）的性能进行优化。
Netmask表明IPv4掩码，它仅在检查过滤器程序中的IPv4广播地址的时候被使用。如果网络掩码对于程序是不可知的或者数据包是在Linux的”任何（any）”伪接口上被捕获的，则赋值0；IPv4广播地址的测试将不被正确进行，但过滤器程序中的其他所有的测试都不会有问题。
函数返回值：返回－1表示发生了错误，此时，pcap_geterr()将被用来显示错误信息; 0表示成功

Compile a packet filter, converting an high level filtering expression (see Filtering expression syntax) in a program that can be interpreted by the kernel-level filtering engine. （将str（如只捕获ARP分组）中给出的分组类型，翻译成内核认识的格式，该格式放到bpf_program * fp中）

6. int pcap_setfilter (pcap_t * p,
struct bpf_program * fp) 　
功能：设置过滤器
返回值：该函数返回值为0，表示成功；不成功，返回值<0

pcap_setfilter()把一个过滤器与核心驱动抓包会话关联起来。一旦pcap_setfilter()被调用，相关的过滤器将被应用到所有的来自网络的数据包上，并且所有的一致的数据包将被复制给应用程序。
Associate a filter to a capture. （使用bpf_program * fp格式，设置过滤器，只需要fp规定的格式），该函数之前需要使用pcap_compile（）
pcap_setfilter() is used to specify a filter program. fp is a pointer to a bpf_program struct, usually the result of a call to pcap_compile().
-1 is returned on failure, in which case pcap_geterr() may be used to display the error text; 0 is returned on success.
See also:
pcap_compile(), pcap_compile_nopcap()

7. int pcap_next_ex
( pcap_t *p,
struct pcap_pkthdr ** pkt_header,
const u_char ** pkt_data
)
Read a packet from an interface or from an offline capture.
（读取符合过滤器要求的分组）
从一个网络接口或离线捕获方式（例如读文件）读取一个数据包。该函数被用来重新获得下一个可用的数据包。pcap_next_ex用指向头和下一个被捕获的数据包的指针为pkt_header和pkt_data参数赋值）
This function is used to retrieve the next available packet, bypassing（不考虑） the callback method traditionally provided by libpcap.
pcap_next_ex fills the pkt_header and pkt_data parameters (see pcap_handler()) with the pointers to the header and to the data of the next captured packet.
The return value can be:
· 1 if the packet has been read without problems （成功时，返回1）
· 0 if the timeout set with pcap_open_live() has elapsed. In this case pkt_header and pkt_data don't point to a valid packet （pcap_open_live()设置的时间到，返回0）
· -1 if an error occurred （返回－1，表示出错）
· -2 if EOF was reached reading from an offline capture