/* *****************************************************************************
 * libg1m/buffer.h -- the libg1m buffer interface.
 * Copyright (C) 2017 Thomas "Cakeisalie5" Touhey <thomas@touhey.fr>
 *
 * This file is part of libg1m.
 * libg1m is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 3.0 of the License,
 * or (at your option) any later version.
 *
 * libg1m 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 GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with libg1m; if not, see <http://www.gnu.org/licenses/>.
 *
 * This interface is there so you can use a custom buffer for the library
 * to read.
 * ************************************************************************** */
#ifndef LIBG1M_BUFFER_H
# define LIBG1M_BUFFER_H
# include <stdlib.h>
# include <stdint.h>

/* ************************************************************************** */
/*  General definition                                                        */
/* ************************************************************************** */
/* There are two use cases:
 * - you want to read data: the `size` of the element to read should be set,
 *   and the `read` callback will be used;
 * - you want to receive data: if the `announce` callback is set, it will be
 *   called with the size of the file to write, in order to prepare space for
 *   it. If the `announce` callback returns an error, then the file will not
 *   be written. If the announcement is successful, then the `write` callback
 *   is used. If there is an error and the `unannounce` callback is set, it
 *   will be called in order to free any allocated buffer.
 *
 * In each case, the `cookie` is sent as the first argument to your callbacks.
 * Here are their types: */

typedef int  g1m_buffer_read_t(void*, unsigned char*, size_t);
typedef int  g1m_buffer_write_t(void*, const unsigned char*, size_t);
typedef int  g1m_buffer_announce_t(void*, size_t);
typedef void g1m_buffer_unannounce_t(void*);

/* ... and the structure of a buffer: */

typedef struct {
	void   *g1m_buffer_cookie;
	size_t  g1m_buffer_offset;

	/* callbacks */
	g1m_buffer_read_t       *g1m_buffer_read;
	g1m_buffer_write_t      *g1m_buffer_write;
	g1m_buffer_announce_t   *g1m_buffer_announce;
	g1m_buffer_unannounce_t *g1m_buffer_unannounce;
} g1m_buffer_t;
/* ************************************************************************** */
/*  File buffer definition                                                    */
/* ************************************************************************** */
/* Callbacks (the cookie is the FILE* pointer) */
extern int g1m_filebuffer_read(void *g1m_arg_cookie,
	unsigned char *g1m_arg_buf, size_t g1m_arg_size);
extern int g1m_filebuffer_write(void *g1m_arg_cookie,
	const unsigned char *g1m_arg_dest, size_t g1m_arg_size);
/* ************************************************************************** */
/*  Memory buffer definition                                                  */
/* ************************************************************************** */
/* Cookie structure */
typedef struct g1m_cursor_s {
	const unsigned char *g1m_cursor_p;
	size_t               g1m_cursor_left;
} g1m_cursor_t;

/* Related callbacks and functions */
extern int g1m_membuffer_read(void *g1m_arg_cookie,
	unsigned char *g1m_arg_dest, size_t g1m_arg_size);
/* ************************************************************************** */
/*  Limited buffer definition                                                 */
/* ************************************************************************** */
/* Cookie structure */
typedef struct g1m_limited_s {
	g1m_buffer_t *g1m_limited_buffer;
	size_t        g1m_limited_left;
} g1m_limited_t;

/* Related functions and callbacks */
int g1m_limbuffer_read(void *g1m_arg_cookie,
	unsigned char *g1m_arg_dest, size_t g1m_arg_size);
int g1m_empty_limbuffer(g1m_buffer_t *g1m_arg_limbuffer);
/* ************************************************************************** */
/*  Buffer macros                                                             */
/* ************************************************************************** */
/* Initialize a file buffer */
# define g1m_filebuffer(F) (g1m_filebuffer_t){ \
	.g1m_buffer_cookie = (void*)(F), \
	.g1m_buffer_read = g1m_filebuffer_read, \
	.g1m_buffer_write = g1m_filebuffer_write}

/* Initialize a memory buffer */
# define g1m_membuffer(P, SZ) (g1m_buffer_t){ \
	.g1m_buffer_cookie = (g1m_cursor_t[]){{ \
		.g1m_cursor_p = (P), .g1m_cursor_left = (SZ)}}, \
	.g1m_buffer_read = g1m_membuffer_read}

/* Initialize a limited buffer */
# define g1m_limbuffer(BUFFER, SZ) (g1m_buffer_t){ \
	.g1m_buffer_cookie = (g1m_limited_t[]){{ \
		.g1m_limited_buffer = (BUFFER), .g1m_limited_left = (SZ)}}, \
	.g1m_buffer_read = g1m_limbuffer_read}

#endif /* LIBG1M_BUFFER_H */