//#  @(#) 1.38 src/somk/somobj.idl, somk.so, som3.0 7/11/96 14:02:07 [12/22/96 21:12:52]

// 96F8647, 96F8648, 96F8850 (C) Copyright IBM Corp. 1992, 1994
// All Rights Reserved
// Licensed Materials - Property of IBM

//  SOMObject: System Object Model root class

#ifndef somobj_idl
#define somobj_idl

//# legacy support macros
//# When somobj.idl is ported to platforms that don't
//# have requirements for legacy support, these macros
//# should not be defined.

#ifndef SOM_NO_LEGACY1
#define SOMLEGACY1
#endif

#define SOMLEGACY2

#if defined (SOMLEGACY1) || defined (SOMLEGACY2)
#define SOMLEGACY1_OR_2
#endif

#if defined (SOMLEGACY1) && defined (SOMLEGACY2)
#define SOMLEGACY1_AND_2
#endif


interface SOMClass;
interface SOMObject;

/*
 *  Define a value large enough to be used in typedefs for character
 *  arrays that need to be able to hold the largest legal file name.
 */
#define FILENAME_MAX 260

/*
 *  IDL does not provide for the use of the type "int".
 *  Although the mapping of a user-defined type named "int" to the
 *  IDL type long, given here, is both binary and source compatible
 *  on AIX and OS/2 2.x, it is still bad form, since the C type "int"
 *  can vary from platform to platform.  This is here only for migration
 *  of OIDL to IDL.  All new IDL files should explicitly select long or
 *  short (as appropriate) instead of "int."
 */
typedef long int;

/*
 *  The following types are commonly used in C programming
 */
typedef octet uchar_t;
typedef unsigned long size_t;

/*
 * This allows use of the type name "signed_char" in SOM IDL.
 * The file sombtype.h defines this to be unsigned char.
 */
typedef octet signed_char;

/*
 *  We define SOMFOREIGN as an anchor within the IDL type system for
 *  "foreign" types that are not expressible in IDL.  Foreign types
 *  can be used at a class implementer's discretion, but we discourage
 *  their use except within "private" sections of an IDL definition.
 *  If you decide to define a foreign type, you must do so by setting
 *  up a typedef for it and then supplying an "impctx" modifier (within
 *  your implementation section) that designates the implementation
 *  context where your type is understood.  You can also optionally
 *  supply a "length" modifier that indicates the number of bytes
 *  needed to hold an instance of the foreign type.  The FILE type
 *  below is an example of a foreign type useful in C programming.
 */

#ifndef _SOMFOREIGN_DEFINED_
  #define _SOMFOREIGN_DEFINED_
  #ifdef __SOMIDL__
    typedef void * SOMFOREIGN;
  #else
    typedef unsigned long SOMFOREIGN;
  #endif /* __SOMIDL__ */
#endif /* !_SOMFOREIGN_DEFINED_ */

typedef SOMFOREIGN FILE;
#pragma modifier FILE: impctx = C, length = 0;

/*
 *  "va_list" is used to represent a standard parameter list constructed
 *  by a caller for functions or methods that can accept a variable number
 *  of arguments.
 */
typedef SOMFOREIGN va_list;
#pragma modifier va_list: impctx = C;

/*
 *  "SOMHANDLE" is used within SOM to represent arguments whose value
 *  is uninterpreted.
 */
typedef SOMFOREIGN SOMHANDLE;
#pragma modifier SOMHANDLE: impctx = SOM;
typedef void* somToken;

/*
 *  "somId" is used to refer to the efficient case-insensitive string
 *  representation used by many SOM run-time methods.
 */
typedef SOMFOREIGN somId;
#pragma modifier somId: impctx = "SOM,static(somIdMarshal,0)";

/*
 *  Kinds of TypeCodes, per CORBA 1.1, p.139
 */
enum TCKind {
    tk_null, tk_void,
    tk_short, tk_long, tk_ushort, tk_ulong,
    tk_float, tk_double, tk_boolean, tk_char,
    tk_octet, tk_any, tk_TypeCode, tk_Principal, tk_objref,
    tk_struct, tk_union, tk_enum, tk_string,
    tk_sequence, tk_array,

    /* SOM extensions follow: */
    tk_pointer, /* tk_pointer takes a parameter list with 1 argument:  */
                /* tk_pointer {TypeCode} - The TypeCode describes the  */
                /* type that the pointer references.                   */
    tk_self,    /* tk_self takes a parameter list with 1 argument:     */
                /* tk_self {name} - The name refers to an enclosing    */
                /* struct or union.  This type, when combined with     */
                /* tk_pointer above, permits the existence of self-    */
                /* -referential pointers in a struct or union.         */
    tk_foreign  /* tk_foreign takes a parameter list with 2 arguments: */
                /* tk_foreign {context, length} - The context is a     */
                /* string that designates an implementation domain     */
                /* where the foreign type is understood.  The length   */
                /* parameter is optional, but if supplied indicates    */
                /* the size of an instance of the type.                */
};

#ifdef SOMLEGACY1
/*
 *  Types defined only for compatibility with SOM Release 1
 */
typedef char integer1;
typedef short integer2;
typedef unsigned short uinteger2;
typedef long integer4;
typedef unsigned long uinteger4;
typedef float float4;
typedef double float8;
typedef string zString;                 /* NULL terminated string */
typedef string fString;                 /* non-terminated string  */
#endif

// The following typedefs are based on somapi.h and somcorba.h, which
// define the published API form of internal SOM data structures.
// We provide these typedefs here in their IDL form primarily to
// satisfy the IDL compiler, which requires that all methods declared
// using IDL have known argument types. Also, as a result of this
// approach, the interface repository will contain the "public" types
// for SOM internal data structures -- not the actual types.

/* -- Special procedure pointer types */
typedef somToken somMethodProc;
typedef somToken somMethodPtr;

/* -- Public Method Table Structure */
struct somMethodTab {
    SOMClass classObject;
};

/*  -- Public Object Instance Structure */
struct SOMAny {
    somMethodTab  *mtab;
};

/* -- Public Method and Data Tokens */
typedef somToken somMToken;
typedef somToken somDToken;

/* -- Public InitCtrl Structs -- */
struct somGenericCtrl {
        somToken mask;
        somToken info;
        long     infoSize;
        somToken ctrlInfo;
};
typedef somGenericCtrl som3InitCtrl;
typedef somGenericCtrl som3DestructCtrl;
typedef somGenericCtrl som3AssignCtrl;

#ifdef SOMLEGACY2
/* SOMLEGACY support for old IDL */
typedef somToken somInitCtrl;
typedef somToken somDestructCtrl;
typedef somToken somAssignCtrl;
#endif

/* -- MethodData structure */
typedef struct somMethodDataStruct {
    somId id;
    long type;                    /* 0=static, 1=dynamic, 2=nonstatic */
    somId descriptor;             /* for use with IR interfaces */
    somMToken mToken;             /* NULL for dynamic methods */
    somMethodPtr method;          /* depends on resolution context */
    somToken *shared;
} somMethodData;

/* -- For building lists of class objects */
struct somClassList {
    SOMClass cls;
    somClassList *next;
};
typedef somClassList *somClasses;

typedef somToken somObjects;

/* -- For building lists of method tables */
struct somMethodTabList {
    somMethodTab      *mtab;
    somMethodTabList  *next;
};
typedef somMethodTabList *somMethodTabs;
typedef somMethodTabList *somParentMtabStructPtr;


typedef octet *somBooleanVector;

// actual exception enum constants found in somcorba.h
enum exception_type { NO_EXCEPTION, USER_EXCEPTION, SYSTEM_EXCEPTION };

struct Environment {
    exception_type major;  // use somcorba.h exception_type values
    octet opaque_data[12]; // #2990
};


//
//
//-------------------------------------------------------------
// SOMObject Interface Definition
//


interface SOMObject
// This is the SOM root class, all SOM classes must be descended from
// <SOMObject>. <SOMObject> has no instance data so there is no
// per-instance cost to to being descended from it.

{

  //### Typedefs

  // a sequence of SOM Objects
  typedef sequence <SOMObject> SOMObjectSequence;

  // a sequence of booleans.
  typedef sequence <octet> BooleanSequence;

  // a structure to describe an object-related offset, and
  // a sequence of class-related offsets
  struct somObjectOffset {
     SOMObject obj;
     long     offset;
  };
  typedef sequence <somObjectOffset> somObjectOffsets;


  //###  Initialization / Termination

  void somDefaultInit(in som3InitCtrl *ctrl);
  // A default initializer for a SOM object. Passing a null ctrl
  // indicates to the receiver that its class is the class of the
  // object being initialized, whereby the initializer will determine
  // an appropriate control structure.

  void somDestruct(in octet doFree, in som3DestructCtrl *ctrl);
  // The default destructor for a SOM object. A nonzero <doFree>
  // indicates that the object storage should be freed by the
  // object's class (via somDeallocate) after uninitialization.
  // As with somDefaultInit, a null ctrl can be passed.

  void somDefaultCopyInit(in som3InitCtrl *ctrl, in SOMObject fromObj);
  // A default copy constructor. Use this to make copies of objects for
  // calling methods with "by-value" argument semantics.

  SOMObject somDefaultAssign(in som3AssignCtrl *ctrl, in SOMObject fromObj);
  // A default assignment operator. Use this to "assign" the state of one
  // object to another.

  //### etc.

  void somDefaultConstCopyInit(in som3InitCtrl *ctrl, in SOMObject fromObj);
  // A default copy constructor that uses a const fromObj.

  void somDefaultVCopyInit(in som3InitCtrl *ctrl, in SOMObject fromObj);
  // A default copy constructor that uses a volatile fromObj.

  void somDefaultConstVCopyInit(in som3InitCtrl *ctrl, in SOMObject fromObj);
  // A default copy constructor that uses a const volatile fromObj.

  SOMObject somDefaultConstAssign(in som3AssignCtrl *ctrl,
                                  in SOMObject fromObj);
  // A default assignment operator that uses a const fromObj.

  SOMObject somDefaultVAssign(in som3AssignCtrl *ctrl, in SOMObject fromObj);
  // A default assignment operator that uses a volatile fromObj.

  SOMObject somDefaultConstVAssign(in som3AssignCtrl *ctrl,
                                   in SOMObject fromObj);
  // A default assignment operator that uses a const volatile fromObj.

#ifdef SOMLEGACY1_OR_2
  void somInit();
  // Obsolete but still supported. Override somDefaultInit instead of somInit.

  void somUninit();
  // Obsolete but still supported. Override somDestruct instead of somUninit.
#endif

  void somFree();
  // The default implementation just calls somDestruct.


  //### Access

  SOMClass somGetClass();
  // Return the receiver's class.

  string somGetClassName();
  // Return the name of the receiver's class.

  long somGetSize();
  // Return the size of the receiver.

  //### Testing Group

  boolean somIsA(in SOMClass aClassObj);
  // Returns 1 (true) if the receiver responds to methods
  // introduced by <aClassObj>, and 0 (false) otherwise.

  boolean somIsInstanceOf(in SOMClass aClassObj);
  // Returns 1 (true) if the receiver is an instance of
  // <aClassObj> and 0 (false) otherwise.

  boolean somRespondsTo(in somId mId);
  // Returns 1 (true) if the indicated method can be invoked
  // on the receiver and 0 (false) otherwise.

  //### Dynamic

  boolean somDispatch(out somToken retValue,
                   in somId methodId,
                   in va_list ap);
  // This method provides a generic, class-specific dispatch mechanism.
  // It accepts as input <retValue> a pointer to the memory area to be
  // loaded with the result of dispatching the method indicated by
  // <methodId> using the arguments in <ap>. <ap> contains the object
  // on which the method is to be invoked as the first argument.
  //
  // Default redispatch stubs invoke this method.

  boolean somClassDispatch(in SOMClass clsObj,
                        out somToken retValue,
                        in somId methodId,
                        in va_list ap);
  // Like somDispatch, but method resolution for static methods is done
  // according to the clsObj instance method table.


  boolean somCastObj(in SOMClass castedCls);
  // Changes the behavior of the target object to that implemented
  // by castedCls. This is possible when all concrete data in castedCls
  // is also concrete in the true class of the target object.
  // Returns true (1) on success, and false (0) otherwise.

  boolean somResetObj();
  // reset an object to its true class. Returns true always.


  //### Development Support

  SOMObject somPrintSelf();
  // Uses <SOMOutCharRoutine> to write a brief string with identifying
  // information about this object.  The default implementation just gives
  // the object's class name and its address in memory.
  // <self> is returned.

  void somDumpSelf(in long level);
  // Uses <SOMOutCharRoutine> to write a detailed description of this object
  // and its current state.
  //
  // <level> indicates the nesting level for describing compound objects
  // it must be greater than or equal to zero.  All lines in the
  // description will be preceeded by <2*level> spaces.
  //
  // This routine only actually writes the data that concerns the object
  // as a whole, such as class, and uses <somDumpSelfInt> to describe
  // the object's current state.  This approach allows readable
  // descriptions of compound objects to be constructed.
  //
  // Generally it is not necessary to override this method, if it is
  // overriden it generally must be completely replaced.

  void somDumpSelfInt(in long level);
  // Uses <SOMOutCharRoutine> to write in the current state of this object.
  // Generally this method will need to be overridden.  When overriding
  // it, begin by calling the parent class form of this method and then
  // write in a description of your class's instance data. This will
  // result in a description of all the object's instance data going
  // from its root ancestor class to its specific class.









#ifdef __SOMIDL__
  implementation {
    releaseorder:
#ifdef SOMLEGACY1_OR_2
        somInit,
        somUninit,
#else
                somoUnused1,
                somoUnused2,
#endif
        somFree,
        somDefaultVCopyInit,
        somGetClassName,
        somGetClass,
        somIsA,
        somRespondsTo,
        somIsInstanceOf,
        somGetSize,
        somDumpSelf,
        somDumpSelfInt,
        somPrintSelf,
        somDefaultConstVCopyInit,
#ifdef SOMLEGACY1
                somoPrivate1,
                somoPrivate2,
                somoPrivate3,
                somoPrivate4,
#else
                        somoUnused3,
                        somoUnused4,
                        somoUnused5,
                        somoUnused6,
#endif
        somDispatch,
        somClassDispatch,
        somCastObj,
        somResetObj,
        somDefaultInit,
        somDestruct,
                somoPrivate5,
                somoPrivate6,
        somDefaultCopyInit,
        somDefaultConstCopyInit,
        somDefaultAssign,
        somDefaultConstAssign,
        somDefaultVAssign,
        somDefaultConstVAssign,
                somoPrivate7,
                somoPrivate8,
                somoPrivate9,
                somoPrivate10,
                somoPrivate11,
                somoPrivate12,
                somoPrivate13,
                somoPrivate14;


    // Class Modifiers
    functionprefix = somo_;
    callstyle = oidl;
    externalstem = somob;
    majorversion = 1;
    minorversion = 7; // for Stingray kernel
    filestem = somobj;
    dllname = "som.dll";

    // Public Method Modifiers
    somDefaultInit: init;
    somDefaultCopyInit: init;
    somDefaultVCopyInit: init;
    somDefaultConstCopyInit: init;
    somDefaultConstVCopyInit: init;
    somGetClassName: dual_owned_result;

  };
#endif /* __SOMIDL__ */
};

#endif  /* somobj_idl */
