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_user	is the (local or) remote user identity to locate as the external address for an internal group member.
[in]	group	is the group where the remote_user is sought.
[in]	opt_svckey	may 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]	svckeylen	specifies the lenght of opt_svckey but is only meaningful if that parameter is not NULL.
[in]	opt_rules	may 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]	ruleslen	specifies the length of opt_rules but is only meaningful if that parameter is not NULL.
[out]	member	will be set to the Actor Identity when it is found, or otherwise it is kept empty and returns true from a2act_isempty().
[out]	out_marks	returns 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_member	the Actor Identity, parsed with one alias level, that should be tested to be a Group Member.
[in]	opt_svckey	may 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]	svckeylen	specifies the lenght of opt_svckey but is only meaningful if that parameter is not NULL.
[in]	opt_rules	may 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]	ruleslen	specifies the length of opt_rules but is only meaningful if that parameter is not NULL.
[out]	out_marks	returns 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]	Group	Member 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]	recipients	member 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]	filters	points 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_marks	are marks that cause a member to be skipped when they miss any of these marks.
[in]	forbidden_marks	are marks that cause a member to be skipped when marked with either of these.
[in]	upcall	is 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]	updata	is the data supplied as accumulator to the upcall callback function.
[in]	opt_svckey	may 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]	svckeylen	specifies the lenght of opt_svckey but is only meaningful if that parameter is not NULL.
[in]	opt_rules	may 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]	ruleslen	specifies 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.