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

 NAME
   sec_rgy_attr_get_effective -  Reads effective attributes by ID

 SYNOPSIS

   #include <dce/sec_rgy_attr.h>

   void sec_rgy_attr_get_effective(
           sec_rgy_handle_t context,
           sec_rgy_domain_t name_domain,
           sec_rgy_name_t name,
           unsigned32 num_attr_keys,
           sec_attr_t attr_keys[],
           sec_attr_vec_t *attr_list,
           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 domain in
          which the named object resides.  The valid values are as follows:

          sec_rgy_domain_principal
                      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 the attr_keys[] array.  If num_attr_keys is set to 0,
          all of the effective attributes that the caller is authorized to
          see are returned.

   attr_keys[]
          An array of values of type sec_attr_t that specify the UUIDs
          of the attributes to be returned if they are effective. 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.

   Output

   attr_list
          A pointer an attribute vector allocated by the server containing
          all of the effective attributes matching the search criteria
          (defined in num_attr_keys or attr_keys[] ).  The server
          allocates a buffer large enough to return all the requested
          attributes so that subsequent calls are not necessary.

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

 DESCRIPTION

   The sec_rgy_attr_get_effective() routine returns the UUIDs of a
   specified object's effective attributes. Effective attributes are
   determined by setting of the schema entry apply_defaults flag:

     +  If the flag is set off, only the attributes directly attached
        to the object are effective.

     +  If the flag is set on, the effective attributes are obtained by
        performing the following steps for each attribute identified by
        UUID in the attr_keys array:

         1. If the object named by name is a principal and if the a
            requested attribute exists on the principal, that attribute
            is effective and is returned. If it does not exist, the
            search continues.

         2. The next step in the search depends on the type of object:
            For principals with accounts:

              a. The organization named in the principal's account is
                 examined to see if an attribute of the requested type
                 exists.  If it does, it is effective and is returned;
                 then the search for that attribute ends. If it does
                 not exist, the search for that attribute continues to
                 the policy object as described in b, below.

              b. The registry policy object is examined to see if an
                 attribute of the requested type exits. If it does, it
                 is returned.  If it does not, a message indicating the
                 no attribute of the type exists for the object is
                 returned.

        For principals without accounts, for groups, and for organizations:
        the registry policy object is examined to see if an attribute of
        the requested type exits. If it does, it is returned.  If it does
        not, a message indicating the no attribute of the type exists for
        the object is returned.

   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.

   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.

   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 requested attribute type is associated with a query trigger,
   the value returned for the attribute will be the binding (as set in
   the schema entry) of the trigger server.  The caller must bind to the
   trigger server and pass the original input query attribute to the
   sec_attr_trig_query call in order to retrieve the attribute value.

 FILES

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

 ERRORS

   error_status_ok

 RELATED INFORMATION

   Functions: sec_intro