
// @(#) 1.14 com/src/odscript/idl/screxten.idl, odscript, od96nt, odnt9712d 2/12/97 12:56:15 [3/21/97 17:22:16]
// ===========================================================================
//
// ScriptExtension.
//
// This class is the basis class for any Part specific script extension
// classes.
//
// Within a part specific script extension class the following modifications
// will normally be made.
//
//      In Init - ensure that the ReqFlags and ReqFlagsMask are set to
//                reflect the set of scripting component capabilities that
//                are required for scripting that part.
//
//      Register - Override to ensure that the proper class and instance
//              objects are registered to support the part. The default
//              may be acceptable for simple, non-container parts. For
//              container parts logic must be added to ensure that any
//              contained scriptable parts are also registered.
//
//      DeRegister - Override to ensure that the same object which was
//              registered is DeRegistered.  Also for container parts
//              the overriding logic should ensure that any contained
//              scriptable parts also are deregistered.
//
//      AddContainedPart - This needs to be overriden for container
//              parts and needs to provide proper registration of a single
//              new part that has been added to this container.
//
//
// ===========================================================================

// ===========================================================================
//  Change History
//      Monday August 26, 1996  at  4:08:26
//              make ReqFlags, ReqFlagsMask into attributes.
//
// ===========================================================================

#ifndef _SCREXTENS_
#define _SCREXTENS_

#ifndef _EXTENSN_
#include "Extensn.idl"
#endif

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

interface   ODScriptExtension;

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

interface ODPart ;
interface ODStorageUnit ;
interface ODScriptComponent;

//==============================================================================
// ODScriptExtension
//==============================================================================

interface ODScriptExtension : ODExtension
{

//==============================================================================
//
// Return values from registration routines.
//
//==============================================================================

 typedef long ODScrRegRet ;
 #define ODScrRegOK     0        // no error
 #define ODScrRegDup    1        // Name collision, 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

//---------------------------------------------------------------------------
//
// InitScriptExtension
//
// Input - owner - base ODPart which is the owner of this extension part
//
// Output - none
//
// Function - provides initialization when there is no persistent form
//            of the script information.
//            N.B. this method should only be called ONCE at the time the
//            object is initialized.
//
//---------------------------------------------------------------------------

 void   InitScriptExtension( in ODPart owner);

//---------------------------------------------------------------------------
//
// SetContainingExtension
//
// Input -  theContExt - pointer to ScriptExtension for containing part
//
// Output - none
//
// Function - provides the interface needed to allow a containing extension
//            object to be identified for this object.
//
//---------------------------------------------------------------------------

 void   SetContainingExtension( in ODScriptExtension theContExt) ;

//---------------------------------------------------------------------------
//
// InitScriptFromStorage
//
// Input - owner - base ODPart which is the owner of this extension part
//         stor  - ODStorageUnit that contains the persistent form of the
//                 script information (as produced by ScriptExternalize
//                 below)
//
// Output - ODBoolean - Any error returns kODFalse
//
// Function - provides initialization when there is a persistent form
//            of the script information.  Uses the Storage unit as follows:
//              property kODPropAttachedScrptType is used to store three
//                      values for the attached script.
//              value kODDSExtensionNamesValue holds a string that is the
//                      name assigned to the extension.
//              value kODDSComponentIdValue holds a string that is the
//                      subtype code for the supporting component. This
//                      value is not present if no component is in use with
//                      the current extension object.
//              value kODDSComponentDataValue holds a binary large object
//                      that is the persistent data that the Component needs
//                      to save. This value is not present if there is no
//                      component in use with the current extension object.
//
//---------------------------------------------------------------------------

 ODBoolean   InitScriptFromStorage(in  ODPart owner,
                                   in  ODStorageUnit stor) ;

//---------------------------------------------------------------------------
//
// RetrieveComponentData
//
// Input - pBufferSize - pointer to long integer that has size of the buffer
//              passed.
//         pBuffer - pointer to buffer to receive the data read.
//
// Output - BufferSize is set to reflect the size of the data for the Component
//          Buffer receives the data. If Buffer is not large enough for the
//              data, no data is transfered and the return value is false
//
// Function - return the binary large object that represents the component's
//              persistent data.  This function is designed to be called from
//              the component. To get the required size for the binary object,
//              the component will call this routine with a buffer and a size.
//              If that buffer is large enough to hold the data, it will be
//              read into the buffer.  In all cases the size will be updated
//              to reflect the size of the data.
//
//              If the data is read into the supplied buffer, the return value
//              is kODTrue.  If the buffer is not large enough or if there is
//              no data to be read, the size will be updated ( equal to zero
//              if there is no data) and the return value will be kODFalse.
//
//---------------------------------------------------------------------------

 ODBoolean  RetrieveComponentData(in long *pBufferSize,
                                  in void *pBuffer) ;

//---------------------------------------------------------------------------
//
// ScriptExternalize
//
// Input - stor  - ODStorageUnit to contain the scripting information for
//                 the current part.
//
// Output - StorageUnit is updated with the script information
//
// Function - The scripting information for the current part (and its contained
//            parts) will be placed in the storage unit supplied.  This routine
//            will place the kODPropAttachedScriptType property in the SU and,
//            will add the Value entries for kODDSExtensionNamesValue to
//            reflect the names assigned to the part.  If there is a Script-
//            Component associated with the extension, the Value
//            kODDSComponentIdValue will be added with a value of the
//            supporting Component's SubType.  If there is Component data
//            to be saved, Value kODDSComponentDataValue will be added to
//            contain that binary value.
//
//---------------------------------------------------------------------------

 void   ScriptExternalize( in ODStorageUnit stor);

//---------------------------------------------------------------------------
//
// ExternalizeComponentData
//
// Input - long BufferSZ - size of component's data block
//         char * Buffer - Locationof component's data block
//         ODStorageUnit *stor - Storage unit to receive the data
//
// Output - void
//
// Function - Cause the data in the indicated buffer to be written to the
//            storage unit as the Component's binary data. If length is
//            negative, the component's data has not changed since the last
//            time it was retrieved and thus the Storage Unit should not be
//            updated.  If the length is zero, there is no data to be written
//            and any prior value is to be purged.  If length is a positive
//            value the indicated data will be written to the SU.
//
//---------------------------------------------------------------------------

 void   ExternalizeComponentData(
                                     in long BufferSZ,
                                     in octet *Buffer,
                                     in ODStorageUnit stor);

//---------------------------------------------------------------------------
//
// PutComponentData
//
// Input - long BufferSZ - size of component's data block
//         octet *Buffer - location of component's data block
//
// Output - Data written to Storage unit for this part.
//
// Function - Will access the storage unit for this Part and will cause
//              the data supplied to be written as the Component's data
//              in that SU.   Length less than or equal to zero has special
//              meaning - see ExternalizeComponentData.
//
//              This Method is intended to be called by the component when
//              it identifies a need to save the current Script data, genrally
//              in response to a user action.
//
//---------------------------------------------------------------------------

 ODBoolean  PutComponentData(
                                      in long   BufferSZ,
                                      in octet *Buffer);

//---------------------------------------------------------------------------
//
// InitScriptEditor
//
// Input - none
//
// Output - ODBoolean - any error returns kODFalse ;
//
// Function - Initializes the Development Environment for the current part.
//            The class of the current part, the class of any contained parts,
//            the current part and the contained parts will be registered with
//            the IDE.
//
//---------------------------------------------------------------------------

 ODBoolean   InitScriptEditor() ;

//---------------------------------------------------------------------------
//
// EndScripting
//
// Input - none
//
// Output - ODBoolean - any error returns kODFalse ;
//
// Function - This method is invoked when the user determines that the
//      script associated with this part is to be removed.  The method will
//      explicitly DeRegister this part and all contained parts at this scope
//      only, remove any persistent information for this extension, and
//      remove the script component that is associated with this extension.
//
//---------------------------------------------------------------------------

 void EndScripting() ;

//---------------------------------------------------------------------------
//
// Register
//
// Input - RegScope - Script extension object that represents the context
//              where registration is to begin.  This will be the current
//              extension object or some container of that object. Objects
//              to be registered for this extension should be passed to the
//              scope indicated by this argument for registration to that
//              scope and any scopes contained by it.
//       - Prefix - a string that is the name prefix to be applied to all
//              names at the current scope when registering to the extension
//              specified by RegScope.
//
// Output - Register the BasePart to RegScoper and all containing Active Scopes
//          return value from ODScrRegRet values
//
// Function - This method is commonly overridden in the Extension for a
//              specific part.  The overriding code can provide a different
//              default name, add logic to register support classes and
//              instances, and should, for container parts, include logic
//              to initiate the registration of all contained scriptable
//              parts.
//
//              Normally the overriding code for this method would NOT
//              invoke the parent class's logic.
//
//---------------------------------------------------------------------------

 ODScrRegRet   Register( in ODScriptExtension RegScope,
                         in string Prefix );

//---------------------------------------------------------------------------
//
// DoRegisterClass
//
// Input - theClass - string that specifies the name of the class to register
//
// Output - Returns ODScrRegRet value.
//
// Function - This method registers the specified class with the current
//              ScriptComponent and with all containing scopes.
//
//---------------------------------------------------------------------------

 ODScrRegRet DoRegisterClass( in string  theClassName);

//---------------------------------------------------------------------------
//
// DoRegisterObject
//
// Input - theObj - The object which is to be registered for scripting
//         itsClass - the class name of that object
//         itsDefaultName - the name to be assigned to this object
//         thePrefix - the name prefix to be used for this object.
//         theNameUsed - output value, if the registration is successful,
//              this pointer will address the name that was actually assigned
//              to this object.  This string must be 'SOMFree'd by the
//              receiver.  If the registration fails, this value is not
//              set.
//         itsScope - the extension where this object is declared.
//         mayAddDigits - boolean, indicates that, if a name collision is
//              identified, then this routine should add a digit string to the
//              name until a unique name is generated.
//
// Output - Returns ODScrRegRet value
//
// Function - This method ensures that each part that is registered
//              properly all containing scopes.
//
//---------------------------------------------------------------------------

 ODScrRegRet DoRegisterObject(
                           in  SOMObject          theObj,
                           in  string             itsClass,
                           in  string             itsDefaultName,
                           in  string             thePrefix,
                           out string             theNameUsed,
                           in  ODScriptExtension  itsScope,
                           in  ODBoolean          mayAddDigits);

//---------------------------------------------------------------------------
//
// DoRegisterObjToComp
//
// Input - theObj - The object which is to be registered for scripting
//         itsClass - the class name of that object
//         itsDefaultName - a name to be used for this object
//         thePrefix - name prefix to be applied to that name in this scope.
//         theNameUsed - return value holds the name actually used for this
//              object.  Set only if registration is OK, must be SOMFree'd by
//              receiver.
//         itsScope - the extension where this object is declared.
//         mayAddDigits - boolean, indicates that, if a name collision is
//              identified, then this routine should add a digit string to the
//              name until a unique name is generated.
//         registeringObject - boolean, true if registering an object, false
//              when registering a container.
//
// Output - Returns ODScrRegRet value
//
// Function - This method ensures that each part that is registered
//              is properly registered in all containing scopes.
//              This logic is used by both DoRegisterObject and
//              DoRegisterContainedPart with the appopriate Component or
//              containing extension routine being called based on which
//              case we are dealing with.
//---------------------------------------------------------------------------

 ODScrRegRet DoRegisterObjToComp(
                            in SOMObject          theObj,
                            in string             itsClass,
                            in string             itsDefaultName,
                            in string             thePrefix,
                            out string            theNameUsed,
                            in ODScriptExtension  itsScope,
                            in ODBoolean          mayAddDigits,
                            in ODBoolean          registeringObject);

//---------------------------------------------------------------------------
//
// DoRegisterContainedPart
//
// Input - thePart - a reference to and ODPart contained in the basepart of
//              this extension.
//         itsName - The name, in this scope, by which this part is identified
//         thePrefix - Prefix to be applied to the name in this scope.
//         RegScope - scope at which registration is to begin.
//         nameUsed - output string pointer, holds name actually used for
//              registration of successful, must be SOMFree'd by receiver.
//              not valid if registration fails.
//         mayAddDigits - boolean - true if this routine may add digits to the
//              name if a name conflict is found.
//
// Output - Returns ODScrRegRet value
//
// Function - This method establishes the current scope as the containing
//              scope of the referenced part, requests the Script Component
//              to validate that the name specified is unambiguous, and
//              adds the name, persistent id and object reference to the
//              local name table.
//
//---------------------------------------------------------------------------

 ODScrRegRet DoRegisterContainedPart(
                           in ODPart             thePart,
                           in string             itsName,
                           in string             itsPrefix,
                           in ODScriptExtension  RegScope,
                           out string            nameUsed,
                           in ODBoolean          mayAddDigits) ;

//---------------------------------------------------------------------------
//
// DeRegister
//
// Input - ExtScope - the ODScriptExtension that represents the scope at
//              which deregistration is to occur (normally the scope where
//              DropContainedPart is invoked.
//         doContScopes - true if references from containing scopes are also
//              to be dropped.  False when invoked by 'EndEditing' which
//              only applies to the single scope.
//
// Output - TBD
//
// Function - This method will commonly be overridden for a Part specific
//              ScriptExtension.  The overriding code should ensure that
//              any objects which were registered, are appropriately
//              deregistered.  Also container parts should provide logic
//              to ensure that any contained parts are deRegistered.
//
//              Normally overriding code would not invoke the parent
//              class version of this code.
//
//---------------------------------------------------------------------------

 void   DeRegister( in ODScriptExtension ExtScope,
                    in ODBoolean doContScopes);

//---------------------------------------------------------------------------
//
// DoDeRegisterObject
//
// Input - theObject - The object which is to be DeRegistered.
//         itsScope  - the Extension object that is the level at which
//              the object is defined.
//         doContScopes - true if references from containing scopes are to
//              be deregistered, false if called from 'endScripting' when only
//              the one scope is to be addressed
//
// Output - TBD
//
// Function - This method provides the logic to ensure that when an object
//              is removed from the scripting environment, it is removed
//              from all containing scopes as well.
//
//---------------------------------------------------------------------------

 void DoDeRegisterObject( in SOMObject          theObject,
                          in ODScriptExtension  itsScope,
                          in ODBoolean          doContScopes) ;

//---------------------------------------------------------------------------
//
// DoDeRegisterContainedPart
//
// Input - thePart - The part which needs to be removed from registration.
//         ExtScope - the scope at which deregistration should begin.
//         doContScopes - boolean, indicating registration should be cleared
//              in any containing scopes as well.
//
// Output - TBD
//
// Function - This method provides the logic to ensure that when an object
//              is removed from the scripting environment, it is removed
//              from all containing scopes as well.
//
//---------------------------------------------------------------------------

 void DoDeRegisterContainedPart( in ODPart             thePart,
                                 in ODScriptExtension  ExtScope,
                                 in ODBoolean          doContScopes) ;

//---------------------------------------------------------------------------
//
// DoDeRegisterExtension
//
// Input - theExt - Registered extension object that should be deregistered
//              at this scope and optionally any containing scopes.
//         doContScopes - boolean - true if deregister is to proceed to the
//              containing scopes.
//
// Output - void
//
// Function - This method deRegisters an extension object with the current
//              ScriptComponent and ensures that any containing Script
//              Components are appropriately notified.
//
//---------------------------------------------------------------------------

 void  DoDeRegisterExtension( in ODScriptExtension theExt,
                              in ODBoolean         doContScopes) ;

//---------------------------------------------------------------------------
//
// AddContainedPart
//
// Input - part - ODPart that has been added to the current object or an
//                object contained within the current object.
//
// Output -
//
// Function - This method is to be called when the part (a container)
//            has a new part added to it.  If the current part is currently
//            scripted or has a containing part that is scripted, we will
//            register the new part for access by the script engine.
//
//---------------------------------------------------------------------------

 ODScrRegRet  AddContainedPart( in ODPart part) ;

//---------------------------------------------------------------------------
//
// DropContainedPart
//
// Input - part - ODPart that has been removed from the current object or an
//                object contained within the current object.
//
// Output -
//
// Function - This method is to be called when the part (a container)
//            has a contained part removed from it.  If the current part is
//            scripted or has a containing part that is scripted, we will
//            drop the registration of the part from the scripting interface
//
//---------------------------------------------------------------------------

 void   DropContainedPart( in ODPart part) ;

//---------------------------------------------------------------------------
//
// GetScriptComponent
//
// Input - SubType - Unsigned long representing the subtype code for
//              the required Component.  May be null if not known.
//
// Output - _ScrComp - set to a reference to an ODScriptComponent object
//          return kODTrue if successful, or kODFalse if not successful
//
// Function - Uses the Component Manager to obtain an instance of an
//              ODScriptComponent that supports the requirements of this
//              part.  If unable to obtain such an object we will report an
//              error. and return kODFalse.
//---------------------------------------------------------------------------

 ODBoolean   GetScriptComponent( in ODULong SubType) ;

//---------------------------------------------------------------------------
//
// CheckComponent
//
// Input - theScope - the scope (Extension object) which is to be checked
//              against the current scope's script component.
//
// Output - returns TRUE if the script component associated with the current
//              extension can support the requirements (as indicated by its
//              ReqFlags and ReqFlagsMask) of the specified extension object.
//              else returns false.
//
// Function - If current script component is null or its flags are not
//              compatible with those of the indicated extension object, return
//              false.  If all is ok, return true.
//
//---------------------------------------------------------------------------

 ODBoolean   CheckComponent( in ODScriptExtension theScope) ;

//---------------------------------------------------------------------------
//
// getContainingExt
//
// Input - none
//
// Output - ODScriptExtension that represents the containing environment.
//
// Function - return the containing extension object.
//
//---------------------------------------------------------------------------

 ODScriptExtension  getContainingExt ();

//---------------------------------------------------------------------------
//
// getScrComp
//
// Input - none
//
// Output - ODScriptComponent that is associated with this extension
//
// Function - return the related ScriptComponent
//
//---------------------------------------------------------------------------

 ODScriptComponent  getScrComp ();

//---------------------------------------------------------------------------
//
// getExtName
//
// Input - none
//
// Output - Return pointer to name assigned to this extension
//
// Function - return the name
//
//---------------------------------------------------------------------------

 string getExtName() ;

//---------------------------------------------------------------------------
//
// setExtName
//
// Input - string - pointer to new name for this extension
//
// Output - none
//
// Function - free storage associated with any earlier name and take ownership
//              of the string passed in.
//
//---------------------------------------------------------------------------

 void  setExtName( in string theName) ;

//---------------------------------------------------------------------------
//
// MarkChanged
//
// Input -none
//
// Output - none
//
// Function - Interface that allows the ability to track when the script
//            has changed.  Will result in calling the draft function
//            SetChangedFromPrev to indicate that the document is modified.
//
//---------------------------------------------------------------------------

 void  MarkChanged() ;

//---------------------------------------------------------------------------
//
// NameChanged
//
// Input - theObject - the Object being renamed
//         newName - proposed name for the object
//         oldName - current name for the object
//
// Output - Boolean - true if name change was acceptable
//
// Function - pass on a name change to the associated component, if an
//            error return that error,  If no error notify any containing
//            extension of the proposed name change.  If that returns an
//            error, then restore previous name and return the error.
//
//---------------------------------------------------------------------------

 ODBoolean  NameChanged( in SOMObject theObject,
                         in string newName,
                         in string oldName) ;

//---------------------------------------------------------------------------
// Attributes
//---------------------------------------------------------------------------

    attribute
        ODSLong            ReqFlags;        // The requirement flags for this
                                            // class - set at initilaization time

    attribute
        ODSLong            ReqFlagsMask;    // Mask of which support flags are
                                            // significant for this class - set
                                            // at initialization time

#ifdef __SOMIDL__
        implementation
        {
                functionprefix = ODScrExt_;


        majorversion = 1;
        minorversion = 0;
        dllname = "oddsscr.dll";

        somInit :       override;
        somUninit :     override;

        releaseorder:
            _get_ReqFlags              ,
            _set_ReqFlags              ,
            _get_ReqFlagsMask          ,
            _set_ReqFlagsMask          ,
            InitScriptExtension        ,
            SetContainingExtension     ,
            InitScriptFromStorage      ,
            RetrieveComponentData      ,
            ScriptExternalize          ,
            ExternalizeComponentData   ,
            PutComponentData           ,
            InitScriptEditor           ,
            EndScripting               ,
            Register                   ,
            DoRegisterClass            ,
            DoRegisterObject           ,
            DoRegisterObjToComp        ,
            DoRegisterContainedPart    ,
            DeRegister                 ,
            DoDeRegisterObject         ,
            DoDeRegisterContainedPart  ,
            DoDeRegisterExtension      ,
            AddContainedPart           ,
            DropContainedPart          ,
            GetScriptComponent         ,
            CheckComponent             ,
            getContainingExt           ,
            getScrComp                 ,
            getExtName                 ,
            setExtName                 ,
            MarkChanged                ,
            NameChanged                 ;

        };
#endif
};

#endif 
