p≡p engine
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.

377 lines
15 KiB

  1. #ifndef GROUP_H
  2. #define GROUP_H
  3. // This file is under GNU General Public License 3.0
  4. // see LICENSE.txt
  5. #include "platform.h"
  6. #include "dynamic_api.h"
  7. #include "message_api.h"
  8. #ifdef __cplusplus
  9. extern "C" {
  10. #endif
  11. /***
  12. * TODO: Note in EACH call that update_identity/myself must be called before entry into the functions
  13. */
  14. /*************************************************************************************************
  15. * In-memory objects and functions for representation of groups
  16. *************************************************************************************************/
  17. /**
  18. * @struct pEp_member
  19. * @brief memory object for holding information about an invited group member
  20. * and whether they have joined the group
  21. * (groups are persistent and are stored in the management database)
  22. */
  23. typedef struct _pEp_member {
  24. pEp_identity *ident; //!< member identity
  25. bool joined; //!< boolean for whether the member has accepted the invite
  26. } pEp_member;
  27. /**
  28. * <!-- new_member() -->
  29. *
  30. * @brief allocate pEp_member struct. This struct only allocates the member object for
  31. * group representation.
  32. *
  33. * @param[in] ident the pEp_identity object representing the member
  34. *
  35. * @retval pEp_member allocated member struct on success
  36. * NULL if ident is not present or other failure occurs
  37. *
  38. * @ownership ownership of all parameters goes to the struct
  39. *
  40. * @warning This is only an in-memory object allocator and performs NONE of the
  41. * database or key management functions for groups or members!
  42. *
  43. */
  44. DYNAMIC_API pEp_member *new_member(pEp_identity *ident);
  45. /**
  46. * <!-- free_member() -->
  47. *
  48. * @brief deallocate pEp_member struct and the identity it points to.
  49. *
  50. * @param[in] member member object to be freed
  51. *
  52. * @ownership ALL objects pointed to by the struct will be freed!
  53. *
  54. * @warning This is only an in-memory object deallocator and performs NONE of the
  55. * database or key management functions for group members!
  56. *
  57. */
  58. DYNAMIC_API void free_member(pEp_member *member);
  59. /**
  60. * @struct member_list
  61. * @brief list structure for pEp_member objects
  62. * @see pEp_member
  63. */
  64. typedef struct _member_list {
  65. pEp_member *member; //!< member object containing the identity and joined status for this list node
  66. struct _member_list *next; //!< pointer to next node in list
  67. } member_list;
  68. /**
  69. * <!-- new_memberlist() -->
  70. *
  71. * @brief allocate member_list node struct. This struct only allocates the member_list object for
  72. * group representation.
  73. *
  74. * @param[in] member the member to be associated with this member_list node
  75. *
  76. * @retval member_list allocated member_list struct on success
  77. * NULL if failure occurs (typically: out of memory)
  78. *
  79. * @ownership ownership of all parameters goes to the struct
  80. *
  81. * @warning This is only an in-memory object allocator and performs NONE of the
  82. * database or key management functions for groups or members!
  83. *
  84. */
  85. DYNAMIC_API member_list *new_memberlist(pEp_member *member);
  86. /**
  87. * <!-- free_memberlist() -->
  88. *
  89. * @brief deallocate the node pointed to by the list argument and all nodes following it in the list
  90. * and their associated objects
  91. *
  92. * @param[in] list memberlist object to be freed
  93. *
  94. * @ownership ALL objects pointed to by the struct will be freed!
  95. *
  96. * @warning This is only an in-memory object deallocator and performs NONE of the
  97. * database or key management functions for group members!
  98. *
  99. */
  100. DYNAMIC_API void free_memberlist(member_list *list);
  101. /**
  102. * <!-- memberlist_add() -->
  103. *
  104. * @brief add memberlist node containing this member to the end of the list
  105. * pointed to by the list argument and return a pointer to the tail of the list
  106. *
  107. * @param[in,out] list node pointing to the list to add to (if this is NULL,
  108. * a new list will be created and returned)
  109. * @param[in] member member to add to the list
  110. *
  111. * @retval member_list tail of list on success (or pointer to new list if input list was NULL)
  112. * NULL if failure occurs (typically: out of memory)
  113. *
  114. * @ownership ownership of all parameters goes to the callee
  115. *
  116. * @warning This is only an in-memory object allocator and performs NONE of the
  117. * database or key management functions for groups or members!
  118. *
  119. */
  120. DYNAMIC_API member_list *memberlist_add(member_list *list, pEp_member *member);
  121. /**
  122. * @struct pEp group
  123. * @brief memory object for holding all information about a group
  124. * (groups are persistent and are stored in the management database)
  125. */
  126. typedef struct _pEp_group {
  127. pEp_identity *group_identity; //!< identity representing this group
  128. pEp_identity *manager; //!< identity of the group manager
  129. member_list *members; //!< list of members associated with group
  130. bool active; //!< boolean true if group is marked as active, else false
  131. } pEp_group;
  132. /**
  133. * <!-- new_group() -->
  134. *
  135. * @brief allocate pEp_group struct. This function does not create
  136. * a group in the database, it only allocates the object for
  137. * group representation.
  138. *
  139. * @param[in] group_identity the pEp_identity object representing the group
  140. * @param[in] manager the pEp_identity object representing the group's manager
  141. * @param[in] memberlist optional list of group members
  142. *
  143. * @retval group allocated group struct on success
  144. * NULL if group_identity is not present or other failure occurs
  145. *
  146. * @ownership ownership of all parameters goes to the struct
  147. *
  148. * @warning This is only an in-memory object allocator and performs NONE of the
  149. * database or key management functions for groups!
  150. *
  151. */
  152. DYNAMIC_API pEp_group *new_group(
  153. pEp_identity *group_identity,
  154. pEp_identity *manager,
  155. member_list *memberlist
  156. );
  157. /**
  158. * <!-- free_group() -->
  159. *
  160. * @brief deallocate pEp_group struct and all objects it points to.
  161. * This function does not dissolve groups, only deallocates the memory object
  162. * representing a group.
  163. *
  164. * @param[in] group group object to be freed
  165. *
  166. * @ownership ALL objects pointed to by the struct will be freed!
  167. *
  168. * @warning This is only an in-memory object deallocator and performs NONE of the
  169. * database or key management functions for groups!
  170. *
  171. */
  172. DYNAMIC_API void free_group(pEp_group *group);
  173. /*************************************************************************************************
  174. * Group management functions
  175. *************************************************************************************************/
  176. /**
  177. * <!-- group_create() -->
  178. *
  179. * @brief Create a group in the database with the input group_identity and manager and invite new members to the group
  180. * if this is an own group (for the external API, this is always the case).
  181. *
  182. * This function sets up the actual database structures for a group and invites new members to the group.
  183. *
  184. * For the external API, it is used when creating an own group. The group is represented by the
  185. * incoming group_identity, which contains the user_id and address for the group.
  186. * If no key is present for the former, it will be generated - if there is already
  187. * a default key for the group_identity in the database, that will be used instead.
  188. * The manager
  189. *
  190. * @param[in] session associated session object
  191. * @param[in,out] group_identity the pEp_identity object representing the group. Must contain at least
  192. * a user_id and address
  193. * @param[in,out] manager the pEp_identity object representing the group's manager. Must contain
  194. * a user_id and address, and there must be a default key for the manager
  195. * present in the database
  196. * @param[in,out] member_ident_list list of group member identities
  197. * @param[in,out] group Optional reference for pointer to group object
  198. * representing the created group.
  199. * (When input is NULL, no object is created)
  200. *
  201. * @retval PEP_STATUS_OK on success
  202. * error on failure
  203. *
  204. * @ownership All input values stay with the caller
  205. *
  206. * @warning starts a DB transaction - do not call from within a function which
  207. * is already in the middle of another one.
  208. *
  209. * @note in,out fields are labelled as such because they get updated by update_identity()/myself()
  210. * and have group flags added. group_identity may have its user_id freed and replaced
  211. * with the canonical own user id.
  212. *
  213. */
  214. DYNAMIC_API PEP_STATUS group_create(
  215. PEP_SESSION session,
  216. pEp_identity *group_identity,
  217. pEp_identity *manager,
  218. identity_list *memberlist,
  219. pEp_group **group
  220. );
  221. /**
  222. * <!-- group_join() -->
  223. *
  224. * @brief Join a group for which we have received an invitation, marking
  225. * our own membership in the database for the group and sending the manager
  226. * a confirmation of the acceptance of the invitation
  227. *
  228. * @param[in] session associated session object
  229. * @param[in] group_identity the pEp_identity object representing the group. Must contain at least
  230. * a user_id and address
  231. * @param[in] as_member the pEp_identity object representing the own identity we want to use to
  232. * join the group. This must match the identity which was invited to the group.
  233. * Must contain a user_id and address.
  234. *
  235. * @retval PEP_STATUS_OK on success
  236. * error on failure
  237. *
  238. * @ownership FIXME
  239. *
  240. *
  241. */
  242. DYNAMIC_API PEP_STATUS group_join(
  243. PEP_SESSION session,
  244. pEp_identity *group_identity,
  245. pEp_identity *as_member
  246. );
  247. /**
  248. * <!-- group_dissolve() -->
  249. *
  250. * @brief Dissolve a group, revoke its key, notify all members of the dissolution and
  251. * revocation, and mark the group as inactive in the database
  252. *
  253. * @param[in] session associated session object
  254. * @param[in] group_identity the pEp_identity object representing the group. Must contain at least
  255. * a user_id and address
  256. * @param[in] manager the pEp_identity object representing the group's manager. Must contain
  257. * a user_id and address, and there must be a default key for the manager
  258. * present in the database
  259. *
  260. * @retval PEP_STATUS_OK on success
  261. * error on failure
  262. *
  263. * @ownership FIXME
  264. *
  265. * @warning For recipients to accept the dissolution, the sender/manager key used must be a key that they
  266. * have a trust entry for.
  267. */
  268. DYNAMIC_API PEP_STATUS group_dissolve(
  269. PEP_SESSION session,
  270. pEp_identity *group_identity,
  271. pEp_identity *manager
  272. );
  273. /**
  274. * <!-- group_invite_member() -->
  275. *
  276. * @brief Invite a member to an extant group, marking the member as invited in the database and
  277. * sending out an invitation to said member
  278. *
  279. * @param[in] session associated session object
  280. * @param[in] group_identity the pEp_identity object representing the group. Must contain at least
  281. * a user_id and address
  282. * @param[in] group_member the pEp_identity object representing the member to invite. Must contain
  283. * a user_id and address, and there must be a default key for the member
  284. * present in the database
  285. *
  286. * @retval PEP_STATUS_OK on success
  287. * error on failure
  288. *
  289. * @ownership FIXME
  290. *
  291. * @note This generates a GroupInvite message even though the group already exists - this is because
  292. * this is the accepted message format for invitations to potential members
  293. *
  294. */
  295. DYNAMIC_API PEP_STATUS group_invite_member(
  296. PEP_SESSION session,
  297. pEp_identity *group_identity,
  298. pEp_identity *group_member
  299. );
  300. /**
  301. * <!-- group_remove_member() -->
  302. *
  303. * @brief Remove a member from a group, deleting the member from the member list and executing a key
  304. * reset on the group identity
  305. *
  306. * @param[in] session associated session object
  307. * @param[in] group_identity the pEp_identity object representing the group. Must contain at least
  308. * a user_id and address
  309. * @param[in] group_member the pEp_identity object representing the member to remove. Must contain
  310. * a user_id and address
  311. *
  312. * @retval PEP_STATUS_OK on success
  313. * error on failure
  314. *
  315. * @ownership FIXME
  316. *
  317. * @todo Revamp implementation and execute key reset
  318. *
  319. */
  320. DYNAMIC_API PEP_STATUS group_remove_member(
  321. PEP_SESSION session,
  322. pEp_identity *group_identity,
  323. pEp_identity *group_member
  324. );
  325. /**
  326. * <!-- group_rating() -->
  327. *
  328. * @brief Get the rating for this group - if the caller is the manager, this will return the aggregate rating
  329. * of group members. For members, this will return the rating of the group_identity
  330. *
  331. * @param[in] session associated session object
  332. * @param[in] group_identity the pEp_identity object representing the group. Must contain at least
  333. * a user_id and address
  334. * @param[in] manager the pEp_identity object representing the member to remove. Must contain
  335. * a user_id and address
  336. * @param[out] rating the group rating
  337. *
  338. * @retval PEP_STATUS_OK on success
  339. * error on failure
  340. *
  341. * @ownership FIXME
  342. *
  343. */
  344. DYNAMIC_API PEP_STATUS group_rating(
  345. PEP_SESSION session,
  346. pEp_identity *group_identity,
  347. pEp_identity *manager,
  348. PEP_rating *rating
  349. );
  350. #ifdef __cplusplus
  351. }
  352. #endif
  353. #endif