/* $Id: mcl_lib_api.h,v 1.3 2003/10/31 14:58:47 chneuman Exp $ */
/*
 *  Copyright (c) 1999-2003 INRIA - All rights reserved
 *  (main author: Vincent Roca - vincent.roca@inrialpes.fr)
 *
 *  This program is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU General Public License
 *  as published by the Free Software Foundation; either version 2
 *  of the License, or (at your option) any later version.
 *
 *  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.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
 *  USA.
 */

#ifndef MCL_LIB_API_H
#define MCL_LIB_API_H

/* 
 * MCL API definition.
 * This is the ONLY header file that must be included by all external
 * applications!
 *
 * This common part of the MCL API includes a reliable multicast specific
 * part, depending on whether ALC or NORM is used.
 * This RM-specific part defines the various control parameters that can
 * be set with mcl_ctl(). You should have a look at it if you build an
 * application on top of MCL.
 */


/****** ALC or NORM Specific Part *********************************************/

/* 
 * library options set with the mcl_ctl() function are defined in these
 * include files.
 */
#ifdef ALC
#include "alc/mcl_lib_api_alc.h"
#elif defined NORM
#include "norm/mcl_lib_api_norm.h"
#else
Error, either ALC or NORM should be defined when including this file according
to the reliable multicast protocol you want to use...
#endif


/****** Common Part ***********************************************************/

/**
 * Open an MCL-ALC or MCL-NORM session.
 * Wether it uses ALC or NORM as its reliable multicast protocol depends
 * on the compilation parameters. The same application cannot concurrently
 * have ALC and NORM sessions, they are mutually exclusive (this is a
 * limitation of the current implementation!).
 *
 * @param  mode	defines the kind of session ("r", "w")
 * @return	returns to appli a unique identifier if ok, or < 0 in case of error
 */
extern int	mcl_open	(const char *mode);

/**
 * Close the MCL session.
 *
 * @param  id	MCL session identifier
 * @return	returns 0 if ok, or < 0 in case of error
 */
extern int	mcl_close	(int id);

extern int	mcl_abort	(int id);

/**
 * Get or set control parameters for the session.
 * Follows the Unix ioctl() syscall interface.
 * Warning: usually the tx and rx contexts are still not fully initialized!
 * This is only done during the first call to mcl_send or mcl_recv...
 *
 * @param id	MCL session identifier
 * @param optname	the option to set/get/change
 * @param optvalue	the associated value to set or to read. It is
 * 			either a simple type (e.g. int) or a structure
 * 			(e.g. struct sockaddr). This value can be either
 * 			set in MCL or read from MCL's internals and
 * 			returned to the appli.
 * @param optlen	the length in bytes of the associated value field
 * @return		returns 0 if ok, or < 0 in case of error
 */
extern int	mcl_ctl		(int id, int optname, void *optvalue,
				 int optlen);

/**
 * mcl_send data sending function.
 *
 * @param id	MCL session identifier
 * @param data	data block; in MCL_OPT_REUSE_APPLI_TX_BUFFER mode, the
 * 		data pointer must be the result of a standard
 * 		malloc/calloc/realloc function call.
 * @param len	data block length in bytes
 * @return	number of bytes sent or -1 if error
 */
extern int	mcl_send	(int id, const void *data, int len);

/**
 * mcl_sendto data sending function.
 *
 * @param id	MCL session identifier
 * @param data	data block; in MCL_OPT_REUSE_APPLI_TX_BUFFER mode, the
 * 		data pointer must be the result of a standard
 * 		malloc/calloc/realloc function call.
 * @param len	data block length in bytes
 * @param saddr	destination address (so far only AF_INET is supported)
 * @param saddr_len	address length (the sockaddr struct is generic!)
 * @return	number of bytes sent or -1 if error
 */
extern int	mcl_sendto	(int id, const void *data, int len,
				 const struct sockaddr *saddr, int saddr_len);

/**
 * mcl_recv data reception function.
 *
 * @param id	MCL session identifier
 * @param buf	pointer to data buffer
 * @param len	data buffer length in bytes
 * @return	number of bytes received or -1 if error
 */
#ifdef STREAM
extern int	mcl_recv	(int id, void *buf, int len, int nb_layer);
#else
extern int	mcl_recv	(int id, void *buf, int len);
#endif
extern int	mcl_recv_flute	(int id, void *buf, int len, unsigned int *toi);
/**
 * mcl_recvfrom data reception function.
 *
 * @param id	MCL session identifier
 * @param data	pointer to data buffer
 * @param len	data buffer length in bytes
 * @param saddr	source address from which data was received
 * 			(so far only AF_INET is supported)
 * @param saddr_len	pointer to address length (sockaddr struct is generic!).
 * 			This argument is modified by mcl_recvfrom to contain
 * 			the actual length of the address at function return.
 * @return	number of bytes received or -1 if error
 */
#ifdef STREAM
extern int	mcl_recvfrom	(int id, void * buf, int len,
				 struct sockaddr *saddr, int *saddr_len, int nb_layer);
#else
extern int	mcl_recvfrom	(int id, void * buf, int len,
				 struct sockaddr *saddr, int *saddr_len);
#endif
extern int	mcl_recvfrom_flute (int id, void * buf, int len,
				 struct sockaddr *saddr, int *saddr_len,
				 unsigned int * toi);

#ifdef ALC
/**
 * mcl_wait_event waits (i.e. blocks) until a given event takes
 * place and then returns.
 * This function is only defined with MCL-ALC sessions.
 *
 * @param id	MCL session identifier
 * @param int	event type
 * @return	0 if ok, -1 if error
 */
extern int	mcl_wait_event	(int id, int event);


/**
 * mcl_select waits until an event occured in one of its file
 * descriptors or until it timeout's.
 * This function currently has many limitations:
 *  - it only waits until on readfs descriptors, other file descriptor
 *    pointers must be NULL
 *  - it only considers a single readfds, waiting on multiple MCL sessions
 *    is not supported
 *  - only MCL session descriptors can be specified in the file descriptor
 *    set. It is not possible to mix non-MCL and MCL descriptors
 *  - it is only available on MCL-ALC sessions.
 * The behavior and parameters are otherwise similar to that of the
 * socket select() system call.
 * @param n	max MCL session identifier plus 1
 * @param readfs	table of MCL session identifier (only one is
 *			currently possible)
 * @param writefs	not supported, must be NULL
 * @param exceptfs	not supported, must be NULL
 * @param timeout	pointer to a timeval structure, indicating how
 *			long select can wait. If NULL, this function
 *			returns immediately
 * @return	On success, it return the number of descriptors contained
 *		in the descriptor sets, which may be zero if the timeout
 *		expires before anything interesting happens.
 *		On error -1 is returned and errno is set appropriately;
 *		the sets and timeout become undefined, so do not rely on
 *		their contents after an error.
 */
extern int	mcl_select	(int n, fd_set *readfds, fd_set *writefds,
				 fd_set *exceptfds, struct timeval *timeout);


/*
 * for mcl_wait_event...
 */
#define	MCL_WAIT_EVENT_END_TX	0
#define	MCL_WAIT_EVENT_END_RX	1
#define	MCL_WAIT_EVENT_CLOSED	2

#endif


#endif /* MCL_LIB_API_H */