sec_attr_trig_query(3sec)
Reads attributes coded with an attribute trigger type of query
Synopsis
#include <dce/sec_attr_trig.h>
void sec_attr_trig_query (
handle_t h,
sec_attr_component_name_t
cell_name,
sec_attr_component_name_t component_name,
sec_attr_trig_cursor_t *cursor,
unsigned32 num_attr_keys,
unsigned32 space_avail,
sec_attr_t attr_keys[ ],
unsigned32 *num_returned,
sec_attr_t attrs[ ],
sec_attr_trig_timeval_sec_t time_to_live[ ],
unsigned32 *num_left,
error_status_t *status);
Parameters
Input
h
A handle referring to the trigger server to be accessed Use the trigger binding information specified in the attribute encoding to acquire a bound handle.
cell_name
A value of sec_attr_component_name_t that identifies the cell in which the object whose attribute is to be accessed resides. Supply a NULL
cell_name to specify the local cell (/.:).
component_name
A value of sec_attr_component_name_t that identifies the name of the object whose attribute is to be accessed. If cell_name specifies a foreign
cell, component_name is interpreted as a UUID in string format since the caller of this interface knows only the UUID, not the name, of the foreign principal.
num_attr_keys
An unsigned 32-bit integer that specifies the number of elements in the attr_keys[ ] array. This integer must be greater than 0.
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. For each attribute instance, the sec_attr_t array contains an attr_id (a UUID of type
uuid_t) to identify the attribute to be queried and an attr_value. attr_value can be used to pass in optional information required by the attribute trigger query. If no
additional information is to be passed, set attr_value to sec_attr_enc_void. This is actually accomplished by setting the sec_attr_encoding_t data type to
sec_attr_enc_void.
The size of the attr_keys[ ] array is determined by num_attr_keys.
Input/Output
cursor
A pointer to a cursor of type sec_attr_trig_cursor_t. As an input parameter, cursor can be initialized (by the server) or uninitialized. If the cursor
is uninitialized, the cursor begins processing the query at the first attribute that satisfies the search criteria. As an output parameter, cursor is positioned past the attributes returned
in this call.
Output
num_returned
A pointer to an unsigned 32-bit integer that specifies the number of attribute instances returned in the attr_keys[ ] array.
attrs[ ]
An array of values of type sec_attr_t. The size of this array is determined by the space_avail parameter and the length by the
num_returned parameter.
time_to_live[ ],
An array of values of type sec_attr_trig_timeval_sec_t. For each attribute in the attrs[ ] array, The time_to_live[ ] array
specifies the time in seconds that the attribute can be safely cached.
num_left
A pointer to an unsigned 32-bit integer that supplies the number of attributes found but not returned because of space constraints in the attrs[ ] buffer.
status
A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error.
Description
The sec_attr_trig_query( ) routine reads attributes coded with a attribute trigger type of query.
The sec_attr_trig_query( ) routine is called by the DCE attribute lookup code for all schema entries that specify a query attribute trigger (sec_attr_trig_type_query specified with the sec_attr_trig_type_flags_t data type). The attribute query code passes the sec_attr_trig_query( ) input parameters to a user-written query attribute trigger server and receives the output parameters back from the server. 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 sec_attr_trig_query( ) input and supply its output.
Multivalued attributes are returned as independent attribute instances sharing the same attribute UUID. A read of an attribute set returns all instances of members of the set; the attribute set instance is not returned.
For objects in the local cell, set the cell_name parameter to NULL, and the component_name parameter to specify the object's name.
For objects in a foreign cell, set the cell_name parameter to identify the name of the foreign cell, and the component_name parameter to the UUID in string format that identifies the object in the foreign cell.
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.
Files
/usr/include/dce/sec_attr_trig.idl
The idl file from which dce/sec_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.
not_all_available
unauthorized
error_status_ok
Related Information
Functions: