/*
 * 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
 * Active router transport protocol's (@c ARTP) main library.
 * @author Tomas Rebok
 * @date 2004
 */
 

#ifndef ARTP_H
#define ARTP_H   1


#include <sys/socket.h>
#include <sys/types.h>
#include <netinet/in.h>
#include <arpa/inet.h>
#include "packet.h"
#include "options.h"
#include "errors.h"


/** Available session's parameters (which could be set by application) */
enum artp_session_params { 
	/** maximal retries timeout                 
	 * Defines the maximal retries timeout for each packet -- when 
	 * acknowledgement doesn't come until this time is reached, session is 
	 * said to be dead. (in seconds)
	 */ 
	RETRIES_TIMEOUT, 
	
	/** maximal segment size                    
	 * Maximal size of packet that could be sent to the network. (in bytes)
	 */ 
	MSS, 

	/** expiration time                         
	 * The expiration time for all sent packets. (in microseconds)
	 */ 
	EXP_TIME, 

	/** maximal seq. numbers count (in acks)    
	 * Defines the maximal count of sequence numbers that could be sent in one
	 * ack packet.
	 */ 
	MAX_ACKS_COUNT,
	
	/** maximal send buffer size           
	 * Maximal size that could be occupied by send buffer. If it's set to 0, 
	 * buffer size is unlimited. (in bytes)
	 */ 
	MAX_SBUFFER_SIZE,

	/** maximal receive buffer size         
	 * Maximal size that could be occupied by receive buffer. If it's set to 0, 
	 * buffer size is unlimited. (in bytes)
	 */
	MAX_RBUFFER_SIZE,
	
	/** maximal receive buffer R.E.D. limit 
	 * The receive buffer size when random early detection (R.E.D.) takes place.
	 * Every incoming packet is then dropped by defined probability.
	 * If it's set to 0 and buffer size is limited, buffer's behavior is like
	 * normal tail drop buffer.
	 */ 
	MAX_RBUFFER_RED_LIMIT,
	
	/** maximal receive buffer R.E.D. probability of packet's dropping
	 * Each incoming packet is dropped by this probability (if R.E.D. buffer
	 * is used.
	 */
	MAX_RBUFFER_RED_PROBABILITY
};


/** Initialize ARTP library.
 * This function makes necessary initialization steps for proper function
 * of ARTP protocol (starts threads, buffers and other structures 
 * initialization, etc.). It MUST be called as a first function! (Before any 
 * using of this protocol).
 *
 * @param sckt
 * 		socket where this protocol should listen on.
 *
 * @param filename
 * 		the name of a config file (or NULL if no config file is required).
 *
 * @return zero
 * 		success.
 *
 * @return nonzero
 * 		related error code if something failed (for further information see
 *      documentation of file @c errors.h).
 */
extern int 
artp_init(int sckt, char *filename);


/** Prepare new connection.
 * This function prepares new connection to be established (all necessary 
 * structures and buffers are created). Then this new session is inserted to
 * its right position in array of pointers to sessions.
 *
 * @param sid
 * 		session identification number of creating session.
 *
 * @param receiver
 * 		the pointer to the place where new session's receiver 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 
artp_prepare_connection(SID_TYPE sid, struct sockaddr *receiver);


/** Destroy session.
 * This function destroys previously created session (all its structures and 
 * buffers are destroyed, too). This session destroying is made like a 
 * garbage collector - each session knows the count of pointers that points
 * to it. When this count is equal to 0, the session is deleted.
 *
 * @param sid
 * 		session identification number of deleted session
 *
 * @param receiver
 * 		the pointer to the place where destroying session's receiver 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 
artp_destroy_connection(SID_TYPE sid, struct sockaddr *receiver);


/** Send ARTP datagram.
 * This function sends ARTP datagram to specified receiver through given 
 * session. It creates packet header and copies there its payload (the 
 * payload is fragmented if necessary). Then it's stored to proper session 
 * buffer.
 *
 * @param dgram
 * 		the pointer to the sending datagram.
 *
 * @param sid
 * 		session identification number
 *
 * @param receiver
 * 		the pointer to the place where session receiver 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 
artp_send_dgram(struct artp_dgram *dgram, SID_TYPE sid, 
		struct sockaddr *receiver);


/** Receive ARTP datagram from established sessions.
 * This function receives ARTP datagram from given sender (sent through given
 * session). This session must be previously established.
 *
 * @param sid
 * 		session identification number
 *
 * @param sender
 * 		the pointer to the place where session's sender/receiver is stored
 *
 * @param dgram
 * 		the pointer to the place where ARTP dgram information could be
 * 		saved.
 *
 * @return zero
 * 		success.
 *
 * @return nonzero
 * 		related error code if something failed (for further information see
 *      documentation of file @c errors.h).
 */
extern int 
artp_receive_dgram(SID_TYPE sid, struct sockaddr *sender, 
		struct artp_dgram *dgram);


/** Receive ARTP datagram from non-established sessions.
 * This function receives ARTP dgram from non-established session.
 *
 * @param sid
 * 		the pointer to the place where session identification number could
 * 		be stored
 *
 * @param sender
 * 		the relevant pointer which will be moved to the place where the
 *      dgram sender is stored.
 *
 * @param dgram
 * 		the pointer to the place where ARTP dgram information could be
 * 		saved.
 *
 * @return zero
 * 		success.
 *
 * @return nonzero
 * 		related error code if something failed (for further information see
 *      documentation of file @c errors.h).
 */
extern int 
artp_receive_any_dgram(SID_TYPE *sid, struct sockaddr **sender, 
		struct artp_dgram *dgram);


/** Free ARTP datagram.
 * This function unallocates space taken by ARTP dgram (the space where 
 * points ARTP dgram pointers).
 *
 * @param dgram
 * 		the pointer to the space where ARTP dgram 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 
artp_free_dgram(struct artp_dgram *dgram);


/** Get undeliverable session.
 * This function returns the non-established session whose packet couldn't be
 * sent.
 *
 * @param sid
 * 		the pointer to the place where session identification number could
 * 		be stored
 *
 * @param receiver
 * 		the relevant pointer which will be moved to the place where the
 *      packet's receiver 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 
artp_get_undlvr_session(SID_TYPE *sid, struct sockaddr *receiver);


/** Get available session identification number.
 * This function finds out available session identification number for given
 * receiver.
 *
 * @param receiver
 * 		the pointer to the place where receiver address is stored
 *
 * @param sid
 * 		the pointer to the place where found session identification number could
 * 		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 
artp_get_sid(struct sockaddr *receiver, SID_TYPE *sid);


/** Set session options.
 * This function sets defined session options. The option value is taken
 * from variable options list (there's taken the first one only). By proper 
 * parameter we can say if we want to use this option or not.
 *
 * @param sid
 * 		the identification number of proper session
 *
 * @param receiver
 * 		the pointer to the place where session's receiver is stored
 *
 * @param use
 * 		indicates whether we have to use this option or not.
 * 		(0 = do not use, 1 = use)
 *
 * @param option
 * 		the option identifier that we want to set
 *
 * @param ...
 * 		option value
 *
 * @return zero
 * 		success.
 *
 * @return nonzero
 * 		related error code if something failed (for further information see
 *      documentation of file @c errors.h).
 */
extern int 
artp_set_session_options(SID_TYPE sid, struct sockaddr *receiver, int use, 
		enum artp_session_options option, ...);


/** Set session parameters.
 * This function sets defined session parameters. The parameter value is 
 * taken from variable options list (there's taken the first one only).
 *
 * @param sid
 * 		the identification number of proper session
 *
 * @param receiver
 * 		the pointer to the place where session's receiver is stored
 *
 * @param param
 * 		the parameter identifier that we want to set
 *
 * @param ...
 * 		parameter value
 *
 * @return zero
 * 		success.
 *
 * @return nonzero
 * 		related error code if something failed (for further information see
 *      documentation of file @c errors.h).
 */
extern int 
artp_set_session_params(SID_TYPE sid, struct sockaddr *sender, 
		enum artp_session_params param, ...);


#endif

/* vim: set ts=4 : */