C++11 library providing functionality common to all adapters.
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.

227 lines
9.4 KiB

  1. // This file is under GNU General Public License 3.0
  2. // see LICENSE.txt
  3. #ifndef LIBPEPADAPTER_GROUP_MANAGER_API_H
  4. #define LIBPEPADAPTER_GROUP_MANAGER_API_H
  5. #include <pEp/message_api.h>
  6. #ifdef __cplusplus
  7. extern "C" {
  8. #endif
  9. DYNAMIC_API PEP_STATUS adapter_group_init();
  10. /*************************************************************************************************
  11. * Group management functions
  12. *************************************************************************************************/
  13. /**
  14. * <!-- adapter_group_create() -->
  15. *
  16. * @brief Create a group in the database with the input group_identity and manager and invite new members to the group
  17. * if this is an own group (for the external API, this is always the case).
  18. *
  19. * This function sets up the actual database structures for a group and invites new members to the group.
  20. *
  21. * For the external API, it is used when creating an own group. The group is represented by the
  22. * incoming group_identity, which contains the user_id and address for the group.
  23. * If no key is present for the former, it will be generated - if there is already
  24. * a default key for the group_identity in the database, that will be used instead.
  25. * The manager
  26. *
  27. * @param[in] session associated session object
  28. * @param[in,out] group_identity the pEp_identity object representing the group. Must contain at least
  29. * a user_id and address
  30. * @param[in,out] manager the pEp_identity object representing the group's manager. Must contain
  31. * a user_id and address, and there must be a default key for the manager
  32. * present in the database
  33. * @param[in,out] member_ident_list list of group member identities
  34. *
  35. * @retval PEP_STATUS_OK on success
  36. * error on failure
  37. *
  38. * @ownership All input values stay with the caller
  39. *
  40. * @warning starts a DB transaction - do not call from within a function which
  41. * is already in the middle of another one.
  42. *
  43. * @note in,out fields are labelled as such because they get updated by update_identity()/myself()
  44. * and have group flags added. group_identity may have its user_id freed and replaced
  45. * with the canonical own user id.
  46. *
  47. */
  48. DYNAMIC_API PEP_STATUS adapter_group_create(
  49. PEP_SESSION session,
  50. pEp_identity *group_identity,
  51. pEp_identity *manager,
  52. identity_list *memberlist);
  53. /**
  54. * <!-- adapter_group_dissolve() -->
  55. *
  56. * @brief Dissolve a group, revoke its key, notify all members of the dissolution and
  57. * revocation, and mark the group as inactive in the database
  58. *
  59. * @param[in] session associated session object
  60. * @param[in] group_identity the pEp_identity object representing the group. Must contain at least
  61. * a user_id and address
  62. * @param[in] manager the pEp_identity object representing the group's manager. Must contain
  63. * a user_id and address, and there must be a default key for the manager
  64. * present in the database
  65. *
  66. * @retval PEP_STATUS_OK on success
  67. * error on failure
  68. *
  69. * @ownership FIXME
  70. *
  71. * @warning For recipients to accept the dissolution, the sender/manager key used must be a key that they
  72. * have a trust entry for.
  73. */
  74. DYNAMIC_API PEP_STATUS adapter_group_dissolve(PEP_SESSION session, pEp_identity *group_identity, pEp_identity *manager);
  75. /**
  76. * <!-- adapter_group_invite_member() -->
  77. *
  78. * @brief Invite a member to an extant group, marking the member as invited in the database and
  79. * sending out an invitation to said member
  80. *
  81. * @param[in] session associated session object
  82. * @param[in] group_identity the pEp_identity object representing the group. Must contain at least
  83. * a user_id and address
  84. * @param[in] group_member the pEp_identity object representing the member to invite. Must contain
  85. * a user_id and address, and there must be a default key for the member
  86. * present in the database
  87. *
  88. * @retval PEP_STATUS_OK on success
  89. * error on failure
  90. *
  91. * @ownership FIXME
  92. *
  93. * @note This generates a GroupCreate message even though the group already exists - this is because
  94. * this is the accepted message format for invitations to potential members
  95. *
  96. */
  97. DYNAMIC_API PEP_STATUS adapter_group_invite_member(
  98. PEP_SESSION session,
  99. pEp_identity *group_identity,
  100. pEp_identity *group_member);
  101. /**
  102. * <!-- adapter_group_remove_member() -->
  103. *
  104. * @brief Remove a member from a group, deleting the member from the member list and executing a key
  105. * reset on the group identity
  106. *
  107. * @param[in] session associated session object
  108. * @param[in] group_identity the pEp_identity object representing the group. Must contain at least
  109. * a user_id and address
  110. * @param[in] group_member the pEp_identity object representing the member to remove. Must contain
  111. * a user_id and address
  112. *
  113. * @retval PEP_STATUS_OK on success
  114. * error on failure
  115. *
  116. * @ownership FIXME
  117. *
  118. * @todo Revamp implementation and execute key reset
  119. *
  120. */
  121. DYNAMIC_API PEP_STATUS adapter_group_remove_member(
  122. PEP_SESSION session,
  123. pEp_identity *group_identity,
  124. pEp_identity *group_member);
  125. /**
  126. * <!-- group_join() -->
  127. *
  128. * @brief Join a group for which we have received an invitation, marking
  129. * our own membership in the database for the group and sending the manager
  130. * a confirmation of the acceptance of the invitation
  131. *
  132. * @param[in] session associated session object
  133. * @param[in] group_identity the pEp_identity object representing the group. Must contain at least
  134. * a user_id and address
  135. * @param[in] as_member the pEp_identity object representing the own identity we want to use to
  136. * join the group. This must match the identity which was invited to the group.
  137. * Must contain a user_id and address.
  138. *
  139. * @retval PEP_STATUS_OK on success
  140. * error on failure
  141. *
  142. * @ownership FIXME
  143. *
  144. *
  145. */
  146. DYNAMIC_API PEP_STATUS adapter_group_join(
  147. PEP_SESSION session,
  148. pEp_identity *group_identity,
  149. pEp_identity *as_member
  150. );
  151. /*************************************************************************************************
  152. * Group query functions
  153. *************************************************************************************************/
  154. /**
  155. * <!-- adapter_group_query_groups() -->
  156. *
  157. * @brief queries the list manager which groups currently exist.
  158. *
  159. * @param[in] session associated session object
  160. * @param[out] groups list of pEp_identity representing
  161. * all group identities that currently exist.
  162. *
  163. * @retval PEP_STATUS_OK on success
  164. * error on failure
  165. *
  166. * @ownership ownership of all parameters goes to the caller
  167. *
  168. */
  169. DYNAMIC_API PEP_STATUS adapter_group_query_groups(PEP_SESSION session, identity_list **groups);
  170. /**
  171. * <!-- adapter_group_query_manager() -->
  172. *
  173. * @brief queries the list manager for the group manager of a given group.
  174. *
  175. * @param[in] session associated session object
  176. * @param[in] group pEp_Identity representing the group identity in question
  177. * @param[out] manager pEp_identity representing the group manager for "group"
  178. *
  179. * @retval PEP_STATUS_OK on success
  180. * error on failure
  181. *
  182. * @ownership ownership of all parameters goes to the caller
  183. *
  184. */
  185. DYNAMIC_API PEP_STATUS adapter_group_query_manager(PEP_SESSION session, const pEp_identity *const group, pEp_identity **manager);
  186. /**
  187. * <!-- adapter_group_query_members() -->
  188. *
  189. * @brief queries the list manager for all members of a given group.
  190. *
  191. * @param[in] session associated session object
  192. * @param[in] group pEp_Identity representing the group identity in question
  193. * @param[out] members list of pEp_identity representing all the members of "group"
  194. *
  195. * @retval PEP_STATUS_OK on success
  196. * error on failure
  197. *
  198. * @ownership ownership of all parameters goes to the caller
  199. *
  200. */
  201. DYNAMIC_API PEP_STATUS adapter_group_query_members(PEP_SESSION session, const pEp_identity *const group, identity_list **members);
  202. #ifdef __cplusplus
  203. };
  204. #endif
  205. #endif //LIBPEPADAPTER_GROUP_MANAGER_API_H