/* distcache, Distributed Session Caching technology
 * Copyright (C) 2000-2003  Geoff Thorpe, and Cryptographic Appliances, Inc.
 *
 * This library is free software; you can redistribute it and/or modify it under
 * the terms of the GNU Lesser General Public License as published by the Free
 * Software Foundation; using version 2.1 of the License. The copyright holders
 * may elect to allow the application of later versions of the License to this
 * software, please contact the author (geoff@distcache.org) if you wish us to
 * review any later version released by the Free Software Foundation.
 *
 * This library 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 Lesser General Public License for more
 * details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library; if not, write to the Free Software Foundation, Inc.,
 * 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */
#ifndef HEADER_LIBNAL_NAL_H
#define HEADER_LIBNAL_NAL_H

/*-----------------------*/
/* "libnal" EXTERNAL API */
/* ----------------------*/

typedef struct st_NAL_ADDRESS NAL_ADDRESS;
typedef struct st_NAL_LISTENER NAL_LISTENER;
typedef struct st_NAL_CONNECTION NAL_CONNECTION;
typedef struct st_NAL_SELECTOR NAL_SELECTOR;
typedef struct st_NAL_BUFFER NAL_BUFFER;

/* Flags passed to NAL_CONNECTION_add_to_selector_ex() */
#define NAL_SELECT_FLAG_READ	(unsigned int)0x0001
#define NAL_SELECT_FLAG_SEND	(unsigned int)0x0002
#define NAL_SELECT_FLAG_RW	(NAL_SELECT_FLAG_READ | NAL_SELECT_FLAG_SEND)

/********************/
/* Global functions */
/********************/

void		NAL_config_set_nagle(int enabled);

/*********************/
/* Address functions */
/*********************/

NAL_ADDRESS *	NAL_ADDRESS_new(void);
void		NAL_ADDRESS_free(NAL_ADDRESS *addr);
void		NAL_ADDRESS_reset(NAL_ADDRESS *addr);
int		NAL_ADDRESS_create(NAL_ADDRESS *addr, const char *addr_string,
				unsigned int def_buffer_size);
unsigned int	NAL_ADDRESS_get_def_buffer_size(const NAL_ADDRESS *addr);
int		NAL_ADDRESS_set_def_buffer_size(NAL_ADDRESS *addr,
				unsigned int def_buffer_size);
int		NAL_ADDRESS_can_connect(const NAL_ADDRESS *addr);
int		NAL_ADDRESS_can_listen(const NAL_ADDRESS *addr);

/**********************/
/* Selector functions */
/**********************/

NAL_SELECTOR *	NAL_SELECTOR_new(void);
void		NAL_SELECTOR_free(NAL_SELECTOR *sel);
int		NAL_SELECTOR_select(NAL_SELECTOR *sel,
				unsigned long usec_timeout,
				int use_timeout);

/********************************/
/* Listener functions (general) */
/********************************/

NAL_LISTENER *	NAL_LISTENER_new(void);
void		NAL_LISTENER_free(NAL_LISTENER *list);
void		NAL_LISTENER_reset(NAL_LISTENER *list);
int		NAL_LISTENER_create(NAL_LISTENER *list,
				const NAL_ADDRESS *addr);
void		NAL_LISTENER_add_to_selector(const NAL_LISTENER *list,
				NAL_SELECTOR *sel);
void		NAL_LISTENER_del_from_selector(const NAL_LISTENER *list,
				NAL_SELECTOR *sel);
int		NAL_LISTENER_finished(const NAL_LISTENER *list);

/************************************/
/* Listener functions (specialised) */
/************************************/

int		NAL_LISTENER_set_fs_owner(NAL_LISTENER *list,
				const char *ownername,
				const char *groupname);
int		NAL_LISTENER_set_fs_perms(NAL_LISTENER *list,
				const char *octal_string);

/**********************************/
/* Connection functions (general) */
/**********************************/

NAL_CONNECTION *NAL_CONNECTION_new(void);
void		NAL_CONNECTION_free(NAL_CONNECTION *conn);
void		NAL_CONNECTION_reset(NAL_CONNECTION *conn);
int		NAL_CONNECTION_create(NAL_CONNECTION *conn,
				const NAL_ADDRESS *addr);
int		NAL_CONNECTION_accept(NAL_CONNECTION *conn,
				NAL_LISTENER *list,
				NAL_SELECTOR *sel);
int		NAL_CONNECTION_set_size(NAL_CONNECTION *conn,
				unsigned int size);
NAL_BUFFER *	NAL_CONNECTION_get_read(NAL_CONNECTION *conn);
NAL_BUFFER *	NAL_CONNECTION_get_send(NAL_CONNECTION *conn);
const NAL_BUFFER *NAL_CONNECTION_get_read_c(const NAL_CONNECTION *conn);
const NAL_BUFFER *NAL_CONNECTION_get_send_c(const NAL_CONNECTION *conn);
int		NAL_CONNECTION_io(NAL_CONNECTION *conn, NAL_SELECTOR *sel);
int		NAL_CONNECTION_io_cap(NAL_CONNECTION *conn, NAL_SELECTOR *sel,
				unsigned int max_read, unsigned int max_send);
int		NAL_CONNECTION_is_established(const NAL_CONNECTION *conn);
void		NAL_CONNECTION_add_to_selector(const NAL_CONNECTION *conn,
				NAL_SELECTOR *sel);
void		NAL_CONNECTION_add_to_selector_ex(const NAL_CONNECTION *conn,
				NAL_SELECTOR *sel, unsigned int flags);
void		NAL_CONNECTION_del_from_selector(const NAL_CONNECTION *conn,
				NAL_SELECTOR *sel);

/**************************************/
/* Connection functions (specialised) */
/**************************************/

int		NAL_CONNECTION_create_pair(NAL_CONNECTION *conn1,
				NAL_CONNECTION *conn2,
				unsigned int def_buffer_size);
#if 0
int		NAL_CONNECTION_create_dummy(NAL_CONNECTION *conn,
				unsigned int def_buffer_size);
#endif
/* These are used by distcache utilities (excluding daemons) in one or two
 * places, and they were not worth explicitly hiding from the libnal
 * abstraction but nevertheless don't warrant a mention in the API. As such,
 * these are left in for simplicity's sake but not mentioned in the documents.
 * If you're silly enough to want to use these, please be my guest. However I
 * don't promise that I won't butcher these at some point, and if anyone wants
 * them anyway, they would probably be better off implementing a new
 * NAL_CONNECTION type to encapsulate arbitrary fd's. */
#if 0
void		NAL_SELECTOR_stdin_add(NAL_SELECTOR *sel);
int		NAL_SELECTOR_stdin_readable(NAL_SELECTOR *sel);
int		NAL_stdin_set_non_blocking(int non_blocking);
#endif

/********************/
/* Buffer functions */
/********************/

NAL_BUFFER *	NAL_BUFFER_new(void);
void		NAL_BUFFER_free(NAL_BUFFER *buf);
void		NAL_BUFFER_reset(NAL_BUFFER *buf);
int		NAL_BUFFER_set_size(NAL_BUFFER *buf,
				unsigned int size);
int		NAL_BUFFER_empty(const NAL_BUFFER *buf);
int		NAL_BUFFER_full(const NAL_BUFFER *buf);
int		NAL_BUFFER_notempty(const NAL_BUFFER *buf);
int		NAL_BUFFER_notfull(const NAL_BUFFER *buf);
unsigned int	NAL_BUFFER_used(const NAL_BUFFER *buf);
unsigned int	NAL_BUFFER_unused(const NAL_BUFFER *buf);
unsigned int	NAL_BUFFER_size(const NAL_BUFFER *buf);
const unsigned char *NAL_BUFFER_data(const NAL_BUFFER *buf);
/* Now we define the general "access" functions for the buffer type */
unsigned int 	NAL_BUFFER_write(NAL_BUFFER *buf,
				const unsigned char *ptr,
				unsigned int size);
unsigned int 	NAL_BUFFER_read(NAL_BUFFER *buf,
				unsigned char *ptr,
				unsigned int size);
void		NAL_BUFFER_transfer(NAL_BUFFER *dest, NAL_BUFFER *src,
				unsigned int max);

/***************** WARNING START ********************/
/* These functions manipulate internal data directly and are to be used with
 * caution - it's easy for data to "go missing" or "get created out of nowhere"
 * by misusing these functions. */
/******** WARNING END - you have been warned ********/

/* Returns a pointer to the tail of the buffer's data, you should never attempt
 * to write more than NAL_BUFFER_unused(buf) bytes from the return value. */
unsigned char *	NAL_BUFFER_write_ptr(NAL_BUFFER *buf);
/* If you wrote data directly to the buffer using ...write_ptr() rather than
 * NAL_BUFFER_write(), then use this call to indicate that the buffer has "size"
 * more bytes available to it at the position ...write_ptr() returned. */
void		NAL_BUFFER_wrote(NAL_BUFFER *buf,
				unsigned int size);

/*************************/
/* En/Decoding functions */
/*************************/

/* This set of functions provide architecture-independant ways of encoding
 * various primitive types. The general format of the functions is;
 *   int NAL_decode_XX(const unsigned char **bin, unsigned int *bin_len,
 *                     XX *val);
 * and
 *   int NAL_encode_XX(unsigned char **bin, unsigned int *cnt,
 *                     const XX val);
 * where 'XX' is the primitive type in question. The behaviour is that bin &
 * bin_len are altered after the encoding/decoding so that bin points to the
 * next unused byte and bin_len is reduced by the number of bytes used. As such,
 * these functions can be used in situations where (i) the input may be
 * insufficient to encode or decode the relevant structure, and (ii) where
 * multiple levels of encoding/decoding may be constructed for aggregate
 * structure types.
 *
 * The return values are zero for failure and non-zero for success.
 */
int NAL_decode_uint32(const unsigned char **bin, unsigned int *bin_len,
			unsigned long *val);
int NAL_decode_uint16(const unsigned char **bin, unsigned int *bin_len,
			unsigned int *val);
int NAL_decode_char(const unsigned char **bin, unsigned int *bin_len,
			unsigned char *val);
int NAL_decode_bin(const unsigned char **bin, unsigned int *bin_len,
			unsigned char *val, unsigned int val_len);

int NAL_encode_uint32(unsigned char **bin, unsigned int *bin_len,
			const unsigned long val);
int NAL_encode_uint16(unsigned char **bin, unsigned int *bin_len,
			const unsigned int val);
int NAL_encode_char(unsigned char **bin, unsigned int *bin_len,
			const unsigned char val);
int NAL_encode_bin(unsigned char **bin, unsigned int *bin_len,
			const unsigned char *val, const unsigned int val_len);

#endif /* !defined(HEADER_LIBNAL_NAL_H) */