nsock.h

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

   so that you can read/write it using the nsock infrastructure.  For example,
   you may want to watch for data from STDIN_FILENO at the same time as you
   read/wrtie various sockets. Ths sd is dup()ed, so you may close or
   otherwise manipulate your copy.  The duped copy will be destroyed when the
   nsi is destroyed 
*/
nsock_iod nsi_new2(nsock_pool nsockp, int sd, void *userdata);

/* If msiod_new returned success, you must free the iod when you are
   done with it to conserve memory (and in some cases, sockets).
   After this call, nsockiod may no longer be used -- you need to
   create a new one with nsi_new().  pending_response tells what to do
   with any events that are pending on this nsock_iod.  This can be
   NSOCK_PENDING_NOTIFY (send a KILL notification to each event),
   NSOCK_PENDING_SILENT (do not send notification to the killed
   events), or NSOCK_PENDING_ERROR (print an error message and quiit
   the program) */
#define NSOCK_PENDING_NOTIFY 1
#define NSOCK_PENDING_SILENT 2
#define NSOCK_PENDING_ERROR 4
void nsi_delete(nsock_iod nsockiod, int pending_response);

/* Sometimes it is useful to store a pointer to information inside
   the nsiod so you can retrieve it during a callback. */
void nsi_setud(nsock_iod nsiod, void *data);

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

/* I didn't want to do this.  Its an ugly hack, but I suspect it will
   be neccessary.  I certainly can't reproduce in nsock EVERYTHING you
   might want to do with a socket.  So I'm offering you this function
   to obtain the socket descriptor which is (usually) wrapped in a
   nsock_iod).  You can do "reasonable" things with it, like setting
   socket receive buffers.  But don't create havok by closing the
   descriptor!  If the descriptor you get back is -1, the iod does not
   currently possess a valid descriptor */
int nsi_getsd(nsock_iod nsiod);

/* Returns the ID of an nsock_iod .  This ID is always unique amongst
   ids for a given nspool (unless you blow through billions of them). */
unsigned long nsi_id(nsock_iod nsockiod);

  /* Returns 1 if an NSI is communicating via SSL, 0 otherwise */
int nsi_checkssl(nsock_iod nsockiod);

/* Returns that host/port/protocol information for the last
   communication (or comm. attempt) this nsi has been involved with.
   By "involved" with I mean interactions like establishing (or trying
   to) a connection or sending a UDP datagram through an unconnected
   nsock_iod.  AF is the address family (AF_INET or AF_INET6), Protocl
   is IPPROTO_TCP or IPPROTO_UDP.  Pass NULL for information you do
   not need.  If ANY of the information you requested is not
   available, 0 will be returned and the unavailable sockets are
   zeroed.  If protocol or af is requested but not available, it will
   be set to -1 (and 0 returned).  The pointers you pass in must be
   NULL or point to allocated address space.  The sockaddr members
   should actually be sockaddr_storage, sockaddr_in6, or sockaddr_in
   with the socklen of them set appropriately (eg
   sizeof(sockaddr_storage) if that is what you are passing). */
int nsi_getlastcommunicationinfo(nsock_iod ms_iod, int *protocol,
				 int *af, struct sockaddr *local, 
				 struct sockaddr *remote, size_t socklen);

/* EVENT CREATION FUNCTIONS -- These functions request asynchronous
   notification of completion of an event.  The handler will never be
   synchronously called back during the event creation call (that
   causes too many hard to debug errors and plus we don't want people
   to have to deal with callbacks until they actually call nsock_loop */

/* These functions generally take a common 5 initial parameters:

   nsock_pool mst -- the is the nsock_pool describing the events you have 
         scheduled, etc

   nsock_iod  nsiod -- The I/O Descriptor that should be used in the 
         request.  Note that timer events don't have this argument since
         they don't use an iod.  You can obtain it in the callback from
	 the nsock_event. 

   nsock_ev_handler handler -- This is the function you want the
	 system to call when your event is triggered (or times out, or
	 hits an error, etc.).  The function should be of this form:
	 void funcname(nsock_pool nsp, nsock_event nse, void *userdata)

   int timeout_msecs -- The timeout for the request in milliseconds.
         If the request hasn't completed (or in a few cases started)
         within the timeout specified, the handler will be called with
         a TIMEOUT status and the request will be aborted.

   void *userdata -- The nsock_event that comes back can
         optionally have a pointer associated with it.  You can set
         that pointer here.  If you don't want one, just pass NULL.

   These functions return an nsock_event_id which can be used to cancel
   the event if neccessary.
*/

typedef void (*nsock_ev_handler)(nsock_pool, nsock_event, void *);

/* Request a TCP connection to another system (by IP address).  The
   in_addr is normal network byte order, but the port number should be
   given in HOST BYTE ORDER.  ss should be a sockaddr_storage,
   sockaddr_in6, or sockaddr_in as appropriate (just like what you
   would pass to connect).  sslen should be the sizeof the structure
   you are passing in. */
nsock_event_id nsock_connect_tcp(nsock_pool nsp, nsock_iod nsiod, 
				 nsock_ev_handler handler, int timeout_msecs, 
				 void *userdata, struct sockaddr *ss,
				 size_t sslen, unsigned short port);

/* Request a UDP "connection" to another system (by IP address).  The
   in_addr is normal network byte order, but the port number should be
   given in HOST BYTE ORDER.  Since this is UDP, no packets are
   actually sent.  The destination IP and port are just associated
   with the nsiod (an actual OS connect() call is made).  You can then
   use the normal nsock write calls on the socket.  There is no
   timeout since this call always calls your callback at the next
   opportunity.  The advantages to having a connected UDP socket (as
   opposed to just specifying an address with sendto() are that we can
   now use a consistent set of write/read calls for TCP/UDP, received
   packets from the non-partner are automatically dropped by the OS,
   and the OS can provide asynchronous errors (see Unix Network
   Programming pp224).  ss should be a sockaddr_storage,
   sockaddr_in6, or sockaddr_in as appropriate (just like what you
   would pass to connect).  sslen should be the sizeof the structure
   you are passing in. */
nsock_event_id nsock_connect_udp(nsock_pool nsp, nsock_iod nsiod, 
				 nsock_ev_handler handler, void *userdata, 
				 struct sockaddr *ss, size_t sslen,
				 unsigned short port);

/* Request an SSL over TCP connection to another system (by IP
   address).  The in_addr is normal network byte order, but the port
   number should be given in HOST BYTE ORDER.  This function will call
   back only after it has made the TCP connection AND done the initial
   SSL negotiation.  From that point on, you use the normal read/write
   calls and decryption will happen transparently. ss should be a
   sockaddr_storage, sockaddr_in6, or sockaddr_in as appropriate (just
   like what you would pass to connect).  sslen should be the sizeof
   the structure you are passing in. */
nsock_event_id nsock_connect_ssl(nsock_pool nsp, nsock_iod nsiod, 
				 nsock_ev_handler handler, int timeout_msecs, 
				 void *userdata, struct sockaddr *ss, 
				 size_t sslen, unsigned short port,
				 nsock_ssl_session ssl_session);

/* Request ssl connection over already established TCP connection.
   nsiod must be socket that is already connected to target
   using nsock_connect_tcp.
   All parameters have the same meaning as in 'nsock_connect_ssl' */
nsock_event_id nsock_reconnect_ssl(nsock_pool nsp, nsock_iod nsiod,
				   nsock_ev_handler handler, int timeout_msecs,
                                   void *userdata, nsock_ssl_session ssl_session);

/* Read up to nlines lines (terminated with \n, which of course
   inclues \r\n), or until EOF, or until the timeout, whichever comes
   first.  Note that NSE_STATUS_SUCCESS will be returned in the case
   of EOF or tiemout if at least 1 char has been read.  Also note that
   you may get more than 'nlines' back -- we just stop once "at least"
   'nlines' is read */
nsock_event_id nsock_readlines(nsock_pool nsp, nsock_iod nsiod, 
			 nsock_ev_handler handler, int timeout_msecs,
			 void *userdata, int nlines);

/* Same as above, except it tries to read at least 'nbytes' instead of 
   'nlines'. */
nsock_event_id nsock_readbytes(nsock_pool nsp, nsock_iod nsiod,
			 nsock_ev_handler handler, int timeout_msecs, 
			 void *userdata, int nbytes);

/* The simplest read function -- returns NSE_STATUS_SUCCESS when it
   reads anything, otherwise it returns timeout, eof, or error as
   appropriate */
nsock_event_id nsock_read(nsock_pool nsp, nsock_iod nsiod, nsock_ev_handler handler, 
		    int timeout_msecs, void *userdata);

/* Write some data to the socket.  If the write is not COMPLETED within timeout_msecs , NSE_STATUS_TIMEOUT will be returned.  If you are supplying NUL-terminated data, you can optionally pass -1 for datalen and nsock_write will figure out the length itself */
nsock_event_id nsock_write(nsock_pool nsp, nsock_iod nsiod, 
		     nsock_ev_handler handler, int timeout_msecs, 
		     void *userdata, const char *data, int datalen);

/* Same as nsock_write except you can use a printf-style format and you can only use this for ASCII strings */
nsock_event_id nsock_printf(nsock_pool nsp, nsock_iod nsiod, 
		      nsock_ev_handler handler, int timeout_msecs, 
		      void *userdata, char *format, ... );

/* Send back an NSE_TYPE_TIMER after the number of milliseconds specified.  Of course it can also return due to error, cancellation, etc. */
nsock_event_id nsock_timer_create(nsock_pool nsp, nsock_ev_handler handler, 
			    int timeout_msecs, void *userdata);

/* Cancel an event (such as a timer or read request).  If notify is
 nonzero, the requester will be sent an event CANCELLED status back to
 the given handler.  But in some cases there is no need to do this
 (like if the function deleting it is the one which created it), in
 which case 0 can be passed to skip the step.  This function returns
 zero if the event is not found, nonzero otherwise */
int nsock_event_cancel(nsock_pool ms_pool, nsock_event_id id, int notify );

/* Grab the latest time as recorded by the nsock library, which does
   so at least once per event loop (in main_loop).  Not only does this
   function (generally) avoid a system call, but in many circumstances
   it is better to use nsock's time rather than the system time.  If
   nsock has never obtained the time when you call it, it will do so
   before returning */
const struct timeval *nsock_gettimeofday();


#ifdef HAVE_PCAP
/*
 * Open pcap device and connect it to nsp. Other parameters have the
 * same meaning as for pcap_open_live in pcap(3).
 * 	device   : pcap-style device name
 * 	snaplen  : size of packet to be copied to handler
 * 	promisc  : whether to open device in promiscous mode
 * 	bpf_fmt	 : berkeley filter 
 * return value: NULL if everything was okay, or error string if error occurred
 * [sorry Fyodor for breaking the API, but it's just simpler]
 * */
char *nsock_pcap_open(nsock_pool nsp, nsock_iod nsiod, 
		const char *pcap_device, int snaplen, int promisc,
		const char *bpf_fmt, ...);

/*
 * Requests exacly one packet to be captured.from pcap. 
 * See nsock_read() for parameters description.
 * */
nsock_event_id nsock_pcap_read_packet(nsock_pool nsp, nsock_iod nsiod, 
			 nsock_ev_handler handler, int timeout_msecs,
			 void *userdata);

/*
 * Gets packet data. This should be called after succesfull receiving of packet
 * to get packet.  If you're not interested in some values, just pass NULL
 * instead of valid pointer.
 * l3_data is just after l2_data in buffer. Feel free to treat l2_data as one
 * buffer with size of (l2_len + l3_len). 
 * Ts time is fixed for systems that don't support proper timing, like Windows.
 * So TS is pointing to time when packet was received or to the time _after_.
 * As a result you'll get longer times than you should, but it's safer to
 * think that host is a bit further. 
 * */
void nse_readpcap(nsock_event nsee,
	const unsigned char **l2_data, size_t *l2_len,
	const unsigned char **l3_data, size_t *l3_len,
	size_t *packet_len, struct timeval *ts); 

/* Well. Just pcap-style datalink. Like DLT_EN10MB or DLT_SLIP. Check in pcap(3) manpage. */
int nsi_pcap_linktype(nsock_iod nsiod);

/* Is this nsiod a pcap descriptor? */
int nsi_is_pcap(nsock_iod nsiod);

#endif /* HAVE_PCAP */

#ifdef __cplusplus
} /* End of 'extern "C"' */
#endif

#endif /* NSOCK_H */