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.

237 lines
6.7 KiB

8 years ago
8 years ago
8 years ago
7 years ago
7 years ago
8 years ago
  1. /**
  2. * @file message.h
  3. * @brief the pEp message structure and functions used to represent messages and pass message
  4. * information back and forth between the engine and its customers. Includes memory management
  5. * for said structs.
  6. * @license GNU General Public License 3.0 - see LICENSE.txt
  7. */
  8. #pragma once
  9. #include <time.h>
  10. #include "pEpEngine.h"
  11. #include "identity_list.h"
  12. #include "bloblist.h"
  13. #include "stringlist.h"
  14. #include "stringpair.h"
  15. #include "timestamp.h"
  16. #ifdef __cplusplus
  17. extern "C" {
  18. #endif
  19. /**
  20. * @enum PEP_text_format
  21. *
  22. * @brief TODO
  23. *
  24. */
  25. typedef enum _PEP_text_format {
  26. PEP_text_format_plain = 0,
  27. PEP_text_format_html,
  28. PEP_text_format_other = 0xff
  29. } PEP_text_format;
  30. /**
  31. * @enum PEP_msg_direction
  32. *
  33. * @brief TODO
  34. *
  35. */
  36. typedef enum _PEP_msg_direction {
  37. PEP_dir_incoming = 0,
  38. PEP_dir_outgoing
  39. } PEP_msg_direction;
  40. struct _message_ref_list;
  41. /**
  42. * @struct message
  43. *
  44. * @brief TODO
  45. *
  46. */
  47. typedef struct _message {
  48. PEP_msg_direction dir;
  49. char *id; // UTF-8 string of message ID
  50. char *shortmsg; // UTF-8 string of short message
  51. char *longmsg; // UTF-8 string of long message
  52. // (plain)
  53. char *longmsg_formatted; // UTF-8 string of long message
  54. // (formatted)
  55. bloblist_t *attachments; // blobs with attachements
  56. char *rawmsg_ref; // reference to raw message data
  57. size_t rawmsg_size; // size of raw message data
  58. timestamp *sent; // when the message is sent
  59. timestamp *recv; // when the message is received
  60. pEp_identity *from; // whom the message is from
  61. identity_list *to; // whom the message is to
  62. pEp_identity *recv_by; // via which identity the message
  63. // is received
  64. identity_list *cc; // whom a CC is being sent
  65. identity_list *bcc; // whom a BCC is being sent
  66. identity_list *reply_to; // where a reply should go to
  67. stringlist_t *in_reply_to; // list of UTF-8 strings with
  68. // MessageIDs of refering messages
  69. struct _message *refering_msg_ref; // reference to refering message
  70. stringlist_t *references; // list of UTF-8 strings with references
  71. struct _message_ref_list *refered_by; // list of references to messages being
  72. // refered
  73. stringlist_t *keywords; // list of UTF-8 strings with keywords
  74. char *comments; // UTF-8 string with comments
  75. stringpair_list_t *opt_fields; // optional fields
  76. PEP_enc_format enc_format; // format of encrypted data
  77. char* _sender_fpr; // INTERNAL USE ONLY - fingerprint of
  78. // sending signer.
  79. // (read_only to the outside)
  80. } message;
  81. /**
  82. * @struct message_ref_list
  83. *
  84. * @brief TODO
  85. *
  86. */
  87. typedef struct _message_ref_list {
  88. message *msg_ref; // reference to message
  89. struct _message_ref_list *next;
  90. } message_ref_list;
  91. /**
  92. * <!-- new_message() -->
  93. *
  94. * @brief Allocate new message
  95. *
  96. * @param[in] dir PEP_dir_incoming or PEP_dir_outgoing
  97. *
  98. * @retval pointer to new message or NULL if out of memory
  99. *
  100. *
  101. */
  102. DYNAMIC_API message *new_message(
  103. PEP_msg_direction dir
  104. );
  105. /**
  106. * <!-- free_message() -->
  107. *
  108. * @brief Free message struct
  109. *
  110. * @param[in] msg message struct to free
  111. * NOTA BENE:
  112. * raw data (msg->rawmsg_ref) and referenced other messages (msg->refering_msg_ref)
  113. * aren't freed and remain in the ownership of the caller!
  114. *
  115. *
  116. */
  117. DYNAMIC_API void free_message(message *msg);
  118. /**
  119. * <!-- message_dup() -->
  120. *
  121. * @brief Duplicate message (deep copy)
  122. *
  123. * @param[in] msg message to duplicate
  124. *
  125. * @retval pointer to duplicate of message pointed by msg or NULL
  126. * @retval NOTA BENE:
  127. * @retval not owned pointees (msg->rawmsg_ref and msg->refering_msg_ref) are shared!
  128. *
  129. *
  130. */
  131. DYNAMIC_API message * message_dup(const message *msg);
  132. /**
  133. * <!-- message_transfer() -->
  134. *
  135. * @brief Assign ownership of all fields of the src message to
  136. * the dst message object passed in. Free respective memory
  137. * in the dst message, and reinitialise and pointers in
  138. * the src message to NULL so that it can be freed properly
  139. * by its owner.
  140. *
  141. * @param[in,out] dst message to clobber and reassign values to
  142. * @param[in,out] src message whose values will be transfered to dst
  143. * NOTA BENE:
  144. * not owned pointees (msg->rawmsg_ref and msg->refering_msg_ref) are shared!
  145. * these are simply transferred.
  146. *
  147. *
  148. */
  149. DYNAMIC_API void message_transfer(message* dst, message *src);
  150. /**
  151. * <!-- new_message_ref_list() -->
  152. *
  153. * @brief Allocate new message reference list
  154. *
  155. * @param[in] msg message to add a reference to or NULL
  156. *
  157. * @retval pointer to new message_ref_list or NULL if out of memory
  158. *
  159. *
  160. */
  161. DYNAMIC_API message_ref_list *new_message_ref_list(message *msg);
  162. /**
  163. * <!-- free_message_ref_list() -->
  164. *
  165. * @brief Free message reference list
  166. *
  167. * @param[in] msg_list message_ref_list to free
  168. *
  169. *
  170. */
  171. DYNAMIC_API void free_message_ref_list(message_ref_list *msg_list);
  172. /**
  173. * <!-- message_ref_list_dup() -->
  174. *
  175. * @brief Duplicate message reference list
  176. *
  177. * paramters:
  178. * src (in) message_ref_list to duplicate
  179. *
  180. * @retval pointer to new message_ref_list or NULL if out of memory
  181. *
  182. *
  183. */
  184. DYNAMIC_API message_ref_list *message_ref_list_dup(
  185. const message_ref_list *src
  186. );
  187. /**
  188. * <!-- message_ref_list_add() -->
  189. *
  190. * @brief Add a reference to a message to a message reference
  191. * list
  192. *
  193. * @param[in] msg_list message_ref_list to add to
  194. * @param[in] msg message to add a reference to
  195. *
  196. * @retval pointer to the last element of message_ref_list or NULL if out of
  197. * @retval memory
  198. *
  199. *
  200. */
  201. DYNAMIC_API message_ref_list *message_ref_list_add(message_ref_list *msg_list,
  202. message *msg);
  203. #ifdef __cplusplus
  204. }
  205. #endif