Document new interrogation macros. Fix text a bit.

[mLib] / conn.h

/* -*-c-*-
 *
 * $Id: conn.h,v 1.5 1999/12/10 23:42:04 mdw Exp $
 *
 * Nonblocking connect handling
 *
 * (c) 1999 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------* 
 *
 * This file is part of the mLib utilities library.
 *
 * mLib is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Library General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * License, or (at your option) any later version.
 * 
 * mLib 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 Library General Public License for more details.
 * 
 * You should have received a copy of the GNU Library General Public
 * License along with mLib; if not, write to the Free
 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
 * MA 02111-1307, USA.
 */

/*----- Revision history --------------------------------------------------* 
 *
 * $Log: conn.h,v $
 * Revision 1.5  1999/12/10 23:42:04  mdw
 * Change header file guard names.
 *
 * Revision 1.4  1999/05/26 21:08:01  mdw
 * Remove redundant structure member.
 *
 * Revision 1.3  1999/05/23 12:12:46  mdw
 * Interface change to make the `conn' selector useful for generic stream
 * sockets rather than just IPv4 ones.
 *
 * Revision 1.2  1999/05/15 10:33:32  mdw
 * Fix copyright notices.
 *
 * Revision 1.1  1999/05/14 21:01:14  mdw
 * Integrated `select' handling bits from the background resolver project.
 *
 */

#ifndef MLIB_CONN_H
#define MLIB_CONN_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Header files ------------------------------------------------------*/

#include <sys/types.h>
#include <sys/socket.h>

#ifndef MLIB_SEL_H
#  include "sel.h"
#endif

/*----- Data structures ---------------------------------------------------*/

/* --- The nonblocking connect structure --- */

typedef struct conn {
  sel_file writer;			/* Select listener */
  void (*func)(int /*fd*/, void */*p*/); /* Handler function */
  void *p;				/* Argument for handler function */
} conn;

/*----- Functions provided ------------------------------------------------*/

/* --- @conn_init@ --- *
 *
 * Arguments:	@conn *c@ = pointer to connection block
 *		@sel_state *s@ = pointer to select state to attach to
 *		@int fd@ = file descriptor of socket to connect
 *		@struct sockaddr *dst@ = destination address
 *		@int dsz@ = size of destination address
 *		@void (*func)(int fd, void *p) = handler function
 *		@void *p@ = argument for the handler function
 *
 * Returns:	---
 *
 * Use:		Sets up a nonblocking connect job.  The socket should already
 *		be bound if you care about that sort of thing.  When the
 *		connection completes, the handler function is called with the
 *		connected socket as an argument.  If the connect fails rather
 *		than completes, the socket is closed, and the handler is
 *		informed of this by being passed a negative file descriptor.
 *		In either case, the select job is then removed.
 */

extern void conn_init(conn */*c*/, sel_state */*s*/, int /*fd*/,
		      struct sockaddr */*dst*/, int /*dsz*/,
		      void (*/*func*/)(int /*fd*/, void */*p*/),
		      void */*p*/);

/* --- @conn_kill@ --- *
 *
 * Arguments:	@conn *c@ = pointer to connection to dispose of
 *
 * Returns:	---
 *
 * Use:		Disposes of a connection when it's not wanted any more.  The
 *		connect handler function is not called.
 */

extern void conn_kill(conn */*c*/);

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif