nsock.h

来自「Ubuntu packages of security software。 相」· C头文件 代码 · 共 538 行 · 第 1/2 页

/***************************************************************************
 * nsock.h -- public interface definitions for the nsock parallel socket   *
 * event library                                                           *
 *                                                                         *
 ***********************IMPORTANT NSOCK LICENSE TERMS***********************
 *                                                                         *
 * The nsock parallel socket event library is (C) 1999-2008 Insecure.Com   *
 * LLC This library is free software; you may redistribute and/or          *
 * modify it under the terms of the GNU General Public License as          *
 * published by the Free Software Foundation; Version 2.  This guarantees  *
 * your right to use, modify, and redistribute this software under certain *
 * conditions.  If this license is unacceptable to you, Insecure.Com LLC   *
 * may be willing to sell alternative licenses (contact                    *
 * [e-mail] ).                                                   *
 *                                                                         *
 * As a special exception to the GPL terms, Insecure.Com LLC grants        *
 * permission to link the code of this program with any version of the     *
 * OpenSSL library which is distributed under a license identical to that  *
 * listed in the included Copying.OpenSSL file, and distribute linked      *
 * combinations including the two. You must obey the GNU GPL in all        *
 * respects for all of the code used other than OpenSSL.  If you modify    *
 * this file, you may extend this exception to your version of the file,   *
 * but you are not obligated to do so.                                     *
 *                                                                         * 
 * If you received these files with a written license agreement stating    *
 * terms other than the (GPL) terms above, then that alternative license   *
 * agreement takes precedence over this comment.                          *
 *                                                                         *
 * Source is provided to this software because we believe users have a     *
 * right to know exactly what a program is going to do before they run it. *
 * This also allows you to audit the software for security holes (none     *
 * have been found so far).                                                *
 *                                                                         *
 * Source code also allows you to port Nmap to new platforms, fix bugs,    *
 * and add new features.  You are highly encouraged to send your changes   *
 * to [e-mail] for possible incorporation into the main         *
 * distribution.  By sending these changes to Fyodor or one the            *
 * insecure.org development mailing lists, it is assumed that you are      *
 * offering Fyodor and Insecure.Com LLC the unlimited, non-exclusive right *
 * to reuse, modify, and relicense the code.  Nmap will always be          *
 * available Open Source, but this is important because the inability to   *
 * relicense code has caused devastating problems for other Free Software  *
 * projects (such as KDE and NASM).  We also occasionally relicense the    *
 * code to third parties as discussed above.  If you wish to specify       *
 * special license conditions of your contributions, just say so when you  *
 * send them.                                                              *
 *                                                                         *
 * This program is distributed in the hope that it will be useful, but     *
 * WITHOUT ANY WARRANTY; without even the implied warranty of              *
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU       *
 * General Public License for more details (                               *
 * http://www.gnu.org/copyleft/gpl.html ).                                 *
 *                                                                         *
 ***************************************************************************/

/* $Id: nsock.h 6635 2007-12-22 06:32:18Z fyodor $ */

/* Would you like to include pcap support in nsock?
 * Pcap support code is currently unstable, so we give
 * you a choice. In future this #define will be removed.*/
#define HAVE_PCAP 1

#ifndef NSOCK_H
#define NSOCK_H



#include <sys/types.h>
#ifndef WIN32
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
#include <sys/time.h>
#endif

#ifdef __cplusplus
extern "C" {
#endif

/* The read calls will generally return after reading at least this
 * much data so that the caller can process it and so that the
 * connection spewing data doesn't monopolize resources.  The caller
 * can always initiate another read request to ask for more.
 */
#define NSOCK_READ_CHUNK_SIZE 0x8FFFF

/*********************  TYPEDEFS ********************/
/* nsock_pool, nsock_iod, and nsock_event are opaque objects that should 
   only be accessed using the appropriate accessor functions (described 
   below).  
 */

/* An nsock_pool aggregates and manages events and i/o descriptors */
typedef void *nsock_pool;

/* nsock_iod is an I/O descriptor -- you create it and then use it to
   make calls to do connect()s, read()s, write()s, etc.  A single IOD
   can handle multiple event calls, but only one at a time.  Also the
   event calls must be in a "reasonable" order.  For example, you
   might start with nsock_connect_tcp() followed by a bunch of
   nsock_read* and nsock_write* calls.  Then you either destroy the
   iod for good with nsi_delete() and allocate a new one via nsi_new
   for your next connection. */
typedef void *nsock_iod;

/* An event is created when you do various calls (for reading, writing,
   connecting, timers, etc) and is provided back to you in the callback
   when the call completes/fails. It is automatically destroyed after
   the callback 
*/
typedef void *nsock_event;

/* Provided by calls which (internally) create an nsock_event.  This allows
   you to cancel the event */
typedef unsigned long nsock_event_id;

/* This is used to save SSL sessionids between SSL connections */
typedef void *nsock_ssl_session;

/********************   PROTOTYPES *******************/


/* Here is the all important looping function that tells the event
   engine to start up and begin processing events.  It will continue
   until all events have been delivered (including new ones started
   from event handlers), or the msec_timeout is reached, or a major
   error has occured.  Use -1 if you don't want to set a maximum time
   for it to run.  A timeout of 0 will return after 1 non-blocking
   loop.  The nsock loop can be restarted again after it returns.  For
   example you could do a series of 15 second runs, allowing you to do
   other stuff between them.  Or you could just schedule a timer to
   call you back every 15 seconds.*/
enum nsock_loopstatus { NSOCK_LOOP_NOEVENTS = 2, NSOCK_LOOP_TIMEOUT, NSOCK_LOOP_ERROR };
enum nsock_loopstatus nsock_loop(nsock_pool nsp, int msec_timeout);

/* This next function returns the errno style error code -- which is only
   valid if the status is NSOCK_LOOP_ERROR was returned by nsock_loop() */
int nsp_geterrorcode(nsock_pool nsp);

/* Every nsp has an ID that is unique across the program execution */
unsigned long nsp_getid(nsock_pool nsp);

/* Note that nsi_get1_ssl_session will increment the usage count
 * of the SSL_SESSION, since nsock does a free when the nsi is
 * destroyed.  It's up to any calling function/etc to do a
 * SSL_SESSION_free() on it.  nsi_get0_ssl_session doesn't
 * increment, and is for informational purposes only.
 */
nsock_ssl_session nsi_get1_ssl_session(nsock_iod nsockiod);
nsock_ssl_session nsi_get0_ssl_session(nsock_iod nsockiod);

/* Sometimes it is useful to store a pointer to information inside
   the NSP so you can retrieve it during a callback. */
void nsp_setud(nsock_pool nsp, void *data);

/* And the function above wouldn't make much sense if we didn't have a way
   to retrieve that data ... */
void *nsp_getud(nsock_pool nsp);

/* Sets a trace/debug level.  Zero (the default) turns tracing off,
   while higher numbers are more verbose.  This is generally only used
   for debugging purposes.  Trace logs are printed to stdout.  The
   initial value is set in nsp_new().  A level of 1 or 2 is usually
   sufficient, but 10 will ensure you get everything.  The basetime
   can be NULL to print trace lines with the current time, otherwise
   the difference between the current time and basetime will be used
   (the time program execution starts would be a good candidate) */
void nsp_settrace(nsock_pool nsp, int tracelevel, const struct timeval *basetime);

/* And here is how you create an nsock_pool.  This allocates, initializes,
   and returns an nsock_pool event aggregator.  In the case of error,
   NULL will be returned.  If you do not wish to immediately associate
   any userdata, pass in NULL. */
nsock_pool nsp_new(void *userdata);

/* If nsp_new returned success, you must free the nsp when you are
   done with it to conserve memory (and in some cases, sockets).
   After this call, nsp may no longer be used.  Any pending events are
   sent an NSE_STATUS_KILL callback and all outstanding iods are
   deleted. */
void nsp_delete(nsock_pool nsp);

/* nsock_event handles a single event.  Its ID is generally returned when
   the event is created, and the event itself is included in callbacks */
/* IF YOU ADD NEW NSE_TYPES YOU MUST INCREASE TYPE_CODE_NUM_BITS SO THAT
   IT IS ALWAYS log2(maximum_nse_type_value + 1) */
#define TYPE_CODE_NUM_BITS 3
enum nse_type { 
	NSE_TYPE_CONNECT=0,
	NSE_TYPE_CONNECT_SSL=1,
	NSE_TYPE_READ=2,
	NSE_TYPE_WRITE=3, 
	NSE_TYPE_TIMER=4,
	NSE_TYPE_PCAP_READ=5,
	NSE_TYPE_MAX=6,
};  /* At some point I was considering a NSE_TYPE_START and NSE_TYPE_CUSTOM */

/* Find the type of an event that spawned a callback */
enum nse_type nse_type(nsock_event nse);

/* Takes an nse_type (as returned by nse_type() and returns a static
   string name that you can use for printing, etc. */
const char *nse_type2str(enum nse_type type);

/* Did the event succeed?  What is the status? */
enum nse_status { NSE_STATUS_NONE = 0, /* User should never see this */
                  NSE_STATUS_SUCCESS, /* Everything went A-OK! */
                  NSE_STATUS_ERROR, /* Uh-oh!  Problem, check the
				       nse_errorcode() */
		  NSE_STATUS_TIMEOUT, /* The async call surpassed the
					 timeout you specified */
		  NSE_STATUS_CANCELLED, /* Someone cancelled the
                                           event. (by calling
                                           nsock_event_cancel. */
		  NSE_STATUS_KILL, /* The event has been killed, this
				      generally means the nspool is
				      being deleted -- you should free
				      up any resources you have
				      allocated and exit.  Don't you
				      dare make any more async nsock calls!  */
		  NSE_STATUS_EOF /* We got EOF and NO DATA -- if we got data
				    first, SUCCESS is reported (see nse_eof() 
				 */
                 }; 

enum nse_status nse_status(nsock_event nse);

/* Takes an nse_status (as returned by nse_status() and returns a static
   string name that you can use for printing, etc. */
const char *nse_status2str(enum nse_status status);

/* This next function tells whether we received an EOF when we
   were reading.  It is generally a better way to check for EOF
   than looking at the status because sometimes we read some data
   before getting the EOF, in which SUCCESS is returned (although
   another read attempt would return a status of EOF).  nse_eof
   returns nonzero if we have reached EOF, zero if we have NOT
   reach EOF.  */
int nse_eof(nsock_event nse);

/* This next function returns the errno style error code -- which is only
   valid if the status is NSE_STATUS_ERROR (this is a normal errno style
   errorcode */
int nse_errorcode(nsock_event nse);

/* Every event has an ID which will be unique throughout the program's execution (for a given nsock_pool) unless you blow through 500,000,000 of them */
nsock_event_id nse_id(nsock_event nse);

/* If you did a read request, and the result was STATUS_SUCCESS, this 
   function provides the buffer that was read in as well as the number
   of chars read.  The buffer should not be modified or free'd .  It is not 
   guaranteed to be NUL-terminated and it may even contain nuls */
char *nse_readbuf(nsock_event nse, int *nbytes);

/* Obtains the nsock_iod (see below) associated with the event.  Note that 
   some events (such as timers) don't have an nsock_iod associated with them
*/
nsock_iod nse_iod(nsock_event nse);


/* nsock_iod is like a "file descriptor" for the nsock library.  You
   use it to request events.  And here is how you create an nsock_iod.
   nsi_new returns NULL if the iod cannot be allocated.  Pass NULL as
   userdata if you don't want to immediately associate any user data
   with the iod. */
nsock_iod nsi_new(nsock_pool nsockp, void *userdata);

/* This version allows you to associate an existing sd with the msi