LIB-11: Update adapter_group.h from engine group.h

src/adapter_group.cc

@@ -12,58 +12,48 @@ extern "C" {
 *************************************************************************************************/
 
 DYNAMIC_API PEP_STATUS adapter_group_create(
-        PEP_SESSION session,
-        pEp_identity *group_identity,
-        pEp_identity *manager,
-        member_list *memberlist,
-        pEp_group **group
-)
+    PEP_SESSION session,
+    pEp_identity *group_identity,
+    pEp_identity *manager,
+    identity_list *memberlist,
+    pEp_group **group)
 {
     return ::group_create(session, group_identity, manager, memberlist, group);
 }
 
-DYNAMIC_API PEP_STATUS adapter_group_join(
-        PEP_SESSION session,
-        pEp_identity *group_identity,
-        pEp_identity *as_member
-)
+DYNAMIC_API PEP_STATUS
+adapter_group_join(PEP_SESSION session, pEp_identity *group_identity, pEp_identity *as_member)
 {
     return ::group_join(session, group_identity, as_member);
 }
 
-DYNAMIC_API PEP_STATUS adapter_group_dissolve(
-        PEP_SESSION session,
-        pEp_identity *group_identity,
-        pEp_identity *manager
-)
+DYNAMIC_API PEP_STATUS
+adapter_group_dissolve(PEP_SESSION session, pEp_identity *group_identity, pEp_identity *manager)
 {
     return ::group_dissolve(session, group_identity, manager);
 }
 
 DYNAMIC_API PEP_STATUS adapter_group_invite_member(
-        PEP_SESSION session,
-        pEp_identity *group_identity,
-        pEp_identity *group_member
-)
+    PEP_SESSION session,
+    pEp_identity *group_identity,
+    pEp_identity *group_member)
 {
     return ::group_invite_member(session, group_identity, group_member);
 }
 
 PEP_STATUS adapter_group_remove_member(
-        PEP_SESSION session,
-        pEp_identity *group_identity,
-        pEp_identity *group_member
-)
+    PEP_SESSION session,
+    pEp_identity *group_identity,
+    pEp_identity *group_member)
 {
     return ::group_remove_member(session, group_identity, group_member);
 }
 
 DYNAMIC_API PEP_STATUS adapter_group_rating(
-        PEP_SESSION session,
-        pEp_identity *group_identity,
-        pEp_identity *manager,
-        PEP_rating *rating
-)
+    PEP_SESSION session,
+    pEp_identity *group_identity,
+    pEp_identity *manager,
+    PEP_rating *rating)
 {
     return ::group_rating(session, group_identity, manager, rating);
 }
@@ -73,28 +63,19 @@ DYNAMIC_API PEP_STATUS adapter_group_rating(
  *************************************************************************************************/
 
 
-DYNAMIC_API PEP_STATUS group_query_groups(
-        PEP_SESSION session,
-        identity_list **groups
-)
+DYNAMIC_API PEP_STATUS group_query_groups(PEP_SESSION session, identity_list **groups)
 {
     return PEP_STATUS_OK;
 }
 
-DYNAMIC_API PEP_STATUS group_query_manager(
-        PEP_SESSION session,
-        const pEp_identity *const group,
-        pEp_identity **manager
-)
+DYNAMIC_API PEP_STATUS
+group_query_manager(PEP_SESSION session, const pEp_identity *const group, pEp_identity **manager)
 {
     return PEP_STATUS_OK;
 }
 
-DYNAMIC_API PEP_STATUS group_query_members(
-        PEP_SESSION session,
-        const pEp_identity *const group,
-        identity_list **members
-)
+DYNAMIC_API PEP_STATUS
+group_query_members(PEP_SESSION session, const pEp_identity *const group, identity_list **members)
 {
     return PEP_STATUS_OK;
 }
@@ -102,4 +83,3 @@ DYNAMIC_API PEP_STATUS group_query_members(
 #ifdef __cplusplus
 }
 #endif
-

src/adapter_group.h

@@ -31,12 +31,12 @@ extern "C" {
  *              The manager
  *
  *  @param[in]      session             associated session object
- *  @param[in]      group_identity      the pEp_identity object representing the group. Must contain at least
+ *  @param[in,out]  group_identity      the pEp_identity object representing the group. Must contain at least
  *                                      a user_id and address
- *  @param[in]      manager             the pEp_identity object representing the group's manager. Must contain
+ *  @param[in,out]  manager             the pEp_identity object representing the group's manager. Must contain
  *                                      a user_id and address, and there must be a default key for the manager
  *                                      present in the database
- *  @param[in]      memberlist          list of group members
+ *  @param[in,out]  member_ident_list   list of group member identities
  *  @param[in,out]  group               Optional reference for pointer to group object
  *                                      representing the created group.
  *                                      (When input is NULL, no object is created)
@@ -44,19 +44,25 @@ extern "C" {
  *  @retval         PEP_STATUS_OK       on success
  *                  error               on failure
  *
- *  @ownership      FIXME
+ *  @ownership      All input values stay with the caller
+ *
+ *  @warning        starts a DB transaction - do not call from within a function which
+ *                  is already in the middle of another one.
  *
- *  TODO: member_list *memberlist -> change to identity_list
+ *  @note           in,out fields are labelled as such because they get updated by update_identity()/myself()
+ *                  and have group flags added. group_identity may have its user_id freed and replaced
+ *                  with the canonical own user id.
  *
  */
 DYNAMIC_API PEP_STATUS adapter_group_create(
-        PEP_SESSION session,
-        pEp_identity *group_identity,
-        pEp_identity *manager,
-        member_list *memberlist,
-        pEp_group **group
+    PEP_SESSION session,
+    pEp_identity *group_identity,
+    pEp_identity *manager,
+    identity_list *memberlist,
+    pEp_group **group
 );
 
+
 /**
  *  <!--       adapter_group_join()       -->
  *