
// @(#) 1.11 com/src/odscript/idl/scrcomp.idl, odscript, od96nt, odnt9712d 10/31/96 12:44:33 [3/21/97 17:26:58]
// ===========================================================================
//
// ScriptComponent.
//
// This class is the base class for all script components.  A script component
// is a separately built and packaged dll (or dlls) that provides scripting
// support for enabled OpenDoc classes.  See ScriptExtension for a description
// of the requirements for making a Part scriptable.
//

// ===========================================================================
//  Change History
//      Monday August 26, 1996  at  4:14:32
//              Add passthru for include ODTypes.h
//      Wednesday September 4, 1996  at  12:45:04
//              Corrections from Review by Stew - use SOMObject and string
//              instead of void * and char *
//
// ===========================================================================
#ifndef _SCRCOMP_
#define _SCRCOMP_

#include "comp.idl"

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

interface   ODScriptComponent ;

//==============================================================================
// Exported symbols
//==============================================================================
//
// Define the 'type' that is used by the component manager
#define kODCompTypeDirectScript  "ODDS"

// Define the 'flags' used to identify scripting features
//    A component will identify what subset of these flags it supports.
//    (specified as part of the data registered with the Component Manager)
//
//    A part must set both a 'requires' mask that is set of these bits
//    that represents the support required by the part and a 'significant'
//    mask that indicates which bits are to be tested. e.g. requires 0x06
//    and significant  0x07 indicates that mask 0x01 must be off and mask
//    0x06 must be on for a component that is to support the part.
//
#define kODDSSupportsRegistration       0x0001
#define kODDSSupportsEventSink          0x0002
#define kODDSSupportsPersistance        0x0004
#define kODDSSupportsSourceEdit         0x0008

 typedef long ODScrRegRet ;
 #define ODScrRegOK     0        // no error
 #define ODScrRegDup    1        // Requested name previously used
 #define ODScrRegMem    2        // Memory allocation error.
 #define ODScrRegNone   3        // Registration not done - no script component
 #define ODScrRegOver   4        // Method not overridden (AddContainedPart)
 #define ODScrRegErr    5        // Component failure - call _GetComponentInstanceError
                                 // for specific error value

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

interface Component ;
interface ODScriptExtension ;

//==============================================================================
// ODScriptingComponent
//==============================================================================

interface ODScriptComponent : Component
{

//  New Public Methods

//---------------------------------------------------------------------------
//
// InitScriptComponent
//
// Input - theExt - pointer to the ODScriptExtension object that is associated
//              with this script component.
//       - hasInitData - boolean that indicates there is initialization data
//              and this component should use ODScriptExtension::RetrieveComponentData
//              to get that data to initialize its environment.
//
// Output - ODScrRegRet
//
// Function - Allows the ScriptComponent to access the
//            ScriptExtension, primarily for persistent
//            data but other interfaces may be used.
//
//---------------------------------------------------------------------------
 ODScrRegRet  InitScriptComponent( in ODScriptExtension  theExt,
                                   in ODBoolean hasInitData ) ;

//---------------------------------------------------------------------------
//
// ActivateScriptComponent
//
// Input - none
//
// Output - ODScrRegRet
//
// Function - Identifies to the ScriptComponent that initialization is
//            complete and that scripts and scripted objects may be
//            initialized. Invoked by the ScriptExtension during the
//            processing of InitFromStorage after InitScriptComponent
//            and any registration calls.
//
//---------------------------------------------------------------------------
 ODScrRegRet  ActivateScriptComponent();

//---------------------------------------------------------------------------
//
// ReleaseAll
//
// Input - none
//
// Output - none
//
// Function - Allows the ScriptComponent to release resources
//            prior to closing down. It will be called by the
//            ODScriptExtension just prior to that object being deleted.
//
//---------------------------------------------------------------------------

 void  ReleaseAll() ;           // Called just before component is released.

//---------------------------------------------------------------------------
//
// InitEditor
//
// Input - none
//
// Output - ODScrRegRet
//
// Function - Request for the Script Component to present its script
//            editor interface with the classes and objects previously
//            registered presented in that interface.
//
//---------------------------------------------------------------------------

 ODScrRegRet  InitEditor () ;          // initialize interactive edit session

//---------------------------------------------------------------------------
//
// CloseScripting
//
// Input - none
//
// Output - none
//
// Function - Request the script component to terminate scripting for the
//      current scope.  All scripts, registration data and internal state
//      should be released.
//
//---------------------------------------------------------------------------

 void  CloseScripting () ;              // Terminate scripting for this scope

//---------------------------------------------------------------------------
//
// AddClass
//
// Input - classname - string that names a class that is to be exposed to
//              the script interface.
//
// Output - ODScrRegRet
//
// Function - Request to the Script Component to add the named class to
//            the set of classes which are available for script access in
//            this environment.
//
//---------------------------------------------------------------------------

 ODScrRegRet  AddClass( in string classname) ;
                                // register the class for scripting access

//---------------------------------------------------------------------------
//
// DropInstance
//
// Input - instance - pointer to an object which was previously registered
//              with this Script Component and which should be removed from
//              the set of objects available for scripting.
//
// Output - ODScrRegRet
//
// Function - The indicated object should be removed from the scripting
//            interface. Correction of references to such an object in the
//            script code is up to the Script Component.
//
//---------------------------------------------------------------------------

 ODScrRegRet  DropInstance(in SOMObject instance) ;
                                // remove object from scripting environment.

//---------------------------------------------------------------------------
//
// DropContainer
//
// Input - container - pointer to an object which was previously registered
//              with this Script Component as a container and which should
//              removed from the current scope.
//
// Output - ODScrRegRet
//
// Function - The indicated container should be removed from the scripting
//            interface. Correction of references to such an object in the
//            script code is up to the Script Component.
//
//---------------------------------------------------------------------------

 ODScrRegRet  DropContainer(in ODScriptExtension container) ;
                                // remove container from scripting environment.

//---------------------------------------------------------------------------
//
// AddInstance
//
// Input - instance - pointer to an object to be exposed for scripting.
//         classname - name of the class to which that instance belongs.
//         instanceName - name by which that instance should be refered to
//              in the scripts.
//         DefinintExt - The extension object which 'owns' this instance.
//              this object can be accessed for information about containing
//              scopes, etc.
//
// Output - ODScrRegRet
//
// Function - The indicated object should be added to the set of objects that
//            are accessable for script access.
//
//---------------------------------------------------------------------------

 ODScrRegRet  AddInstance(in SOMObject instance,
                        in string classname,
                        in string instanceName,
                        in ODScriptExtension DefiningExt ) ;
                                // register the object for scripting access

//---------------------------------------------------------------------------
//
// AddContainer
//
// Input - instance - pointer to the container object, a ODScriptExtension
//         classname - the name of the class for that container.
//         containerName - name by which the contaner should be refered to
//              in the scripts.
//         DefinintExt - The extension object which 'owns' this container
//              this object can be accessed for information about containing
//              scopes, etc.
//
// Output - ODScrRegRet
//
// Function - The indicated container should be added to the set of objects that
//            are accessable for script access.
//
//---------------------------------------------------------------------------

 ODScrRegRet  AddContainer( in SOMObject instance,
                          in string classname,
                          in string containerName,
                          in ODScriptExtension DefiningExt ) ;
                                // register the object for scripting access

//---------------------------------------------------------------------------
//
// GetComponentData
//
// Input - pBufferSize - pointer to a long that has the size of the Buffer
//         pBuffer - pointer to buffer to receive the data block
//
// Output - *pBufferSize updated with the actual size of the Component Data
//          pBuffer - if the size that was input was sufficient the buffer
//            will receive the Component Data.
//
// Function - This interface will be invoked by the ScriptExtension when it
//            needs the component's persistent data, i.e. any data that the
//            component needs to save across uses of the part.  This would
//            include the actual scripts, cached descriptive information or
//            other information that the component needs to have saved.
//
//            If the buffer size provided is not sufficient, the pBufferSize
//            value should be updated with the size that is actually required.
//            If the Buffer was large enough, then the component's data
//            should be copied to that buffer and again the BufferSize
//            should be updated to reflect the actual size of the data.
//
//---------------------------------------------------------------------------

 void  GetComponentData( inout long  pBufferSize,
                         in void* pBuffer) ;
                                // interface to get persistent data for Component

//---------------------------------------------------------------------------
//
// Rename
//
// Input - pObject pointer to an object that was previously registered for
//              script access
//         pNewName - pointer to a string that is the new name to be assigned
//              to that instance.
//
// Output - ODScrRegRet
//
// Function - This interface is provided to support a user's ability to specify
//            a name for an object, after the object has been exposed for
//            scripting.  The name for the object should be changed by the
//            component.  Any fixup of references to the old object name is
//            the responsibility of the component.
//
//---------------------------------------------------------------------------

 ODScrRegRet  Rename( in SOMObject  pObject, in char *pNewName) ;

#ifdef __SOMIDL__
        implementation
        {
                functionprefix = ODScrComp_ ;
  passthru C_xh = \
"#include <ODTypes.h>                                                       " \
"                                                                           " \
"//                                                                         " \
"// Define the 'type' that is used by the component manager                 " \
"#define kODCompTypeDirectScript  \"ODDS\"                                  " \
"                                                                           " \
"// Define the 'flags' used to identify scripting features                  " \
"//    A component will identify what subset of these flags it supports.    " \
"//    (specified as part of the data registered with the Component Manager)" \
"//                                                                         " \
"//    A part must set both a 'requires' mask that is set of these bits     " \
"//    that represents the support required by the part and a 'significant' " \
"//    mask that indicates which bits are to be tested. e.g. requires 0x06  " \
"//    and significant  0x07 indicates that mask 0x01 must be off and mask  " \
"//    0x06 must be on for a component that is to support the part.         " \
"//                                                                         " \
"#define kODDSSupportsRegistration       0x0001                             " \
"#define kODDSSupportsEventSink          0x0002                             " \
"#define kODDSSupportsPersistance        0x0004                             " \
"#define kODDSSupportsSourceEdit         0x0008                             " \
"                                                                           " \
"typedef long ODScrRegRet ;                                                 " \
"#define ODScrRegOK     0        // no error                                " \
"#define ODScrRegDup    1        // Requested name previously used          " \
"#define ODScrRegMem    2        // Memory allocation error.                " \
"#define ODScrRegNone   3        // Registration not done - no script comp. " \
"#define ODScrRegOver   4        // Method not overridden (AddContainedPart)" \
"#define ODScrRegErr    5        // Component failure - call _GetComponentInstanceError" \
"                                // for specific error value                ";


      majorversion = 1;
      minorversion = 0;
      dllname = "oddsscr.dll";
      releaseorder:
          InitScriptComponent      ,
          ActivateScriptComponent  ,
          ReleaseAll               ,
          AddClass                 ,
          AddInstance              ,
          AddContainer             ,
          DropInstance             ,
          DropContainer            ,
          InitEditor               ,
          CloseScripting           ,
          GetComponentData         ,
          Rename                    ;

        };
#endif
};

#endif 
