VMS Help DCE_SECURITY, API Routines, sec_rgy_attr_lookup_by_id  *Conan The Librarian (sorry for the slow response - running on an old VAX)

 NAME
   sec_rgy_attr_lookup_by_id - Reads a specified object's attribute(s),
                               expanding attribute sets into individual
                               member attributes

 SYNOPSIS

   #include <dce/sec_rgy_attr.h>

   void sec_rgy_attr_lookup_by_id (
           sec_rgy_handle_t context,
           sec_rgy_domain_t name_domain,
           sec_rgy_name_t name,
           sec_attr_cursor_t *cursor,
           unsigned32 num_attr_keys,
           unsigned32 space_avail,
           sec_attr_t attr_keys[],
           unsigned32 *num_returned,
           sec_attr_t attrs[],
           unsigned32 *num_left,
           error_status_t *status);

 PARAMETERS

   Input

   context
          An opaque handle bound to a registry server.  Use
          sec_rgy_site_open() to acquire a bound handle.

   name_domain
          A value of type sec_rgy_domain_t that identifies the registry
          domain in which the object specified by name resides. The valid
          values are as follows:

          sec_rgy_domain_person
                      The name identifies a principal.

          sec_rgy_domain_group
                      The name identifies a group.

          sec_rgy_domain_org
                      The name identifies an organization.

   This parameter is ignored if name is policy or replist.

   name   A pointer to a sec_rgy_name_t character string containing the
          name of the person, group, or organization to which the
          attribute is attached.

   num_attr_keys
          An unsigned 32-bit integer that specifies the number of elements
          in the attr_keys array.  Set this parameter to 0 to return all
          of the object's attributes that the caller is authorized to see.

   space_avail
          An unsigned 32-bit integer that specifies the size of the
          attr_keys array.

   attr_keys[]
          An array of values of type sec_attr_t that identify the attribute
          type ID of the attribute instance(s) to be looked up. If the
          attribute type is associated with a query attribute trigger,
          the sec_attr_t attr_value field can be used to pass in optional
          information required by the attribute trigger query.  If no
          information is to be passed in the attr_value field (whether
          the type indicates an attribute trigger query or not), set the
          attribute's encoding type to sec_rgy_attr_enc_void.  The size
          of the attr_keys[] array is determined by the num_attr_keys
          parameter.

   Input/Output

   cursor
          A pointer to a sec_attr_cursor_t. As an input parameter, cursor
          is a pointer to a sec_attr_cursor_t initialized by a
          sec_rgy_attr_srch_cursor_init call. As an output parameter,
          cursor is a pointer to a sec_attr_cursor_t that is positioned
          past components returned in this call.

   Output

   num_returned
          A pointer to a 32-bit unsigned integer that specifies the number
          of attribute instances returned in the attrs[] array.

   attrs  An array of values of type sec_attr_t that contains the
          attributes retrieved by UUID. The size of the array is
          determined by space_avail and the length by num_returned.

   num_left
          A pointer to a 32-bit unsigned integer that supplies the number
          of attributes that were found but could not be returned because
          of space constraints in the attrs[] buffer.  To ensure that all
          the attributes will be returned, increase the size of the
          attrs[] array by increasing the size of space_avail and
          num_returned.

   status
          A pointer to the completion status.  On successful completion,
          the routine returns error_status_ok, or, if the requested
          attributes were not available, it returns the message
          not_all_available.  Otherwise, it returns an error.

 DESCRIPTION

   The sec_rgy_attr_lookup_by_id() function reads those attributes
   specified by UUID for an object specified by name. This routine is
   similar to the sec_rgy_attr_lookup_no_expand routine with one
   exception: for attribute sets, the sec_rgy_attr_lookup_no_expand
   routine returns a sec_attr_t for the set instance only; it does not
   expand the set and return a sec_attr_t for each member in the set.
   This call expands attribute sets and returns a sec_attr_t for each
   member in the set.

   If the num_attr_keys parameter is set to 0, all of the object's
   attributes that the caller is authorized to see are returned.  This
   routine is useful for programmatic access.

   For multi-valued attributes, the call returns a sec_attr_t for each
   value as an individual attribute instance. For attribute sets, the call
   returns a sec_attr_t  for each member of the set; it does not return
   the set instance.

   The attr_keys[] array, which specifies the attributes to be returned,
   contains values of type sec_attr_t.  These values consist of:

     +  attr_id, a UUID that identifies the attribute type

     +  attr_value, values of sec_attr_value_t that specify the attribute's
        encoding type and values.

   Use the attr_id field of each attr_keys array element, to specify the
   UUID that identifies the attribute type to be returned.

   If the attribute instance to be read is not associated with a query
   trigger or no additional information is required by the query trigger,
   an attribute UUID is all that is required. For these attribute
   instances, supply the attribute UUID in the input array and set the
   attribute encoding (in sec_attr_encoding_t) to sec_attr_enc_void.

   If the attribute instance to be read is associated with a query
   attribute trigger that requires additional information before it
   can process the query request, use a sec_attr_value_t to supply the
   requested information.

   To do this:

     +  Set the sec_attr_encoding_t to an encoding type that is compatible
        with the information required by the query attribute trigger.

     +  Set the sec_attr_value_t to hold the required information.

   Note that if you set num_attr_keys to zero to return all of the object's
   attributes and that attribute is associated with a query attribute
   trigger, the attribute trigger will be called with no input attribute
   information (that would normally have been passed in via the attr_value
   field).

   The cursor parameter specifies a cursor of type sec_attr_cursor_t
   initialized to the point in the attribute list at which to start
   processing the query.  Use the sec_attr_cursor_init function to
   initialize cursor. If cursor is uninitialized, the server begins
   processing the query at the first attribute that satisfies the search
   criteria.

   The num_left parameter contains the number of attributes that were
   found but could not be returned because of space constraints of the
   attrs[] array. (Note that this number may be inaccurate if the target
   server allows updates between successive queries.) To obtain all of the
   remaining attributes, set the size of the attrs[] array so that it is
   large enough to hold the number of attributes listed in num_left.

   Permissions Required

   The sec_rgy_attr_lookup_by_id() routine requires the query permission
   set for each attribute type identified in the attr_keys[] array. These
   permissions are defined as part of the ACL manager set in the schema
   entry of each attribute type.

 FILES

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

 ERRORS

   unauthorized

   registry server unavailable

   trigger server unavailable

   error_status_ok

 RELATED INFORMATION

   Functions: sec_intro
              sec_rgy_attr_lookup_no_expand
              sec_rgy_attr_attr_lookup_by_name