JSScriptingSuite.h

Go to the documentation of this file.

// ADOBE SYSTEMS INCORPORATED
// Copyright  2002-2003 Adobe Systems Incorporated
// All Rights Reserved
//
// NOTICE:  Adobe permits you to use, modify, and distribute this
// file in accordance with the terms of the Adobe license agreement
// accompanying it.  If you have received this file from a source
// other than Adobe, then your use, modification, or distribution
// of it requires the prior written permission of Adobe.
#ifndef __JSScriptingSuite__
#define __JSScriptingSuite__

#if MC_WIN
#include <crtdefs.h>
#endif

#ifndef __ASTypes__
#include "ASTypes.h"
#endif

#ifndef __ASPragma__
#include "ASPragma.h"
#endif

#ifndef __SPFiles__
#include "SPFiles.h"
#endif

#ifdef __cplusplus
extern "C" {
#endif

#pragma PRAGMA_IMPORT_BEGIN


/*******************************************************************************
 * @defgroup JavaScriptSuite
 **/

#define kJSScriptingSuite               "JavaScript Scripting Suite"
#define kJSScriptingSuiteVersion4       4L
#define kJSScriptingSuiteVersion3       3L
#define kJSScriptingSuiteVersion2       2L
#define kJSScriptingSuiteVersion1       1L
#define kJSScriptingSuiteVersion        kJSScriptingSuiteVersion3
#define kJSScriptingVersion             kJSScriptingSuiteVersion


//-------------------------------------------------------------------------------
//  Error codes.
//-------------------------------------------------------------------------------
#define kJSScriptExecutionError         'ScEr'  
#define kJSScriptInternalError          'ScIE'  
#define kJSScriptGeneralError           'ScGr'  
#define kJSScriptCantCreateEngine       'ScCJ'  
#define kJSScriptBadEnginReference      'ScBR'  
#define kJSScriptLanguageNotSupported   'Sc!s'  
#define kJSBufferTooSmall               'Sbts'        // close defgroup, because I don't want others to appear in it.

/*******************************************************************************
 **
 ** Types
 **
 **/

typedef struct _t_JSEngine              * JSEngineRef; 
enum  JavaScriptExecutionMode
{
    kJSExecutionModeNoDebug             = 1,    
    kJSExecutionModeDebugOnError        = 2,    
    kJSExecutionModeDebugAtBeginning    = 3 
};



/*******************************************************************************
 * @ingroup JavaScriptSuite

    How to use the Scripting suite:
    
    To execute a JavaScript script inside a host application, you must acquire 
    and use a JavaScript engine instance.

    A typical use of the engine:

        JSEngineRef     engineRef = NULL;
        SPErr           err = noErr;

        JSScriptingSuite2 * sScriptingSuite = NULL;
        err = basicSuite->AcquireSuite(kJSScriptingSuite, 
                                   kJSScriptingSuiteVersion, 
                                   (const void **)&sScriptingSuite);
        if ( err == kSPNoError ) 
        {
            err = sScriptingSuite->CreateEngine( &engineRef );
            if ( err == kSPNoError )
            {
                const ASUnicode        scriptText[] = {'a', 'l', 'e', 'r', 't', '(', '\'', 'h', 'i', '\'', ')', ';', 0 } ;  //    Script to create a new document
                const ASUnicode        * result = NULL;
            
                err = sScriptingSuite->ExecuteScript( engineRef, scriptText, kJSExecutionModeNoDebug, &result );
                if ( err == kJSScriptExecutionError )
                {
                    //  If error during execution, display a dialog containing returned error information string.
                    // ErrorAlert( result );
                }
            }
        }
        
        ...
        
        err = sScriptingSuite->DeleteEngine( engineRef );
        engineRef = NULL;

        basicSuite->ReleaseSuite(kJSScriptingSuite, 
                                   kJSScriptingSuiteVersion);


    Notes:
    
        Do not deallocate the result value.  The engine instance owns it and will dispose of it.

        The engine instance doesn't need to be deleted after calling ExecuteJavaScript.  If you execute 
        multiple JavaScript scripts inside the same engine instance they will share the same context 
        (including global variables).  If you want scripts to execute independently use a different 
        engine instance for each script.
*/

typedef struct {

    ASAPI ASBoolean (*ScriptIsRunning) ( void );

    ASAPI ASErr (*CreateEngine) ( JSEngineRef * engineRefPtr );
    
    ASAPI ASErr (*DeleteEngine) ( JSEngineRef engineRef );

    ASAPI ASErr (*SetIncludePath) ( JSEngineRef engineRef, const ASUnicode * includePath );
    
    ASAPI ASErr (*GetIncludePath) ( JSEngineRef engineRef, ASUnicode * includePathBuff, long * buffSize );

    ASAPI ASErr (*ExecuteScript) ( JSEngineRef              engineRef,
                                   const ASUnicode          * script,
                                   JavaScriptExecutionMode  executionMode,
                                   const ASUnicode          ** result );


    ASAPI ASErr (*SuspendResumeAppleEventProcessing) (ASBoolean suspend);
    
    ASAPI ASErr (*IsAppleEventProcessingSuspended) (ASBoolean* suspended);

    ASAPI ASErr (*HasSuspendedAppleEvents) (ASBoolean* hasEvents);

} JSScriptingSuite4;

typedef struct {

    ASAPI ASBoolean (*ScriptIsRunning) ( void );

    ASAPI ASErr (*CreateEngine) ( JSEngineRef * engineRefPtr );
    
    ASAPI ASErr (*DeleteEngine) ( JSEngineRef engineRef );

    ASAPI ASErr (*SetIncludePath) ( JSEngineRef engineRef, const ASUnicode * includePath );
    
    ASAPI ASErr (*GetIncludePath) ( JSEngineRef engineRef, ASUnicode * includePathBuff, long * buffSize );

    ASAPI ASErr (*ExecuteScript) ( JSEngineRef              engineRef,
                                   const ASUnicode          * script,
                                   JavaScriptExecutionMode  executionMode,
                                   const ASUnicode          ** result );


    ASAPI ASErr (*SuspendResumeAppleEventProcessing) (ASBoolean suspend);
    
    ASAPI ASErr (*IsAppleEventProcessingSuspended) (ASBoolean* suspended);

} JSScriptingSuite3;

typedef struct {

    ASAPI ASBoolean (*ScriptIsRunning) ( void );

    ASAPI ASErr (*CreateEngine) ( JSEngineRef * engineRefPtr );
    
    ASAPI ASErr (*DeleteEngine) ( JSEngineRef engineRef );

    ASAPI ASErr (*SetIncludePath) ( JSEngineRef engineRef, const ASUnicode * includePath );
    
    ASAPI ASErr (*GetIncludePath) ( JSEngineRef engineRef, ASUnicode * includePathBuff, long * buffSize );

    ASAPI ASErr (*ExecuteScript) ( JSEngineRef              engineRef,
                                   const ASUnicode          * script,
                                   JavaScriptExecutionMode  executionMode,
                                   const ASUnicode          ** result );




    ASAPI ASErr (*CreateEngineAPE) ( JSEngineRef * engineRefPtr, intptr_t apeEngineRef  );

} JSScriptingSuite2;



typedef struct {

    ASAPI ASBoolean (*ScriptIsRunning) ( void );

    ASAPI ASErr (*CreateEngine) ( JSEngineRef * engineRefPtr );
    
    ASAPI ASErr (*DeleteEngine) ( JSEngineRef engineRef );

    ASAPI ASErr (*SetIncludePath) ( JSEngineRef engineRef, const ASUnicode * includePath );
    
    ASAPI ASErr (*GetIncludePath) ( JSEngineRef engineRef, ASUnicode * includePathBuff, long * buffSize );

    ASAPI ASErr (*ExecuteScript) ( JSEngineRef              engineRef,
                                   const ASUnicode          * script,
                                   JavaScriptExecutionMode  executionMode,
                                   const ASUnicode          ** result );

} JSScriptingSuite1;



/*******************************************************************************
 * @defgroup Script Value suite
 **/
typedef struct Opaque_ScriptValueRef*                   ScriptValueRef;

enum
{
    kScriptValue_Undefined,
    kScriptValue_Null,
    kScriptValue_Boolean,
    kScriptValue_Number,
    kScriptValue_String,
    kScriptValue_Array,
    kScriptValue_Object,
    kScriptValue_ByteArray
};
typedef SPInt32 ScriptValueType;

enum
{
    kScriptValue_Double,
    kScriptValue_Int32,
    kScriptValue_UInt32,
    kScriptValue_Int64,
};
typedef SPInt32 ScriptValueNumericType;

typedef SPBoolean (*ScriptKeyIterator)(SPUInt32, const char*, void* userData);

#define kScriptValueSuite                "Script Value Suite"
#define kScriptValueSuiteVersion1        1L

typedef struct {
    ASAPI ASErr (*CreateUndefined)(ScriptValueRef* valueRef);
    ASAPI ASErr (*CreateNull)(ScriptValueRef* valueRef);
    ASAPI ASErr (*CreateBoolean)(SPBoolean value, ScriptValueRef* valueRef);
    ASAPI ASErr (*CreateDouble)(double value, ScriptValueRef* valueRef);
    ASAPI ASErr (*CreateInt32)(SPInt32 value, ScriptValueRef* valueRef);
    ASAPI ASErr (*CreateUInt32)(SPUInt32 value, ScriptValueRef* valueRef);
    ASAPI ASErr (*CreateInt64)(int64_t value, ScriptValueRef* valueRef);
    ASAPI ASErr (*CreateUTF8)(const char* value, ScriptValueRef* valueRef);
    ASAPI ASErr (*CreateArray)(ScriptValueRef* valueRef);
    ASAPI ASErr (*CreateObject)(ScriptValueRef* valueRef);

    ASAPI ASErr (*DestroyValue)(ScriptValueRef valueRef);

    ASAPI ASErr (*GetType)(ScriptValueRef valueRef, ScriptValueType* type);
    ASAPI ASErr (*GetNumericType)(ScriptValueRef valueRef, ScriptValueNumericType* type);
    ASAPI ASErr (*GetBoolean)(ScriptValueRef valueRef, ASBoolean* value);
    ASAPI ASErr (*GetDouble)(ScriptValueRef valueRef, double* value);
    ASAPI ASErr (*GetInt32)(ScriptValueRef valueRef, SPInt32* value);
    ASAPI ASErr (*GetUInt32)(ScriptValueRef valueRef, SPUInt32* value);
    ASAPI ASErr (*GetInt64)(ScriptValueRef valueRef, int64_t* value);

    ASAPI ASErr (*GetUTF8Length)(ScriptValueRef valueRef, SPUInt32* length);
    ASAPI ASErr (*GetUTF8)(ScriptValueRef valueRef, SPUInt32 length, char* buffer);

    ASAPI ASErr (*IterateKeys)(ScriptValueRef valueRef, ScriptKeyIterator iterator, void* userData);
    ASAPI ASErr (*HasProperty)(ScriptValueRef valueRef, const char* name, SPBoolean* value);
    ASAPI ASErr (*GetProperty)(ScriptValueRef valueRef, const char* name, ScriptValueRef* value);
    ASAPI ASErr (*SetProperty)(ScriptValueRef valueRef, const char* name, ScriptValueRef value, SPBoolean move);

    ASAPI ASErr (*GetArrayLength)(ScriptValueRef valueRef, SPUInt32* count);
    ASAPI ASErr (*GetArrayValue)(ScriptValueRef valueRef, SPUInt32 index, ScriptValueRef* value);
    ASAPI ASErr (*SetArrayValue)(ScriptValueRef valueRef, SPUInt32 index, ScriptValueRef value, SPBoolean move);
    ASAPI ASErr (*AppendArrayValue)(ScriptValueRef valueRef, ScriptValueRef value, SPBoolean move);
} ScriptValueSuite1;

/*******************************************************************************
 * @defgroup LiveObjectSuite
 **/

#define kLiveObjectScriptSuite                "LiveObject Script Suite"
#define kLiveObjectScriptSuiteVersion1        1L

typedef struct {
    ASAPI ASErr    (*PerformAction) (ScriptValueRef args, ScriptValueRef* result, SPBoolean* isError);
} LiveObjectScriptSuite1;


#pragma PRAGMA_IMPORT_END

#ifdef __cplusplus
}
#endif

#endif // __JSScriptingSuite__