-- IDL module extracted from ITU-T Q.816.1 (08/2001)

/* This IDL code is intended to be stored in a file named "itut_q816_1.idl"
located in the search path used by IDL compilers on your system. */

#ifndef ITUT_Q816_1_IDL
#define ITUT_Q816_1_IDL

#include <CosNaming.idl>
#include <itut_q816.idl>
#include <itut_x780.idl>

#pragma prefix "itu.int"


module itut_q816 {

// IMPORTED TYPES

	// Types imported from CosNaming
	typedef CosNaming::NamingContext NamingContext;
	typedef CosNaming::Istring KindType;

// INTERFACES

	/** The Name Iterator interface is used to retrieve the results from
	a Containment interface getContained or getContainedByKind operation 
	using the iterator design pattern. */

	interface NameIterator {

		/** This method is used to retrieve the next "howMany" results 
		in the result set. 
		@param howMany	The maximum number of items to be returned in
					the results. Fewer may be returned if that is
					all that is left, or to balance delay
					with efficiency.
		@param results	The next batch of results.
		@return		True if there are more results after those
					being returned. If the return value is true
					the results set should not be empty, as this
					forces the client to poll for results.
					Instead the call should block.
		*/

		boolean getNext(in unsigned short howMany,
			out NameSetType results)
			raises (itut_x780::ApplicationError);

		/** This method is used to destroy the iterator and release its 
		resources. The iterator, though, is automatically destroyed 
		after the last results are returned, and may be destroyed if
		unused for an unreasonably long period. */

		void destroy();

	}; // end of interface NameIterator


	/** The Containment Service interface is used to retrieve from a 
	managed system information about the containment relationships between
	the managed objects on the system. Containment relationships are 
	represented through names. An object that is contained by another
	object is named relative to it. All managed object names are 
	registered with the Containment Service. */

	interface Containment {

		/** This method is used to check to see if a name is registered
		with the Containment Service. 
		@param name		The name to check to see if it is registered
		@return			True if the name is registered. All components
						of the submitted name match a registered name.
		*/

		boolean exists (in NameType name)
			raises (itut_x780::ApplicationError);

		/** This method is used to retrieve the names of the objects
		contained under a target object. An object is contained by the 
		target object if its name begins with all but the last 
		component of the target object's name. The iterator design 
		pattern is used to support returning potentially large numbers 
		of names. If the name does not exist, an application error
		exception is raised indicating an invalidParameter (See X.780
		for application error exception codes.)
		@param name		The name of the object for which the contained
						objects are sought. Need not contain the final
						name component (where ID=Object, kind = facade)
		@param scope		The scope is used to identify what part of
						the tree of contained objects to return.
		@param howMany		The maximum number of names to return in the 
						results. If there are more than howMany names,
						an iterator must be used to return the rest.
		@param iterator		A reference to an iterator to return additional 
						results. If all results are returned in 
						response to the call, this shall be null.
		@return			The names of the contained objects. Must 
						always contain the final name component.
		*/

		NameSetType getContained (in NameType name,
			in ScopeType scope,
			in unsigned short howMany,
			out NameIterator iterator)
			raises (itut_x780::ApplicationError);

		/** This method is used to retrieve the names of the objects
		contained under a target object that match a specific kind. 
		An object's kind is the value of the kind field in the 
		next-to-last component of its name. This field must match
		the submitted kind value.
		@see getContained
		@param name		The name of the object for which the contained
						objects are sought. Need not contain the final
						name component (where ID=Object, kind = facade)
		@param scope		The scope is used to identify what part of
						the tree of contained objects to return.
		@param kind		The value that must be matched in the kind
						field of the next-to-last component in the
						names returned.
		@param howMany		The maximum number of names to return in the 
						results. If there are more than howMany names,
						an iterator must be used to return the rest.
		@param iterator		A reference to an iterator to return additional 
						results. If all results are returned in 
						response to the call, this shall be null.
		@return			The names of the contained objects. Must 
						always contain the final name component.
		*/

		NameSetType getContainedByKind (in NameType name,
			in ScopeType scope,
			in KindType kind,
			in unsigned short howMany,
			out NameIterator iterator)
			raises (itut_x780::ApplicationError);
					
	};	// end of interface Containment 


	/** The Containment Component interface extends the Containment 
	interface to add functions used internally to a managed system.
	*/

	interface ContainmentComponent : Containment {

		/** This method is used to register a local root naming context
		with the terminator service. Re-registering a name results in
		the newly supplied reference subsequently being used by the
		service, if it needs to access the root naming context. */

		void registerLocalRoot 	(in NameType name,
							in NamingContext localRoot)
							raises (itut_x780::ApplicationError);

		/** This method is used to remove a local root naming context
		registration. */

		void unregisterLocalRoot (in NameType name)
			raises (itut_x780::ApplicationError);

		/** This method is used to add a name to the Containment 
		Service. The name must be relative to an existing name or
		local root name. This means all but the last two name 
		components of the submitted name must match all but the last 
		name component of a registered name. Also, the name must
		be unique. This means that all but the last name component
		of the submitted name cannot match all but the last name
		component of any other registered name. If the name has
		no relative superior object registered, the name is not
		registered and a create error exception is raised with the 
		cause set to badName. If the name is not unique, the name
		is not registered and a create error exception is raised
		with the cause set to duplicateName. (See X.780 for
		create error exeption codes.)
		@param name	The name to be added.
		*/

		void addName (in NameType name)
			raises (itut_x780::ApplicationError, 
				itut_x780::CreateError);

		/** This method is used to remove a name from the Containment
		Service. There must be no contained names registered with
		the Containment service when a name is removed. This means 
		there must be no other names beginning with all but the last 
		name component of the name to be removed. If there are, the
		name is not removed and a DeletError exception is raised with
		the cause set to containsObjects (see X.780). If the name
		does not exist, an application error is raised with the
		cause set to invalidParameter (See X.780).
		@param name	The name to be removed.
		*/

		void removeName	(in NameType name)
			raises 	(itut_x780::ApplicationError, 
					 itut_x780::DeleteError);


	};	// end of interface ContainmentComponent 

}; // end of module itut_q816

#endif // end of #ifndef ITUT_Q816_1_IDL