/* @(#)96       1.5  src/security/idl/sec_attr_trig.idl, security.src, os2dce21.dss, 960602a.1  5/17/95  09:50:39 */
/*
 * COMPONENT_NAME:  security.src
 *
 * FUNCTIONS:
 *
 * ORIGINS: 72
 *
 */
/*
 * @OSF_COPYRIGHT@
 * COPYRIGHT NOTICE
 * 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: sec_attr_trig.idl,v $
 * Revision 1.1.2.2  1994/06/17  18:42:30  devsrc
 * 	cr10872 - fix copyright
 * 	[1994/06/17  18:10:35  devsrc]
 *
 * Revision 1.1.2.1  1994/03/02  17:55:26  hanfei
 * 	Initial ERA drop
 * 	[1994/02/18  19:19:56  hanfei]
 * 
 * $EndLog$
 */
/*
** Copyright (c) Hewlett-Packard Company 1993
** Unpublished work. All Rights Reserved.
**
**      Attribute Trigger Interface
**            security/idl/sec_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(7009bbd8-b065-11cc-aa74-08001e039d7d)
]
interface sec_attr_trig {
    import "dce/sec_attr_base.idl";
    /*
     * Private Datatypes for the attribute trigger interface
     */
    /* s e c _ 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                        sec_attr_trig_timeval_sec_t;
    
    /* s e c _ 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;
    } sec_attr_trig_cursor_t;
    /* s e c _ 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:
     *        cell_name - identifies the cell in which `component_name'
     *            resides.  A NULL cell_name is interpreted as /.:
     *            or the local cell.
     *        component_name - identifies the registry object on which
     *            to perform this operation. If the cell_name specifies
     *            a foreign cell, the component name is interpreted
     *            as a UUID in string format since the caller of this
     *            interface for foreign principals will only know the
     *            UUID, not the name, of the foreign principal.
     *        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 sec_attr_trig_query (
        [in]        handle_t                        h,
        [in]        sec_attr_component_name_t       cell_name,
        [in]        sec_attr_component_name_t       component_name,
        [in, out]   sec_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)]
                        sec_attr_trig_timeval_sec_t    time_to_live[],
        [out]       unsigned32                      *num_left,
        [out]       error_status_t                  *st
    );
    /* s e c _ a t t r _ t r i g _ u p d a t e
     *
     * Write/Create an attribute.  This is an atomic operation.  All
     * attributes are written/created or none are modified.
     * 
     * The first attribute causing the update to fail is identified in
     * "failure_index".  If the failure cannot be attributed to a
     * given attribute, then -1 is returned in the failure index.
     *
     * Multi-valued Attributes:
     * If the schema entry for a given attribute specifies that
     * multi-valued attributes are not allowed AND an instance of
     * that attribute type already exists on the object, the instance
     * is overwritten with the new attribute.  If multi-valued attributes
     * are allowed, a new instance is created without modification to
     * the already-present instance.
     *
     * Attribute Sets:
     * This operation may be used to update attribute set instances.
     * No expansion of a set to its members occurs on update operations.
     *
     *    In Parameters:
     *        cell_name - identifies the cell in which `component_name'
     *            resides.  A NULL cell_name is interpreted as /.:
     *            or the local cell.
     *        component_name - identifies the registry object on which
     *            to perform this operation.
     *        num_to_write - specifies the number of attributes in
     *            the in_attrs array.
     *        space_avail - specifies the size of the out_attrs array.
     *        in_attrs - contains the attribute instances to be written.
     *
     *    Out Parameters:
     *        num_returned - specifies the number of attribute
     *            instances returned in the out_attrs array.
     *        out_attrs - contains the output attributes suitable for
     *            storage in the attribute database.
     *        num_left - hints at the number of output attributes
     *            remaining that could not be returned due to 
     *            space limitations in out_attrs.  This operation
     *            should be retried with a larger out_attrs array.
     *        failure_index - in an error case, contains the index
     *            of the element in in_attrs[] that caused the update to
     *            fail, or -1 if the failure cannot be attributed to
     *            a given attribute.
     *
     * Errors:
     *    Unauthorized
     *    Database read only
     *    Server unavailable
     *    Invalid/Unsupported attribute type
     *    Invalid encoding type
     *    Value not unique
     *    Site read only
     */
    void sec_attr_trig_update (
        [in]        handle_t                        h,
        [in]        sec_attr_component_name_t       cell_name,
        [in]        sec_attr_component_name_t       component_name,
        [in]        unsigned32                      num_to_write,
        [in]        unsigned32                      space_avail,
        [in, size_is(num_to_write)]
                    sec_attr_t                      in_attrs[],
        [out]       unsigned32                      *num_returned,
        [out, size_is(space_avail), length_is(*num_returned)]
                    sec_attr_t                      out_attrs[],
        [out]       unsigned32                      *num_left,
        [out]       signed32                        *failure_index,
        [out]       error_status_t                  *st
    );
}
