VMS Help DCE_SECURITY, API Routines, sec_attr_trig_query  *Conan The Librarian (sorry for the slow response - running on an old VAX)

 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