codec_base.h 5.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147
  1. #ifndef _LSUP_CODEC_BASE_H
  2. #define _LSUP_CODEC_BASE_H
  3. #include "graph.h"
  4. /** @brief Codec iterator type.
  5. *
  6. * This structure holds state data including input and output for encoding and
  7. * decoding RDF. Normally it should not be inspected ormanipulated directly,
  8. * but rather passed to codec iteration functions for processing RDF.
  9. *
  10. * NOTE: This should be used as an opaque handle, however it is exposed here
  11. * for easier inclusion into each codec.
  12. */
  13. typedef struct codec_iter_t {
  14. char * rep; // String representation of a RDF fragment.
  15. LSUP_Triple * trp; // RDF fragment being encoded or decoded.
  16. LSUP_GraphIterator *gr_it; // Graph iterator.
  17. LSUP_NSMap * nsm; // Namespace map.
  18. size_t cur; // Internal cursor.
  19. LSUP_rc rc; // Internal return code.
  20. char * str_s; // Temporary string.
  21. char * str_p; // Temporary string.
  22. char * str_o; // Temporary string.
  23. } LSUP_CodecIterator;
  24. /** @brief Term encoder callback type.
  25. *
  26. * @param[in] term Single term handle.
  27. *
  28. * @param[in] nsm Namespace map. May be NULL for no prefix shortening.
  29. *
  30. * @param[out] rep Pointer to a string to be filled with the encoded term. The
  31. * caller is in charge of freeing the string after use. Returns undefined on
  32. * error.
  33. *
  34. * @return LSUP_OK on successful encoding; <0 for other errors.
  35. */
  36. typedef LSUP_rc (*term_enc_fn_t)(
  37. const LSUP_Term *term, const LSUP_NSMap *nsm, char **rep);
  38. /** TODO
  39. */
  40. typedef LSUP_rc (*term_dec_fn_t)(
  41. const char *rep, const LSUP_NSMap *nsm, LSUP_Term **term);
  42. /** @brief Initialize a graph encoding loop.
  43. *
  44. * This prototype is to be implemented by graph encoding loops. It should
  45. * create an iterator and perform all initial setup for finding triples.
  46. *
  47. * @param[in] gr The graph to be encoded. The graph's namespace map is used by the
  48. * codec for namespace prefixing. The graph may only be freed after the loop is
  49. * finalized.
  50. *
  51. * @return A codec iterator handle to be passed to a #gr_codec_iter_fn_t
  52. * function and, eventually, to a #gr_codec_done_fn_t function.
  53. */
  54. typedef LSUP_CodecIterator * (*gr_encode_init_fn_t)(const LSUP_Graph *gr);
  55. /** @brief Perform one encoding iteration.
  56. *
  57. * Implementations of this prototype should perform all the steps to encode one
  58. * or more triples into a complete RDF fragment representing a complete triple
  59. * or a set thereof. The input unit is up to the implementation.
  60. *
  61. * @param[in] it Iterator handle.
  62. *
  63. * @param[out] res Handle to be populated with a string obtained from encoding.
  64. * This pointer must be passed initialized (it may be NULL) and should be
  65. * eventually freed manually at the end of the loop (it is reallocated at each
  66. * iteration, so memory from a previous iteration may be overwritten with new
  67. * data).
  68. *
  69. * @return LSUP_OK if a new token was processed; LSUP_END if the end of the
  70. * loop was reached.
  71. */
  72. typedef LSUP_rc (*gr_codec_iter_fn_t)(LSUP_CodecIterator *it, void **res);
  73. typedef void (*gr_codec_done_fn_t)(LSUP_CodecIterator *it);
  74. /** @brief Prototype for decoding a complete RDF document into a graph.
  75. *
  76. * Implementations SHOULD consume data from the file handle in chunks.
  77. *
  78. * @param[in] rep Open file handle pointing to the RDF data. Implementations
  79. * MUST NOT close the file handle.
  80. *
  81. * @param[out] gr Pointer to a graph handle to be generated from decoding.
  82. *
  83. * @param[out] ct If not NULL, it may be populated with the number of triples
  84. * parsed (which may be different from the resulting graph size).
  85. * Implementations may choose not not use this, and they must account for the
  86. * value to be NULL.
  87. *
  88. * @return Implementations MUST return LSUP_OK on success and a negative value
  89. * on parsing error.
  90. */
  91. typedef LSUP_rc (*gr_decode_fn_t)(FILE *rep, LSUP_Graph **gr, size_t *ct);
  92. /** @brief Codec structure.
  93. *
  94. * An instance of this structure is usually defined at compile time (see
  95. * examples in "include/codec_*.h" and "src/codec_*.c") and should have the
  96. * following defined:
  97. *
  98. * - name: A brief (16-char max), human-readable to identify the codec.
  99. * - mimetype: MIME type (32-char max) associated with the codec.
  100. * - extension: File extension associated with the serialized file.
  101. *
  102. * - term_encoder: Encode a single term.
  103. *
  104. * - gr_encode_init: Initialize a graph decoding loop.
  105. * - gr_encode_iter: Run one iteration of encoding on one or more triples.
  106. * - gr_encode_done: Finalize the encoding loop and free the support data.
  107. *
  108. * - term_decoder: Decode a single term.
  109. * - gr_decoder: Decode a RDF document into a graph.
  110. *
  111. * For documentation on the individual encoding and decoding callbaks, see the
  112. * related function prototypes.
  113. */
  114. typedef struct codec_t {
  115. char name[16]; // Name of the codec.
  116. char mimetype[32]; // MIME type associated with the codec.
  117. char extension[8]; // Serialized file extension.
  118. // Encoding.
  119. term_enc_fn_t term_encoder; // Term encoder function.
  120. gr_encode_init_fn_t gr_encode_init; // Graph encoder initialization.
  121. gr_codec_iter_fn_t gr_encode_iter; // Graph encoder iteration.
  122. gr_codec_done_fn_t gr_encode_done; // Graph encoder finalization.
  123. // Decoding.
  124. term_dec_fn_t term_decoder; // Term decoder function.
  125. gr_decode_fn_t gr_decoder; // Graph decoder function.
  126. } LSUP_Codec;
  127. #endif