/*
 * Active Router Transport Protocol (ARTP) implementation
 * Copyright (c) 2004, Tomas Rebok
 * All rights reserved.
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the "BSD License" which is
 * distributed with the software in the file LICENSE.
 *
 * 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 BSD
 * License for more details.
 */

/** @file
 * @c ARTP options definition and their manipulating functions.
 * @author Tomas Rebok
 * @date 2004
 */


#ifndef ARTP_OPTIONS_H
#define ARTP_OPTIONS_H   1


/** The total options count. */
#define OPTIONS_COUNT 3


#include <stdarg.h>
#include "structs.h"
#include "packet.h"


/** The list of available options. */
enum artp_session_options {
	/** maximal MSS           
	 * Send this option to your partner when you want to receive packets 
	 * that has to be lesser than given size.
	 */ 
	MAX_MSS,
	
	/** maximal datagram size 
	 * Send this option to your partner when you want to receive datagrams
	 * that has to be lesser than given size.
	 */ 
	 MAX_DGRAM_LEN,

	 /** retransmits' timeout  
	  * This option is used for receiver's determining too old information
	  * in his packets history (history used for determining duplicities). 
	  *
	  * NOTE: If you're sure that you will send less than 2^32 packets you 
	  * may not use this option.
	  */ 
	 RETRANSMITS_TIMEOUT
};


/** Initialize options.
 * This function initializes options - creates necessary structure and sets 
 * default options which has to be set for each session.
 *
 * @return zero
 * 		success
 * 		
 * @return nonzero
 * 		related error code if something failed (for further information see
 * 		documentation of file @c errors.h).
 */
extern int
options_init();


/** Set global sessions options.
 * This function sets global sessions options as read from config file.
 *
 * @param option_name
 * 		the pointer to the space where option name is stored.
 *
 * @param option_value
 * 		the pointer to the space where option value is stored.
 *
 * @param use
 * 		indicates whether this option has to be used or not
 * 		(0 = don't use, 1 = use).
 */
extern int
set_global_option(char *option_name, char *option_value, int use);


/** Set default session options.
 * This function is used for setting defaultly set options for given session.
 *
 * @param session
 * 		the pointer to the place where session information is stored.
 *
 * @return zero
 * 		success
 * 		
 * @return nonzero
 * 		related error code if something failed (for further information see
 * 		documentation of file @c errors.h).
 */
extern int 
set_default_options(struct session_item *session);


/** Find out session options.
 * This function finds out options which has to be sent as a part of ARTP 
 * packet. There're returned no options for non-established sessions.
 *
 * @param session
 * 		the pointer to the place where session information is stored.
 *
 * @param packet
 * 		the pointer to the place where currently send packet is stored 
 * 		(currently unused - for further purposes).
 *
 * @param options
 * 		the relevant pointer which will be moved to the place where returned
 * 		options will be stored.
 *
 * @param size
 * 		the pointer to the place where size of returned options will be stored.
 *
 * @return zero
 * 		success
 *
 * @return nonzero
 * 		related error code if something failed (for further information see
 * 		documentation of file @c errors.h).
 */
extern int 
get_session_options(struct session_item *session, struct artp_dgram *dgram, 
		char **options, int *size);


/** Parse session options.
 * This function is used for parsing received options and saving their values
 * to relevant structure. Previously saved (and allocated) options which
 * wasn't covered in parsed string will be unallocated.
 *
 * @param session
 * 		the pointer to the place where session information is stored.
 *
 * @param options
 * 		the pointer to the place where options to parse are stored.
 *
 * @param size
 * 		given options size.
 *
 * @return zero
 * 		success
 *
 * @return nonzero
 * 		related error code if something failed (for further information see
 * 		documentation of file @c errors.h).
 */
extern int 
parse_session_options(struct session_item *session, char *options, int size);


/** Set options using.
 * This function is used for setting using of defined options (and their 
 * values).
 *
 * @param session
 * 		the pointer to the place where session information is stored.
 *
 * @param use
 * 		indicates whether this option will be used or not
 * 		(0 = don't use, 1 = use).
 *
 * @param option_id
 * 		option identification number.
 *
 * @param ap
 * 		the pointer to the place where variable parameters list is stored
 * 		(the option value is obtained from this list).
 *
 * @return zero
 * 		success
 * 		
 * @return nonzero
 * 		related error code if something failed (for further information see
 * 		documentation of file @c errors.h).
 */
extern int 
use_options(struct session_item *session, int use, 
		enum artp_session_options option_id, va_list *ap);


#endif

/* vim: set ts=4 : */