namespace.h 4.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152
  1. #ifndef _LSUP_NAMESPACE_H
  2. #define _LSUP_NAMESPACE_H
  3. #include "core.h"
  4. /** @brief Namespace prefix length, including terminator.
  5. */
  6. #define PFX_LEN 8
  7. /** @brief Default namespace. Only available upon environment initialization.
  8. */
  9. #define LSUP_DEF_NSM LSUP_default_env->nsm
  10. /** @brief Namespace map structure.
  11. *
  12. * It contains a double hash map of pfx->ns and ns->pfx for fast 2-way lookup.
  13. *
  14. * Prefixes are fixed PFX_LEN-size strings, namespaces are arbitrary sized
  15. * strings.
  16. */
  17. typedef struct hashmap LSUP_NSMap;
  18. /** @brief Namespace prefix type.
  19. */
  20. typedef char ns_pfx[PFX_LEN];
  21. /** @brief Create a new namespace map.
  22. *
  23. * @return A pointer to an empty map. It must be freed with #LSUP_nsmap_free().
  24. */
  25. LSUP_NSMap *
  26. LSUP_nsmap_new (void);
  27. /** @brief Free a namespace map and its internal structures.
  28. *
  29. * @param[in] map The map to free.
  30. */
  31. void
  32. LSUP_nsmap_free (LSUP_NSMap *map);
  33. /** @brief Add a prefix -> namespace pair to the map or update it.
  34. *
  35. * If the prefix already exists, it is quietly updated with the new value.
  36. *
  37. * @param[in] map The map to add to.
  38. *
  39. * @param[in] pfx The namespace prefix.
  40. *
  41. * @param[in] nsstr Fully qualified namespace.
  42. *
  43. * @return LSUP_OK if the record was added or replaced; LSUP_MEM_ERR if an
  44. * allocation error occurred.
  45. */
  46. LSUP_rc
  47. LSUP_nsmap_add (LSUP_NSMap *map, const char *pfx, const char *nsstr);
  48. /** @brief Remove a prefix -> namespace pair from a map.
  49. *
  50. * @param[in] map The map to remove from.
  51. *
  52. * @param[in] pfx The namespace prefix to remove.
  53. *
  54. * @return LSUP_OK on successful delete; LSUP_NOACTION if no record was found.
  55. */
  56. LSUP_rc
  57. LSUP_nsmap_remove (LSUP_NSMap *map, const char *pfx);
  58. /** @brief Get the namespace for a prefix.
  59. *
  60. * @param[in] map The map to look up the namespace in.
  61. *
  62. * @param[in] pfx The prefix to look up.
  63. *
  64. * @return A pointer to the namespace string. Note that this is not a copy and
  65. * should not be modified directly.
  66. */
  67. const char *
  68. LSUP_nsmap_get_ns (LSUP_NSMap *map, const char *pfx);
  69. /** @brief Get the prefix for a namespace.
  70. *
  71. * @param[in] map The map to look up the prefix in.
  72. *
  73. * @param[in] pfx The namespace to look up.
  74. *
  75. * @return Found prefix, or NULL if the namespace is not mapped.
  76. */
  77. const char *
  78. LSUP_nsmap_get_pfx (LSUP_NSMap *map, const char *ns);
  79. /** @brief Convert a namespace-prefixed string to a FQ URI sring if mapped.
  80. *
  81. * @param[in] map Namespace map to look up.
  82. *
  83. * @param[in] uri URI string to denormalize.
  84. *
  85. * @param[out] fq_uri String pointer to be filled with the FQ URI. If the
  86. * namespace is not in the map or an error occurred, this will be NULL.
  87. * The caller is in charge of freeing the memory.
  88. *
  89. * @return LSUP_OK on success, LSUP_NORESULT if no entry was found in the map,
  90. * LSUP_MEM_ERR if a memory allocation error ocurred.
  91. */
  92. LSUP_rc
  93. LSUP_nsmap_normalize_uri (
  94. LSUP_NSMap *map, const char *pfx_uri, char **fq_uri);
  95. /** @brief Convert a FQ URI string to a prefixed string if the prefix is found.
  96. *
  97. * TODO Note that this function does not attempt to find the longest or
  98. * shortest namespace prefix in case of conflicts (e.g. when both
  99. * `http://example.edu/` and `http://example.edu/data/` are mapped and
  100. * `http://example.edu/data/51937642` is being denormalized). In such
  101. * case, the first prefix that is found is assigned.
  102. *
  103. * @param[in] map Namespace map to look up.
  104. *
  105. * @param[in] uri URI string to normalize.
  106. *
  107. * @param[out] String pointer to be filled with the prefixed URI. If the
  108. * namespace is not in the map or an error occurred, this will be NULL.
  109. * The caller is in charge of freeing the memory.
  110. *
  111. * @return LSUP_OK on success, LSUP_NORESULT if no entry was found in the map,
  112. * LSUP_MEM_ERR if a memory allocation error ocurred.
  113. */
  114. LSUP_rc
  115. LSUP_nsmap_denormalize_uri (
  116. LSUP_NSMap *map, const char *fq_uri, char **pfx_uri);
  117. /** @brief Dump all entries of a namespace map.
  118. *
  119. * @param[in] map Map to dump.
  120. *
  121. * @return 2-dimensional array of strings, with as many rows as namespace
  122. * entries, and two columns: the first for the namespace prefix, the second
  123. * for the namespace.
  124. */
  125. const char ***
  126. LSUP_nsmap_dump (const LSUP_NSMap *map);
  127. #endif