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


#ifndef ARTP_SBUFFERS_H
#define ARTP_SBUFFERS_H   1


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


/** Initialize send buffers.
 * This function makes some initial steps - currently it initializes mutex
 * used for retransmit structure.
 *
 * @return zero
 *      success
 *
 * @return nonzero
 *      related error code if something failed (for further information see
 *      documentation of file @c errors.h).
 */
extern int 
sbuffers_init(void);


/** Create send buffer.
 * At the beginning this function searches first free space for creating new 
 * buffer in the array of pointers to all allocated buffers. 
 * If there's any, it's used. If there isn't,
 * the array is resized and last pointer is used. 
 * Then all slippers are made and all buffer's parameters are set to 
 * its default values. 
 *
 * @param receiver
 *      the pointer to the place where session receiver is stored.
 *
 * @return above or equal zero
 *      success. Creating buffer identification number is returned.
 *
 * @return below zero
 *      related error code if something failed (for further information see
 *      documentation of file @c errors.h).
 */
extern int 
sbuffers_create(struct sockaddr *receiver);


/** Destroy send buffers.
 * This function destroys relevant send buffer. It unallocates place used
 * by that buffer and makes some other clearing steps (deletes all sent and
 * unsent packets, destroys all its help structures and semaphores, etc.).
 *
 * @param id_buffer
 *      the identification number of destroying buffer.
 *
 * @return zero
 *      success
 *
 * @return nonzero
 *      related error code if something failed (for further information see
 *      documentation of file @c errors.h).
 */
extern int 
sbuffers_destroy(int id_buffer);


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


/** Add packet to send.
 * This function adds packet which has to be sent. This adding is a bit 
 * complicated
 * because of slipper (this is made for mutual exclusion of reading and adding 
 * threads). First of all new item is inserted to the end of complete buffer 
 * (after slipper) and its signed as a new slipper. Then all necessary
 * information is copied to the old slipper and then it's signed (the old
 * slipper) as a new valid item.
 *
 * @param id_buffer
 * 		the identification number of send buffer.
 *
 * @param receiver
 * 		the pointer to the place where the packet's receiver is stored. It's 
 * 		used for non-established sessions only. Otherwise it could be NULL.
 *
 * @param sid
 * 		the session identification number. It's used for non-established 
 * 		sessions only. Otherwise it could be any value.
 *
 * @param value
 * 		the pointer to the place where the packet value is stored.
 *
 * @param size
 * 		the size of packet payload.
 *
 * @param seq
 * 		the packet sequence number.
 *
 * @return zero
 * 		success.
 *
 * @return nonzero
 *      related error code if something failed (for further information see
 *      documentation of file @c errors.h).
 */
extern int 
sbuffers_add_packet(int id_buffer, struct sockaddr *receiver, SID_TYPE sid, 
		char *value, int size, SEQ_TYPE seq);


/** Get packet dedicated to send.
 * This function returns packet which has to be sent (and its other information
 * if necessary).
 *
 * @param id_buffer
 * 		the identification number of send buffer.
 *
 * @param value
 * 		the relevant pointer which will be moved to the place where the
 * 		packet payload will be saved.
 *
 * @param size
 * 		the pointer to the place where the packet size will be stored.
 *
 * @param receiver
 * 		the relevant pointer which will be moved to the place where the
 * 		packet 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 
sbuffers_get_packet(int id_buffer, char **value, int *size, 
		struct sockaddr **receiver);


/** Move packet from send packets buffer to sent packets buffer.
 * This function moves defined acket from send packets buffer to sent 
 * packets buffer. This function has to be called after packet sending.
 * If the packet is different from the one stored in buffer, it won't do any 
 * steps (this situation may
 * appear when two threads sent the same packet simultaneously).
 * The adding is a bit complicated again (because of threads mutual exclusion).
 * The moved packet is inserted at the end of sent packets buffer (after the 
 * old slipper) and is signed as a slipper, too. All its values are copied to 
 * the old one (pointers are moved only). Now we have to insert this new packet
 * into the structure for retransmissions (it's sorted by packet next 
 * retransmission time). Then the moved packet is signed as a valid item.
 *
 * @param id_buffer
 * 		the identification number of send buffer.
 * 
 * @param bitstream
 * 		the pointer to the place where the moved packet value is stored.
 *
 * @param size
 * 		the size of moved packet payload.
 *
 * @param sent_time
 * 		the time when moved packet was sent.
 *
 * @param time_to_resend
 * 		the time when this packet should be resent (if no acknowledge will 
 * 		come).
 *
 * @return zero
 * 		success.
 *
 * @return nonzero
 *      related error code if something failed (for further information see
 *      documentation of file @c errors.h).
 */
extern int 
sbuffers_send_event(int id_buffer, char *bitstream, int size, double sent_time,
		double time_to_resend);


/** Move last resend packet to its new position in retransmit structure.
 * This function has to be called after retransmitting some packet. It moves 
 * that packet to its new position (depending on its next time to resend) in
 * structure for retransmissions.
 *
 * @param time_to_resend
 *		time when was this packet should be resend next.
 *
 * @return zero
 * 		success.
 *
 * @return nonzero
 *      related error code if something failed (for further information see
 *      documentation of file @c errors.h).
 */
extern int 
sbuffers_resend_event(double time_to_resend);


/** Delete packet from sent packets buffer.
 * This function deletes packet from sent buffer after incoming acknowledgement
 * packet. Packet is searched depending on its sequence number (for established
 * sessions) or depending on its sequence number, sender and session
 * identifier (for non-established sessions). It's deleted from structure for
 * retransmissions, too. If deleted packet wasn't resent, its sent time is
 * returned, too (for computing round trip time). Its size is returned, too.
 *
 * @param id_buffer
 * 		the identification number of send buffer.
 *
 * @param sender
 * 		the pointer to the place where sender's address is stored.
 *
 * @param sid
 * 		the session identification number which this packet belongs to.
 *
 * @param seq
 * 		packet sequence number.
 *
 * @param size
 * 		the pointer to the place where deleted packet size will be stored.
 *
 * @param time
 * 		the pointer to the place where deleted packet sent time 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 
sbuffers_ack_event(int id_buffer, struct sockaddr *sender, SID_TYPE sid, 
		SEQ_TYPE seq, int *size, double *time);


/** Return the smallest time to resend.
 * This function looks to the head of structure for retransmissions and 
 * returns the minimal time when some packet has to be resend (if any).
 *
 * @return above zero
 * 		the minimal packet resend time.
 *
 * @return below zero
 *      related error code if something failed (for further information see
 *      documentation of file @c errors.h).
 */
extern double 
sbuffers_get_top_rsnd_time(void);


/** Return packet to resend.
 * This function returns packet which has to be resent (it's taken from the 
 * head of structure for retransmissions).
 *
 * @param value
 * 		the relevant pointer which will be moved to the place where the
 * 		packet payload will be saved.
 *
 * @param size
 * 		the pointer to the place where the packet size will be stored.
 *
 * @param receiver
 * 		the relevant pointer which will be moved to the place where the
 * 		packet's receiver is stored.
 *
 * @param first_send_time
 * 		the pointer to the place where the packet's first send time could be
 * 		stored (used for detecting connection errors).
 * 		
 * @return zero
 * 		success.
 *
 * @return nonzero
 *      related error code if something failed (for further information see
 *      documentation of file @c errors.h).
 */
extern int 
sbuffers_get_rsnd_packet(char **value, int *size, struct sockaddr **receiver, 
		double *first_send_time);


/** Skip the top packet in structure for retransmissions.
 * This function skips the leading packet in structure for retransmissions.
 * It's used when connection fail is detected - no other packets which belongs
 * to that connection are retransmitted any more.
 *
 * @return zero
 * 		success.
 *
 * @return nonzero
 *      related error code if something failed (for further information see
 *      documentation of file @c errors.h).
 */
extern int 
sbuffers_ignore_first_rsnd();


#endif

/* vim: set ts=4 : */