NAME
sec_attr_trig_query - 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
sec_addr_trig_cursor_init routine) or uninitialized. 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 an
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.
Multi-valued 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 cursor parameter specifies a cursor of type sec_attr_trig_cursor_t
that establishes the point in the attribute list at which to start
processing the query. Use the sec_attr_trig_cursor_init function to
initialize a list cursor. If cursor is uninitialized, the server begins
processing the query at the first attribute that satisfies the search
criteria. Note that generally, sec_attr_trig_cursor_init function makes
a remote call to the specified server. To initialize the cursor without
making this remote call, set the sec_attr_trig_cursor_init function
valid parameter to 0.
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
SYS$COMMON:[DCE$LIBRARY]SEC_ATTR_TRIG.IDL
The idl file from which sec_attr_trig.h was derived.
ERRORS
not_all_available
unauthorized
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_attr_trig_cursor_init
sec_attr_trig_update