
// @(#) 1.5 com/src/odscript/idl/cmgrsrvr.idl, odscript, od96nt, odnt9712d 10/31/96 12:43:59 [3/21/97 17:26:46]
// ===========================================================================
//
// Component manager Server
//
// Provides interface for management of the Component Registry.
//
// Implements the Registry using a platform specific format (INI files
// for OS/2 and Win NT/95, TBD for AIX).
//
// Interfaces provided to search the registry, add entries, remove entries
// get the information from an entry, get the information needed to
// create an instance of the class described by the registry, etc.
//
// ===========================================================================

#include <snglicls.idl>

#ifndef _ODTYPESM_
#include <ODTypesM.idl>
#endif

#ifndef _COMPONENTMANAGER_
#include <compmgr.idl>
#endif

#ifndef _COMPONENTMANAGERSERVER_
#define _COMPONENTMANAGERSERVER_

//==============================================================================
// Classes defined in this interface
//==============================================================================

interface ComponentManagerServer;

//==============================================================================
// Classes used by this interface
//==============================================================================

interface Component;

//==============================================================================
// Implementation Types
//==============================================================================

typedef somToken LinkedList;
typedef somToken ComponentLink;
typedef somToken HAB;
typedef somToken HINI;
typedef somToken HMTX;
typedef somToken HANDLE ;               // windows handle

//==============================================================================
// Class ComponentManager
//==============================================================================

interface ComponentManagerServer : SOMClass {

#ifdef __SOMIDL__

//---------------------------------------------------------------------------
//
// Function - CountComponents
//
// Inputs - A ComponentDescription block that specifies the search requirements
//              to be used to identify entries that are to be counted.
//
// Outputs - Returns a count of the number of entries that matched the
//              search conditions.
//
// Description - Searches the cached Component Registry information for items
//              which match the criteria specified by the input ComponentDescription.
//              Search algorithm will match entries as follows:
//                      1. If the entry in the ComponentDescription is NULL
//                         it 'matches' all entries in the Registry
//                      2. If the entry for Type, SubType or Manufacturer is
//                         not null, it 'matches' only if it is equal to the
//                         corresponding value in the registry.
//                      3. If the FlagsMask is not null, the flag bits implied
//                         by that mask that are specified in the input block
//                         must match the corresponding bits in the Registry
//
//---------------------------------------------------------------------------

ODULong          CountComponents(in ComponentDescription *plooking);

//---------------------------------------------------------------------------
//
// Function - FindNextComponent
//
// Inputs - plastFound - description of previously located registry entry
//          plooking   - description of search critera
//          pfound     - description block to receive info for a matched entry
//          Each of these inputs is a pointer to a ComponentDescription block.
//
// Outputs - Block indicated by pfound will be filled in with the Type, SubType
//           Flags and Manufacturer values for the matching entry.
//           Return value is zero if a match was found, non-zero if no match
//           or an error.
//
// Description - If the plastFound entry is not null, it is used to locate
//              a previously 'found' entry, by searching for an entry that
//              matches the Type and SubType specified in that block.  If
//              plastFound is NULL, the search will begin at the first
//              entry in the Registry.  The search uses plooking in the same
//              way as CountEntries above.  When a matching entry is found,
//              the Type, SubType, Manufacturer and Flags for that entry
//              are set into the block indicated by pfound.
//
//---------------------------------------------------------------------------

OSErr            FindNextComponent(in ComponentDescription *plastFound,
                                   in ComponentDescription *plooking,
                                   out ComponentDescription pfound);

//---------------------------------------------------------------------------
//
// Function - GetComponentInfo
//
// Inputs - ComponentDescription block that specifies the Registry entry
//          for which we want the string values.
//          Pointers to string pointers to receive the long string values
//          from the Registry entry identified.
//
// Outputs - If the specified entry is found, SOMAlloc is used to allocate
//           storage for each of the string values in that entry.  The
//           string value is then copied into that storage.  The caller must
//           use SOMFree to release the storage.
//           Returns zero if successful or non-zero if error occurs (not found,
//           or unable to allocate storage).
//
// Description - Locate the entry specified by ptheComponent (uses Type and
//              SubType values only).  If found, allocate storage to hold the
//              string values and initialize that storage with the strings.
//
//---------------------------------------------------------------------------

OSErr            GetComponentInfo(in ComponentDescription *ptheComponent,
                                  out string pcomponentClassName,
                                  out string pcomponentDLL,
                                  out string pcomponentName,
                                  out string pcomponentInfo);

//---------------------------------------------------------------------------
//
// Function - GetComponentRefcon
//
// Inputs - ComponentDescription block identifying the Type and SubType
//          of the Refcon to be accessed
//
// Outputs - Returns the component Refcon that has been placed in shared
//           storage associated with the Type and SubType specified.
//
// Description - Use the Type and SubType to construct the needed shared storage
//               access identifier.  Use that identifier to access the Refcon
//               stored earlier.
//
//---------------------------------------------------------------------------

ODSLong          GetComponentRefcon(in ComponentDescription *ptheComponent);

//---------------------------------------------------------------------------
//
// Function - SetComponentRefcon
//
// Inputs - ComponentDescription block identifying the Type and SubType
//          that identifies this Refcon.
//          Long integer that is the value for the Refcon.
//
// Outputs - Refcon is updated in storage with the specified value.
//
// Description - Use the Type and SubType specified to construct the shared
//               storage identifer for this component.  Use that key to set
//               the value of the associated Refcon to the value supplied.
//
//---------------------------------------------------------------------------

void             SetComponentRefcon(in ComponentDescription *ptheComponent,
                                    in ODSLong Refcon);

//---------------------------------------------------------------------------
//
// Function - OpenComponent
//
// Inputs - ComponenDescription block that specifies the requirements for the
//          component we wish to open.
//        - pointers to string values to receive the ClassName and DLL name for
//          the component.
//        - pointer to Unsigned long that will receive the version information
//          for the component
//
// Outputs - Strings will be allocated and initialized for the ClassName and
//           DLL name and the version number will be set.  The caller must
//           release the storage allocated for the strings using SOMFree.
//           Returns zero if successful or nonzero if no matching entry was
//           found in the Registry.
//
// Description - Uses the values in the ComponentDescription to locate a
//               matching entry (see CountEntries for search algorithm).
//               If a match is found, allocates storage for the ClassName and
//               DLL name and sets the string values.
//               Note - the Caller is expected to use these values to actually
//               create an instance of the component.
//
//---------------------------------------------------------------------------

void             OpenComponent(in ComponentDescription *ptheComponent,
                               out string pcomponentClassName,
                               out string pcomponentClassDLL,
                               out ODULong pcomponentVersion);

//---------------------------------------------------------------------------
//
// Function - OpenDefaultComponent (a misnomer)
//
// Inputs - Type and SubType codes (as Unsigned integers), pointers to
//          locations for the ClassName and DLL name and Version values
//
// Outputs - Storage is allocated for the ClassName and DLL name and the
//           string values are set.  Caller must use SOMFree to release that
//           storage as appropriate.
//
// Description - This function is misnamed.  It really does a search for
//               the Registry entry that matches the Type and SubType specified
//               and then proceeds just as OpenComponent above.  There is no
//               concept of 'default' implemented.
//
//---------------------------------------------------------------------------

void             OpenDefaultComponent(in OSType componentType,
                                      in OSType componentSubType,
                                      out string pcomponentClassName,
                                      out string pcomponentClassDLL,
                                      out ODULong pcomponentVersion);

//---------------------------------------------------------------------------
//
// Function - InstallComponent
//
// Inputs - ComponentRegistryData block that contains the complete description
//          for a new Compoent Registry entry.
//
// Outputs - Returns zero if successful or non-zero if an error occurs.  It
//           will treat a pre-existing entry with the same Type and Subtype as
//           an error and will not modify that entry.
//
// Description - Will create a new entry in the Registry to reflect the data
//               specified in the Data block. On OS/2 and Windows NT/95 the
//               registry is implemented using INI files with the following
//               structure:
//                   [COMPONENT]    - component section
//                     TYPESTYP     - zero or more Type/SubType values as
//                                    keywords with no value associated.
//                   [TYPESTYP]     - a section for each of the values in
//                                    the set of Type/SubType values listed
//                                    under component
//                     TYPE = xxxx  - Keyword value pairs for each of the
//                                    component information items.  Type,
//                                    SubType and Manufacturer are strings of
//                                    less than 5 characters which will be
//                                    mashed into an Unsigned Long in the
//                                    inernal representation (with blank
//                                    padding if needed).  The Flags and Version
//                                    values will be represented as hexadecimal
//                                    unsigned integer values.  The other fields
//                                    will be simple strings.  (ClassName, DLL
//                                    name, Name and Info.
//               Note - AIX implementation is still to be done.
//
//---------------------------------------------------------------------------

OSErr            InstallComponent(in ComponentRegistryData *ptheData);

//---------------------------------------------------------------------------
//
// Function - UninstallComponent
//
// Inputs - Type and SubType values that specify the component to be deleted
//
// Outputs - Returns zero if successful or nonzero if Failure.
//
// Description - For OS/2 and Windows NT/95, uses the INI file format
//               described above (InstallComponent).  Will remove the
//               entry for the Type/SubType and will remove the Type/SubType
//               entry under 'COMPONENTS' at the top level.
//
//---------------------------------------------------------------------------

OSErr            UninstallComponent(in OSType componentType,
                                    in OSType componentSubType);

implementation {

#ifdef _PLATFORM_OS2_
        HAB         hab;                // application block handle
        HINI        hini;               // INI handle
        HMTX        hmtxCMGR;           // mutex control handle
#endif
#ifdef _PLATFORM_NT_
        char *      inifilename ;       // INI filename
        HANDLE      hmtxCMGR ;          // mutex handle
#endif

        LinkedList *componentRegistryList;

        majorversion = 1;
        minorversion = 0;
        functionprefix = CMGRSRV_;
        metaclass = SOMMSingleInstance;
        releaseorder :  CountComponents,
                        FindNextComponent,
                        GetComponentInfo,
                        GetComponentRefcon,
                        SetComponentRefcon,
                        OpenComponent,
                        OpenDefaultComponent,
                        InstallComponent,
                        UninstallComponent,
                        FindComponent;
        somDefaultInit: override, init;
        somDestruct: override;

        passthru C_xih = "#define REQUEST_TIMEOUT  30 * 1000  // 30 seconds;"
                         "#define COMPONENTS     \"COMPONENTS\"   "
                         "#define COMP_CLASS     \"COMP_CLASS\"   "
                         "#define COMP_TYPE      \"COMP_TYPE\"    "
                         "#define COMP_SUBTYPE   \"COMP_SUBTYPE\" "
                         "#define COMP_MFTR      \"COMP_MFTR\"    "
                         "#define COMP_FLAGS     \"COMP_FLAGS\"   "
                         "#define COMP_VERSION   \"COMP_VERSION\" "
                         "#define COMP_DLL       \"COMP_DLL\"     "
                         "#define COMP_NAME      \"COMP_NAME\"    "
                         "#define COMP_INFO      \"COMP_INFO\"    "
                         "#define COMP_REFCON    \"\\SHAREMEM\\COMP_REFCON\"  "
                         "#define CMGR_INI_FILENAME   \"opendoc.ini\" " ;
        passthru C_xh  = "#include <cmgrutil.h>                   ";
        dllname = "oddsscr.dll";
};

#endif

};

#endif
