Name

priv_attr_trig_query - Retrieves attributes stored by a trigger server for a specified principal for inclusion in the principal’s EPAC

Synopsis

#include <dce/priv_attr_trig.h> void priv_attr_trig_query (
handle_t h,
sec_id_foreign_t principal,
unsigned32 num_upstream_delegates,
sec_id_foreign_t upstream_delegates[],
priv_attr_trig_cursor_t ∗cursor,
unsigned32 num_attr_keys,
unsigned32 space_avail,
sec_attr_t attr_keys[],
unsigned32 ∗num_returned,
sec_attr_t attrs[],
priv_attr_trig_timeval_sec_t time_to_live[],
unsigned32 ∗num_left,
error_status_t ∗status);

Parameters

Input

hAn opaque handle bound to a trigger server.  Use the trigger binding information specified in the attribute encoding to acquire a bound handle. 

principalA value of type sec_id_foreign_t that identifies the UUID, name, and cell of the principal(s) whose attributes are to be retrieved. 

num_upstream_delegates
If principal is a member of a delegation chain, an unsigned 32-bit integer that specifies the number of delegates in the chain upstream from (before) this principal.  The upstream delegate chain ordering reflects the sequence in which delegates were added to the chain.  For example, the delegation initiator will always be first in the chain. 

upstream_delegates
If the privilege sever is adding principal to a delegation chain, an array of values of type sec_id_foreign_t that identify the UUID and cell of each delegate in the upstream delegation chain.  Note that principal names are not provided. 

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

space_availAn 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.  The size of the attr_keys[] array is determined by the num_attr_keys parameter. 

Input/Output

cursorA pointer to a priv_attr_trig_cursor_t.  As an input parameter, cursor is a pointer to a priv_attr_trig_cursor_t initialized by a the sec_attr_cursor_init() call.  As an output parameter, cursor is a pointer to a priv_attr_trig_cursor_t that is positioned past the components returned in this call. 

Output Parameters

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

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

time_to_live[]
An array of values of type priv_attr_trig_timeval_sec_t that specifies, for each attribute in the attrs[] array The size of the array is determined by space_avail and the length by num_returned. 

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

statusA 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 priv_attr_trig_query() function is used by the privilege server to retrieve attributes for a principal specified by UUID and include them in the principal’s EPAC. The privilege server calls this function when it gets a request for ERAs in an EAPC. 

Although generally this routine it is not called directly, this reference page is provided for users who are writing the attribute trigger servers that will receive priv_attr_trig_query() input and supply its output. 

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

For multivalued 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 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 priv_attr_trig_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 priv_attr_trig_query() 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

/usr/include/dce/priv_attr_trig.idl
The idl file from which dce/priv_attr_trig.h was derived. 

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. 

unauthorized

registry server unavailable

trigger server unavailable

error_status_ok

Related Information

Functions: sec_rgy_attr_cursor_init(3sec), sec_intro(3sec).