/* @(#)25       1.4  src/security/idl/priv_attr_trig.idl, security.src, os2dce21.dss, 960602a.1  5/17/95  09:51:22 */
/*
 * COMPONENT_NAME:  security.src
 *
 * FUNCTIONS:
 *
 * ORIGINS: 72
 *
 */
/*
 * Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc.
 * ALL RIGHTS RESERVED (DCE).  See the file named COPYRIGHT.DCE for
 * the full copyright text.
 */
/*
 * HISTORY
 * $Log: priv_attr_trig.idl,v $
 * Revision 1.1.2.4  1994/09/28  20:50:15  greg
 * 	CR11843: Include delegation chain in priv_attr_trig_query interface.
 * 	[1994/09/28  17:59:58  greg]
 *
 * Revision 1.1.3.2  94/09/21  9:44:02  greg
 * 	Add delegate info to priv_attr_trig callouts.
 * 
 * Revision 1.1.2.3  1994/08/25  16:19:40  mdf
 * 	final changes based on builds
 * 	[1994/08/25  16:19:27  mdf]
 * 
 * 	bumped version number
 * 	[1994/08/24  19:08:51  mdf]
 * 
 * 	Ensure the  DCE 1.1 version of priv_attr_trig.idl
 * 	defines the protocol the way we expect it to work for a while,
 * 	minimally.
 * 	[1994/08/24  18:58:44  mdf]
 * 
 * Revision 1.1.2.2  1994/08/10  19:21:50  annie
 * 	expand copyright with OSF copyright text
 * 	[1994/08/10  17:16:06  annie]
 * 
 * Revision 1.1.2.1  1994/07/15  15:00:06  mdf
 * 	Hewlett Packard Security Code Drop
 * 	[1994/07/14  17:59:43  mdf]
 * 
 * $EndLog$
 */
/*
** Copyright (c) Hewlett-Packard Company 1994
** Unpublished work. All Rights Reserved.
**
**      Attribute Trigger Interface
**            security/idl/priv_attr_trig.idl
**
** Binding model:
**
**  The attribute binding model is the same as the 
**  ACL binding model.
**  An RPC handle is obtained to an object, and any residual portion
**  of the name is passed as the component name.  This is the
**  mechanism that the ACL interface uses for implementing
**  a junction point in the name system.
**
*/
[
    uuid(409fe97a-7ef5-11cd-ac74-080009353559),
    version(1.0)
]
interface priv_attr_trig {
    import "dce/sec_attr_base.idl";
    import "dce/sec_base.idl";
    /*
     * Private Datatypes for the attribute trigger interface
     */
    /* p r i v _ a t t r _ t r i g_ t i m e v a l _ s e c _ t
     *
     *    The seconds portion of a UNIX timeval.
     */
    typedef signed32	priv_attr_trig_timeval_sec_t;
    
    /* p r i v _ a t t r _ t r i g_ c u r s o r _ t;
     *
     * Attribute trigger cursor for interative operations.
     * 
     *     source - identifies the server that initialized the cursor.
     *    object_handle - identifies the object (specified by 
     *        schema_name in the schema i/f or component_name in the
     *        attr i/f) upon which the operation is being performed.
     *    entry_handle - identifies the current entry (a schema_entry
     *        in the schema i/f or an attribute_instance in the
     *        attr i/f) for this operation.
     *    valid - if set to `0', indicates uninitialized cursor.
     *        The server will set to `1' upon initialization.
     */
    typedef struct {
            uuid_t	source;
            signed32	object_handle;
            signed32	entry_handle;
            boolean32	valid;
    } priv_attr_trig_cursor_t;
    /* p r i v _ a t t r _ t r i g_ q u e r y
     *
     * Read attribute(s) by ID.  Useful for programmatic access.
     * The number of query attribute keys (num_attr_keys)
     * may not be 0.
     *
     * Multi-valued attributes:
     * Multi-valued attributes are returned as independent attribute
     * instances sharing the same attribute id.
     *
     * Attribute Sets:
     * A read of an attribute set returns all instances of members
     * of that set.  The attribute set instance will not be returned.
     *
     * The list cursor is used to establish the point
     * in the attribute list from which the server should start
     * processing the query.  List cursors should be initialized with
     * the sec_attr_cursor_init function.  If the list cursor parameter
     * is uninitialized, the server will begin processing the query with
     * the first attribute that satisfies the search criteria.
     *
     * If the output parameter num_left is larger than 0, then the
     * output buffer supplied was not big enough.  Num_left is a hint
     * at the number of attributes that were not possible to return
     * due to space constraints.  This number may be inaccurate if
     * the server allows updates between succesive query calls.
     *
     *    In Parameters:
     *        principal - identifies the cell and principals UUID's and
     *		  names.
     *        num_upstream_delegates - if "principal" is being added
     *            to an existing delegation chain, the number of delegates
     *            in that existing ("upstream") delegation chain.
     *        upstream_delegates - if "principal" is being added
     *            to an existing delegation chain, identifies the cell and
     *            principal uuids of each delegate in the upstream 
     *            delegation chain.  Names of upstream delegates are
     *            not provided.   The upstream delegate chain ordering reflects
     *            the sequence in which delegates were added to the chain by
     *            the DCE privilege service.  E.G. the "initiator" 
     *            will always be first.
     *        num_attr_keys - specifies the number of elements in the
     *            input attr_keys array.
     *        space_avail - specifies the size of the output attrs array.
     *        attr_keys - in the attr_id field of each element, contains
     *            the attribute type id of the attribute instance(s)
     *            requested by this lookup. If the requested attribute
     *            type is associated with a query trigger, the attr_val
     *            field may be used to pass in optional information 
     *            required by the trigger query. If no information is
     *            to be passed in the attr_val field (whether the type
     *            indicates a trigger query or not), the attr_val
     *            encoding type should be set to
     *            sec_attr_enc_void.
     *            
     *    In/Out Parameters:
     *        cursor - in: initialized or uninitialized cursor; 
     *            out: cursor advanced past attributes returned in
     *            this call.
     *            To avoid making a remote cursor_init call, simply
     *            set cursor->valid = 0 before the first call to
     *            this operation.
     *
     *    Out Parameters:
     *        num_returned - specifies the number of attribute instances
     *            returned in the attrs array.
     *        attrs - contains the attributes retrieved by id.
     *        time_to_live - specifies, for each attribute in
     *            attrs, the lifetime in seconds for which the 
     *            attribute may be safely cached.
     *        num_left - hints at the number of attributes matching the
     *            search criteria that could not be returned due to
     *            space contraints in the attrs buffer.
     *
     * Warnings:
     *    Not_all_available       Not all of the requested attributes
     *                           were available.
     *
     * Errors:
     *    Unauthorized
     *    Invalid/Unsupported attribute type
     */
    void priv_attr_trig_query (
        [in]        handle_t                        h,
        [in]        sec_id_foreign_t       	    principal,
	[in]        unsigned32                      num_upstream_delegates,
        [in, size_is(num_upstream_delegates)]
                    sec_id_foreign_t                upstream_delegates[],
        [in, out]   priv_attr_trig_cursor_t         *cursor,
        [in]        unsigned32                      num_attr_keys,
        [in]        unsigned32                      space_avail,
        [in, size_is(num_attr_keys)]
                    sec_attr_t                      attr_keys[],
        [out]       unsigned32                      *num_returned,
        [out, size_is(space_avail), length_is(*num_returned)]
                    sec_attr_t                      attrs[],
        [out, size_is(space_avail), length_is(*num_returned)]
                    priv_attr_trig_timeval_sec_t    time_to_live[],
        [out]       unsigned32                      *num_left,
        [out]       error_status_t                  *st
    );
}
