lsup_rdf/include/codec_base.h

#ifndef _LSUP_CODEC_BASE_H
#define _LSUP_CODEC_BASE_H

#include "graph.h"


/** @brief Codec iterator type.
 *
 * This structure holds state data including input and output for encoding and
 * decoding RDF. Normally it should not be inspected ormanipulated directly,
 * but rather passed to codec iteration functions for processing RDF.
 *
 * NOTE: This should be used as an opaque handle, however it is exposed here
 * for easier inclusion into each codec.
 */
typedef struct codec_iter_t {
    char *              rep;        // String representation of a RDF fragment.
    LSUP_Triple *       trp;        // RDF fragment being encoded or decoded.
    LSUP_GraphIterator *gr_it;      // Graph iterator.
    LSUP_NSMap *        nsm;        // Namespace map.
    size_t              cur;        // Internal cursor.
    LSUP_rc             rc;         // Internal return code.
    char *              str_s;      // Temporary string.
    char *              str_p;      // Temporary string.
    char *              str_o;      // Temporary string.
} LSUP_CodecIterator;


/** @brief Term encoder callback type.
 *
 * @param[in] term Single term handle.
 *
 * @param[in] nsm Namespace map. May be NULL for no prefix shortening.
 *
 * @param[out] rep Pointer to a string to be filled with the encoded term. The
 *  caller is in charge of freeing the string after use. Returns undefined on
 *  error.
 *
 * @return LSUP_OK on successful encoding; <0 for other errors.
 */
typedef LSUP_rc (*term_enc_fn_t)(
        const LSUP_Term *term, const LSUP_NSMap *nsm, char **rep);


/** @brief Initialize a graph encoding loop.
 *
 * This prototype is to be implemented by graph encoding loops. It should
 * create an iterator and perform all initial setup for finding triples.
 *
 * @param[in] gr The graph to be encoded. The graph's namespace map is used by the
 * codec for namespace prefixing. The graph may only be freed after the loop is
 * finalized.
 *
 * @return A codec iterator handle to be passed to a #gr_codec_iter_fn_t
 * function and, eventually, to a #gr_codec_done_fn_t function.
 */
typedef LSUP_CodecIterator * (*gr_encode_init_fn_t)(const LSUP_Graph *gr);


/** @brief Perform one encoding iteration.
 *
 * Implementations of this prototype should perform all the steps to encode one
 * or more triples into a complete RDF fragment representing a complete triple
 * or a set thereof. The input unit is up to the implementation.
 *
 * @param[in] it Iterator handle.
 *
 * @param[out] res Handle to be populated with a string obtained from encoding.
 * This pointer must be passed initialized (it may be NULL) and should be
 * eventually freed manually at the end of the loop (it is reallocated at each
 * iteration, so memory from a previous iteration may be overwritten with new
 * data).
 *
 * @return LSUP_OK if a new token was processed; LSUP_END if the end of the
 *  loop was reached.
 */
typedef LSUP_rc (*gr_codec_iter_fn_t)(LSUP_CodecIterator *it, void **res);

typedef void (*gr_codec_done_fn_t)(LSUP_CodecIterator *it);


/** @brief Prototype for decoding a string into a LSUP_Term.
 *
 * Implementations MAY ignore any other tokens after finding the first one.
 *
 * @param[in] rep NT representation of the term.
 *
 * @param[in] nsm Namespace map handle.
 *
 * @param[out] Pointer to the term handle to be created. Implementaions SHOULD
 *  return NULL on a parse error.
 *
 * @return Implementations MUST return LSUP_OK on success and a negative value
 *  on parsing error.
 */
typedef LSUP_rc (*term_decode_fn_t)(
        const char *rep, const LSUP_NSMap *nsm, LSUP_Term **term);


/** @brief Prototype for decoding a complete RDF document into a graph.
 *
 * Implementations SHOULD consume data from the file handle in chunks.
 *
 * @param[in] rep Open file handle pointing to the RDF data. Implementations
 * MUST NOT close the file handle.
 *
 * @param[out] gr Pointer to a graph handle to be generated from decoding.
 *
 * @param[out] ct If not NULL, it may be populated with the number of triples
 *  parsed (which may be different from the resulting graph size).
 *  Implementations may choose not not use this, and they must account for the
 *  value to be NULL.
 *
 * @return Implementations MUST return LSUP_OK on success and a negative value
 *  on parsing error.
 */
typedef LSUP_rc (*gr_decode_fn_t)(FILE *rep, LSUP_Graph **gr, size_t *ct);


/** @brief Codec structure.
 *
 * An instance of this structure is usually defined at compile time (see
 * examples in "include/codec_*.h" and "src/codec_*.c") and should have the
 * following defined:
 *
 * - name: A brief (16-char max), human-readable to identify the codec.
 * - mimetype: MIME type (32-char max) associated with the codec.
 * - extension: File extension associated with the serialized file.
 *
 * - term_encoder: Encode a single term.
 *
 * - gr_encode_init: Initialize a graph decoding loop.
 * - gr_encode_iter: Run one iteration of encoding on one or more triples.
 * - gr_encode_done: Finalize the encoding loop and free the support data.
 *
 * - term_decoder: Decode a single term.
 * - gr_decoder: Decode a RDF document into a graph.
 *
 * For documentation on the individual encoding and decoding callbaks, see the
 * related function prototypes.
 */
typedef struct codec_t {
    char                name[16];       // Name of the codec.
    char                mimetype[32];   // MIME type associated with the codec.
    char                extension[8];   // Serialized file extension.

    // Encoding.
    term_enc_fn_t       term_encoder;   // Term encoder function.

    gr_encode_init_fn_t gr_encode_init; // Graph encoder initialization.
    gr_codec_iter_fn_t  gr_encode_iter; // Graph encoder iteration.
    gr_codec_done_fn_t  gr_encode_done; // Graph encoder finalization.

    // Decoding.
    term_decode_fn_t    term_decoder;   // Term decoder function.
    gr_decode_fn_t      gr_decoder;     // Graph decoder function.
} LSUP_Codec;

#endif