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


#ifndef ARTP_ABUFFERS_H
#define ARTP_ABUFFERS_H   1


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


/** Initialize ack 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
abuffers_init(void);


/** Create ack buffer.
 * This function allocates place for relevant buffer and initializes its
 * parameters.
 *
 * @param id_buffer
 * 		the identification number of buffer to be created.
 *
 * @param sid
 * 		the identification number of session which this buffer will be 
 * 		created for.
 *
 * @param sender
 * 		pointer to the place where the sender of received packets 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
abuffers_create(int id_buffer, SID_TYPE sid, struct sockaddr *sender);


/** Destroy ack buffer.
 * This function destroys relevant ack buffer. It unallocates place used by
 * that buffer and makes some other clearing steps (e.g. removes this buffer 
 * from structure for sending ack packets, etc.).
 *
 * @param id_buffer
 * 		identification number of buffer to be destroyed.
 *
 * @return zero
 * 		success
 *
 * @return nonzero
 * 		related error code if something failed (for further information see 
 * 		documentation of file @c errors.h).
 */
extern int
abuffers_destroy(int id_buffer);


/** Store incoming sequence number to relevant buffer.
 * This function adds sequence number of incoming packet to given buffer 
 * identified by its id. If it's the first sequence number saving for this 
 * session, it inserts the pointer of this session to the right place in 
 * structure for sending ack packets (depending on its latest time to send).
 *
 * @param id_buffer
 * 		the identification number of ack buffer.
 *
 * @param sid
 * 		the identification number of session that this sequence number relates 
 * 		to (used when this session isn't created).
 *
 * @param sender
 * 		pointer to the place where the information about actual packet's sender
 * 		is stored (it's the same as above - used when this session isn't 
 * 		created).
 *
 * @param seq
 * 		the sequence number that has to be stored.
 *
 * @param latest_send_time
 * 		the latest time when the ack packet must be sent.
 *
 * @param maximal_count
 * 		the maximal count of sequence numbers in one ack packet (after 
 * 		reaching this count the ack packet is immediately sent).
 *
 * @return zero
 * 		success
 *
 * @return nonzero
 * 		related error code if something failed (for further information see 
 * 		documentation of file @c errors.h).
 */
extern int
abuffers_add_seq(int id_buffer, SID_TYPE sid, struct sockaddr *sender, 
		SEQ_TYPE seq, double latest_send_time, int maximal_count);


/** Get next ack packet which should be sent.
 * This function looks whether there's any ack packet which should be sent 
 * in specified time. If there's any it returns all information about that
 * packet and removes related buffer from structure for sending ack packets.
 *
 * @param time
 * 		actual time
 *
 * @param sid
 * 		the pointer to the place where session's identification number will be
 * 		stored.
 *
 * @param receiver
 * 		the relevant pointer which will be moved to the place where the 
 * 		receiver of returned ack packet will be stored.
 *
 * @param value
 * 		the relevant pointer which will be moved to the place where the 
 * 		payload of returned ack packet will be stored.
 *
 * @param size
 * 		the pointer to the place where the size of ack packet payload 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
abuffers_get_ack(double time, SID_TYPE *sid, struct sockaddr **receiver, 
		char **value, int *size);


#endif

/* vim: set ts=4 : */