NAME

sec_acl_get_printstring-Obtain human-readable representations of permissions supported by an ACL manager.

SYNOPSIS

#include <dce/daclif.h>

void sec_acl_get_printstring(
    sec_acl_handle_t prot_obj_handle,
    uuid_t *manager_type,
    unsigned32 count_max,
    uuid_t *manager_type_next,
    sec_acl_printstring_t *manager_info,
    boolean32 *tokenize,
    unsigned32 *num_printstrings,
    unsigned32 *count,
    sec_acl_printstring_t printstrings[],
    error_status_t *status);

PARAMETERS

Input

prot_obj_handle

Handle referring to a protected object.

manager_type

An ACL manager type UUID of the protected object.

count_max

Maximum number of elements the calling client is prepared to receive in its printstrings[] array.

Output

manager_type_next

Identifies the next ACL manager type in a linked list or "chain" of ACL manager types, which can be successively followed until the chain is exhausted (for example, such a chain can be used to support > 32 permission bits). The end of an ACL manager chain is indicated by uuid_nil.

manager_info

Name and help information for the ACL manager, as well as a complete set of supported permission bits.

tokenize

Identifies potential ambiguity in the concatenation of permission printstrings (that is, in the printstring fields of the elements of the printstrings[] array).

num_printstrings

Total number (1, ···, 32) of permission bits and printstrings supported by the ACL manager.

count

Actual number of printstrings returned (in printstrings[]).

printstrings[]

Array of size count, of printstrings representing the permission bits supported by the ACL manager.

status

Completion status. On successful completion, error_status_ok is returned. Otherwise, an error (!= error_status_ok) is returned.

DESCRIPTION

The sec_acl_get_printstring() routine returns information about the ACL manager specified by manager_type, managing an ACL of the protected object specified by prot_obj_handle. This information is returned in the printstrings[] array, which contains one or more entry for each distinct permission the ACL manager supports.

The sec_acl_get_printstring() routine also returns, in num_printstrings, the total number of printstrings supported by the ACL manager. An invocation of this routine is completely successful only if count = num_printstrings.

In addition to returning information about the permissions themselves, this routine returns instructions in the tokenize parameter about concatenating the printstrings associated with them (this is useful for user interfaces to ACL editors). When tokenize is 0 ("false"), the permission printstrings may be concatenated without ambiguity (for example, in a user interface to an ACL editor); when non-0 ("true"), this property does not hold and the permission printstrings must be "tokenised" (that is, separated by disambiguating characters; for example, non-alphanumeric characters, such as whitespace) to avoid ambiguity when concatenated.

The ACL manager must support at least one printstring[] array element pertaining to each permission supported by the ACL manager. If it supports more than one ("aliases") for a given permission, by convention the simpler entries appear toward the beginning of the printstring[] array.

For more information (and an example), see rdacl_get_printstring() (.cX rdacl_getprint ).

NOTES

Implementations layer this routine over the rdacl RPC interface operation rdacl_get_printstring().

ERRORS

error_status_ok, sec_acl_unknown_manager_type.

SEE ALSO

Functions: sec_acl_bind(), sec_acl_get_manager_types(), sec_acl_get_manager_types_semantics().

Protocols: rdacl_get_printstring().