ARPA2 Common Libraries  2.6.2
Functions
Group Functions

Functions

void group_init (void)
 Initialise the ARPA2 Group system. More...
 
void group_fini (void)
 Finalise the ARPA2 Group system. More...
 
bool group_iterate (const a2act_t *sender, const char **filters, group_marks required_marks, group_marks forbidden_marks, const uint8_t *opt_svckey, unsigned svckeylen, const char *opt_rules, unsigned ruleslen, group_iterate_upcall upcall, void *updata)
 Process the Ruleset defined for a Group. More...
 
bool group_hasmember (const a2act_t *potential_member, const uint8_t *opt_svckey, unsigned svckeylen, const char *opt_rules, unsigned ruleslen, group_marks *out_marks)
 Determine the rights of a Group Member. More...
 
bool group_findmember (const a2id_t *remote_user, const a2id_t *group, const uint8_t *opt_svckey, unsigned svckeylen, const char *opt_rules, unsigned ruleslen, a2act_t *member, group_marks *out_marks)
 Lookup the Group Member address from their "remote" address. More...
 

Detailed Description

Groups defines functions to help working with them.

Function Documentation

◆ group_findmember()

bool group_findmember ( const a2id_t remote_user,
const a2id_t group,
const uint8_t *  opt_svckey,
unsigned  svckeylen,
const char *  opt_rules,
unsigned  ruleslen,
a2act_t member,
group_marks out_marks 
)

Lookup the Group Member address from their "remote" address.

Group members have an Actor Identity built from the group with added "+" and member name, which is the internal alias for users with a delivery address outside the group. This function iterates over the group details to lookup the Actor identity for the delivery address.

This is not the same as group_hasmember(), which starts from a known Actor Identity group.nosp@m.+mem.nosp@m.ber@d.nosp@m.omai.nosp@m.n.nam.nosp@m.e. It is not the same as Communication Access or Document Access, even when those produce the same Actor Identity, because these are set independently for these applications, and may rely on resources being assigned to the group.

This function finds the group member by group iteration, and not knowing beforehand what the member name will be. It also delivers group rights, rather than for another form of access.

Parameters
[in]remote_useris the (local or) remote user identity to locate as the external address for an internal group member.
[in]groupis the group where the remote_user is sought.
[in]opt_svckeymay be NULL or otherwise provides the group Service Key. NULL requests the default group Service Key, to be derived from the domain in local and without a Database Secret.
[in]svckeylenspecifies the lenght of opt_svckey but is only meaningful if that parameter is not NULL.
[in]opt_rulesmay be NULL to perform Iteration on the remote to search the database for an ACL Ruleset or, if this parameter is not NULL, it will be used instead.
[in]ruleslenspecifies the length of opt_rules but is only meaningful if that parameter is not NULL.
[out]memberwill be set to the Actor Identity when it is found, or otherwise it is kept empty and returns true from a2act_isempty().
[out]out_marksreturns the marks for the member. This is set to GROUP_VISITOR when the member was not found or when any error occurs, including not having found the group.
Returns
true on success, or false with a Common Error code in case of problems. Problems include the non-existence of the group, which is signaled as A2XS_ERR_MISSING_RULESET, but not the non-existence of the member.

◆ group_fini()

void group_fini ( void  )

Finalise the ARPA2 Group system.

This may do cleanup operations.

◆ group_hasmember()

bool group_hasmember ( const a2act_t potential_member,
const uint8_t *  opt_svckey,
unsigned  svckeylen,
const char *  opt_rules,
unsigned  ruleslen,
group_marks out_marks 
)

Determine the rights of a Group Member.

This call can be made to determine if an Actor Identity matches the ruleset for a group, and has a rule that defines its identity. For that specific identity, the marks are harvested and returned. When no marks are found, the GROUP_VISITOR marking is returned. When no ruleset is found, meaning that the group does not exist, the same marks are set but an error is returned with the Common Error code A2XS_ERR_MISSING_RULESET.

Parameters
[in]potential_memberthe Actor Identity, parsed with one alias level, that should be tested to be a Group Member.
[in]opt_svckeymay be NULL or otherwise provides the Service Key. NULL requests the default Service Key, to be derived from the domain in local and without a Database Secret.
[in]svckeylenspecifies the lenght of opt_svckey but is only meaningful if that parameter is not NULL.
[in]opt_rulesmay be NULL to perform Iteration on the remote to search the database for an ACL Ruleset or, if this parameter is not NULL, it will be used instead.
[in]ruleslenspecifies the length of opt_rules but is only meaningful if that parameter is not NULL.
[out]out_marksreturns the marks for the potential_member. This is set to GROUP_VISITOR when the member was not found or when any error occurs, including not having found the group.
Returns
true on success, or false with a Common Error code in case of problems. Problems include the non-existence of the group, which is signaled as A2XS_ERR_MISSING_RULESET, but not the non-existence of the member.

◆ group_init()

void group_init ( void  )

Initialise the ARPA2 Group system.

This has a mirror image for cleaup in group_fini().

◆ group_iterate()

bool group_iterate ( const a2act_t sender,
const char **  filters,
group_marks  required_marks,
group_marks  forbidden_marks,
const uint8_t *  opt_svckey,
unsigned  svckeylen,
const char *  opt_rules,
unsigned  ruleslen,
group_iterate_upcall  upcall,
void *  updata 
)

Process the Ruleset defined for a Group.

Iterate over a group and attempt delivery to each member's delivery address, including the sender's.

Parameters
[in]GroupMember Identity for the sender, as retrieved from access_comm(). The userid part is used as the group name and the single +alias is the member name for the sender on the list.
[in]recipientsmember addresses, consisting of the group name, zero or more members and possibly +-+ to switch to suppression of recipients. This is an array, to allow one iteration to match multiple recipients member addresses. When multiple match, there will still be only one delivery suggested.
[in]filterspoints to a NULL-terminated array of strings that each represent an alternative filter that might pass members during iteration. The filter strings each contain a sequence "+mid" strings, with "+-+" to toggle from accepting to rejection (or back) within a filter string. The filter string ends at a NUL or "@" character. When no "+mid" occurs in a filter string it will pass all members marked with GROUP_RECV. Though it is possible to insert a group name without "+" before the first "+mid", this may end up as a bug when group names contain a "+" as is formally permitted – so don't do that.
[in]required_marksare marks that cause a member to be skipped when they miss any of these marks.
[in]forbidden_marksare marks that cause a member to be skipped when marked with either of these.
[in]upcallis the callback function that is invoked for each member, presenting the member alias and its delivery address, along with the markings for the entry.
[in]updatais the data supplied as accumulator to the upcall callback function.
[in]opt_svckeymay be NULL or otherwise provides the Service Key. NULL requests the default Service Key, to be derived from the domain in local and without a Database Secret.
[in]svckeylenspecifies the lenght of opt_svckey but is only meaningful if that parameter is not NULL.
[in]opt_rulesmay be NULL to perform Iteration on the remote to search the database for an ACL Ruleset or, if this parameter is not NULL, it will be used instead.
[in]ruleslenspecifies the length of opt_rules but is only meaningful if that parameter is not NULL.
Returns
This function returns true on success, which implies that some ruleset was found, even when the marks or other selective criteria did not cause a callback. Failures are of a technical nature, and return false while setting errno to a com_err code. This includes having found no group members, in which case errno is set to A2XS_ERR_MISSING_RULESET.