JSScriptingSuite.h

Go to the documentation of this file.
00001 // ADOBE SYSTEMS INCORPORATED
00002 // Copyright  2002-2003 Adobe Systems Incorporated
00003 // All Rights Reserved
00004 //
00005 // NOTICE:  Adobe permits you to use, modify, and distribute this
00006 // file in accordance with the terms of the Adobe license agreement
00007 // accompanying it.  If you have received this file from a source
00008 // other than Adobe, then your use, modification, or distribution
00009 // of it requires the prior written permission of Adobe.
00026 #ifndef __JSScriptingSuite__
00027 #define __JSScriptingSuite__
00028 
00029 #include "ASTypes.h"
00030 #include "ASPragma.h"
00031 #include "SPFiles.h"
00032 
00033 #ifdef __cplusplus
00034 extern "C" {
00035 #endif
00036 
00037 #pragma PRAGMA_IMPORT_BEGIN
00038 
00039 
00040 /*******************************************************************************
00041  * @defgroup JavaScriptSuite
00042  **/
00043 
00045 #define kJSScriptingSuite               "JavaScript Scripting Suite"
00046 #define kJSScriptingSuiteVersion2       2L
00047 #define kJSScriptingSuiteVersion1       1L
00048 #define kJSScriptingSuiteVersion        kJSScriptingSuiteVersion2
00049 #define kJSScriptingVersion             kJSScriptingSuiteVersion
00050 
00051 
00052 //-------------------------------------------------------------------------------
00053 //  Error codes.
00054 //-------------------------------------------------------------------------------
00063 #define kJSScriptExecutionError         'ScEr'  
00064 #define kJSScriptInternalError          'ScIE'  
00065 #define kJSScriptGeneralError           'ScGr'  
00066 #define kJSScriptCantCreateEngine       'ScCJ'  
00067 #define kJSScriptBadEnginReference      'ScBR'  
00068 #define kJSScriptLanguageNotSupported   'Sc!s'  
00069 #define kJSBufferTooSmall               'Sbts'        // close defgroup, because I don't want others to appear in it.
00072 
00073 /*******************************************************************************
00074  **
00075  ** Types
00076  **
00077  **/
00078 
00080 typedef struct _t_JSEngine              * JSEngineRef; 
00084 enum  JavaScriptExecutionMode
00085 {
00086     kJSExecutionModeNoDebug             = 1,    
00087     kJSExecutionModeDebugOnError        = 2,    
00088     kJSExecutionModeDebugAtBeginning    = 3 
00089 };
00090 
00091 
00092 
00093 /*******************************************************************************
00094  * @ingroup JavaScriptSuite
00095 
00096     How to use the Scripting suite:
00097     
00098     To execute a JavaScript script inside a host application, you must acquire 
00099     and use a JavaScript engine instance.
00100 
00101     A typical use of the engine:
00102 
00103         JSEngineRef     engineRef = NULL;
00104         ASAPI           err = kSpNoError;
00105         
00106         err = sScriptingSuite->CreateEngine( &engineRef );
00107         if ( err == kSPNoError )
00108         {
00109             const char      scriptText[] = "documents.add();"   //  Script to create a new document
00110             const char      * result = NULL;
00111             
00112             err = sScriptingSuite->ExecuteJavaScript( engineRef, scriptText, &result );
00113             if ( err == kASScriptExecutionError )
00114             {
00115                 //  If error during execution, display a dialog containing returned error information string.
00116                 ErrorAlert( result );
00117             }
00118         }
00119         
00120         ...
00121         
00122         err = sScriptingSuite->DeleteEngine( engineRef );
00123         engineRef = NULL;
00124 
00125 
00126     Notes:
00127     
00128         Do not deallocate the result value.  The engine instance owns it and will dispose of it.
00129 
00130         The engine instance doesn't need to be deleted after calling ExecuteJavaScript.  If you execute 
00131         multiple JavaScript scripts inside the same engine instance they will share the same context 
00132         (including global variables).  If you want scripts to execute independently use a different 
00133         engine instance for each script.
00134 */
00135 
00138 typedef struct {
00139 
00141     ASAPI ASBoolean (*ScriptIsRunning) ( void );
00142 
00144     ASAPI ASErr (*CreateEngine) ( JSEngineRef * engineRefPtr );
00145     
00147     ASAPI ASErr (*DeleteEngine) ( JSEngineRef engineRef );
00148 
00152     ASAPI ASErr (*SetIncludePath) ( JSEngineRef engineRef, const ASUnicode * includePath );
00153     
00159     ASAPI ASErr (*GetIncludePath) ( JSEngineRef engineRef, ASUnicode * includePathBuff, long * buffSize );
00160 
00168     ASAPI ASErr (*ExecuteScript) ( JSEngineRef              engineRef,
00169                                    const ASUnicode          * script,
00170                                    JavaScriptExecutionMode  executionMode,
00171                                    const ASUnicode          ** result );
00172 
00174 
00175 
00176 
00178     ASAPI ASErr (*CreateEngineAPE) ( JSEngineRef * engineRefPtr, intptr_t apeEngineRef  );
00179 
00180 } JSScriptingSuite2;
00181 
00182 
00183 
00186 typedef struct {
00187 
00189     ASAPI ASBoolean (*ScriptIsRunning) ( void );
00190 
00192     ASAPI ASErr (*CreateEngine) ( JSEngineRef * engineRefPtr );
00193     
00195     ASAPI ASErr (*DeleteEngine) ( JSEngineRef engineRef );
00196 
00200     ASAPI ASErr (*SetIncludePath) ( JSEngineRef engineRef, const ASUnicode * includePath );
00201     
00207     ASAPI ASErr (*GetIncludePath) ( JSEngineRef engineRef, ASUnicode * includePathBuff, long * buffSize );
00208 
00216     ASAPI ASErr (*ExecuteScript) ( JSEngineRef              engineRef,
00217                                    const ASUnicode          * script,
00218                                    JavaScriptExecutionMode  executionMode,
00219                                    const ASUnicode          ** result );
00220 
00221 } JSScriptingSuite1;
00222 
00223 
00224 #pragma PRAGMA_IMPORT_END
00225 
00226 #ifdef __cplusplus
00227 }
00228 #endif
00229 
00230 
00231 #endif // __JSScriptingSuite__