Annotation of embedaddon/libnet/win32/wpdpack/Include/remote-ext.h, revision 1.1.1.1

1.1       misho       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
                     48: extern "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: */
                    338: struct 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: */
                    380: struct 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: //\{
                    417: pcap_t *pcap_open(const char *source, int snaplen, int flags, int read_timeout, struct pcap_rmtauth *auth, char *errbuf);
                    418: int pcap_createsrcstr(char *source, int type, const char *host, const char *port, const char *name, char *errbuf);
                    419: int pcap_parsesrcstr(const char *source, int *type, char *host, char *port, char *name, char *errbuf);
                    420: int pcap_findalldevs_ex(char *source, struct pcap_rmtauth *auth, pcap_if_t **alldevs, char *errbuf);
                    421: struct 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: //\{ 
                    431: SOCKET pcap_remoteact_accept(const char *address, const char *port, const char *hostlist, char *connectinghost, struct pcap_rmtauth *auth, char *errbuf);
                    432: int pcap_remoteact_list(char *hostlist, char sep, int size, char *errbuf);
                    433: int pcap_remoteact_close(const char *host, char *errbuf);
                    434: void pcap_remoteact_cleanup();
                    435: //\}
                    436: // End of remote capture functions
                    437: 
                    438: #ifdef __cplusplus
                    439: }
                    440: #endif
                    441: 
                    442: 
                    443: #endif
                    444: 

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>