//#
//#  COMPONENT_NAME: somi
//#
//#  ORIGINS: 27
//#
//#
//#   25H7912  (C)  COPYRIGHT International Business Machines Corp. 1992,1996,1996 
//#  All Rights Reserved
//#  Licensed Materials - Property of IBM
//#  US Government Users Restricted Rights - Use, duplication or
//#  disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
//#
//#  @(#) 2.9.1.4 src/somi/ir/somir/containr.idl, somi.corba, som3.0 12/26/95 16:35:29 [12/22/96 21:12:27]


//#  Container: CORBA Interface for container objects

#ifndef containr_idl
#define containr_idl

#include <somobj.idl>


#ifndef containd_idl
  interface Contained;
  typedef string Identifier;
#endif /* containd_idl */

interface Container : SOMObject
//
// CORBA 1.1, 7.5.1, p.131
//
// Container is a generic interface that is common to all of the
// SOM CORBA-compliant Interface Repository (IR) objects that can
// be used to hold or contain other objects.  The different types
// of Container objects are: ModuleDefs, InterfaceDefs, and OperationDefs,
{
    typedef string InterfaceName;
    //
    // Valid values for InterfaceName are limited to the following set:
    //	 {"AttributeDef", "ConstantDef", "ExceptionDef", "InterfaceDef",
    //	  "ModuleDef", "ParameterDef", "OperationDef", "TypeDef", "all"}

    struct ContainerDescription {
	Contained  contained_object;
	Identifier name;
	any	   value;
    };

    sequence<Contained> contents(in InterfaceName limit_type,
				 in boolean exclude_inherited);
    // Returns a list of objects contained by the receiving object.
    // This operation is used to navigate thru the hierarchy of objects.
    // Starting with the Repository object, use this operation to list
    // all of the objects in the Repository, then all of the objects
    // within the ModuleDef objects, then all of the objects in the
    // InterfaceDefs, etc.
    //
    // If restrict_type is set to "all", objects of all interface types
    // are returned, otherwise only objects of the requested interface type
    // will be returned.  If exclude_inherited is set to TRUE, inherited
    // objects, if any, will not be returned.
    //
    // You are responsible for freeing the contents of the returned
    // sequence when you are finished with it.	Use a code fragment
    // similar to the following to free it:
    //
    //	  if (containedSeq._length)
    //	      long i;
    //	      for(i=0; i<containedSeq._length; i++)
    //		SOMObject_somFree(containedSeq._buffer[i]);
    //	      SOMFree (containedSeq._buffer);

    sequence<Contained> lookup_name(in Identifier search_name,
				    in long levels_to_search,
				    in InterfaceName limit_type,
				    in boolean exclude_inherited);
    // Locates an object by name within the receiving object, or within
    // objects contained in the receiving object.  Search_name specifies
    // the name of the object to be found.  Levels_to_search controls
    // whether the lookup is constrained to the receiving object or
    // whether it includes objects contained withing the receiving object.
    // (Set levels_to_search to -1 to search the receiver and all contained
    // objects, -- set it to 1 to search the receiver only.)  If
    // limit_type is set to "all", objects of all interface types
    // are returned, otherwise only objects of the requested interface type
    // will be returned.  Only the values "AttributeDef", "ConstantDef",
    // "ExceptionDef", "InterfaceDef", "ModuleDef", "ParameterDef",
    // "OperationDef", "TypeDef", or "all" may be specified for limit_type.
    // If exclude_inherited is set to TRUE, inherited objects will not be
    // included in the returned sequence.
    //
    // You are responsible for freeing the contents of the returned
    // sequence when you are finished with it.	Use a code fragment
    // similar to the following to free it:
    //
    //	  if (containedSeq._length)
    //	      long i;
    //	      for(i=0; i<containedSeq._length; i++)
    //		SOMObject_somFree(containedSeq._buffer[i]);
    //	      SOMFree (containedSeq._buffer);

    sequence<ContainerDescription> describe_contents(in InterfaceName limit_type,
						     in boolean exclude_inherited,
						     in long max_returned_objs);
    // Combines the "contents" operation and the "describe" operation.  For
    // each object returned by the contents operation, the description of
    // the object is returned by invoking its "describe" operation.
    //
    // Max_returned_objs can be used to limit the number of objects that can
    // be returned.  If max_returned_objs is set to -1, results for all
    // contained objects will be returned.
    //
    // Note: You should SOMFree result._buffer when you are done with it
    // as well as result._buffer[x].value._value !

#ifdef __SOMIDL__
  implementation {
      releaseorder: contents, lookup_name, describe_contents
		  ;

      //# Class Modifiers
      callstyle = idl;
      majorversion = 2;
      minorversion = 3;
      filestem = containr;
      dllname = "somir.dll";

      passthru C_h =
	""
	"    #include <somtcnst.h>"
	"    #include <stdio.h>"
	"    #include <somir.h>"
	"    #include <containd.h>"
	"";
      passthru C_xh =
	""
	"    #include <somtcnst.xh>"
	"    #include <stdio.h>"
	"    #include <somir.xh>"
	"    #include <containd.xh>"
	"";

      //# Method Modifiers
      somDefaultInit: override, init;
      somDestruct: override;
      somDumpSelf: override;
      somDumpSelfInt: override;
#if defined __SOM_KERNEL_LEVEL && __SOM_KERNEL_LEVEL >= 250
      describe_contents: dual_owned_result;
#else
      contents: caller_owns_result;
      lookup_name: caller_owns_result, caller_owns_parameters="search_name";
#endif

  };
#endif /* __SOMIDL__ */
};

#endif	/* containr_idl */
