/sys$common/syshlp/helplib.hlb DCE_SECURITY, API Routines, rdacl_get_printstring  *Conan The Librarian (sorry for the slow response - running on an old VAX)

 NAME
   rdacl_get_printstring - Returns printable ACL strings

 SYNOPSIS

   #include <dce/rdaclif.h>

   void rdacl_get_printstring(
           handle_t h,
           uuid_t *manager_type,
           unsigned32 size_avail,
           uuid_t *manager_type_chain,
           sec_acl_printstring_t *manager_info,
           boolean32 *tokenize,
           unsigned32 *total_num_printstrings,
           unsigned32 *size_used,
           sec_acl_printstring_t printstrings[],
           error_status_t *status);

 PARAMETERS

   Input

   h     A handle referring to the target object.

   manager_type
         A pointer to the UUID identifying the type of the ACL manager
         in question. There may be more than one type of ACL manager
         protecting the object whose ACL is bound to the input handle.
         Use this parameter to distinguish them. Use
         rdacl_get_manager_types() to acquire a list of the manager
         types protecting a given object.

   size_avail
         An unsigned 32-bit integer containing the allocated length of the
         printstrings[] array.

   Output

   manager_type_chain
         If the target object ACL contains more than 32 permission bits,
         multiple manager types are used, one for each 32-bit wide "slice"
         of permissions.  The UUID returned in manager_type_chain refers
         to the next ACL manager in the chain. If there are no more ACL
         managers for this ACL, uuid_nil is returned.

   manager_info
         Provides a name and helpstring for the given ACL manager.

   tokenize
         When FALSE this variable indicates that the returned permission
         printstrings are unambiguous and therefore may be concatenated
         when printed without confusion.  When TRUE, however, this property
         does not hold, and the strings need to be separated when printed
         or passed.

   total_num_printstrings
         An unsigned 32-bit integer containing the total number of
         permission printstrings supported by this ACL manager type.

   size_used
         An unsigned 32-bit integer containing the number of permission
         entries returned in the printstrings[] array.

   printstrings[]
         An array of permission printstrings of type sec_acl_printstring_t.
         Each entry of the array is a structure containing three
         components:

         printstring
               A character string of maximum length sec_acl_printstring_len
               containing the printable representation of a specified
               permission.

         helpstring
               A character string of maximum length
               sec_acl_printstring_help_len containing some text that can
               be used to describe the specified permission.

         permissions
               A sec_acl_permset_t permission set describing the
               permissions that are to be represented with the companion
               printstring.  The array consists of one such entry for
               each permission supported by the ACL manager identified
               by manager_type.

   status
         A pointer to the completion status.  On successful completion, the
         routine returns error_status_ok.  Otherwise, it returns an error.

 DESCRIPTION

   The rdacl_get_printstring() routine returns an array of printable
   representations (called printstrings) for each permission bit or
   combination of permission bits the specified ACL manager will support.
   The ACL manager type specified must be one of the types indicated by
   the ACL handle.

   In addition to returning the printstrings, this routine also returns
   instructions about how to print the strings. When the tokenize variable
   is set to FALSE, a print string might be r or w, which could be
   concatenated in the display as rw without any confusion. However, when
   the tokenize variable is TRUE, it implies the printstrings might be of
   a form like read or write, which must be displayed separated by spaces
   or colons or something.

   In any list of permission printstrings, there may appear to be some
   redundancy. ACL managers often define aliases for common permission
   combinations. By convention, however, simple entries need to appear
   at the beginning of the printstrings[] array, and combinations need to
   appear at the end.

 NOTES

   This call is not intended to be used by application programs.  The
   sec_acl Application Programming Interface (API) provides all the
   functionality necessary to use the ACL facility. This reference page
   is provided for programmers who wish to write an ACL manager.  In
   order to write an ACL manager, a programmer must implement the entire
   rdacl interface.

   This network interface is called on the client side via the sec_acl
   local interface. Developers are responsible for implementing the
   server side of this interface. Test server code is included as a
   sample implementation.

 FILES
     SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL
                The idl file from which dce/rdaclif.h was derived.

 ERRORS

   sec_acl_unknown_manager_type
                The manager type selected is not among those referenced by
                the input handle.

   error_status_ok
                The call was successful.

 RELATED INFORMATION

   Functions: sec_intro
              sec_acl_bind
              rdacl_get_manager_types