Top | ![]() |
![]() |
![]() |
![]() |
typedef | InfAclAccountId |
struct | InfAclAccount |
enum | InfAclSetting |
struct | InfAclMask |
struct | InfAclSheet |
struct | InfAclSheetSet |
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 |
GBoxed ├── InfAclAccount ├── InfAclMask ├── InfAclSheet ╰── InfAclSheetSet GEnum ╰── InfAclSetting
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.
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.
const gchar *
inf_acl_account_id_to_string (InfAclAccountId account
);
Translates the given account ID to a unique string identifier.
#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.
#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.
InfAclAccount * inf_acl_account_new (InfAclAccountId id
,const gchar *name
);
Creates a new InfAclAccount.
InfAclAccount *
inf_acl_account_copy (const InfAclAccount *account
);
Creates a copy of account
.
A new InfAclAccount. Free with
inf_acl_account_free()
when no longer needed.
[transfer full]
void
inf_acl_account_free (InfAclAccount *account
);
Releases all resources allocated by account
.
void inf_acl_account_array_free (InfAclAccount *accounts
,guint n_accounts
);
Releases all resources allocated by an array of InfAclAccounts.
accounts |
An array of InfAclAccount objects. |
[array length=n_accounts] |
n_accounts |
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.
A new InfAclAccount on success, or NULL
on
failure. Free with inf_acl_account_free()
when no longer needed.
[transfer full]
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.
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.
void
inf_acl_mask_free (InfAclMask *mask
);
Releases a InfAclMask that was created with inf_acl_mask_copy()
.
void
inf_acl_mask_clear (InfAclMask *mask
);
Resets a mask so that all fields are zero.
gboolean
inf_acl_mask_empty (const InfAclMask *mask
);
Checks whether the given mask is empty, i.e. all fields are set to zero.
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
.
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.
mask |
The InfAclMask to initialize. |
|
settings |
An array of InfAclSettings to set. |
[array length=n_settings] |
n_settings |
The number of settings. |
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
.
InfAclMask * inf_acl_mask_and1 (InfAclMask *mask
,InfAclSetting setting
);
Disables the bit corresponding to setting in mask
, leaving all other bits
alone.
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
.
InfAclMask * inf_acl_mask_or1 (InfAclMask *mask
,InfAclSetting setting
);
Enables the bit corresponding to setting in mask
, leaving all other bits
alone.
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.
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.
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.
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 newly-allocated copy of sheet
. Free with
inf_acl_sheet_free()
when no longer in use.
[transfer full]
void
inf_acl_sheet_free (InfAclSheet *sheet
);
Frees a InfAclSheet allocated by inf_acl_sheet_copy()
.
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.
InfAclSheetSet *
inf_acl_sheet_set_new (void
);
Creates a new InfAclSheetSet. Add sheets with
inf_acl_sheet_set_add_sheet()
.
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()
.
sheets |
An array of InfAclSheets. |
[array length=n_sheets] |
n_sheets |
Number of elements in |
A new InfAclSheetSet. Free with
inf_acl_sheet_set_free()
when no longer needed.
[transfer full]
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 new InfAclSheetSet. Free with
inf_acl_sheet_set_free()
when no longer needed.
[transfer full]
void
inf_acl_sheet_set_free (InfAclSheetSet *sheet_set
);
Releases all resources allocated for sheet_set
.
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.
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.
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.
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
.
sheet_set |
A InfAclSheetSet, or |
[allow-none][transfer full] |
other |
The sheet set to merge. |
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 new InfAclSheetSet. Free with
inf_acl_sheet_set_free()
when no longer needed.
[transfer full]
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.
sheet_set |
||
account |
The InfAclAccountId representing the unique account ID of the account whose ACL sheet is to be found. |
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.
sheet_set |
||
account |
The InfAclAccountId representing the unique account ID of the account whose ACL sheet is to be found. |
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
.
xml |
The XML node from which to read the sheet set. |
|
error |
Location to read error information, if any. |
A InfAclSheetSet, or NULL
. Free with
inf_acl_sheet_set_free()
when no longer needed.
[transfer full]
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()
.
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.
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.
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 |
|
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. |
|
The number of elements in the |