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.

171 lines
4.9 KiB

6 years ago
3 years ago
6 years ago
6 years ago
6 years ago
3 years ago
6 years ago
6 years ago
  1. /**
  2. * @file baseprotocol.h
  3. * @brief base protocol (FIXME: derived from filename)
  4. * @license GNU General Public License 3.0 - see LICENSE.txt
  5. */
  6. #pragma once
  7. #include "message.h"
  8. #ifdef __cplusplus
  9. extern "C" {
  10. #endif
  11. /**
  12. * @enum base_protocol_type
  13. *
  14. * @brief TODO
  15. *
  16. */
  17. typedef enum _base_protocol_type {
  18. BASE_SIGN = 0,
  19. BASE_SYNC = 1,
  20. BASE_KEYRESET = 2
  21. } base_protocol_type;
  22. /**
  23. * <!-- base_decorate_message() -->
  24. *
  25. * @brief Decorate a message with payload
  26. *
  27. * @param[in] session session handle
  28. * @param[in,out] msg message to decorate (contains return result on success)
  29. * @param[in] type base protocol type
  30. * @param[in] payload payload to send
  31. * @param[in] size size of payload
  32. * @param[in] fpr optional key to sign or NULL
  33. *
  34. * @retval PEP_STATUS_OK on success
  35. * @retval error_status on failure
  36. *
  37. * @ownership
  38. * - On success (and only then), ownership of the payload is assigned to the msg structure
  39. * - Ownership of the msg remains with the caller
  40. *
  41. */
  42. PEP_STATUS base_decorate_message(
  43. PEP_SESSION session,
  44. message *msg,
  45. base_protocol_type type,
  46. char *payload,
  47. size_t size,
  48. const char *fpr
  49. );
  50. /**
  51. * <!-- base_prepare_message() -->
  52. *
  53. * @brief Prepare a sync message with payload
  54. *
  55. * @param[in] session session handle
  56. * @param[in] me identity to use for the sender
  57. * @param[in] partner identity to use for the receiver
  58. * @param[in] type base protocol type
  59. * @param[in] payload payload to send
  60. * @param[in] size size of payload
  61. * @param[in] fpr optional key to sign or NULL
  62. * @param[out] result returned message with payload on success
  63. *
  64. * @retval PEP_STATUS_OK on success
  65. * @retval error_status on failure
  66. *
  67. * @ownership
  68. * - On (and only on) success, ownership of payload is assigned to the result structure
  69. * - Ownership of the result goes to the caller
  70. *
  71. */
  72. PEP_STATUS base_prepare_message(
  73. PEP_SESSION session,
  74. const pEp_identity *me,
  75. const pEp_identity *partner,
  76. base_protocol_type type,
  77. char *payload,
  78. size_t size,
  79. const char *fpr,
  80. message **result
  81. );
  82. /**
  83. * <!-- base_extract_message() -->
  84. *
  85. * @brief Extract a sync message from a pEp message
  86. *
  87. * @param[in] session session handle
  88. * @param[in] msg message to analyze
  89. * @param[in] type base protocol type to extract
  90. * @param[out] size size of extracted payload, or 0 if not found
  91. * @param[out] payload extracted payload, if sync message is found.
  92. * otherwise, NULL
  93. * @param[out] fpr if message was correctly signed then fpr of signature's
  94. * key, otherwise NULL
  95. *
  96. * @retval PEP_STATUS_OK if no error occurred, whether or not sync message was found
  97. * @retval error_status any other value on error
  98. *
  99. * @ownership
  100. * - Payload may point to msg attachment, but the ownership does not change
  101. * - If fpr != NULL the ownership goes to the caller
  102. *
  103. * @todo Volker, expand this definition from sync message. What do we call these? Administrative messages? - K
  104. *
  105. */
  106. PEP_STATUS base_extract_message(
  107. PEP_SESSION session,
  108. message *msg,
  109. base_protocol_type type,
  110. size_t *size,
  111. const char **payload,
  112. char **fpr
  113. );
  114. /**
  115. * <!-- try_base_prepare_message() -->
  116. *
  117. * @brief Prepare a sync message with payload. This is the internal function to be used by
  118. * asynchronous network protocol implementations. This function differs from
  119. * base_prepare_message in that it calls messageToSend(NULL) in case there is a missing
  120. * or wrong passphrase, but more explanation is required here.
  121. *
  122. * @param[in] session session handle
  123. * @param[in] me identity to use for the sender
  124. * @param[in] partner identity to use for the receiver
  125. * @param[in] type base protocol type
  126. * @param[in] payload payload to send
  127. * @param[in] size size of payload
  128. * @param[in] fpr optional key to sign or NULL
  129. * @param[out] result returned message with payload on success
  130. *
  131. * @ownership
  132. * - On (and only on) success, ownership of payload is assigned to the result structure
  133. * - Ownership of the result goes to the caller
  134. *
  135. * @todo Volker, I need a better explanation of the use case here to document correctly - K
  136. *
  137. * @see base_prepare_message()
  138. */
  139. PEP_STATUS try_base_prepare_message(
  140. PEP_SESSION session,
  141. const pEp_identity *me,
  142. const pEp_identity *partner,
  143. base_protocol_type type,
  144. char *payload,
  145. size_t size,
  146. const char *fpr,
  147. message **result
  148. );
  149. #ifdef __cplusplus
  150. }
  151. #endif