/*****************************************************************************\
 * Copyright (c) 2004 Mark Aylett <mark@emantic.co.uk>                       *
 *                                                                           *
 * Permission is hereby granted, free of charge, to any person obtaining a   *
 * copy of this software and associated documentation files (the             *
 * "Software"), to deal in the Software without restriction, including       *
 * without limitation the rights to use, copy, modify, merge, publish,       *
 * distribute, sublicense, and/or sell copies of the Software, and to permit *
 * persons to whom the Software is furnished to do so, subject to the        *
 * following conditions:                                                     *
 *                                                                           *
 * The above copyright notice and this permission notice shall be included   *
 * in all copies or substantial portions of the Software.                    *
 *                                                                           *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS   *
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF                *
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN *
 * NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,  *
 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR     *
 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE *
 * USE OR OTHER DEALINGS IN THE SOFTWARE.                                    *
\*****************************************************************************/

/**
 * \file mar_c.h
 * \brief The MAR API header file.
 */

#ifndef INCLUDED_MAR_C
#define INCLUDED_MAR_C

#ifndef INCLUDED_MAR_STORAGE_C
#include "mar_storage_c.h"
#endif /* INCLUDED_MAR_STORAGE_C */

#ifndef INCLUDED_MAR_TYPES_C
#include "mar_types_c.h"
#endif /* INCLUDED_MAR_TYPES_C */

/**
 * \brief The meta archive handle type.
 */

typedef struct mar_* mar_t;

/**
 * \brief Copy an existing meta archive.
 *
 * \param dst A handle to the destination meta archive.
 *
 * \param src A handle to the source meta archive.
 *
 * \return zero on success or -1 on failure, in which case #mar_errno can be
 * used to determine the error.
 *
 * \sa #mar_retain.
 */

MAR_API int
mar_copy(mar_t dst, mar_t src);

/**
 * \brief Create an in-memory meta archive.
 *
 * \return A handle to the newly created meta archive or NULL on failure, in
 * which case #mar_errno can be used to determine the error.
 *
 * \sa #mar_open and #mar_release.
 */

MAR_API mar_t
mar_create(void);

/**
 * \brief Create or open a file-based meta archive.
 *
 * \param path A path to the file to be created or opened.
 *
 * \param flags The \ref OpenFlags "flags" used to create or open the file.
 *
 * \param ... The permissions used to create a new file. Required when the
 * #MAR_CREAT flag has been specified, otherwise ignored.
 *
 * \return A handle to the newly created meta archive or NULL on failure, in
 * which case #mar_errno can be used to determine the error.
 *
 * \sa #mar_create and #mar_release.
 */

MAR_API mar_t
mar_open(const char* path, int flags, ...);

/**
 * \brief Release meta archive handle.
 *
 * This function must be used to release handles allocated by either the
 * #mar_create or #mar_open functions.
 *
 * \param mar A handle to the meta archive to be released.
 *
 * \return zero on success or -1 on failure, in which case #mar_errno can be
 * used to determine the error.
 *
 * \sa #mar_create, #mar_open and #mar_retain.
 */

MAR_API int
mar_release(mar_t mar);

/**
 * \brief Retain additional reference to meta archive handle.
 *
 * \param mar A handle to the meta archive.
 *
 * \return zero on success or -1 on failure, in which case #mar_errno can be
 * used to determine the error.
 *
 * \sa #mar_copy and #mar_release.
 */

MAR_API int
mar_retain(mar_t mar);

/**
 * \brief Remove all pairs contained within meta archive.
 *
 * \param mar A handle to the meta archive.
 *
 * \return zero on success or -1 on failure, in which case #mar_errno can be
 * used to determine the error.
 *
 * \sa #mar_unsetbykey and #mar_unsetbyord.
 */

MAR_API int
mar_removepairs(mar_t mar);

/**
 * \brief Set meta pair within meta archive.
 *
 * \param mar A handle to the meta archive.
 *
 * \param pair A pair specifying the key and a pointer to and size of the meta
 * data.
 *
 * \param ord An optional output parameter in which the ordinal of the meta
 * pair would be returned.
 *
 * \return zero on success or -1 on failure, in which case #mar_errno can be
 * used to determine the error.
 *
 * \sa #mar_setmeta.
 */

MAR_API int
mar_setpair(mar_t mar, const mar_pair_t* pair, size_t* ord);

/**
 * \brief Set meta data within meta archive.
 *
 * \param mar A handle to the meta archive.
 *
 * \param ord The ordinal of an existing meta pair.
 *
 * \param data A pointer to the meta data to be copied.
 *
 * \param size The size of the meta data to be copied.
 *
 * \return zero on success or -1 on failure, in which case #mar_errno can be
 * used to determine the error.
 *
 * \sa #mar_setpair.
 */

MAR_API int
mar_setmeta(mar_t mar, size_t ord, const void* data, size_t size);

/**
 * \brief Unset meta pair (by key) within meta archive.
 *
 * \param mar A handle to the meta archive.
 *
 * \param key The key of the meta pair.
 *
 * \param ord An optional output parameter in which the ordinal of the meta
 * pair would be returned.
 *
 * \return zero on success, #MAR_NOMATCH if no matching pair exists, or -1 on
 * failure, in which case #mar_errno can be used to determine the error.
 *
 * \sa #mar_removepairs, #mar_unsetbyord and #mar_tokey.
 */

MAR_API int
mar_unsetbykey(mar_t mar, const char* key, size_t* ord);

/**
 * \brief Unset meta pair (by ordinal) within meta archive.
 *
 * \param mar A handle to the meta archive.
 *
 * \param ord The ordinal of the meta pair.
 *
 * \return zero on success, #MAR_NOMATCH if no matching pair exists, or -1 on
 * failure, in which case #mar_errno can be used to determine the error.
 *
 * \sa #mar_removepairs, #mar_unsetbykey and #mar_toord.
 */

MAR_API int
mar_unsetbyord(mar_t mar, size_t ord);

/**
 * \brief Obtain meta data (by key) from meta archive.
 *
 * \param mar A handle to the meta archive.
 *
 * \param key The key of the meta pair.
 *
 * \param size An optional output parameter in which the size of the meta data
 * would be returned.
 *
 * \return A pointer to the meta data or NULL on failure, in which case
 * #mar_errno can be used to determine the error.
 *
 * \sa #mar_metabyord, #mar_metapair and #mar_tokey.
 */

MAR_API const void*
mar_metabykey(mar_t mar, const char* key, size_t* size);

/**
 * \brief Obtain meta data (by ordinal) from meta archive.
 *
 * \param mar A handle to the meta archive.
 *
 * \param ord The zero-based ordinal of the meta pair.
 *
 * \param size An optional output parameter in which the size of the meta data
 * would be returned.
 *
 * \return A pointer to the meta data or NULL on failure, in which case
 * #mar_errno can be used to determine the error.
 *
 * \sa #mar_metabykey, #mar_metapair and #mar_toord.
 */

MAR_API const void*
mar_metabyord(mar_t mar, size_t ord, size_t* size);

/**
 * \brief Obtain meta pair from meta archive.
 *
 * \param mar A handle to the meta archive.
 *
 * \param pair The output parameter in which the pair will be returned.
 *
 * \param ord The zero-based ordinal of the meta pair.
 *
 * \return zero on success, #MAR_NOMATCH if no matching pair exists, or -1 on
 * failure, in which case #mar_errno can be used to determine the error.
 *
 * \sa #mar_metabykey, #mar_metabyord and #mar_metapairs.
 */

MAR_API int
mar_metapair(mar_t mar, mar_pair_t* pair, size_t ord);

/**
 * \brief Obtain the number of pairs contained within meta archive.
 *
 * \param mar A handle to the meta archive.
 *
 * \param size The output parameter in which the number of pairs will be
 * returned.
 *
 * \return zero on success or -1 on failure, in which case #mar_errno can be
 * used to determine the error.
 *
 * \sa #mar_metapair.
 */

MAR_API int
mar_metapairs(mar_t mar, size_t* size);

/**
 * \brief Obtain key based on ordinal in meta archive.
 *
 * \param mar A handle to the meta archive.
 *
 * \param key The output parameter in which the key will be returned.
 *
 * \param ord The zero-based ordinal of the key to be returned.
 *
 * \return zero on success, #MAR_NOMATCH if no matching pair exists, or -1 on
 * failure, in which case #mar_errno can be used to determine the error.
 *
 * \sa #mar_unsetbykey, #mar_metabykey and #mar_toord.
 */

MAR_API int
mar_tokey(mar_t mar, mar_key_t key, size_t ord);

/**
 * \brief Obtain ordinal based on key in meta archive.
 *
 * \param mar A handle to the meta archive.
 *
 * \param ord The output parameter in which the ordinal will be returned.
 *
 * \param key The key of the meta pair.
 *
 * \return zero on success, #MAR_NOMATCH if no matching pair exists, or -1 on
 * failure, in which case #mar_errno can be used to determine the error.
 *
 * \sa #mar_unsetbyord, #mar_metabyord and #mar_tokey.
 */

MAR_API int
mar_toord(mar_t mar, size_t* ord, const char* key);

/**
 * \brief Insert user data from file into meta archive.
 *
 * \param mar A handle to the meta archive.
 *
 * \param path A path to the file from which the user data is read.
 *
 * \return zero on success or -1 on failure, in which case #mar_errno can be
 * used to determine the error.
 * 
 * \sa #mar_setuser and #mar_write.
 */

MAR_API int
mar_insert(mar_t mar, const char* path);

/**
 * \brief Read user data from meta archive.
 *
 * \param mar A handle to the meta archive.
 *
 * \param buf The output buffer to which the user data will be copied.
 *
 * \param size The number of bytes to be read.
 *
 * \return The number of bytes actually read or zero to signal end-of-file. -1
 * is returned on failure, in which case #mar_errno can be used to determine
 * the error.
 *
 * \sa #mar_seek, #mar_extract and #mar_user.
 */

MAR_API ssize_t
mar_read(mar_t mar, void* buf, size_t size);

/**
 * \brief Reposition user data offset within meta archive.
 *
 * \param mar A handle to the meta archive.
 *
 * \param offset The offset calculated according to the \ref SeekWhence
 * "whence" directive.
 *
 * \param whence The \ref SeekWhence "whence" directive.
 *
 * \return The resulting offset location in bytes from the beginning of the
 * user data or -1 on failure, in which case #mar_errno can be used to
 * determine the error.
 *
 * \sa #mar_read and #mar_write.
 */

MAR_API off_t
mar_seek(mar_t mar, off_t offset, int whence);

/**
 * \brief Set user data within meta archive.
 *
 * \param mar A handle to the meta archive.
 *
 * \param data A pointer to the user data to be copied.
 *
 * \param size The size of the user data to be copied.
 *
 * \return zero on success or -1 on failure, in which case #mar_errno can be
 * used to determine the error.
 *
 * \sa #mar_insert and #mar_write.
 */

MAR_API int
mar_setuser(mar_t mar, const void* data, size_t size);

/**
 * \brief Flush meta archive buffers.
 *
 * \param mar A handle to the meta archive.
 *
 * \return zero on success or -1 on failure, in which case #mar_errno can be
 * used to determine the error.
 */

MAR_API int
mar_sync(mar_t mar);

/**
 * \brief Truncate user data within meta archive.
 *
 * \param mar A handle to the meta archive.
 *
 * \param size The size to which the user data will be truncated.
 *
 * \return zero on success or -1 on failure, in which case #mar_errno can be
 * used to determine the error.
 */

MAR_API int
mar_truncate(mar_t mar, size_t size);

/**
 * \brief Write user data to meta archive.
 *
 * \param mar A handle to the meta archive.
 *
 * \param buf The buffer from which the user data will be copied.
 *
 * \param size The number of bytes to be written.
 *
 * \return The number of bytes actually written or -1 on failure, in which case
 * #mar_errno can be used to determine the error.
 *
 * \sa #mar_insert, #mar_seek and #mar_setuser.
 */

MAR_API ssize_t
mar_write(mar_t mar, const void* buf, size_t size);

/**
 * \brief Extract user data from meta archive into file.
 *
 * \param mar A handle to the meta archive.
 *
 * \param path A path to the file to which the user data will be written.
 *
 * \return zero on success or -1 on failure, in which case #mar_errno can be
 * used to determine the error.
 *
 * \sa #mar_read and #mar_user.
 */

MAR_API int
mar_extract(mar_t mar, const char* path);

/**
 * \brief Obtain user data from meta archive.
 *
 * \param mar A handle to the meta archive.
 *
 * \param size An optional output parameter in which the size of the user data
 * would be returned.
 *
 * \return A pointer to the user data or NULL on failure, in which case
 * #mar_errno can be used to determine the error.
 *
 * \sa #mar_read, #mar_extract and #mar_usersize.
 */

MAR_API const void*
mar_user(mar_t mar, size_t* size);

/**
 * \brief Obtain size of user data within meta archive.
 *
 * \param mar A handle to the meta archive.
 *
 * \param size The output parameter in which the size of the user data will be
 * returned.
 *
 * \return zero on success or -1 on failure, in which case #mar_errno can be
 * used to determine the error.
 *
 * \sa #mar_user.
 */

MAR_API int
mar_usersize(mar_t mar, size_t* size);

/**
 * \brief Obtain last error number.
 *
 * \return the last error number or zero if no error has occurred.
 */

MAR_API int
mar_errno(void);

#endif /* INCLUDED_MAR_C */