NAME

sec_rgy_attr_lookup_by_name — Reads a single attribute instance for a specific object

Synopsis

void sec_rgy_attr_lookup_by_name(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
char ∗attr_name,
sec_attr_t ∗attr,
error_status_t ∗status);

Parameters

Input

contextAn 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. 

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

attr_nameA pointer to a character string that specifies the name of the attribute to be retrieved. 

Output

attrA pointer to a sec_attr_t that contains the first instance of the named attribute. 

statusA pointer to the completion status.  The completion status can be one of the following:

error_status_ok
All instances of the value were returned with no errors.

more_available
A multivalued attribute was specified as name and the routine completed successfully.  For multivalued attributes, this routine returns the first instance of the attribute. 

attribute_set_instance
An attribute set was specified as name and the routine completed successfully. 

An error message if the routine did not complete successfully. 

Description

The sec_rgy_attr_lookup_by_name() routine returns the named attribute for a named object.  This routine is useful for an interactive editor. 

For multivalued attributes, this routine returns the first instance of the attribute.  To retrieve every instance of the attribute, use the sec_rgy_attr_lookup_by_id call, supplying the attribute Universal Unique Identifier (UUID) returned in the attr parameter. 

For attribute sets, the routine returns the attribute set instance, not the member instances.  To retrieve all members of the set, use the sec_rgy_attr_lookup_by_id call, supplying the the attribute set UUID returned in the attr parameter. 

After a successful call, free the resources allocated by this routine for the attr parameter, with the sec_attr_util_inst_free_ptrs() routine. 

Warning:

This routine does not provide for input data to an attribute trigger query operation.  If the named attribute is associated with a query attribute trigger, the attribute trigger will be called with no input attribute value information. 

Permissions Required

The sec_rgy_attr_lookup_by_name() routine requires the q (query) permission set for the attribute type of the attribute instance identified by attr_name.  These permissions are defined as part of the access control list (ACL) manager set in the schema entry of each attribute type. 

Errors

The following describes a partial list of errors that might be returned.  Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages. 

registry server unavailable

trigger server unavailable

unauthorized

error_status_ok

Related Information

Functions: sec_intro(3sec), sec_rgy_attr_lookup_by_id(3sec), sec_rgy_attr_lookup_no_expand(3sec).