Previous 199869 Revisions Next

r32890 Thursday 23rd October, 2014 at 06:23:44 UTC by Miodrag Milanović
line endings (nw)
[src/lib/winpcap]remote-ext.h

trunk/src/lib/winpcap/remote-ext.h
r241401r241402
1/*
2 * Copyright (c) 2002 - 2003
3 * NetGroup, Politecnico di Torino (Italy)
4 * All rights reserved.
5 * 
6 * Redistribution and use in source and binary forms, with or without 
7 * modification, are permitted provided that the following conditions 
8 * are met:
9 * 
10 * 1. Redistributions of source code must retain the above copyright 
11 * notice, this list of conditions and the following disclaimer.
12 * 2. Redistributions in binary form must reproduce the above copyright 
13 * notice, this list of conditions and the following disclaimer in the 
14 * documentation and/or other materials provided with the distribution. 
15 * 3. Neither the name of the Politecnico di Torino nor the names of its 
16 * contributors may be used to endorse or promote products derived from 
17 * this software without specific prior written permission. 
18 * 
19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
20 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
21 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
22 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
23 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
24 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
25 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 
26 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 
27 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
28 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
29 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 * 
31 */
32 
33 
34#ifndef __REMOTE_EXT_H__
35#define __REMOTE_EXT_H__
36 
37 
38#ifndef HAVE_REMOTE
39#error Please do not include this file directly. Just define HAVE_REMOTE and then include pcap.h
40#endif
41 
42// Definition for Microsoft Visual Studio
43#if _MSC_VER > 1000
44#pragma once
45#endif
46 
47#ifdef __cplusplus
48extern "C" {
49#endif
50 
51/*!
52   \file remote-ext.h
53 
54   The goal of this file it to include most of the new definitions that should be
55   placed into the pcap.h file.
56 
57   It includes all new definitions (structures and functions like pcap_open().
58    Some of the functions are not really a remote feature, but, right now, 
59   they are placed here.
60*/
61 
62 
63 
64// All this stuff is public
65/*! \addtogroup remote_struct
66   \{
67*/
68 
69 
70 
71 
72/*!
73   \brief Defines the maximum buffer size in which address, port, interface names are kept.
74 
75   In case the adapter name or such is larger than this value, it is truncated.
76   This is not used by the user; however it must be aware that an hostname / interface
77   name longer than this value will be truncated.
78*/
79#define PCAP_BUF_SIZE 1024
80 
81 
82/*! \addtogroup remote_source_ID
83   \{
84*/
85 
86 
87/*!
88   \brief Internal representation of the type of source in use (file, 
89   remote/local interface).
90 
91   This indicates a file, i.e. the user want to open a capture from a local file.
92*/
93#define PCAP_SRC_FILE 2
94/*!
95   \brief Internal representation of the type of source in use (file, 
96   remote/local interface).
97 
98   This indicates a local interface, i.e. the user want to open a capture from 
99   a local interface. This does not involve the RPCAP protocol.
100*/
101#define PCAP_SRC_IFLOCAL 3
102/*!
103   \brief Internal representation of the type of source in use (file, 
104   remote/local interface).
105 
106   This indicates a remote interface, i.e. the user want to open a capture from 
107   an interface on a remote host. This does involve the RPCAP protocol.
108*/
109#define PCAP_SRC_IFREMOTE 4
110 
111/*!
112   \}
113*/
114 
115 
116 
117/*! \addtogroup remote_source_string
118 
119   The formats allowed by the pcap_open() are the following:
120   - file://path_and_filename [opens a local file]
121   - rpcap://devicename [opens the selected device devices available on the local host, without using the RPCAP protocol]
122   - rpcap://host/devicename [opens the selected device available on a remote host]
123   - rpcap://host:port/devicename [opens the selected device available on a remote host, using a non-standard port for RPCAP]
124   - adaptername [to open a local adapter; kept for compability, but it is strongly discouraged]
125   - (NULL) [to open the first local adapter; kept for compability, but it is strongly discouraged]
126 
127   The formats allowed by the pcap_findalldevs_ex() are the following:
128   - file://folder/ [lists all the files in the given folder]
129   - rpcap:// [lists all local adapters]
130   - rpcap://host:port/ [lists the devices available on a remote host]
131 
132   Referring to the 'host' and 'port' paramters, they can be either numeric or literal. Since
133   IPv6 is fully supported, these are the allowed formats:
134 
135   - host (literal): e.g. host.foo.bar
136   - host (numeric IPv4): e.g. 10.11.12.13
137   - host (numeric IPv4, IPv6 style): e.g. [10.11.12.13]
138   - host (numeric IPv6): e.g. [1:2:3::4]
139   - port: can be either numeric (e.g. '80') or literal (e.g. 'http')
140 
141   Here you find some allowed examples:
142   - rpcap://host.foo.bar/devicename [everything literal, no port number]
143   - rpcap://host.foo.bar:1234/devicename [everything literal, with port number]
144   - rpcap://10.11.12.13/devicename [IPv4 numeric, no port number]
145   - rpcap://10.11.12.13:1234/devicename [IPv4 numeric, with port number]
146   - rpcap://[10.11.12.13]:1234/devicename [IPv4 numeric with IPv6 format, with port number]
147   - rpcap://[1:2:3::4]/devicename [IPv6 numeric, no port number]
148   - rpcap://[1:2:3::4]:1234/devicename [IPv6 numeric, with port number]
149   - rpcap://[1:2:3::4]:http/devicename [IPv6 numeric, with literal port number]
150   
151   \{
152*/
153 
154 
155/*!
156   \brief String that will be used to determine the type of source in use (file,
157   remote/local interface).
158 
159   This string will be prepended to the interface name in order to create a string
160   that contains all the information required to open the source.
161 
162   This string indicates that the user wants to open a capture from a local file.
163*/
164#define PCAP_SRC_FILE_STRING "file://"
165/*!
166   \brief String that will be used to determine the type of source in use (file,
167   remote/local interface).
168 
169   This string will be prepended to the interface name in order to create a string
170   that contains all the information required to open the source.
171 
172   This string indicates that the user wants to open a capture from a network interface.
173   This string does not necessarily involve the use of the RPCAP protocol. If the
174   interface required resides on the local host, the RPCAP protocol is not involved
175   and the local functions are used.
176*/
177#define PCAP_SRC_IF_STRING "rpcap://"
178 
179/*!
180   \}
181*/
182 
183 
184 
185 
186 
187/*!
188   \addtogroup remote_open_flags
189   \{
190*/
191 
192/*!
193   \brief Defines if the adapter has to go in promiscuous mode.
194 
195   It is '1' if you have to open the adapter in promiscuous mode, '0' otherwise.
196   Note that even if this parameter is false, the interface could well be in promiscuous
197   mode for some other reason (for example because another capture process with 
198   promiscuous mode enabled is currently using that interface).
199   On on Linux systems with 2.2 or later kernels (that have the "any" device), this
200   flag does not work on the "any" device; if an argument of "any" is supplied,
201   the 'promisc' flag is ignored.
202*/
203#define PCAP_OPENFLAG_PROMISCUOUS      1
204 
205/*!
206   \brief Defines if the data trasfer (in case of a remote
207   capture) has to be done with UDP protocol.
208 
209   If it is '1' if you want a UDP data connection, '0' if you want
210   a TCP data connection; control connection is always TCP-based.
211   A UDP connection is much lighter, but it does not guarantee that all
212   the captured packets arrive to the client workstation. Moreover, 
213   it could be harmful in case of network congestion.
214   This flag is meaningless if the source is not a remote interface.
215   In that case, it is simply ignored.
216*/
217#define PCAP_OPENFLAG_DATATX_UDP         2
218 
219 
220/*!
221   \brief Defines if the remote probe will capture its own generated traffic.
222 
223   In case the remote probe uses the same interface to capture traffic and to send
224   data back to the caller, the captured traffic includes the RPCAP traffic as well.
225   If this flag is turned on, the RPCAP traffic is excluded from the capture, so that
226   the trace returned back to the collector is does not include this traffic.
227*/
228#define PCAP_OPENFLAG_NOCAPTURE_RPCAP   4
229 
230/*!
231   \brief Defines if the local adapter will capture its own generated traffic.
232 
233   This flag tells the underlying capture driver to drop the packets that were sent by itself. 
234   This is usefult when building applications like bridges, that should ignore the traffic
235   they just sent.
236*/
237#define PCAP_OPENFLAG_NOCAPTURE_LOCAL   8
238 
239/*!
240   \brief This flag configures the adapter for maximum responsiveness.
241 
242   In presence of a large value for nbytes, WinPcap waits for the arrival of several packets before 
243   copying the data to the user. This guarantees a low number of system calls, i.e. lower processor usage, 
244   i.e. better performance, which is good for applications like sniffers. If the user sets the 
245   PCAP_OPENFLAG_MAX_RESPONSIVENESS flag, the capture driver will copy the packets as soon as the application 
246   is ready to receive them. This is suggested for real time applications (like, for example, a bridge) 
247   that need the best responsiveness.*/
248#define PCAP_OPENFLAG_MAX_RESPONSIVENESS   16
249 
250/*!
251   \}
252*/
253 
254 
255/*!
256   \addtogroup remote_samp_methods
257   \{
258*/
259 
260/*!
261   \brief No sampling has to be done on the current capture.
262 
263   In this case, no sampling algorithms are applied to the current capture.
264*/
265#define PCAP_SAMP_NOSAMP   0
266 
267/*!
268   \brief It defines that only 1 out of N packets must be returned to the user.
269 
270   In this case, the 'value' field of the 'pcap_samp' structure indicates the
271   number of packets (minus 1) that must be discarded before one packet got accepted.
272   In other words, if 'value = 10', the first packet is returned to the caller, while
273   the following 9 are discarded.
274*/
275#define PCAP_SAMP_1_EVERY_N   1
276 
277/*!
278   \brief It defines that we have to return 1 packet every N milliseconds.
279 
280   In this case, the 'value' field of the 'pcap_samp' structure indicates the 'waiting
281   time' in milliseconds before one packet got accepted.
282   In other words, if 'value = 10', the first packet is returned to the caller; the next 
283   returned one will be the first packet that arrives when 10ms have elapsed. 
284*/
285#define PCAP_SAMP_FIRST_AFTER_N_MS 2
286 
287/*!
288   \}
289*/
290 
291 
292/*!
293   \addtogroup remote_auth_methods
294   \{
295*/
296 
297/*!
298   \brief It defines the NULL authentication.
299 
300   This value has to be used within the 'type' member of the pcap_rmtauth structure.
301   The 'NULL' authentication has to be equal to 'zero', so that old applications
302   can just put every field of struct pcap_rmtauth to zero, and it does work.
303*/
304#define RPCAP_RMTAUTH_NULL 0
305/*!
306   \brief It defines the username/password authentication.
307 
308   With this type of authentication, the RPCAP protocol will use the username/
309   password provided to authenticate the user on the remote machine. If the
310   authentication is successful (and the user has the right to open network devices)
311   the RPCAP connection will continue; otherwise it will be dropped.
312 
313   This value has to be used within the 'type' member of the pcap_rmtauth structure.
314*/
315#define RPCAP_RMTAUTH_PWD 1
316 
317/*!
318   \}
319*/
320 
321 
322 
323 
324/*!
325 
326   \brief This structure keeps the information needed to autheticate
327   the user on a remote machine.
328   
329   The remote machine can either grant or refuse the access according 
330   to the information provided.
331   In case the NULL authentication is required, both 'username' and
332   'password' can be NULL pointers.
333   
334   This structure is meaningless if the source is not a remote interface;
335   in that case, the functions which requires such a structure can accept
336   a NULL pointer as well.
337*/
338struct pcap_rmtauth
339{
340   /*!
341      \brief Type of the authentication required.
342 
343      In order to provide maximum flexibility, we can support different types
344      of authentication based on the value of this 'type' variable. The currently 
345      supported authentication methods are defined into the
346      \link remote_auth_methods Remote Authentication Methods Section\endlink.
347 
348   */
349   int type;
350   /*!
351      \brief Zero-terminated string containing the username that has to be 
352      used on the remote machine for authentication.
353       
354      This field is meaningless in case of the RPCAP_RMTAUTH_NULL authentication
355      and it can be NULL.
356   */
357   char *username;
358   /*!
359      \brief Zero-terminated string containing the password that has to be 
360      used on the remote machine for authentication.
361       
362      This field is meaningless in case of the RPCAP_RMTAUTH_NULL authentication
363      and it can be NULL.
364   */
365   char *password;
366};
367 
368 
369/*!
370   \brief This structure defines the information related to sampling.
371 
372   In case the sampling is requested, the capturing device should read
373   only a subset of the packets coming from the source. The returned packets depend
374   on the sampling parameters.
375 
376   \warning The sampling process is applied <strong>after</strong> the filtering process.
377   In other words, packets are filtered first, then the sampling process selects a
378   subset of the 'filtered' packets and it returns them to the caller.
379*/
380struct pcap_samp
381{
382   /*!
383      Method used for sampling. Currently, the supported methods are listed in the
384      \link remote_samp_methods Sampling Methods Section\endlink.
385   */
386   int method;
387 
388   /*!
389      This value depends on the sampling method defined. For its meaning, please check
390      at the \link remote_samp_methods Sampling Methods Section\endlink.
391   */
392   int value;
393};
394 
395 
396 
397 
398//! Maximum lenght of an host name (needed for the RPCAP active mode)
399#define RPCAP_HOSTLIST_SIZE 1024
400 
401 
402/*!
403   \}
404*/ // end of public documentation
405 
406 
407// Exported functions
408 
409 
410 
411/** \name New WinPcap functions
412 
413   This section lists the new functions that are able to help considerably in writing
414   WinPcap programs because of their easiness of use.
415 */
416//\{
417pcap_t *pcap_open(const char *source, int snaplen, int flags, int read_timeout, struct pcap_rmtauth *auth, char *errbuf);
418int pcap_createsrcstr(char *source, int type, const char *host, const char *port, const char *name, char *errbuf);
419int pcap_parsesrcstr(const char *source, int *type, char *host, char *port, char *name, char *errbuf);
420int pcap_findalldevs_ex(char *source, struct pcap_rmtauth *auth, pcap_if_t **alldevs, char *errbuf);
421struct pcap_samp *pcap_setsampling(pcap_t *p);
422 
423//\}
424// End of new winpcap functions
425 
426 
427 
428/** \name Remote Capture functions
429 */
430//\{ 
431SOCKET pcap_remoteact_accept(const char *address, const char *port, const char *hostlist, char *connectinghost, struct pcap_rmtauth *auth, char *errbuf);
432int pcap_remoteact_list(char *hostlist, char sep, int size, char *errbuf);
433int pcap_remoteact_close(const char *host, char *errbuf);
434void pcap_remoteact_cleanup();
435//\}
436// End of remote capture functions
437 
438#ifdef __cplusplus
439}
440#endif
441 
442 
443#endif
444 
1/*
2 * Copyright (c) 2002 - 2003
3 * NetGroup, Politecnico di Torino (Italy)
4 * All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions
8 * are met:
9 *
10 * 1. Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
12 * 2. Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 * 3. Neither the name of the Politecnico di Torino nor the names of its
16 * contributors may be used to endorse or promote products derived from
17 * this software without specific prior written permission.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 *
31 */
32
33
34#ifndef __REMOTE_EXT_H__
35#define __REMOTE_EXT_H__
36
37
38#ifndef HAVE_REMOTE
39#error Please do not include this file directly. Just define HAVE_REMOTE and then include pcap.h
40#endif
41
42// Definition for Microsoft Visual Studio
43#if _MSC_VER > 1000
44#pragma once
45#endif
46
47#ifdef __cplusplus
48extern "C" {
49#endif
50
51/*!
52   \file remote-ext.h
53
54   The goal of this file it to include most of the new definitions that should be
55   placed into the pcap.h file.
56
57   It includes all new definitions (structures and functions like pcap_open().
58    Some of the functions are not really a remote feature, but, right now,
59   they are placed here.
60*/
61
62
63
64// All this stuff is public
65/*! \addtogroup remote_struct
66   \{
67*/
68
69
70
71
72/*!
73   \brief Defines the maximum buffer size in which address, port, interface names are kept.
74
75   In case the adapter name or such is larger than this value, it is truncated.
76   This is not used by the user; however it must be aware that an hostname / interface
77   name longer than this value will be truncated.
78*/
79#define PCAP_BUF_SIZE 1024
80
81
82/*! \addtogroup remote_source_ID
83   \{
84*/
85
86
87/*!
88   \brief Internal representation of the type of source in use (file,
89   remote/local interface).
90
91   This indicates a file, i.e. the user want to open a capture from a local file.
92*/
93#define PCAP_SRC_FILE 2
94/*!
95   \brief Internal representation of the type of source in use (file,
96   remote/local interface).
97
98   This indicates a local interface, i.e. the user want to open a capture from
99   a local interface. This does not involve the RPCAP protocol.
100*/
101#define PCAP_SRC_IFLOCAL 3
102/*!
103   \brief Internal representation of the type of source in use (file,
104   remote/local interface).
105
106   This indicates a remote interface, i.e. the user want to open a capture from
107   an interface on a remote host. This does involve the RPCAP protocol.
108*/
109#define PCAP_SRC_IFREMOTE 4
110
111/*!
112   \}
113*/
114
115
116
117/*! \addtogroup remote_source_string
118
119   The formats allowed by the pcap_open() are the following:
120   - file://path_and_filename [opens a local file]
121   - rpcap://devicename [opens the selected device devices available on the local host, without using the RPCAP protocol]
122   - rpcap://host/devicename [opens the selected device available on a remote host]
123   - rpcap://host:port/devicename [opens the selected device available on a remote host, using a non-standard port for RPCAP]
124   - adaptername [to open a local adapter; kept for compability, but it is strongly discouraged]
125   - (NULL) [to open the first local adapter; kept for compability, but it is strongly discouraged]
126
127   The formats allowed by the pcap_findalldevs_ex() are the following:
128   - file://folder/ [lists all the files in the given folder]
129   - rpcap:// [lists all local adapters]
130   - rpcap://host:port/ [lists the devices available on a remote host]
131
132   Referring to the 'host' and 'port' paramters, they can be either numeric or literal. Since
133   IPv6 is fully supported, these are the allowed formats:
134
135   - host (literal): e.g. host.foo.bar
136   - host (numeric IPv4): e.g. 10.11.12.13
137   - host (numeric IPv4, IPv6 style): e.g. [10.11.12.13]
138   - host (numeric IPv6): e.g. [1:2:3::4]
139   - port: can be either numeric (e.g. '80') or literal (e.g. 'http')
140
141   Here you find some allowed examples:
142   - rpcap://host.foo.bar/devicename [everything literal, no port number]
143   - rpcap://host.foo.bar:1234/devicename [everything literal, with port number]
144   - rpcap://10.11.12.13/devicename [IPv4 numeric, no port number]
145   - rpcap://10.11.12.13:1234/devicename [IPv4 numeric, with port number]
146   - rpcap://[10.11.12.13]:1234/devicename [IPv4 numeric with IPv6 format, with port number]
147   - rpcap://[1:2:3::4]/devicename [IPv6 numeric, no port number]
148   - rpcap://[1:2:3::4]:1234/devicename [IPv6 numeric, with port number]
149   - rpcap://[1:2:3::4]:http/devicename [IPv6 numeric, with literal port number]
150   
151   \{
152*/
153
154
155/*!
156   \brief String that will be used to determine the type of source in use (file,
157   remote/local interface).
158
159   This string will be prepended to the interface name in order to create a string
160   that contains all the information required to open the source.
161
162   This string indicates that the user wants to open a capture from a local file.
163*/
164#define PCAP_SRC_FILE_STRING "file://"
165/*!
166   \brief String that will be used to determine the type of source in use (file,
167   remote/local interface).
168
169   This string will be prepended to the interface name in order to create a string
170   that contains all the information required to open the source.
171
172   This string indicates that the user wants to open a capture from a network interface.
173   This string does not necessarily involve the use of the RPCAP protocol. If the
174   interface required resides on the local host, the RPCAP protocol is not involved
175   and the local functions are used.
176*/
177#define PCAP_SRC_IF_STRING "rpcap://"
178
179/*!
180   \}
181*/
182
183
184
185
186
187/*!
188   \addtogroup remote_open_flags
189   \{
190*/
191
192/*!
193   \brief Defines if the adapter has to go in promiscuous mode.
194
195   It is '1' if you have to open the adapter in promiscuous mode, '0' otherwise.
196   Note that even if this parameter is false, the interface could well be in promiscuous
197   mode for some other reason (for example because another capture process with
198   promiscuous mode enabled is currently using that interface).
199   On on Linux systems with 2.2 or later kernels (that have the "any" device), this
200   flag does not work on the "any" device; if an argument of "any" is supplied,
201   the 'promisc' flag is ignored.
202*/
203#define PCAP_OPENFLAG_PROMISCUOUS      1
204
205/*!
206   \brief Defines if the data trasfer (in case of a remote
207   capture) has to be done with UDP protocol.
208
209   If it is '1' if you want a UDP data connection, '0' if you want
210   a TCP data connection; control connection is always TCP-based.
211   A UDP connection is much lighter, but it does not guarantee that all
212   the captured packets arrive to the client workstation. Moreover,
213   it could be harmful in case of network congestion.
214   This flag is meaningless if the source is not a remote interface.
215   In that case, it is simply ignored.
216*/
217#define PCAP_OPENFLAG_DATATX_UDP         2
218
219
220/*!
221   \brief Defines if the remote probe will capture its own generated traffic.
222
223   In case the remote probe uses the same interface to capture traffic and to send
224   data back to the caller, the captured traffic includes the RPCAP traffic as well.
225   If this flag is turned on, the RPCAP traffic is excluded from the capture, so that
226   the trace returned back to the collector is does not include this traffic.
227*/
228#define PCAP_OPENFLAG_NOCAPTURE_RPCAP   4
229
230/*!
231   \brief Defines if the local adapter will capture its own generated traffic.
232
233   This flag tells the underlying capture driver to drop the packets that were sent by itself.
234   This is usefult when building applications like bridges, that should ignore the traffic
235   they just sent.
236*/
237#define PCAP_OPENFLAG_NOCAPTURE_LOCAL   8
238
239/*!
240   \brief This flag configures the adapter for maximum responsiveness.
241
242   In presence of a large value for nbytes, WinPcap waits for the arrival of several packets before
243   copying the data to the user. This guarantees a low number of system calls, i.e. lower processor usage,
244   i.e. better performance, which is good for applications like sniffers. If the user sets the
245   PCAP_OPENFLAG_MAX_RESPONSIVENESS flag, the capture driver will copy the packets as soon as the application
246   is ready to receive them. This is suggested for real time applications (like, for example, a bridge)
247   that need the best responsiveness.*/
248#define PCAP_OPENFLAG_MAX_RESPONSIVENESS   16
249
250/*!
251   \}
252*/
253
254
255/*!
256   \addtogroup remote_samp_methods
257   \{
258*/
259
260/*!
261   \brief No sampling has to be done on the current capture.
262
263   In this case, no sampling algorithms are applied to the current capture.
264*/
265#define PCAP_SAMP_NOSAMP   0
266
267/*!
268   \brief It defines that only 1 out of N packets must be returned to the user.
269
270   In this case, the 'value' field of the 'pcap_samp' structure indicates the
271   number of packets (minus 1) that must be discarded before one packet got accepted.
272   In other words, if 'value = 10', the first packet is returned to the caller, while
273   the following 9 are discarded.
274*/
275#define PCAP_SAMP_1_EVERY_N   1
276
277/*!
278   \brief It defines that we have to return 1 packet every N milliseconds.
279
280   In this case, the 'value' field of the 'pcap_samp' structure indicates the 'waiting
281   time' in milliseconds before one packet got accepted.
282   In other words, if 'value = 10', the first packet is returned to the caller; the next
283   returned one will be the first packet that arrives when 10ms have elapsed.
284*/
285#define PCAP_SAMP_FIRST_AFTER_N_MS 2
286
287/*!
288   \}
289*/
290
291
292/*!
293   \addtogroup remote_auth_methods
294   \{
295*/
296
297/*!
298   \brief It defines the NULL authentication.
299
300   This value has to be used within the 'type' member of the pcap_rmtauth structure.
301   The 'NULL' authentication has to be equal to 'zero', so that old applications
302   can just put every field of struct pcap_rmtauth to zero, and it does work.
303*/
304#define RPCAP_RMTAUTH_NULL 0
305/*!
306   \brief It defines the username/password authentication.
307
308   With this type of authentication, the RPCAP protocol will use the username/
309   password provided to authenticate the user on the remote machine. If the
310   authentication is successful (and the user has the right to open network devices)
311   the RPCAP connection will continue; otherwise it will be dropped.
312
313   This value has to be used within the 'type' member of the pcap_rmtauth structure.
314*/
315#define RPCAP_RMTAUTH_PWD 1
316
317/*!
318   \}
319*/
320
321
322
323
324/*!
325
326   \brief This structure keeps the information needed to autheticate
327   the user on a remote machine.
328   
329   The remote machine can either grant or refuse the access according
330   to the information provided.
331   In case the NULL authentication is required, both 'username' and
332   'password' can be NULL pointers.
333   
334   This structure is meaningless if the source is not a remote interface;
335   in that case, the functions which requires such a structure can accept
336   a NULL pointer as well.
337*/
338struct pcap_rmtauth
339{
340   /*!
341      \brief Type of the authentication required.
342
343      In order to provide maximum flexibility, we can support different types
344      of authentication based on the value of this 'type' variable. The currently
345      supported authentication methods are defined into the
346      \link remote_auth_methods Remote Authentication Methods Section\endlink.
347
348   */
349   int type;
350   /*!
351      \brief Zero-terminated string containing the username that has to be
352      used on the remote machine for authentication.
353     
354      This field is meaningless in case of the RPCAP_RMTAUTH_NULL authentication
355      and it can be NULL.
356   */
357   char *username;
358   /*!
359      \brief Zero-terminated string containing the password that has to be
360      used on the remote machine for authentication.
361     
362      This field is meaningless in case of the RPCAP_RMTAUTH_NULL authentication
363      and it can be NULL.
364   */
365   char *password;
366};
367
368
369/*!
370   \brief This structure defines the information related to sampling.
371
372   In case the sampling is requested, the capturing device should read
373   only a subset of the packets coming from the source. The returned packets depend
374   on the sampling parameters.
375
376   \warning The sampling process is applied <strong>after</strong> the filtering process.
377   In other words, packets are filtered first, then the sampling process selects a
378   subset of the 'filtered' packets and it returns them to the caller.
379*/
380struct pcap_samp
381{
382   /*!
383      Method used for sampling. Currently, the supported methods are listed in the
384      \link remote_samp_methods Sampling Methods Section\endlink.
385   */
386   int method;
387
388   /*!
389      This value depends on the sampling method defined. For its meaning, please check
390      at the \link remote_samp_methods Sampling Methods Section\endlink.
391   */
392   int value;
393};
394
395
396
397
398//! Maximum lenght of an host name (needed for the RPCAP active mode)
399#define RPCAP_HOSTLIST_SIZE 1024
400
401
402/*!
403   \}
404*/ // end of public documentation
405
406
407// Exported functions
408
409
410
411/** \name New WinPcap functions
412
413   This section lists the new functions that are able to help considerably in writing
414   WinPcap programs because of their easiness of use.
415 */
416//\{
417pcap_t *pcap_open(const char *source, int snaplen, int flags, int read_timeout, struct pcap_rmtauth *auth, char *errbuf);
418int pcap_createsrcstr(char *source, int type, const char *host, const char *port, const char *name, char *errbuf);
419int pcap_parsesrcstr(const char *source, int *type, char *host, char *port, char *name, char *errbuf);
420int pcap_findalldevs_ex(char *source, struct pcap_rmtauth *auth, pcap_if_t **alldevs, char *errbuf);
421struct pcap_samp *pcap_setsampling(pcap_t *p);
422
423//\}
424// End of new winpcap functions
425
426
427
428/** \name Remote Capture functions
429 */
430//\{
431SOCKET pcap_remoteact_accept(const char *address, const char *port, const char *hostlist, char *connectinghost, struct pcap_rmtauth *auth, char *errbuf);
432int pcap_remoteact_list(char *hostlist, char sep, int size, char *errbuf);
433int pcap_remoteact_close(const char *host, char *errbuf);
434void pcap_remoteact_cleanup();
435//\}
436// End of remote capture functions
437
438#ifdef __cplusplus
439}
440#endif
441
442
443#endif
444

https://github.com/mamedev/mame/commit/2cc8e27769db78ee63d2b579005d1a7c5f0fbb0f

Previous 199869 Revisions Next

© 1997-2024 The MAME Team