![]() |
![]() |
![]() |
libinfinity-0.6 Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy |
#include <libinfinity/common/inf-acl.h> typedef InfAclAccountId; struct InfAclAccount; enum InfAclSetting; struct InfAclMask; struct InfAclSheet; struct InfAclSheetSet; InfAclAccountId inf_acl_account_id_from_string (const gchar *id
); const gchar * inf_acl_account_id_to_string (InfAclAccountId account
); #define INF_ACL_ACCOUNT_ID_TO_POINTER (id) #define INF_ACL_ACCOUNT_POINTER_TO_ID (ptr) InfAclAccount * inf_acl_account_new (InfAclAccountId id
,const gchar *name
); InfAclAccount * inf_acl_account_copy (const InfAclAccount *account
); void inf_acl_account_free (InfAclAccount *account
); void inf_acl_account_array_free (InfAclAccount *accounts
,guint n_accounts
); InfAclAccount * inf_acl_account_from_xml (xmlNodePtr xml
,GError **error
); void inf_acl_account_to_xml (const InfAclAccount *account
,xmlNodePtr xml
); InfAclMask * inf_acl_mask_copy (const InfAclMask *mask
); void inf_acl_mask_free (InfAclMask *mask
); void inf_acl_mask_clear (InfAclMask *mask
); gboolean inf_acl_mask_empty (const InfAclMask *mask
); gboolean inf_acl_mask_equal (const InfAclMask *lhs
,const InfAclMask *rhs
); InfAclMask * inf_acl_mask_set1 (InfAclMask *mask
,const InfAclSetting setting
); InfAclMask * inf_acl_mask_setv (InfAclMask *mask
,const InfAclSetting *settings
,guint n_settings
); InfAclMask * inf_acl_mask_and (const InfAclMask *lhs
,const InfAclMask *rhs
,InfAclMask *out
); InfAclMask * inf_acl_mask_and1 (InfAclMask *mask
,InfAclSetting setting
); InfAclMask * inf_acl_mask_or (const InfAclMask *lhs
,const InfAclMask *rhs
,InfAclMask *out
); InfAclMask * inf_acl_mask_or1 (InfAclMask *mask
,InfAclSetting setting
); InfAclMask * inf_acl_mask_neg (const InfAclMask *mask
,InfAclMask *out
); gboolean inf_acl_mask_has (const InfAclMask *mask
,InfAclSetting setting
); extern const InfAclMask INF_ACL_MASK_ALL; extern const InfAclMask INF_ACL_MASK_DEFAULT; extern const InfAclMask INF_ACL_MASK_LEAF; extern const InfAclMask INF_ACL_MASK_ROOT; extern const InfAclMask INF_ACL_MASK_SUBDIRECTORY; InfAclSheet * inf_acl_sheet_new (InfAclAccountId account
); InfAclSheet * inf_acl_sheet_copy (const InfAclSheet *sheet
); void inf_acl_sheet_free (InfAclSheet *sheet
); gboolean inf_acl_sheet_perms_from_xml (xmlNodePtr xml
,InfAclMask *mask
,InfAclMask *perms
,GError **error
); void inf_acl_sheet_perms_to_xml (const InfAclMask *mask
,const InfAclMask *perms
,xmlNodePtr xml
); InfAclSheetSet * inf_acl_sheet_set_new (void
); InfAclSheetSet * inf_acl_sheet_set_new_external (const InfAclSheet *sheets
,guint n_sheets
); InfAclSheetSet * inf_acl_sheet_set_copy (const InfAclSheetSet *sheet_set
); void inf_acl_sheet_set_free (InfAclSheetSet *sheet_set
); void inf_acl_sheet_set_sink (InfAclSheetSet *sheet_set
); InfAclSheet * inf_acl_sheet_set_add_sheet (InfAclSheetSet *sheet_set
,InfAclAccountId account
); void inf_acl_sheet_set_remove_sheet (InfAclSheetSet *sheet_set
,InfAclSheet *sheet
); InfAclSheetSet * inf_acl_sheet_set_merge_sheets (InfAclSheetSet *sheet_set
,const InfAclSheetSet *other
); InfAclSheetSet * inf_acl_sheet_set_get_clear_sheets (const InfAclSheetSet *sheet_set
); InfAclSheet * inf_acl_sheet_set_find_sheet (InfAclSheetSet *sheet_set
,InfAclAccountId account
); const InfAclSheet * inf_acl_sheet_set_find_const_sheet (const InfAclSheetSet *sheet_set
,InfAclAccountId account
); InfAclSheetSet * inf_acl_sheet_set_from_xml (xmlNodePtr xml
,GError **error
); void inf_acl_sheet_set_to_xml (const InfAclSheetSet *sheet_set
,xmlNodePtr xml
);
GBoxed +----InfAclAccount
GEnum +----InfAclSetting
GBoxed +----InfAclMask
GBoxed +----InfAclSheet
GBoxed +----InfAclSheetSet
The basic ACL data structure is InfAclSheet, which represents settings for one user and one node in the infinote directory. One setting can have three states: it can be enabled, it can be disabled or it can be set to default which means to take the setting from the the default account or the parent directory. The default user for the root node must not have any setting set to default.
The various settings are represented by the InfAclSetting enumeration. This specifies different operations for which access can be granted or denied to different users. InfAclMask represents a bitfield of all A InfAclSheetSet represents a set of InfAclSheets, for different users. There is one InfAclSheetSet for each node of a infinote directory.
Usually, for application programming, the functions in this class need not be used. All relevant functionality is exposed by the InfBrowser interface.
typedef GQuark InfAclAccountId;
This type represents a unique identifier for a user account.
struct InfAclAccount { InfAclAccountId id; gchar* name; };
This boxed type specifies basic user account information.
InfAclAccountId |
A unique ID for this account. |
gchar * |
A human readable account name. |
typedef enum { INF_ACL_CAN_ADD_SUBDIRECTORY, INF_ACL_CAN_ADD_DOCUMENT, INF_ACL_CAN_SYNC_IN, INF_ACL_CAN_REMOVE_NODE, INF_ACL_CAN_EXPLORE_NODE, INF_ACL_CAN_SUBSCRIBE_CHAT, INF_ACL_CAN_SUBSCRIBE_SESSION, INF_ACL_CAN_JOIN_USER, INF_ACL_CAN_QUERY_ACCOUNT_LIST, INF_ACL_CAN_CREATE_ACCOUNT, INF_ACL_CAN_OVERRIDE_ACCOUNT, INF_ACL_CAN_REMOVE_ACCOUNT, INF_ACL_CAN_QUERY_ACL, INF_ACL_CAN_SET_ACL, } InfAclSetting;
Defines the actual permissions that can be granted or revoked for different users.
The user is allowed to create a new subdirectory node. | |
The user is allowed to create a new leaf node. | |
The user is allowed to create documents with non-empty content. | |
The user is allowed to remove a child node. | |
The user is allowed to explore a subdirectory node in the directory tree. | |
The user can subscribe to the global server-wide chat. | |
The user is allowed to subscribe to a session in the directory tree. | |
The user is allowed to join a user into the session which corresponds to the node. | |
The user is allowed to query the full list of ACL accounts. | |
The user can create a new account on the server. | |
The user can create an account under a name that exists already, overriding the login credentials. | |
The user can remove user accounts. | |
The user is allowed to query the full ACL for this node. | |
The user is allowed to change the ACL of this node, or create new nodes with a non-default ACL. |
struct InfAclMask { /* leave quite some space for future use */ guint64 mask[4]; };
This structure represents a mask of InfAclSettings, where each setting can be either turned on or off.
guint64 |
A 256 bit wide bitfield of InfAclSettings. |
struct InfAclSheet { InfAclAccountId account; InfAclMask mask; InfAclMask perms; };
A set of permissions to be applied for a particular account and a particular node in the infinote directory.
InfAclAccountId |
The account for which to apply the permissions in this sheet. |
InfAclMask |
Mask which specifies which of the permissions in the perms
field take effect. Fields which are masked-out are left at their default
value and inherited from the parent node. |
InfAclMask |
Mask which specifies whether or not the user is allowed to perform the various operations defined by InfAclSetting. |
struct InfAclSheetSet { const InfAclSheet* sheets; guint n_sheets; };
A set of InfAclSheets, one for each user.
const InfAclSheet * |
An array of InfAclSheet objects. |
guint |
The number of elements in the sheets array. |
InfAclAccountId inf_acl_account_id_from_string (const gchar *id
);
Converts the given string into a unique account identifier which can be used with the rest of the ACL API.
|
A string representation of an account ID. |
Returns : |
The account ID which is equivalent to the given string. |
const gchar * inf_acl_account_id_to_string (InfAclAccountId account
);
Translates the given account ID to a unique string identifier.
|
A InfAclAccountId. |
Returns : |
A string representation of the given account ID, or NULL if
the account does not exist. The return value must not be freed. |
#define INF_ACL_ACCOUNT_ID_TO_POINTER(id)
Converts a InfAclAccountId to a pointer such that the pointer represents a unique representation of the given ID. The pointer should not be used for anything else except comparisons with other pointer obtained in this way, for example in hash table lookups.
|
A InfAclAccountId. |
#define INF_ACL_ACCOUNT_POINTER_TO_ID(ptr)
Converts a pointer obtained with INF_ACL_ACCOUNT_ID_TO_POINTER
back into
the original InfAclAccountId value.
|
A pointer obtained with INF_ACL_ACCOUNT_ID_TO_POINTER . |
InfAclAccount * inf_acl_account_new (InfAclAccountId id
,const gchar *name
);
Creates a new InfAclAccount.
|
The unique ID of the new account. |
|
The human-readable name of the new account. |
Returns : |
A new InfAclAccount object. |
InfAclAccount * inf_acl_account_copy (const InfAclAccount *account
);
Creates a copy of account
.
|
The InfAclAccount to copy. |
Returns : |
A new InfAclAccount. Free with inf_acl_account_free() when no longer
needed. |
void inf_acl_account_free (InfAclAccount *account
);
Releases all resources allocated by account
.
|
A InfAclAccount. |
void inf_acl_account_array_free (InfAclAccount *accounts
,guint n_accounts
);
Releases all resources allocated by an array of InfAclAccounts.
|
An array of InfAclAccount objects. |
|
The number of elements in the array. |
InfAclAccount * inf_acl_account_from_xml (xmlNodePtr xml
,GError **error
);
Attempts to deserialize an InfAclAccount that was written to an XML node
by the function inf_acl_account_to_xml()
. If an error occurs, such as
mandatory fields being missing, the function returns NULL
and error
is
set.
|
An XML node. |
|
Location to store error information, if any. |
Returns : |
A new InfAclAccount on success, or NULL on failure. Free with
inf_acl_account_free() when no longer needed. |
void inf_acl_account_to_xml (const InfAclAccount *account
,xmlNodePtr xml
);
Serializes the properties of account
into the XML node xml
. The function
inf_acl_account_from_xml()
does the reverse operation and deserializes the
account object from the XML.
|
A InfAclAccount. |
|
The XML node to write the account attributes to. |
InfAclMask * inf_acl_mask_copy (const InfAclMask *mask
);
Creates a dynamically allocated copy of mask
. This function should not
usually be used since masks can simply created on the stack and copied
by value. This function is mainly meant for the boxed type definition and
for language bindings.
|
The InfAclMask to copy. |
Returns : |
A new InfAclMask. Free with inf_acl_mask_free() when no longer
needed. |
void inf_acl_mask_free (InfAclMask *mask
);
Releases a InfAclMask that was created with inf_acl_mask_copy()
.
|
The InfAclMask to free. |
void inf_acl_mask_clear (InfAclMask *mask
);
Resets a mask so that all fields are zero.
|
The InfAclMask to reset. |
gboolean inf_acl_mask_empty (const InfAclMask *mask
);
Checks whether the given mask is empty, i.e. all fields are set to zero.
|
A InfAclMask. |
Returns : |
TRUE if mask has all fields zero, or FALSE otherwies. |
gboolean inf_acl_mask_equal (const InfAclMask *lhs
,const InfAclMask *rhs
);
Checks whether the two masks are equal.
InfAclMask * inf_acl_mask_set1 (InfAclMask *mask
,const InfAclSetting setting
);
Initializes mask
such that all permissions are off except the one
corresponding to setting
.
|
The InfAclMask to initialize. |
|
The permission to set. |
Returns : |
The mask itself. |
InfAclMask * inf_acl_mask_setv (InfAclMask *mask
,const InfAclSetting *settings
,guint n_settings
);
Initializes mask
such that all permissions are off except the ones
specified in the settings
array.
|
The InfAclMask to initialize. |
|
An array of InfAclSettings to set. |
|
The number of settings. |
Returns : |
The mask itself. |
InfAclMask * inf_acl_mask_and (const InfAclMask *lhs
,const InfAclMask *rhs
,InfAclMask *out
);
Computes the bitwise AND of lhs
and rhs
and writes the result to out
.
out
is allowed to be equivalent to lhs
and/or rhs
.
|
First mask. |
|
Second mask. |
|
Output mask. |
Returns : |
The output mask. |
InfAclMask * inf_acl_mask_and1 (InfAclMask *mask
,InfAclSetting setting
);
Disables the bit corresponding to setting in mask
, leaving all other bits
alone.
|
A InfAclMask. |
|
The setting to unset. |
Returns : |
The mask itself. |
InfAclMask * inf_acl_mask_or (const InfAclMask *lhs
,const InfAclMask *rhs
,InfAclMask *out
);
Computes the bitwise OR of lhs
and rhs
and writes the result to out
.
out
is allowed to be equivalent to lhs
and/or rhs
.
|
First mask. |
|
Second mask. |
|
Output mask. |
Returns : |
The output mask. |
InfAclMask * inf_acl_mask_or1 (InfAclMask *mask
,InfAclSetting setting
);
Enables the bit corresponding to setting in mask
, leaving all other bits
alone.
|
A InfAclMask. |
|
The setting to add. |
Returns : |
The mask itself. |
InfAclMask * inf_acl_mask_neg (const InfAclMask *mask
,InfAclMask *out
);
Negates the given mask bitwise and writes the result to out
. The output
mask is allowed to be equivalent to mask
itself.
|
The mask to negate. |
|
The output mask. |
Returns : |
The output mask. |
gboolean inf_acl_mask_has (const InfAclMask *mask
,InfAclSetting setting
);
Returns TRUE
if the given mask has the bit which corresponds to setting
set, or FALSE
otherwise.
|
A InfAclMask. |
|
The setting to check. |
Returns : |
TRUE if the bit corresponding to setting is set in mask . |
extern const InfAclMask INF_ACL_MASK_SUBDIRECTORY; /* only applicable for subdirectory node */
InfAclSheet * inf_acl_sheet_new (InfAclAccountId account
);
Creates a dynamically allocated InfAclSheet. This is usually not needed because you can copy the structs by value, but it is useful for properties and bindings. The new sheet will hold permissions for the given account. The permissions will initially be all masked out.
|
The InfAclAccountId representing a unique account id. |
Returns : |
A new InfAclSheet. Free with inf_acl_sheet_free() when no longer
in use. |
InfAclSheet * inf_acl_sheet_copy (const InfAclSheet *sheet
);
Makes a dynamically allocated copy of sheet
. This should not be used by
applications because you can copy the structs by value, but it is useful
for properties and bindings.
|
A InfAclSheet. |
Returns : |
A newly-allocated copy of sheet . Free with
inf_acl_sheet_free() when no longer in use. |
void inf_acl_sheet_free (InfAclSheet *sheet
);
Frees a InfAclSheet allocated by inf_acl_sheet_copy()
.
|
A InfAclSheet. |
gboolean inf_acl_sheet_perms_from_xml (xmlNodePtr xml
,InfAclMask *mask
,InfAclMask *perms
,GError **error
);
This function extracts the permission mask and the permission flags from
the XML node xml
. The counterpart to this function is
inf_acl_sheet_perms_to_xml()
. If an error occurs the function returns
FALSE
and error
is set.
void inf_acl_sheet_perms_to_xml (const InfAclMask *mask
,const InfAclMask *perms
,xmlNodePtr xml
);
This function writes the given permission mask and permission flags to the
XML node xml
. They can be converted back using the
inf_acl_sheet_perms_from_xml()
function.
|
Permission mask to write. |
|
Individiual permissions to write. |
|
error: Location to store error information, if any. |
InfAclSheetSet * inf_acl_sheet_set_new (void
);
Creates a new InfAclSheetSet. Add sheets with
inf_acl_sheet_set_add_sheet()
.
Returns : |
A new InfAclSheetSet. Free with inf_acl_sheet_set_free() . |
InfAclSheetSet * inf_acl_sheet_set_new_external (const InfAclSheet *sheets
,guint n_sheets
);
Creates a new InfAclSheetSet refererencing the given ACL sheets. The created sheet set is only holding a reference to the given array, so it must stay alive as long as the sheet set is alive.
No new sheets can be added to the returned sheet set with
inf_acl_sheet_set_add_sheet()
, or removed with
inf_acl_sheet_set_remove_sheet()
.
|
An array of InfAclSheets |
|
Number of elements in sheets . |
Returns : |
A new InfAclSheetSet. Free with inf_acl_sheet_set_free() when
no longer needed. |
InfAclSheetSet * inf_acl_sheet_set_copy (const InfAclSheetSet *sheet_set
);
Creates a copy of sheet_set
. If sheet_set
was created with
inf_acl_sheet_set_new_external()
, the copied sheet set will also only hold
a reference to the external sheets, and the same restrictions apply.
|
A InfAclSheetSet. |
Returns : |
A new InfAclSheetSet. Free with inf_acl_sheet_set_free() when
no longer needed. |
void inf_acl_sheet_set_free (InfAclSheetSet *sheet_set
);
Releases all resources allocated for sheet_set
.
|
A InfAclSheetSet. |
void inf_acl_sheet_set_sink (InfAclSheetSet *sheet_set
);
If a sheet set was created with inf_acl_sheet_set_new_external()
, this
function lifts the restrictions that come with it by making an internal
copy of the ACL sheets.
|
A InfAclSheetSet. |
InfAclSheet * inf_acl_sheet_set_add_sheet (InfAclSheetSet *sheet_set
,InfAclAccountId account
);
Adds a new default sheet for account
to sheet_set
. The function returns
a pointer to the new sheet. The pointer stays valid as long as no other
sheet is added to the set. If there is already a sheet for account
in the
set, then the existing sheet is returned instead.
This function can only be used if the sheet set has not been created with
the inf_acl_sheet_set_new_external()
function.
|
A InfAclSheetSet. |
|
The InfAclAccountId representing a unique account ID. |
Returns : |
A InfAclSheet for the new account. |
void inf_acl_sheet_set_remove_sheet (InfAclSheetSet *sheet_set
,InfAclSheet *sheet
);
Removes a sheet from sheet_set
. sheet
must be one of the sheets inside
sheet_set
. The sheet is removed by replacing it with the last sheet in
the set, so the order of sheets is not preserved.
This function can only be used if the sheet set has not been created with
the inf_acl_sheet_set_new_external()
function.
|
A InfAclSheetSet. |
|
The sheet to remove. |
InfAclSheetSet * inf_acl_sheet_set_merge_sheets (InfAclSheetSet *sheet_set
,const InfAclSheetSet *other
);
Replaces all sheets that are present in other
in sheet_set
with the ones
from other
. Note that an empty sheet in other
(with all permissions
masked out) causes the corresponding sheet in sheet_set
to be removed.
If sheet_set
is NULL
it is treated like an empty sheet set, i.e. the
merged sheet set is a copy of other
. In that case a new sheet set is
created and returned, unless other
is empty. If the merged sheet set
ends up empty, it is freed and the function returns NULL
.
|
A InfAclSheetSet, or NULL . |
|
The sheet set to merge. |
Returns : |
The merged sheet set, or NULL when the merged sheet set would
be empty. |
InfAclSheetSet * inf_acl_sheet_set_get_clear_sheets (const InfAclSheetSet *sheet_set
);
Returns a new sheet set with all sheets that are present in sheet_set
,
but with all permissions masked. When this set is merged with the original
set, all permissions will be reset to default for all accounts. Before
the merge, the returned sheet set can be modified. This allows to replace
the current permissions with new ones atomically.
|
A InfAclSheetSet. |
Returns : |
A new InfAclSheetSet. Free with inf_acl_sheet_set_free() when
no longer needed. |
InfAclSheet * inf_acl_sheet_set_find_sheet (InfAclSheetSet *sheet_set
,InfAclAccountId account
);
Returns the InfAclSheet for account
. If there is no such sheet in
sheet_set
, the function returns NULL
.
This function can only be used if the sheet set has not been created with
the inf_acl_sheet_set_new_external()
function.
|
A InfAclSheetSet. |
|
The InfAclAccountId representing the unique account ID of the account whose ACL sheet is to be found. |
Returns : |
A InfAclSheet for account , or NULL . |
const InfAclSheet * inf_acl_sheet_set_find_const_sheet (const InfAclSheetSet *sheet_set
,InfAclAccountId account
);
Returns the InfAclSheet for account
. If there is no such sheet in
sheet_set
, the function returns NULL
.
The difference between this function and
inf_acl_sheet_set_find_sheet()
is that this function returns a sheet
that cannot be modified, but it can also be used on a sheet set created
with the inf_acl_sheet_set_new_external()
function.
|
A InfAclSheetSet. |
|
The InfAclAccountId representing the unique account ID of the account whose ACL sheet is to be found. |
Returns : |
A InfAclSheet for account , or NULL . |
InfAclSheetSet * inf_acl_sheet_set_from_xml (xmlNodePtr xml
,GError **error
);
Reads a sheet set from xml
that has been written with
inf_acl_sheet_set_to_xml()
. If an error occurs the function returns
NULL
and error
is set. If there is no ACL stored in xml
, the function
returns NULL
without setting error
.
|
The XML node from which to read the sheet set. |
|
Location to read error information, if any. |
Returns : |
A InfAclSheetSet, or NULL . Free with inf_acl_sheet_set_free()
when no longer needed. |
void inf_acl_sheet_set_to_xml (const InfAclSheetSet *sheet_set
,xmlNodePtr xml
);
Serializes the sheet set given by sheet_set
into an XML node. The sheet
set can be deserialized again with inf_acl_sheet_set_from_xml()
.
|
The InfAclSheetSet to serialize. |
|
The XML node to serialize sheet_set into. |