
// @(#) 1.3 com/src/odscript/idl/compmgr.idl, odscript, od96nt, odnt9712d 10/31/96 12:44:07 [3/21/97 17:26:47]
// ===========================================================================
//
// Component manager
//
// Component Manager (as opposed to Component Manager Server) will reside in
// the users storage and will communicate with the Server.  It is possible
// that the server will actually be 'remote' or at least in a separate process.
// though that is not in fact implemented at this time.
//
// Provides interface for management of the Component Registry.
//
// Provides the services needed in the current process to actuall create
// an instance of a Component based on information from the Server.
//
// Interfaces provided to search the registry, add entries, remove entries
// get the information from an entry, create an instance of a Component, etc
//
// ===========================================================================

#ifndef _COMPONENT_
#include <comp.idl>
#endif

#ifndef _COMPONENTMANAGER_
#define _COMPONENTMANAGER_

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

interface ComponentManager;
interface M_ComponentManager;

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

interface Component;

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

#if defined(__SOMIDL__) && defined(EMIT_COMPMGR_TYPES)
#pragma somemittypes on
#endif

typedef unsigned long OSType;

struct ComponentDescription {
        OSType  componentType;
        OSType  componentSubType;
        OSType  componentManufacturer;
        ODULong componentVersion ;
        ODULong componentFlags;
        ODULong componentFlagsMask;
};

const   ODULong CMGR_MAX_STRING    = 256;

typedef char CMGRString[CMGR_MAX_STRING];

struct ComponentRegistryData {
        OSType        componentType;
        OSType        componentSubType;
        OSType        componentManufacturer;
        ODULong       componentFlags;
        ODULong       componentVersion;
        CMGRString    componentDLL;           // dll name string
        CMGRString    componentClassName;     // som class name
        CMGRString    componentName;          // name string
        CMGRString    componentInfo;          // info string
};

#if defined(__SOMIDL__) && defined(COMPMGR_EMIT_TYPES)
#pragma somemittypes off
#endif

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

interface M_ComponentManager : SOMClass {

#ifdef __SOMIDL__


implementation {

        Environment    ev;

        majorversion = 1;
        minorversion = 0;
        functionprefix = M_CMGR_;
        releaseorder : Reserved1;
        somDefaultInit: override, init;
        somDestruct: override;
        dllname = "oddsscr.dll";
};

#endif

};

interface ComponentManager : SOMObject {

//---------------------------------------------------------------------------
//
// Function - CountComponents
//
// Inputs - pointer to Component Description block that specifies the
//          components to be counted.
//
// Outputs - Count of matching Components as returned by the server.
//
// Description - Invokes the corresponding server method to compute the count
//
//---------------------------------------------------------------------------

ODULong      CountComponents(in ComponentDescription *plooking);

//---------------------------------------------------------------------------
//
// Function - FindNextComponent
//
// Inputs - pointers to three Component Description blocks.  plastFound (if
//          not null) indicates the Type and SubType of the last Component
//          found and thus controls where the search continues.  plooking
//          specifies the search criteria, and pfound will receive the Type
//          SubType, Flags and Manufacturer values for a matching entry
//
// Outputs - Returns zero if successful or non-zero if an error or no matching
//           entry was found.
//
// Description - The corresponding server function is used to do the search.
//
//---------------------------------------------------------------------------

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

//---------------------------------------------------------------------------
//
// Function - GetComponentInfo
//
// Inputs - pointer to a ComponentDescription block that specifies the Type and
//          SubType of the Component for which information is requested.
//          Pointers to a CMGRString for each of the values being requested -
//          ClassName, DLL name, Name and Info.  Any of these pointers may
//          be null.
//
// Outputs - If the search is successful, the indicated CMGRString areas will
//           be set to reflect the string value returned by the server.
//
// Description - The corresponding server routine is used to get the
//              information. The storage allocated by the server is released
//              after the information is copied to the target area.
//
//---------------------------------------------------------------------------

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

//---------------------------------------------------------------------------
//
// Function - GetComponentRefcon
//
// Inputs - ComponentDescription block that specifies the Type and SubType
//              of the Component for which the Refcon is to be accessed.
//
// Outputs - Returns the Refcon value returned by the server
//
// Description - The server will access the Refcon from shared storage based
//              on the Type/SubType passed in.  Note Only OS/2 is currently
//              fully implemented.
//
//---------------------------------------------------------------------------

ODSLong      GetComponentRefcon(in ComponentDescription *ptheComponent);

//---------------------------------------------------------------------------
//
// Function - SetComponentRefcon
//
// Inputs - ComponentDescription block that specifies the Type and Subtype
//          of the component.
//          long integer that specifies the Refcon value.
//
// Outputs - none
//
// Description - The specified value will be set into shared storage based
//              on the Type/SubType specified.  Note: Only OS/2 is fully
//              implemented at this time.
//
//---------------------------------------------------------------------------

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

//---------------------------------------------------------------------------
//
// Function - OpenComponent
//
// Inputs - Component Description block that specifies the Component requested.
//
// Outputs - Returns a pointer to an instance of the component described or
//           NULL if no matching component was found.
//
// Description - Will use the Server to get the ClassName and DLL name of the
//              component class described.  That information is used to create
//              an instance of that class that is returned to the caller
//
//---------------------------------------------------------------------------

Component    OpenComponent(in ComponentDescription *ptheComponent);

//---------------------------------------------------------------------------
//
// Function - OpenDefaultComponent (a misnomer)
//
// Inputs - Type and SubType codes that specify the desired component
//
// Outputs - returns a pointer to an instance of the component that supports
//           the Type/SubType specified, or NULL if no such component could be
//           located.
//
// Description - Invokes the corresponding Server method to get the class name
//              and DLL name for the class that supports the specified Component
//              That information is used to create an instance of the
//              class which is returned to the caller.
//
//---------------------------------------------------------------------------

Component    OpenDefaultComponent(in OSType componentType,
                                  in OSType componentSubType);

//---------------------------------------------------------------------------
//
// Function - CloseComponent
//
// Inputs - pointer to an instance of the Component class.
//
// Outputs - returns zero if the reference was valid and non zero if the
//           reference was null.
//
// Description - Will release the component indicated by the reference.
//
//---------------------------------------------------------------------------

OSErr        CloseComponent(in Component theComponentInstance);

//---------------------------------------------------------------------------
//
// Function - InstallComponent
//
// Inputs - ComponentRegistryData block describing the Component to be
//              added to the Registry
//
// Outputs - Returns zero if successful or non-zero if an error occurs
//
// Description - Invokes the corresponding Server method.
//
//---------------------------------------------------------------------------

OSErr        InstallComponent(in ComponentRegistryData *ptheData);

//---------------------------------------------------------------------------
//
// Function - UninstallComponent
//
// Inputs - Type and SubType specifying the Registry entry to be removed.
//
// Outputs - returns zero if successful or non-zero if an error.
//
// Description - Invokes the corresponding Server method
//
//---------------------------------------------------------------------------

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

#ifdef __SOMIDL__

implementation
{

        majorversion = 1;
        minorversion = 0;
        dllname = "oddsscr.dll";
        metaclass = M_ComponentManager;
        functionprefix = CMGR_;
        releaseorder :  CountComponents,
                        FindNextComponent,
                        GetComponentInfo,
                        GetComponentRefcon,
                        SetComponentRefcon,
                        OpenComponent,
                        OpenDefaultComponent,
                        CloseComponent,
                        InstallComponent,
                        UninstallComponent;
        somDefaultInit: override, init;
        somDestruct: override;

        passthru C_xh  = "// macro UlongToStr(L,S) - use to convert the unsigned long "
                         "//    value L to a string in the array S.  S must be at least"
                         "//    five characters wide"
                         "#define UlongToStr(L,S)  S[0] = (char) ((L >> 24) & 0xff) ; \ "
                         "                         S[1] = (char) ((L >> 16) & 0xff) ; \ "
                         "                         S[2] = (char) ((L >>  8) & 0xff) ; \ "
                         "                         S[3] = (char) ((L >>  0) & 0xff) ; \ "
                         "                         S[4] = '\0'  "
                         "// macro StrToUlong(S,L) - use to convert the string at S into"
                         "//    an unsigned long (32 bit) value.  S must be at least"
                         "//    four characters wide"
                         "#define StrToUlong(S,L) L = ( (unsigned int) S[0] << 24 ) | \ "
                         "                            ( (unsigned int) S[1] << 16 ) | \ "
                         "                            ( (unsigned int) S[2] <<  8 ) | \ "
                         "                            ( (unsigned int) S[3] <<  0 ) " ;

};

#endif

};
#endif
