ARPA2 Common Libraries  2.3.1
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...
 

Detailed Description

Groups defines functions to help working with them.

Function Documentation

◆ 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.