You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

182 lines
5.0 KiB

8 years ago
3 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
  1. /**
  2. * @file bloblist.h
  3. * @brief functions for list structure to hold data of unspecified format (hence,
  4. * "blob list"); can contain addition format information in structure's mime info
  5. * @license GNU General Public License 3.0 - see LICENSE.txt
  6. */
  7. #pragma once
  8. #include <stddef.h>
  9. #include "dynamic_api.h"
  10. #include "stringpair.h"
  11. #ifdef __cplusplus
  12. extern "C" {
  13. #endif
  14. /**
  15. * @enum content_disposition_type
  16. *
  17. * @brief TODO
  18. *
  19. */
  20. typedef enum {
  21. PEP_CONTENT_DISP_ATTACHMENT = 0,
  22. PEP_CONTENT_DISP_INLINE = 1,
  23. PEP_CONTENT_DISP_OTHER = -1 // must be affirmatively set
  24. } content_disposition_type;
  25. /**
  26. * @struct bloblist_t
  27. *
  28. * @brief TODO
  29. *
  30. */
  31. typedef struct _bloblist_t {
  32. char *value; // blob
  33. size_t size; // size of blob
  34. char *mime_type; // UTF-8 string of MIME type of blob or
  35. // NULL if unknown
  36. char *filename; // UTF-8 string of file name of blob or
  37. // NULL if unknown
  38. content_disposition_type disposition;
  39. // default is attachment when allocated
  40. // (see mime.h and RFC2183)
  41. struct _bloblist_t *next; // this is a single linked list
  42. void (*release_value)(char *); // pointer to release function;
  43. // pEp_free() if not set
  44. } bloblist_t;
  45. /**
  46. * <!-- new_bloblist() -->
  47. *
  48. * @brief Allocate a new bloblist
  49. *
  50. * @param[in] blob blob to add to the list
  51. * @param[in] size size of the blob
  52. * @param[in] mime_type MIME type of the blob data or NULL if unknown
  53. * @param[in] filename file name of origin of blob data or NULL if unknown
  54. *
  55. * @retval pointer to new bloblist_t or NULL if out of memory
  56. *
  57. * @ownership
  58. * - the ownership of the blob goes to the bloblist struct
  59. * - mime_type and filename are copied (copies belong to bloblist struct,
  60. * the originals remain in the ownership of the caller)
  61. *
  62. * @warning if blob is on a different heap, then after the call, release_value has to
  63. * be set by the adapter; this is relevant on operating systems with
  64. * multiple heaps like Microsoft Windows
  65. *
  66. */
  67. DYNAMIC_API bloblist_t *new_bloblist(char *blob, size_t size, const char *mime_type,
  68. const char *filename);
  69. /**
  70. * <!-- free_bloblist() -->
  71. *
  72. * @brief Free bloblist
  73. *
  74. * @param[in] bloblist bloblist to free
  75. *
  76. *
  77. */
  78. DYNAMIC_API void free_bloblist(bloblist_t *bloblist);
  79. /**
  80. * <!-- bloblist_dup() -->
  81. *
  82. * @brief Duplicate bloblist
  83. *
  84. * @param[in] src bloblist to duplicate
  85. *
  86. * @retval pointer to a new bloblist_t or NULL if out of memory
  87. *
  88. * @warning this is an expensive operation because all blobs are copied
  89. *
  90. */
  91. DYNAMIC_API bloblist_t *bloblist_dup(const bloblist_t *src);
  92. /**
  93. * <!-- bloblist_add() -->
  94. *
  95. * @brief Add reference to a blob to bloblist
  96. *
  97. * @param[in] bloblist bloblist to add to
  98. * @param[in] blob blob
  99. * @param[in] size size of the blob
  100. * @param[in] mime_type MIME type of the blob or NULL if unknown
  101. * @param[in] filename file name of the blob or NULL if unknown
  102. *
  103. * @retval pointer to the last element of bloblist or NULL if out of memory or
  104. * @retval NULL passed in as blob value
  105. *
  106. * @ownership
  107. * - the ownership of the blob goes to the bloblist struct
  108. * - mime_type and filename are copied and belong to the bloblist struct, the originals remain in the ownership of the caller.
  109. *
  110. * @note Bloblist input parameter equal to NULL or with value == NULL is a valid
  111. * empty input list.
  112. *
  113. * @note If there is release_value set in bloblist it is copied to the added
  114. * leaf
  115. *
  116. */
  117. DYNAMIC_API bloblist_t *bloblist_add(bloblist_t *bloblist, char *blob, size_t size,
  118. const char *mime_type, const char *filename);
  119. /**
  120. * <!-- bloblist_length() -->
  121. *
  122. * @brief Get length of bloblist
  123. *
  124. * @param[in] bloblist bloblist struct to determine length of
  125. *
  126. * @retval length of bloblist in number of elements
  127. *
  128. *
  129. */
  130. DYNAMIC_API int bloblist_length(const bloblist_t *bloblist);
  131. /**
  132. * <!-- set_blob_content_disposition() -->
  133. *
  134. * @brief Set blob content disposition and parameters
  135. * when necessary
  136. *
  137. * @param[in] blob bloblist struct to change disposition for
  138. * @param[in] disposition disposition type (see enum)
  139. *
  140. *
  141. */
  142. DYNAMIC_API void set_blob_disposition(bloblist_t* blob,
  143. content_disposition_type disposition);
  144. /**
  145. * <!-- bloblist_join() -->
  146. *
  147. * @brief TODO
  148. *
  149. * @param[in] *first bloblist_t
  150. * @param[in] *second bloblist_t
  151. *
  152. */
  153. DYNAMIC_API bloblist_t* bloblist_join(bloblist_t* first, bloblist_t* second);
  154. #ifdef __cplusplus
  155. }
  156. #endif