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