/*
 * 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 library for receive buffers.
 * @author Tomas Rebok
 * @date 2004
 */


#ifndef ARTP_RBUFFERS_H
#define ARTP_RBUFFERS_H   1


#include <netinet/in.h>
#include <sys/socket.h>
#include "packet.h"


/** Initialize receive buffers.
 * This function doesn't include any code this time. It is defined for further
 * purposes.
 *
 * @return zero
 *      success
 *
 * @return nonzero
 *      related error code if something failed (for further information see
 *      documentation of file @c errors.h).
 */
extern int 
rbuffers_init(void);


/** Create receive buffer.
 * This function allocates place for relevant buffer and initializes its
 * parameters.
 *
 * @param id_buffer
 * 		identification number of creating buffer.
 * 
 * @return zero
 * 		success
 *
 * @return nonzero
 * 		related error code if something failed (for further information see
 *      documentation of file @c errors.h).
 */
extern int 
rbuffers_create(int id_buffer);


/** Destroy receive buffer.
 * This function destroys relevant receive buffer. It unallocates place used 
 * by that buffer and makes some other clearing steps (deletes all completely 
 * and incompletely received datagrams, destroys all its structures, etc.).
 *
 * @param id_buffer
 *      identification number of destroyed buffer.
 *
 * @return zero
 *      success
 *
 * @return nonzero
 *      related error code if something failed (for further information see
 *      documentation of file @c errors.h).
 */
extern int 
rbuffers_destroy(int id_buffer);


/** Return identified receive buffer size.
 * This function finds out receive buffer size and returns it.
 *
 * @param id_buffer
 *      identification number of receive buffer.
 *
 * @param buffer_size
 *      the pointer to the place where buffer size 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
rbuffers_get_size(int id_buffer, unsigned long int *buffer_size);


/** Add incoming packet payload into receive buffer.
 * This function adds packet payload into receive buffer. If the whole 
 * datagram consists of 1 fragment, it's immediately saved into complete 
 * datagrams buffer. If that datagram consists of more than one fragment, 
 * the packet is saved into incomplete datagrams buffer. After coming of the 
 * last fragment the whole datagram is moved to complete datagrams buffer.
 *
 * @param id_buffer
 * 		identification number of receive buffer.
 *
 * @param value
 * 		the pointer to the place where the packet payload is stored.
 *
 * @param payload_size
 * 		payload size of adding packet.
 *
 * @param sender
 * 		the pointer to the place where the information about packet's sender
 * 		is stored (used for non-established sessions).
 *
 * @param sid
 * 		session identification number
 * 
 * @param type
 * 		packet type
 *
 * @param seq
 * 		packet sequence number
 *
 * @param dseq
 * 		packet data sequence (or arbitrary value if adding control packet).
 *
 * @param frag_id
 * 		data datagram fragment identification number (if adding control 
 * 		packet, it MUST be set to 1).
 *
 * @param frag_count
 * 		data datagram fragments count (if adding control packet, it MUST be 
 * 		set to 1).
 *
 * @param current_time
 * 		current time (it's equal to packet incoming time)
 *
 * @param retransmits_timeout
 * 		retransmits_timeout sent by our partner to determine old packets in
 * 		structure for duplicity check. Set it to 0 if our partner doesn't 
 * 		send this option.
 *
 * @return zero
 * 		success
 *
 * @return nonzero
 *		related error code if something failed (for further information see
 *		documentation of file @c errors.h).
 */
extern int 
rbuffers_add_packet(int id_buffer, char *value, int payload_size, 
		struct sockaddr *sender, SID_TYPE sid, enum packet_type type, 
		SEQ_TYPE seq, DSEQ_TYPE dseq, FRAGMENTS_TYPE frag_id, 
		FRAGMENTS_TYPE frag_count, double current_time, 
		unsigned int retransmits_timeout);


/** Obtain completely received datagram.
 * This functions gets one completely received datagram (if any). If that
 * datagram consists of more than one fragment it will be assembled from all 
 * its fragments.
 *
 * @param id_buffer
 * 		identification number of receive buffer.
 *
 * @param value
 * 		the relevant pointer which will be moved to the place where the
 * 		datagram payload will be saved.
 *
 * @param size
 * 		the pointer to the place where the payload size could be stored.
 *
 * @param type
 * 		the pointer to the place where the datagram type could be stored.
 *
 * @param dseq
 * 		the pointer to the place where the payload data sequence number 
 * 		could be stored.
 *
 * @param sender
 * 		the relevant pointer which will be moved to the place where the 
 * 		datagram's sender is stored.
 *
 * @param sid
 * 		the pointer to the place where the 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 
rbuffers_get_dgram(int id_buffer, char **value, int *size, 
		enum packet_type *type, DSEQ_TYPE *dseq, struct sockaddr **sender, 
		SID_TYPE *sid);


#endif

/* vim: set ts=4 : */