/* @(#)98       1.6  src/security/idl/sec_rgy_attr_sch.idl, security.src, os2dce21.dss, 960602a.1  5/17/95  09:50:54 */
/*
 * 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_rgy_attr_sch.idl,v $
 * Revision 1.1.2.3  1994/08/04  16:13:05  mdf
 * 	Hewlett Packard Security Code Drop
 * 	[1994/07/26  19:10:11  mdf]
 *
 * Revision 1.1.2.2  1994/06/17  18:42:36  devsrc
 * 	cr10872 - fix copyright
 * 	[1994/06/17  18:10:41  devsrc]
 * 
 * Revision 1.1.2.1  1994/03/02  17:55:32  hanfei
 * 	Initial ERA drop
 * 	[1994/02/18  19:20:00  hanfei]
 * 
 * $EndLog$
 */
/*
** Copyright (c) Hewlett-Packard Company 1993
** Unpublished work. All Rights Reserved.
**
**      Registry Attributes Schema Manipulation Interface
**
**
*/

[
    local
]

interface sec_rgy_attr_sch {
    import "dce/rgybase.idl";
    import "dce/sec_attr_base.idl";

    /*
     * Private Datatypes for the schema interface
     */
    
    /*
     * SCHEMA OPERATIONS
     */

    /* s e c _ r g y _ a t t r _ s c h _ c r e a t e _ e n t r y
     *
     * Create a new schema entry.  Presumably you must be 
     * authorized to add entries to the schema - 
     * that is handled by the targetserver.
     *	In Parameters:
     *		schema_name - identifies the schema object on which
     *			to perform this operation.
     *		schema_entry - a schema entry with a value in every
     *			field except perhaps the optional fields:
     *			trig_types, trig_bind, and comment.
     *
     * Errors:
     *	sec_attr_bad_name
     *	sec_attr_bad_encoding_type
     *	sec_attr_bad_acl_mgr_set
     *	sec_attr_bad_acl_mgr_type
     *	sec_attr_bad_permset
     *	sec_attr_bad_intercell_action
     *	sec_attr_trig_bind_info_missing
     *	sec_attr_bad_bind_info
     *	sec_attr_bad_bind_svr_name
     *	sec_attr_bad_bind_prot_level
     *	sec_attr_bad_bind_authn_svc
     *	sec_attr_bad_bind_authz_svc
     *	sec_attr_bad_uniq_query_accept
     *	sec_attr_bad_scope
     *	sec_attr_bad_comment
     *	sec_attr_type_id_exists
     *	sec_attr_name_exists
     *	sec_attr_unauthorized
     *	sec_attr_svr_read_only
     *	sec_attr_svr_unavailable
     *	sec_attr_no_memory
     */
     
    void sec_rgy_attr_sch_create_entry (
	[in]	sec_rgy_handle_t		context,
	[in]	sec_attr_component_name_t	schema_name,
	[in]	sec_attr_schema_entry_t		*schema_entry,
	[out]	error_status_t			*st_p
	);
     

    /* s e c _ r g y _ a t t r _ s c h _ d e l e t e _ e n t r y
     *
     * Delete a schema entry.  This is a radical operation
     * that will delete or invalidate any existing 
     * attributes of this type on nodes dominated by  
     * the schema.  Access to this operation should be
     * severely limited.
     *	In Parameters:
     *		schema_name - identifies the schema object on which
     *			to perform this operation.
     *		attr_id - attribute type uuid of entry to be deleted.
     *
     * Errors:
     *	sec_attr_sch_entry_not_found
     *	sec_attr_unauthorized
     *	sec_attr_svr_read_only
     *	sec_attr_svr_unavailable
     *	sec_attr_no_memory
     */
     
    void sec_rgy_attr_sch_delete_entry (
	[in]	sec_rgy_handle_t		context,
	[in]	sec_attr_component_name_t	schema_name,
	[in]	uuid_t				*attr_id,
	[out]	error_status_t			*st_p
	);
     

    /* s e c _ r g y _ a t t r _ s c h _ u p d a t e _ e n t r y
     *
     * Update the modifiable fields of a schema entry
     * identified by the attr_id in the input schema_entry.
     * See sec_attr_base.idl for the modifiable fields.
     *
     * If a field is indicated by its flag in modify_parts, that
     * field from the input schema entry will completely replace
     * the current field of the existing schema entry.  All other
     * fields will remain untouched.  Note that fields which are
     * arrays of structures (like acl_mgr_set and trig_binding)
     * will be *completely* replaced by the new input array.
     * This operation will not simply add one more element to
     * the existing array.
     *
     *	In Parameters:
     *		schema_name - identifies the schema object on which
     *			to perform this operation.
     *		modify_parts - this flag set identifies the fields
     *			in the input schema_entry that should be updated.
     *			Fields not indicated by modify_parts will retain
     *			their current values.
     *		schema_entry - a schema entry whow fields are null
     *			except for the fields indicated by modify_parts.
     *
     * Errors:
     *	sec_attr_field_no_update
     *	sec_attr_bad_name
     *	sec_attr_bad_acl_mgr_set
     *	sec_attr_bad_acl_mgr_type
     *	sec_attr_bad_permset
     *	sec_attr_bad_intercell_action
     *	sec_attr_trig_bind_info_missing
     *	sec_attr_bad_bind_info
     *	sec_attr_bad_bind_svr_name
     *	sec_attr_bad_bind_prot_level
     *	sec_attr_bad_bind_authn_svc
     *	sec_attr_bad_bind_authz_svc
     *	sec_attr_bad_uniq_query_accept
     *	sec_attr_bad_comment
     *	sec_attr_name_exists
     *	sec_attr_sch_entry_not_found
     *	sec_attr_unauthorized
     *	sec_attr_svr_read_only
     *	sec_attr_svr_unavailable
     *	sec_attr_no_memory
     */
     
    void sec_rgy_attr_sch_update_entry (
	[in]	sec_rgy_handle_t		context,
	[in]	sec_attr_component_name_t	schema_name,
	[in]	sec_attr_schema_entry_parts_t	modify_parts,
	[in]	sec_attr_schema_entry_t		*schema_entry,
	[out]	error_status_t			*st_p
	);
     

    /* s e c _ r g y _ a t t r _ s c h _ c u r s o r _ i n i t
     *
     * Initialize a scan cursor
     *	In Parameters:
     *		schema_name - identifies the schema object on which
     *			to perform this operation.
     *		
     *	Out Parameters:
     *		cur_num_entries - the current total number of entries in 
     *			the schema at the time of this call.
     *		cursor - cursor initialized to the first in the
     *			list of entries in the named schema.
     *
     * Errors:
     *	sec_attr_unauthorized
     *	sec_attr_svr_unavailable
     *	sec_attr_no_memory
     */
     
    void sec_rgy_attr_sch_cursor_init (
	[in]	sec_rgy_handle_t		context,
	[in]	sec_attr_component_name_t	schema_name,
	[out]	unsigned32			*cur_num_entries,
	[out]	sec_attr_cursor_t		*cursor,
	[out]	error_status_t			*st_p
	);


    /* s e c _ r g y _ a t t r _ s c h _ c u r s o r _ a l l o c
     *
     * Allocate a scan cursor which must be released
     * with sec_rgy_attr_sch_cursor_release.
     * This is a local operation that is used *instead of*
     * the remote sec_rgy_attr_sch_cursor_init.
     * Either sec_rgy_attr_sch_cursor_init or sec_rgy_attr_sch_cursor_alloc
     * must be used to allocate a cursor for use in lookup operations.
     *
     *	Out Parameters:
     *		cursor - cursor initialized to the first in the
     *			list of attributes on this object.
     *
     * Errors:
     *	sec_attr_no_memory
     */

    void sec_rgy_attr_sch_cursor_alloc (
	[out]	sec_attr_cursor_t	*cursor,
	[out]	error_status_t		*st_p
	);


    /* s e c _ r g y _ a t t r _ s c h _ c u r s o r _ r e s e t
     *
     * Reset a cursor that has been allocated with 
     * either sec_rgy_attr_sch_cursor_init or sec_rgy_attr_sch_cursor_alloc
     * so that it may be used to process a new query.
     * This allows the caller to reuse a curser instead of
     * releasing and re-allocating. 
     * 
     * This is a local operation.
     *
     *	Out Parameters:
     *		cursor - cursor initialized to the first in the
     *			list of attributes on this object.
     *
     * Errors:
     *	sec_attr_bad_cursor
     *
     */
    void sec_rgy_attr_sch_cursor_reset (
	[in, out]	sec_attr_cursor_t	*cursor,
	[out]		error_status_t		*st_p
	);


    /* s e c _ r g y _ a t t r _ s c h _ c u r s o r _ r e l e a s e
     *
     * Release any state associated with a scan cursor allocated
     * with either sec_rgy_attr_sch_cursor_init or 
     * sec_rgy_attr_sch_cursor_alloc.
     * This is a local-only operation.
     *	In/Out Parameters:
     *		cursor - in: initialized cursor;
     *			 out: uninitialized cursor with resources released
     */

    void sec_rgy_attr_sch_cursor_release (
        [in, out]   sec_attr_cursor_t	*cursor,
        [out]       error_status_t	*st_p
    );

     
    /* s e c _ r g y _ a t t r _ s c h _ s c a n
     *
     * Read num_to_read entries from the named schema - 
     * useful for a browser.
     *	In Parameters:
     *		schema_name - identifies the schema object on which
     *			to perform this operation.
     *		num_to_read - specifies the size of the 
     *			schema_entries array and the max number of
     *			entries to be returned in this call.
     *
     *	In/Out Parameters:
     *		cursor - in: initialized cursor; 
     *			out: cursor advanced past entries returned
     *			in this call.
     *
     *	Out Parameters:
     *		num_read - specifies the number of entries 
     *			returned in schema_entries.
     *		schema_entries - array containing num_read entries.
     *
     * Errors:
     *	sec_attr_bad_cursor
     *	sec_attr_unauthorized
     *	sec_attr_svr_unavailable
     *	sec_attr_no_memory
     *
     */
     
    void sec_rgy_attr_sch_scan (
	[in]		sec_rgy_handle_t		context,
	[in]		sec_attr_component_name_t	schema_name,
	[in, out]	sec_attr_cursor_t		*cursor,
	[in]		unsigned32			num_to_read,
	[out]		unsigned32			*num_read,
	[out, size_is(num_to_read), length_is(*num_read)]
			sec_attr_schema_entry_t		schema_entries[],
	[out]		error_status_t			*st_p
	);
     

    /* s e c _ r g y _ a t t r _ s c h _ l o o k u p _ b y _ n a m e 
     *
     * Read a schema entry by name - useful for an interactive
     * editor.
     *	In Parameters:
     *		schema_name - identifies the schema object on which
     *			to perform this operation.
     *		attr_name - attribute name identifying the entry
     *
     *	Out Parameters:
     *		schema_entry - entry identified by attr_name. 
     *
     * Errors:
     *	sec_attr_sch_entry_not_found
     *	sec_attr_bad_name
     *	sec_attr_unauthorized
     *	sec_attr_svr_unavailable
     *	sec_attr_no_memory
     */
     
    void sec_rgy_attr_sch_lookup_by_name (
	[in]		sec_rgy_handle_t		context,
	[in]		sec_attr_component_name_t	schema_name,
	[in, string]	char				*attr_name,
	[out]		sec_attr_schema_entry_t		*schema_entry,
	[out]		error_status_t			*st_p
	);
     

    /* s e c _ r g y _ a t t r _ s c h _ l o o k u p _ b y _ i d
     *
     * Read a schema entry by ID.  Useful for 
     * programmatic access.
     *	In Parameters:
     *		schema_name - identifies the schema object on which
     *			to perform this operation.
     *		attr_id - attribute type uuid identifying the entry.
     *
     *	Out Parameters:
     *		schema_entry - entry identified by attr_id. 
     *
     * Errors:
     *	sec_attr_sch_entry_not_found
     *	sec_attr_unauthorized
     *	sec_attr_svr_unavailable
     *	sec_attr_no_memory
     */
     
    void sec_rgy_attr_sch_lookup_by_id (
	[in]	sec_rgy_handle_t		context,
	[in]	sec_attr_component_name_t	schema_name,
	[in]	uuid_t				*attr_id,
	[out]	sec_attr_schema_entry_t		*schema_entry,
	[out]	error_status_t			*st_p
	);


    /* s e c _ r g y _ a t t r _ s c h _ g e t _ a c l _ m g r s 
     *
     * Retrieve the acl_mgr_types that protect the objects
     * dominated by the named schema.  The returned acl_mgr_types
     * are valid for use in the acl_mgr_set field of a schema_entry
     * for the named schema.
     *
     * If num_acl_mgr_types is greater than size_used, this operation
     * should be called again with a bigger acl_mgr_types buffer.
     *
     *	In Parameters:
     *		schema_name - identifies the schema object on which
     *			to perform this operation.
     *		size_avail - size of the acl_mgr_types array
     *
     *	Out Parameters:
     *		size_used - number of acl_mgr_types returned
     *		num_acl_mgr_types - total number of acl_mgr_types
     *			supported for this schema.  
     *		acl_mgr_types - array containing 'size_used' 
     *			acl_mgr_type UUIDs.
     *
     * Errors:
     *	sec_attr_unauthorized
     *	sec_attr_svr_unavailable
     *	sec_attr_no_memory
     */
     
    void sec_rgy_attr_sch_get_acl_mgrs (
	[in]	sec_rgy_handle_t		context,
	[in]	sec_attr_component_name_t	schema_name,
        [in]	unsigned32			size_avail,
        [out]	unsigned32			*size_used,
        [out]	unsigned32			*num_acl_mgr_types,
        [out, size_is(size_avail), length_is(*size_used)]
		uuid_t				acl_mgr_types[],
	[out]	error_status_t			*st_p
	);


    /* s e c _ r g y _ a t t r _ s c h _ a c l m g r _ s t r i n g s
     *
     * Retrieve printable representations for each permission bit that the 
     * input acl_mgr_type will support.  There may be aliases for common
     * permission combinations - by convention simple entries should
     * appear at the beginning of the array, and combinations should at the
     * appear at the end.  When false the tokenize flag indicates that
     * permission printstrings are unambiguous and therefore printstrings
     * for various permissions can be concatenated.  When true, however,
     * this property does not hold and the strings should be tokenized
     * before input or output. 
     *
     * The acl_mgr_info string provides a name and
     * help info for the manager type as well as the complete set of
     * supported permission bits. total_num_printstrings is the total
     * number of acl printstrings supported by this acl manager type - if
     * it is greater than the size avail, this function should be invoked
     * again with a buffer of the appropriate size.
     *
     * If acl_mgr_type supports more than 32 permission
     * bits, multiple manager types can be used - one for each 32 bit wide
     * slice of permissions.  When this is the case the acl_mgr_type_chain
     * parameter is set to the uuid of the next manager type in the set.  The
     * final result for the chain returns uuid_nil in the manager_type_chain
     * parameter.
     *
     *	In Parameters:
     *		schema_name - identifies the schema object on which
     *			to perform this operation.
     *		acl_mgr_type - the UUID of the acl_mgr_type for which
     *			the printstrings are to be returned.
     *		size_avail - size of the printstrings array
     *
     *	Out Parameters:
     *		acl_mgr_type_chain - if not uuid_nil, identifies the
     *			next acl_mgr_type UUID in a chain supporting
     *			acl managers with more than 32 permission bits.
     *		acl_mgr_info - printstrings containing the name, help info,
     *			and complete set of supported permission bits
     *			for this acl_mgr.
     *		tokenize - if true, permission bit strings should be
     *			tokenized.
     *		total_num_permstrings -  the total number of permission 
     *			printstrings supported by this acl_mgr_type.
     *		size_used - number of perm printstrings returned
     *		permstrings - array containing the printstrings for
     *			each permission supported by this acl_mgr_type.
     *
     * Errors:
     *	sec_attr_unauthorized
     *	sec_attr_svr_unavailable
     *	sec_attr_no_memory
     *
     */
     void sec_rgy_attr_sch_aclmgr_strings (
	[in]		sec_rgy_handle_t	context,
	[in]		sec_attr_component_name_t schema_name,
        [in, ref]	uuid_t			*acl_mgr_type,   
        [in]		unsigned32		size_avail,
        [out]		uuid_t			*acl_mgr_type_chain,
        [out]		sec_acl_printstring_t	*acl_mgr_info,
        [out, ref]	boolean32		*tokenize,
        [out]		unsigned32		*total_num_printstrings,
        [out, ref]	unsigned32		*size_used,
        [out, size_is(size_avail), length_is(*size_used)]
			sec_acl_printstring_t	permstrings[],
	[out]		error_status_t		*st_p
    );

}
