Interfaces and Methods

IActiveScript

The scripting engine must implement the IActiveScript interface in order to be an ActiveX Scripting engine.

Methods in Vtable Order

IUnknown methods Description
QueryInterface Returns pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

IActiveScript methods Description
SetScriptSite Informs the scripting engine of the IActiveScriptSite site provided by the host.
GetScriptSite Retrieves the site object associated with the ActiveX Scripting engine.
SetScriptState Puts the scripting engine into the given state.
GetScriptState Retrieves the current state of the scripting engine.
Close Causes the scripting engine to abandon any currently loaded script, lose its state, and release any interface pointers it has to other objects, thus entering a closed state.
AddNamedItem Adds the name of a root-level item to the scripting engine's name space.
AddTypeLib Adds a type library to the name space for the script.
GetScriptDispatch Retrieves the IDispatch interface for the methods and properties associated with the running script itself.
GetCurrentScriptThreadID Retrieves a scripting-engine-defined identifier for the currently executing thread.
GetScriptThreadID Retrieves a scripting-engine-defined identifier for the thread associated with the given Microsoft Win32® thread.
GetScriptThreadState Retrieves the current state of a script thread.
InterruptScriptThread Interrupts the execution of a running script thread.
Clone Clones the current scripting engine (minus any current execution state), returning a loaded, unsited scripting engine in the current thread.

IActiveScript::AddNamedItem

HRESULT AddNamedItem(
    LPCOLESTR pstrName,  // address of item name
    DWORD dwFlags        // item flags
);

Adds the name of a root-level item to the scripting engine's name space. A root-level item is an object with properties and methods, an event source, or both.

pstrName

[in] Address of a buffer that contains the name of the item as viewed from the script. The name must be unique and persistable.

dwFlags

[in] Flags associated with item. Can be a combination of these values:

Value	Meaning
SCRIPTITEM_ISPERSISTENT	Indicates that the item should be saved if the scripting engine is saved. Similarly, setting this flag indicates that a transition back to the initialized state should retain the item's name and type information (the scripting engine must, however, release all pointers to interfaces on the actual object).
SCRIPTITEM_ISSOURCE	Indicates that the item sources events that the script can sink. Children (properties of the object that are in themselves objects) can also source events to the script. This is not recursive, but it provides a convenient mechanism for the common case, for example, of adding a container and all of its member controls.
SCRIPTITEM_ISVISIBLE	Indicates that the item's name is available in the name space of the script, allowing access to the properties, methods, and events of the item. Because by convention the properties of the item include the item's children, all child object properties and methods (and their children, recursively) will be accessible.
SCRIPTITEM_GLOBALMEMBERS	Indicates that the item is a collection of global properties and methods associated with the script. Normally, a scripting engine would ignore the object name (other than for the purpose of using it as a cookie for IActiveScriptSite::GetItemInfo, or for resolving explicit scoping) and expose its members as global variables and methods. This allows the host to extend the library (run-time functions and so on) available to the script. It is left to the scripting engine to deal with name conflicts (for example, when two SCRIPTITEM_GLOBALMEMBERS items have methods of the same name), although an error should not be returned because of this situation.
SCRIPTITEM_NOCODE	Indicates that the item is simply a name being added to the script's name space, and should not be treated as an item for which code should be associated. For example, without this flag being set, VBScript will create a separate module for the named item, and C++ might create a separate wrapper class for the named item.
SCRIPTITEM_CODEONLY	Indicates that the named item represents a code-only object, and that the host has no IUnknown to be associated with this code-only object. The host only has a name for this object. In object-oriented languages such as C++, this flag would create a class. Not all languages support this flag.

Returns

S_OK The named item was successfully added to the script's name space.
E_UNEXPECTED The call was not expected (for example, the scripting engine has not yet been loaded or initialized).
E_POINTER An invalid pointer was specified.
E_INVALIDARG An argument was invalid.

IActiveScript::AddTypeLib

HRESULT AddTypeLib(
    REFGUID guidTypeLib,  // LIBID of type library
    DWORD dwMaj,          // major version number
    DWORD dwMin,          // minor version number
    DWORD dwFlags         // option flags
);

Adds a type library to the name space for the script. This is similar to the #include directive in C/C++. It allows a set of predefined items such as class definitions, typedefs, and named constants to be added to the run-time environment available to the script.

guidTypeLib: [in] LIBID of the type library to add.
dwMaj: [in] Major version number.
dwMin: [in] Minor version number.
dwFlags: [in] Option flags. Can be SCRIPTTYPELIB_ISCONTROL, which indicates that the type library describes an ActiveX control used by the host.

Returns

S_OK The specified type library was successfully added.
E_UNEXPECTED The call was not expected (for example, the scripting engine has not yet been loaded or initialized).
TYPE_E_CANTLOADLIBRARY The specified type library could not be loaded.
E_INVALIDARG An argument was invalid.

IActiveScript::Clone

HRESULT Clone(
    IActiveScript **ppscript  // receives pointer to IActiveScript
);

Clones the current scripting engine (minus any current execution state), returning a loaded, unsited scripting engine in the current thread. The state of this new scripting engine should be identical to the state the original scripting engine would be in if it were transitioned back to the initialized state.

ppscript: [out] Address of a variable that receives a pointer to the IActiveScript interface of the unsited, cloned scripting engine. The host must create a site and call SetScriptSite on the new scripting engine before it will be in the initialized state and, therefore, usable.

The Clone method is an optimization of IPersist*::Save, CoCreateInstance, and IPersist*::Load, so the state of the new scripting engine should be the same as if the state of the original scripting engine were saved and loaded into a new scripting engine. Named items are duplicated in the cloned scripting engine, but specific object pointers for each item are forgotten and are obtained with GetItemInfo. This allows an identical object model with per-thread entry points (an apartment model) to be used.

This method is used for multithreaded server hosts that can run multiple instances of the same script. The scripting engine may return E_NOTIMPL, in which case the host can achieve the same result by duplicating the persistent state and creating a new instance of the scripting engine with IPersist*.

This method can be called from non-base threads without resulting in a non-base callout to host objects or to IActiveScriptSite.

Returns

S_OK The scripting engine was successfully cloned.
E_NOTIMPL The Clone method is not supported.
E_POINTER An invalid pointer was specified.
E_UNEXPECTED The call was not expected (for example, the scripting engine has not yet been loaded or initialized).

IActiveScript::Close

HRESULT Close(void);

Causes the scripting engine to abandon any currently loaded script, lose its state, and release any interface pointers it has to other objects, thus entering a closed state. Event sinks, immediately executed script text, and macro invocations that are already in progress are completed before the state changes (use InterruptScriptThread to cancel a running script thread). This method must be called by the creating host before it calls Release to prevent circular reference problems.

Returns

S_OK The script was successfully closed.
S_FALSE The method succeeded, but the script was already closed.
OLESCRIPT_S_PENDING The method was queued successfully, but the state hasn't changed yet. When the state changes, the site will be called back on IActiveScriptSite::OnStateChange.
E_UNEXPECTED The call was not expected (for example, the scripting engine was already in the closed state).

IActiveScript::GetCurrentScriptThreadID

HRESULT GetCurrentScriptThreadID(
    SCRIPTTHREADID *pstidThread  // receives scripting thread identifier
);

Retrieves a scripting-engine-defined identifier for the currently executing thread. The identifier can be used in subsequent calls to script thread execution-control methods such as InterruptScriptThread.

pstidThread: [out] Address of a variable that receives the script thread identifier associated with the current thread. The interpretation of this identifier is left to the scripting engine, but it can be just a copy of the Windows thread identifier. If the Win32 thread terminates, this identifier becomes unassigned and can subsequently be assigned to another thread.

This method can be called from non-base threads without resulting in a non-base callout to host objects or to IActiveScriptSite.

Returns

S_OK The identifier was successfully retrieved.
E_POINTER An invalid pointer was specified.

IActiveScript::GetScriptDispatch

HRESULT GetScriptDispatch(
    LPCOLESTR pstrItemName  // address of item name
    IDispatch **ppdisp      // receives IDispatch pointer
);

Retrieves the IDispatch interface for the methods and properties associated with the running script itself.

pstrItemName: [in] Address of a buffer that contains the name of the item for which the caller needs the associated dispatch object. If this parameter is NULL, the dispatch object contains as its members all of the global methods and properties defined by the script. Through the IDispatch interface and the associated ITypeInfo interface, the host can invoke script methods or view and modify script variables.
ppdisp: [out] Address of a variable that receives a pointer to the object associated with the script's global methods and properties. If the scripting engine does not support such an object, NULL is returned.

Because methods and properties can be added by calling IActiveScriptParse, the IDispatch interface returned by this function can dynamically support new methods and properties. Similarly, IDispatch::GetTypeInfo should return a new, unique ITypeInfo when methods and properties are added. Note, however, that language engines must not change the IDispatch interface in a way that is incompatible with any previous ITypeInfo interface returned. That implies, for example, that DISPIDs will never be reused.

Returns

S_OK The dispatch object for the script was successfully retrieved.
S_FALSE The scripting engine does not support a dispatch object; the ppdisp parameter is set to NULL.
E_UNEXPECTED The call was not expected (for example, the scripting engine has not yet been loaded or initialized).
E_POINTER An invalid pointer was specified.
E_INVALIDARG An argument was invalid.

IActiveScript::GetScriptSite

HRESULT GetScriptSite(
    REFIID iid,           // interface identifier
    void **ppvSiteObject  // address of host site interface
);

Retrieves the site object associated with the ActiveX Scripting engine.

iid: [in] Identifier of the requested interface.
ppvSiteObject: [out] Address of the location that receives the interface pointer to the host's site object.

Returns

S_OK The site object was successfully retrieved.
S_FALSE No site has been set; ppvSiteObject is set to NULL.
E_POINTER An invalid pointer was specified.
E_INVALIDARG An argument was invalid.
E_NOINTERFACE The specified interface is not supported.

IActiveScript::GetScriptState

HRESULT GetScriptState(
    SCRIPTSTATE *pss  // address of structure for state information
);

Retrieves the current state of the scripting engine. This method can be called from non-base threads without resulting in a non-base callout to host objects or to IActiveScriptSite.

pss: [out] Address of a variable that receives a value defined in the SCRIPTSTATE enumeration. The value indicates the current state of the scripting engine associated with the calling thread.

Returns

S_OK The state information was successfully retrieved.
E_POINTER An invalid pointer was specified.

IActiveScript::GetScriptThreadID

HRESULT GetScriptThreadID(
    DWORD dwWin32ThreadID,       // Win32 thread identifier
    SCRIPTTHREADID *pstidThread  // receives scripting thread identifier
);

Retrieves a scripting-engine-defined identifier for the thread associated with the given Win32 thread. This identifier can be used in subsequent calls to script thread execution control methods such as InterruptScriptThread.

dwWin32ThreadID: [in] Thread identifier of a running Win32 thread in the current process. Use the GetCurrentScriptThreadID function to retrieve the thread identifier of the currently executing thread.
pstidThread: [out] Address of a variable that receives the script thread identifier associated with the given Win32 thread. The interpretation of this identifier is left to the scripting engine, but it can be just a copy of the Windows thread identifier. Note that if the Win32 thread terminates, this identifier becomes unassigned and may subsequently be assigned to another thread.

This method can be called from non-base threads without resulting in a non-base callout to host objects or to IActiveScriptSite.

Returns

S_OK The identifier was successfully retrieved.
E_POINTER An invalid pointer was specified.
E_UNEXPECTED The call was not expected (for example, the scripting engine has not yet been loaded or initialized).

IActiveScript::GetScriptThreadState

HRESULT GetScriptThreadState(
    SCRIPTTHREADID stidThread,    // identifier of script thread
    SCRIPTTHREADSTATE *pstsState  // receives state flag
);

Retrieves the current state of a script thread.

stidThread

[in] Identifier of the thread for which the state is desired, or one of the following special thread identifiers:

Value	Meaning
SCRIPTTHREADID_CURRENT	The currently executing thread.
SCRIPTTHREADID_BASE	The base thread; that is, the thread in which the scripting engine was instantiated.

pstsState

[out] Address of a variable that receives the state of the indicated thread. The state is indicated by one of the named constant values defined by the SCRIPTTHREADSTATE enumeration. If this parameter does not identify the current thread, the state may change at any time.

This method can be called from non-base threads without resulting in a non-base callout to host objects or to IActiveScriptSite.

Returns

S_OK The current state was successfully retrieved.
E_POINTER An invalid pointer was specified.
E_UNEXPECTED The call was not expected (for example, the scripting engine has not yet been loaded or initialized).

IActiveScript::InterruptScriptThread

HRESULT InterruptScriptThread(
    SCRIPTTHREADID   stidThread,  // identifier of thread
    const EXCEPINFO *pexcepinfo,  // receives error information
    DWORD dwFlags
);

Interrupts the execution of a running script thread (an event sink, an immediate execution, or a macro invocation). This method can be used to terminate a script that is stuck (for example, in an infinite loop). It can be called from non-base threads without resulting in a non-base callout to host objects or to IActiveScriptSite.

stidThread

[in] Thread identifier of the thread to interrupt, or one of the following special thread identifier values:

Value	Meaning
SCRIPTTHREADID_CURRENT	The currently executing thread.
SCRIPTTHREADID_BASE	The base thread; that is, the thread in which the scripting engine was instantiated.
SCRIPTTHREADID_ALL	All threads. The interrupt is applied to all script methods currently in progress. Note that unless the caller has requested that the script be disconnected, by calling SetScriptState with the SCRIPTSTATE_DISCONNECTED or SCRIPTSTATE_INITIALIZED flag, the next scripted event causes script code to run again.

pexcepinfo

[in] Address of an EXCEPINFO structure that receives error information associated with the error condition.

dwFlags

[in] Option flags associated with the interruption. Can be one of these values:

Value	Meaning
SCRIPTINTERRUPT_DEBUG	If supported, enter the scripting engine's debugger at the current script execution point.
SCRIPTINTERRUPT_RAISEEXCEPTION	If supported by the scripting engine's language, let the script handle the exception. Otherwise, the script method is aborted and the error code is returned to the caller; that is, the event source or macro invoker.

Returns

S_OK The given thread was successfully interrupted.
E_POINTER An invalid pointer was specified.
E_INVALIDARG An argument was invalid.
E_UNEXPECTED The call was not expected (for example, the scripting engine has not yet been loaded or initialized).

IActiveScript::SetScriptSite

HRESULT SetScriptSite(
    IActiveScriptSite *pScriptSite  // address of host script site
);

Informs the scripting engine of the IActiveScriptSite site provided by the host. This method must be called before any other IActiveScript methods can be used.

pScriptSite: [in] Address of the host-supplied script site to be associated with this instance of the scripting engine. The site must be uniquely assigned to this scripting engine instance; it cannot be shared with other scripting engines.

Returns

S_OK The host site was set successfully.
E_POINTER An invalid pointer was specified.
E_INVALIDARG An argument was invalid.
E_FAIL An unspecified error occurred; the scripting engine was unable to finish initializing the site.
E_UNEXPECTED The call was not expected (for example, a site was already set).

IActiveScript::SetScriptState

HRESULT SetScriptState(
    SCRIPTSTATE ss  // identifier of new state
);

Puts the scripting engine into the given state. This method can be called from non-base threads without resulting in a non-base callout to host objects or to IActiveScriptSite.

ss

[in] Sets the scripting engine to the given state. Can be one of the values defined in the SCRIPTSTATE enumeration:

SCRIPTSTATE_INITIALIZED

Returns the scripting engine back to the initialized state from the started, connected, or disconnected state. Because languages can vary widely in semantics, scripting engines are not required to support this state transition. Engines that support IActiveScript::Clone must, however, support this state transition. Hosts must prepare for this transition and take the appropriate action: Release the current scripting engine, create a new scripting engine, and call Load or InitNew (and possibly also call ParseScriptText). Use of this transition should be considered an optimization of the above steps. Note that any information the scripting engine has obtained about the names of Named Items and the type information describing Named Items remains valid.

Because languages vary widely, defining the exact semantics of this transition is difficult. At a minimum, the scripting engine must disconnect from all events, and release all of the SCRIPTINFO_IUNKNOWN pointers obtained by calling IActiveScriptSite::GetItemInfo. The engine must refetch these pointers after the script is run again. The scripting engine should also reset the script back to an initial state that is appropriate for the language. VBScript, for example, resets all variables and retains any code added dynamically by calling IActiveScriptParse with the SCRIPTTEXT_ISPERSISTENT flag set. Other languages may need to retain current values (such as Lisp because there is no code/data separation) or reset to a well-known state (this includes languages with statically initialized variables). These languages may or may not retain code added by calling IActiveScriptParse.

Note that the transition to the started state should have the same semantics (that is, it should leave the scripting engine in the same state) as calling IPersist*::Save to save the scripting engine, and then calling IPersist*::Load to load a new scripting engine; these actions should have the same semantics as IActiveScript::Clone. Scripting engines that do not yet support Clone or IPersist* should carefully consider how the transition to the started state should behave, so that such a transition would not violate the above conditions if Clone or IPersist* support was later added.

During this transition to the started state, the scripting engine will disconnect from event sinks after the appropriate destructors, and so on, are executed in the script. To avoid having these destructors executed, the host can first move the script into the disconnected state before moving into the started state.

Use InterruptScriptThread to cancel a running script thread without waiting for current events, and so on, to finish running.

SCRIPTSTATE_STARTED

The transition to this mode causes any code that was queued during the initialized state to be executed. From this state, script code can be executed, for example, by calling IActiveScriptParse::ParseScriptText or by calling the IDispatch interface obtained from IActiveScript::GetScriptDispatch. The transition to this state is also the appropriate time to execute routines such as a main()-like script routine, if appropriate for the script language.

SCRIPTSTATE_CONNECTED

Causes the script to connect to events. If this is a transition from the initialized state, the scripting engine should transition through the started state, performing the necessary actions, before entering the connected state and connecting to events.

SCRIPTSTATE_DISCONNECTED

Causes the script to disconnect from event sinks. This can be done either logically (ignoring events received) or physically (calling Unadvise on the appropriate connection points). Returning to the connected state reverses this process. If this is a transition from the initialized state, the scripting engine should transition through the started state, performing the necessary actions, before entering the disconnected state. Event sinks that are in progress are completed before the state changes (use InterruptScriptThread to cancel a running script thread). The script's execution state is maintained. For example, an HTML browser may put the scripting engine into this state when a scripted HTML page is moved into the LRU cache, before the page is actually destroyed.

Returns

S_OK The script successfully entered the given state.
S_FALSE The method succeeded, but the script was already in the given state.
OLESCRIPT_S_PENDING The method was queued successfully, but the state hasn't changed yet. When the state changes, the site will be called back through the IActiveScriptSite::OnStateChange method.
E_FAIL The scripting engine does not support the transition back to the initialized state. The host must discard this scripting engine and create, initialize, and load a new scripting engine to achieve the same effect.
E_UNEXPECTED The call was not expected (for example, the scripting engine has not yet been loaded or initialized).

IActiveScriptParse

If the ActiveX Scripting engine allows raw text code scriptlets to be added to the script, or allows expression text to be evaluated at run time, it implements IActiveScriptParse. For interpreted scripting languages that have no independent authoring environment, such as Visual Basic Script, this provides an alternate mechanism (other than IPersist*) to get script code into the scripting engine, and to attach script fragments to various object events.

IActiveScriptParse::AddScriptlet

HRESULT AddScriptlet(
    LPCOLESTR pstrDefaultName,   // address of default name of scriptlet
    LPCOLESTR pstrCode,          // address of scriptlet text
    LPCOLESTR pstrItemName,      // address of item name
    LPCOLESTR pstrSubItemName,   // address of subitem name
    LPCOLESTR pstrEventName,     // address of event name
    LPCOLESTR pstrEndDelimiter , // address of end-of-scriptlet delimiter
    DWORD dwFlags,               // scriptlet flags
    BSTR *pbstrName,             // address of actual name of scriptlet
    EXCEPINFO *pexcepinfo        // address of exception information
);

Adds a code scriptlet to the script. This method is used in environments where the persistent state of the script is intertwined with the host document and must be restored under the host's control, rather than through IPersist*. The primary examples are HTML scripting languages that allow scriptlets of code embedded in the HTML document to be attached to intrinsic events (for example, ONCLICK="button1.text='Exit'").

pstrDefaultName

[in] Address of a default name to associate with the scriptlet. If the scriptlet does not contain naming information (as in the ONCLICK example above), this name will be used to identify the scriptlet. If this parameter is NULL, the scripting engine manufactures a unique name, if necessary.

pstrCode

[in] Address of the scriptlet text to add. The interpretation of this string depends on the scripting language.

pstrItemName

[in] Address of a buffer that contains the item name associated with this scriptlet. This parameter, in addition to pstrSubItemName, identifies the object for which the scriptlet is an event handler.

pstrSubItemName

[in] Address of a buffer that contains the name of a subobject of the named item with which this scriptlet is associated; this name must be found in the named item's type information. This parameter is NULL if the scriptlet is to be associated with the named item instead of a subitem. This parameter, in addition to pstrItemName, identifies the specific object for which the scriptlet is an event handler.

pstrEventName

[in] Address of a buffer that contains the name of the event for which the scriptlet is an event handler.

pstrEndDelimiter

[in] Address of the end-of-scriptlet delimiter. When pstrCode is parsed from a stream of text, the host typically uses a delimiter, such as two single quotation marks ("), to detect the end of the scriptlet. This parameter specifies the delimiter that the host used, allowing the scripting engine to provide some conditional primitive preprocessing (for example, replacing a single quotation mark ['] with two single quotation marks for use as a delimiter). Exactly how (and if) the scripting engine makes use of this information depends on the scripting engine. Set this parameter to NULL if the host did not use a delimiter to mark the end of the scriptlet.

dwFlags

[in] Flags associated with the scriptlet. Can be a combination of the following values:

Value	Meaning
SCRIPTTEXT_ISVISIBLE	Indicates that the script text should be visible (and, therefore, callable by name) as a global method in the name space of the script.
SCRIPTTEXT_ISPERSISTENT	Indicates that the code added during this call should be saved if the scripting engine is saved (for example, through a call to *IPersist::Save**), or if the scripting engine is reset by way of a transition back to the initialized state.

pbstrName

[out] The actual name used to identify the scriptlet. This will be, in order of preference: a name explicitly specified in the scriptlet text, the default name provided in pstrDefaultName, or a unique name synthesized by the scripting engine.

pexcepinfo

[out] Pointer to a structure containing exception information. This structure should be filled in if DISP_E_EXCEPTION is returned.

Returns

S_OK The scriptlet was successfully added to the script--the pbstrName parameter contains the scriptlet's name.
OLESCRIPT_E_INVALIDNAME The default name supplied is invalid in this scripting language.
OLESCRIPT_E_SYNTAX An unspecified syntax error occurred in the scriptlet.
DISP_E_EXCEPTION An exception occurred in the parsing of the scriptlet; the pexcepinfo parameter contains information about the exception.
E_UNEXPECTED The call was not expected (for example, the scripting engine has not yet been loaded or initialized).
E_NOTIMPL This method is not supported; the scripting engine does not support adding event-sinking scriptlets.
E_POINTER An invalid pointer was specified.
E_INVALIDARG An argument was invalid.

IActiveScriptParse::InitNew

HRESULT InitNew(void);

Initializes the scripting engine.

Before the scripting engine can be used, one of the following methods must be called: IPersist*::Load, IPersist*::InitNew, or IActiveScriptParse::InitNew. The semantics of this method are identical to IPersistStreamInit::InitNew, in that this method tells the scripting engine to initialize itself. Note that it is not valid to call both InitNew and Load, nor is it valid to call InitNew or Load more than once.

Returns

S_OK The scripting engine was successfully initialized.
E_FAIL An error occurred during initialization.

See also IActiveScriptParse::InitNew

IActiveScriptParse::ParseScriptText

HRESULT ParseScriptText(
    LPCOLESTR pstrCode,         // address of scriptlet text
    LPCOLESTR pstrItemName,     // address of item name
    IUnknown *punkContext,      // address of debugging context
    LPCOLESTR pstrEndDelimiter, // address of end-of-scriptlet delimiter
    DWORD dwFlags,              // scriptlet flags
    VARIANT *pvarResult,        // address of buffer for results
    EXCEPINFO *pexcepinfo       // address of buffer for error data
);

Parses the given code scriptlet, adding declarations into the name space and evaluating code as appropriate.

pstrCode

[in] Address of the scriptlet text to evaluate. The interpretation of this string depends on the scripting language.

pstrItemName

[in] Address of the item name that gives the context in which the scriptlet is to be evaluated. If this parameter is NULL, the code is evaluated in the scripting engine's global context.

punkContext

[in] Address of context object. This object is reserved for use in a debugging environment, where such a context may be provided by the debugger to represent an active run-time context. If this parameter is NULL, the engine uses pstrItemName to identify the context.

pstrEndDelimiter

dwFlags

[in] Flags associated with the scriptlet. Can be a combination of these values:

Value	Meaning
SCRIPTTEXT_ISEXPRESSION	If the distinction between a computational expression and a statement is important but syntactically ambiguous in the script language, this flag specifies that the scriptlet is to be interpreted as an expression, rather than as a statement or list of statements. By default, statements are assumed unless the correct choice can be determined from the syntax of the scriptlet text.
SCRIPTTEXT_ISPERSISTENT	Indicates that the code added during this call should be saved if the scripting engine is saved (for example, through a call to *IPersist::Save**), or if the scripting engine is reset by way of a transition back to the initialized state.
SCRIPTTEXT_ISVISIBLE	Indicates that the script text should be visible (and, therefore, callable by name) as a global method in the name space of the script.

pvarResult

[out] Address of a buffer that receives the results of scriptlet processing, or NULL if the caller expects no result (that is, the SCRIPTTEXT_ISEXPRESSION value is not set).

pexcepinfo

[out] Address of a structure that receives exception information. This structure is filled if ParseScriptText returns DISP_E_EXCEPTION.

If the scripting engine is in the initialized state, no code will actually be evaluated during this call; rather, such code is queued and executed when the scripting engine is transitioned into (or through) the started state. Because execution is not allowed in the initialized state, it is an error to call this method with the SCRIPTTEXT_ISEXPRESSION flag when in the initialized state.

The scriptlet can be an expression, a list of statements, or anything allowed by the script language. For example, this method is used in the evaluation of the HTML <SCRIPT> tag, which allows statements to be executed as the HTML page is being constructed, rather than just compiling them into the script state.

The code passed to this method must be a valid, complete portion of code. For example, in VBScript it is illegal to call this method once with Sub Foo(x) and then a second time with End Sub. The parser must not wait for the second call to complete the subroutine, but rather must generate a parse error because a subroutine declaration was started but not completed.

Returns

S_OK The expression or statement(s) has been evaluated. The pvarResult parameter contains the result, if any.
E_POINTER An invalid pointer was specified.
E_INVALIDARG An argument was invalid.
E_UNEXPECTED The call was not expected (for example, the scripting engine is in the uninitialized or closed state, or the SCRIPTTEXT_ISEXPRESSION flag was set and the scripting engine is in the initialized state).
DISP_E_EXCEPTION An exception occurred in the processing of the scriptlet. The pexcepinfo parameter contains information about the exception.
OLESCRIPT_E_SYNTAX An unspecified syntax error occurred in the scriptlet.
E_NOTIMPL This method is not supported. The scripting engine does not support run-time evaluation of expressions or statements.

IActiveScriptError

An object implementing this interface is passed to IActiveScriptSite::OnScriptError whenever the scripting engine encounters an unhandled error. The host then calls methods on this object to obtain information about the error that occurred.

IActiveScriptError::GetExceptionInfo

HRESULT GetExceptionInfo(
    EXCEPINFO *pexcepinfo  // structure for exception information
);

Retrieves information about an error that occurred while the scripting engine was running a script.

pexcepinfo: [out] Address of an EXCEPINFO structure that receives error information.

Returns

S_OK The error information was successfully retrieved.
E_FAIL An error occurred.

IActiveScriptError::GetSourceLineText

HRESULT GetSourceLineText(
    BSTR *pbstrSourceLine  // address of buffer for source line
);

Retrieves the line in the source file where an error occurred while a scripting engine was running a script.

pbstrSourceLine: [out] Address of a buffer that receives the line of source code in which the error occurred.

Returns

S_OK The line in the source file was successfully retrieved.
E_FAIL An error occurred.

IActiveScriptError::GetSourcePosition

HRESULT GetSourcePosition(
    DWORD *pdwSourceContext,  // context cookie
    ULONG *pulLineNumber,     // line number of error
    LONG *pichCharPosition    // character position of error
);

Retrieves the location in the source code where an error occurred while the scripting engine was running a script.

pdwSourceContext: [out] Address of a variable that receives a cookie that identifies the context. The interpretation of this parameter depends on the host application.
pulLineNumber: [out] Address of a variable that receives the line number in the source file where the error occurred.
pichCharPosition: [out] Address of a variable that receives the character position in the line where the error occurred.

Returns

S_OK The error location was successfully retrieved.
E_FAIL An error occurred.

IActiveScriptSite

The host must create a site for the ActiveX Scripting engine by implementing IActiveScriptSite. Usually, this site will be associated with the container of all the objects that are visible to the script (for example, the ActiveX controls). Typically, this container will correspond to the document or page being viewed. Internet Explorer, for example, would create such a container for each HTML page being displayed. Each ActiveX control (or other automation object) on the page, and the scripting engine itself, would be enumerable within this container.

IActiveScriptSite::GetDocVersionString

HRESULT GetDocVersionString(
    BSTR *pbstrVersionString  // address of document version string
);

Retrieves a host-defined string that uniquely identifies the current document version from the host's point of view. If the related document has changed outside the scope of ActiveX Scripting (as in the case of an HTML page being edited with NotePad), the scripting engine can save this along with its persisted state, forcing a recompile the next time the script is loaded.

pstrVersionString: [out] Address of the host-defined document version string.

Returns

S_OK The document version string was successfully retrieved. The pstrVersionString parameter contains the string.
E_NOTIMPL This method is not supported. The scripting engine should assume that the script is in sync with the document.

IActiveScriptSite::GetItemInfo

HRESULT IActiveScriptSite::GetItemInfo(
    LPCOLESTR pstrName,     // address of item name
    DWORD dwReturnMask,     // bit mask for information retrieval
    IUnknown **ppunkItem,   // address of pointer to item's IUnknown
    ITypeInfo **ppTypeInfo  // address of pointer to item's ITypeInfo
);

Allows the scripting engine to obtain information about an item added with IActiveScript::AddNamedItem.

pstrName

[in] The name associated with the item, as specified in IActiveScript::AddNamedItem.

dwReturnMask

[in] A bit mask specifying what information about the item should be returned. The scripting engine should request the minimum needed information because some of the return parameters (for example, ITypeInfo) can take considerable time to load or generate. Can be a combination of the following values:

Value	Meaning
SCRIPTINFO_IUNKNOWN	Return the IUnknown interface for this item.
SCRIPTINFO_ITYPEINFO	Return the ITypeInfo interface for this item.

ppunkItem

[out] Address of a variable that receives a pointer to the IUnknown interface associated with the given item. The scripting engine can use the QueryInterface method to obtain the IDispatch interface for the item. This parameter receives NULL if dwReturnMask does not include the SCRIPTINFO_IUNKNOWN value. Also, it receives NULL if there is no object associated with the item name; this mechanism is used to create a simple class when the named item was added with the SCRIPTITEM_CODEONLY flag set.

ppTypeInfo

[out] Address of a variable that receives a pointer to the ITypeInfo interface associated with the item. This parameter receives NULL if dwReturnMask does not include the SCRIPTINFO_ITYPEINFO value, or if type information is not available for this item. If type information is not available, the object cannot source events, and name binding must be realized with IDispatch::GetIDsOfNames. Note that this ITypeInfo describes the coclass (TKIND_COCLASS) because the object may support multiple interfaces and event interfaces. If the item supports the IProvideMultipleTypeInfo interface, the ITypeInfo interface corresponds to the ITypeInfo of index zero obtained from IProvideMultipleTypeInfo::GetInfoOfIndex.

This method retrieves only the information indicated by the dwReturnMask parameter. This improves performance, for example, in the case where an ITypeInfo interface is not needed for an item.

Returns

S_OK The requested interface pointer was successfully retrieved. The ppunkItem or ppTypeInfo parameter contains the pointer.
E_POINTER An invalid pointer was specified.
E_INVALIDARG An argument was invalid.
TYPE_E_ELEMENTNOTFOUND An item of the specified name was not found.

IActiveScriptSite::GetLCID

HRESULT GetLCID(
    LCID *plcid  // address of variable for language identifier
);

Retrieves the locale identifier associated with the host's user interface. The scripting engine uses the identifier to ensure that error strings and other user-interface elements surfaced by the engine appear in the appropriate language. If this method returns E_NOTIMPL, the system-defined locale identifier should be used.

plcid: [out] Address of a variable that receives the locale identifier for user-interface elements displayed by the scripting engine.

Returns

S_OK The locale identifier was successfully retrieved. The plcid parameter contains the identifier.
E_POINTER An invalid pointer was specified.
E_NOTIMPL This method is not implemented. Use the system-defined locale.

IActiveScriptSite::OnEnterScript

HRESULT OnEnterScript(void);

Informs the host that the scripting engine has begun executing the script code.

The scripting engine must call this method on every entry or reentry into the scripting engine. For example, if the script calls an object that then fires an event handled by the scripting engine, the scripting engine must call OnEnterScript before executing the event, and must call OnLeaveScript after executing the event but before returning to the object that fired the event. Calls to this method can be nested. Every call to OnEnterScript requires a corresponding call to OnLeaveScript.

Returns

S_OK The method succeeded.

IActiveScriptSite::OnLeaveScript

HRESULT IActiveScriptSite::OnLeaveScript(void);

Informs the host that the scripting engine has returned from executing script code.

The scripting engine must call this method before returning control to a caller that entered the scripting engine. For example, if the script calls an object that then fires an event handled by the scripting engine, the scripting engine must call OnEnterScript before executing the event, and must call OnLeaveScript after executing the event before returning to the object that fired the event. Calls to this method can be nested. Every call to OnEnterScript requires a corresponding call to OnLeaveScript.

Returns

S_OK The method was successful.

IActiveScriptSite::OnScriptError

HRESULT IActiveScriptSite::OnScriptError(
    IActiveScriptError*pase  // address of error interface
);

Informs the host that an execution error occurred while the engine was running the script.

pase: [in] Address of the error object's IActiveScriptError interface. A host can use this interface to obtain information about the execution error.

Returns

S_OK The scripting engine should continue running the script as best as possible (perhaps abandoning the processing of this event).
S_FALSE The scripting engine should continue running the script in the debugger, if a debugger is available. If a debugger is not available, this error should be handled in the same way as E_FAIL.
E_FAIL The scripting engine should abort execution of the script and return it to the initialized state. In this case, the pexcepinfo parameter obtained from IActiveScriptError::GetExceptionInfo is generally passed to OnScriptTerminate.

IActiveScriptSite::OnScriptTerminate

HRESULT OnScriptTerminate(
    VARIANT *pvarResult,   // address of script results
    EXCEPINFO *pexcepinfo  // address of structure with exception information
);

Informs the host that the script has completed execution.

pvarResult: [in] Address of a variable that contains the script result, or NULL if the script produced no result.
pexcepinfo: [in] Address of an EXCEPINFO structure that contains exception information generated when the script terminated, or NULL if no exception was generated.

The scripting engine calls this method before the call to OnStateChange(SCRIPTSTATE_INITIALIZED) is completed. The OnScriptTerminate method can be used to return completion status and results to the host. Note that many script languages, which are based on sinking events from the host, have life spans that are defined by the host. In this case, this method may never be called.

Returns

S_OK The method succeeded.

IActiveScriptSite::OnStateChange

HRESULT IActiveScriptSite::OnStateChange(
    SCRIPTSTATE ssScriptState  // new state of engine
);

Informs the host that the scripting engine has changed states.

ssScriptState: [in] Value that indicates the new script state. See IActiveScript::GetScriptState for a description of the states.

Returns

S_OK The method succeeded.

IActiveScriptSiteWindow

This interface is implemented by hosts that support a user interface on the same object as IActiveScriptSite. Hosts that do not support a user interface, such as servers, would not implement the IActiveScriptSiteWindow interface. The scripting engine accesses this interface by calling QueryInterface from IActiveScriptSite.

IActiveScriptSite::EnableModeless

HRESULT IActiveScriptSite::EnableModeless(
    BOOL fEnable  // enable flag
);

Causes the host to enable or disable its main window as well as any modeless dialog boxes.

fEnable: [in] Flag that, if TRUE, enables the main window and modeless dialogs or, if FALSE, disables them.

This method is identical to IOleInPlaceFrame::EnableModeless.

Calls to this method can be nested.

Returns

S_OK The method was successful.
E_FAIL An error occurred.

IActiveScriptSite::GetWindow

HRESULT GetWindow(
    HWND *phwnd  // address of variable for window handle
);

Retrieves the handle of a window that can act as the owner of a pop-up window that the scripting engine needs to display.

phwnd: [out] Address of a variable that receives the window handle.

This method is similar to IOleWindow::GetWindow.

Returns

S_OK The window handle was successfully retrieved.
E_FAIL An error occurred.

Enumerations

SCRIPTSTATE

typedef enum tagSCRIPTSTATE {
    SCRIPTSTATE_UNINITIALIZED = 0,
    SCRIPTSTATE_INITIALIZED   = 5,
    SCRIPTSTATE_STARTED       = 1,
    SCRIPTSTATE_CONNECTED     = 2,
    SCRIPTSTATE_DISCONNECTED  = 3,
    SCRIPTSTATE_CLOSED        = 4
} SCRIPTSTATE;

Contains named constant values that specify the state of a scripting engine. This enumeration is used by the IActiveScript::GetScriptState, IActiveScript::SetScriptState, and IActiveScriptSite::OnStateChange methods.

Elements

SCRIPTSTATE_UNINITIALIZED The script has just been created, but has not yet been initialized using an IPersist* interface and IActiveScript::SetScriptSite.
SCRIPTSTATE_INITIALIZED The script has been initialized, but is not running (connecting to other objects or sinking events) or executing any code. Code can be queried for execution by calling IActiveScriptParse::ParseScriptText.
SCRIPTSTATE_STARTED The script can execute code, but is not yet sinking the events of objects added by the IActiveScript::AddNamedItem method.
SCRIPTSTATE_CONNECTED The script is loaded and connected for sinking events.
SCRIPTSTATE_DISCONNECTED The script is loaded and has a run-time execution state, but is temporarily disconnected from sinking events.
SCRIPTSTATE_CLOSED The script has been closed. The scripting engine no longer works and returns errors for most methods.

SCRIPTTHREADSTATE

typedef enum tagSCRIPTTHREADSTATE {
    SCRIPTTHREADSTATE_NOTINSCRIPT  = 0,
    SCRIPTTHREADSTATE_RUNNING      = 1
} SCRIPTTHREADSTATE;

Contains named constant values that specify the state of a thread in a scripting engine. This enumeration is used by the IActiveScript::GetScriptThreadState method.

Elements

SCRIPTTHREADSTATE_NOTINSCRIPT The specified thread is not currently servicing a scripted event, processing immediately executed script text, or running a script macro.
SCRIPTTHREADSTATE_RUNNING The specified thread is actively servicing a scripted event, processing immediately executed script text, or running a script macro.

IUnknown methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.

IActiveScript methods	Description
SetScriptSite	Informs the scripting engine of the IActiveScriptSite site provided by the host.
GetScriptSite	Retrieves the site object associated with the ActiveX Scripting engine.
SetScriptState	Puts the scripting engine into the given state.
GetScriptState	Retrieves the current state of the scripting engine.
Close	Causes the scripting engine to abandon any currently loaded script, lose its state, and release any interface pointers it has to other objects, thus entering a closed state.
AddNamedItem	Adds the name of a root-level item to the scripting engine's name space.
AddTypeLib	Adds a type library to the name space for the script.
GetScriptDispatch	Retrieves the IDispatch interface for the methods and properties associated with the running script itself.
GetCurrentScriptThreadID	Retrieves a scripting-engine-defined identifier for the currently executing thread.
GetScriptThreadID	Retrieves a scripting-engine-defined identifier for the thread associated with the given Microsoft Win32® thread.
GetScriptThreadState	Retrieves the current state of a script thread.
InterruptScriptThread	Interrupts the execution of a running script thread.
Clone	Clones the current scripting engine (minus any current execution state), returning a loaded, unsited scripting engine in the current thread.

S_OK	The named item was successfully added to the script's name space.
E_UNEXPECTED	The call was not expected (for example, the scripting engine has not yet been loaded or initialized).
E_POINTER	An invalid pointer was specified.
E_INVALIDARG	An argument was invalid.

S_OK	The specified type library was successfully added.
E_UNEXPECTED	The call was not expected (for example, the scripting engine has not yet been loaded or initialized).
TYPE_E_CANTLOADLIBRARY	The specified type library could not be loaded.
E_INVALIDARG	An argument was invalid.

S_OK	The scripting engine was successfully cloned.
E_NOTIMPL	The Clone method is not supported.
E_POINTER	An invalid pointer was specified.
E_UNEXPECTED	The call was not expected (for example, the scripting engine has not yet been loaded or initialized).

S_OK	The script was successfully closed.
S_FALSE	The method succeeded, but the script was already closed.
OLESCRIPT_S_PENDING	The method was queued successfully, but the state hasn't changed yet. When the state changes, the site will be called back on IActiveScriptSite::OnStateChange.
E_UNEXPECTED	The call was not expected (for example, the scripting engine was already in the closed state).

S_OK	The identifier was successfully retrieved.
E_POINTER	An invalid pointer was specified.

S_OK	The dispatch object for the script was successfully retrieved.
S_FALSE	The scripting engine does not support a dispatch object; the ppdisp parameter is set to NULL.
E_UNEXPECTED	The call was not expected (for example, the scripting engine has not yet been loaded or initialized).
E_POINTER	An invalid pointer was specified.
E_INVALIDARG	An argument was invalid.

S_OK	The site object was successfully retrieved.
S_FALSE	No site has been set; ppvSiteObject is set to NULL.
E_POINTER	An invalid pointer was specified.
E_INVALIDARG	An argument was invalid.
E_NOINTERFACE	The specified interface is not supported.

S_OK	The state information was successfully retrieved.
E_POINTER	An invalid pointer was specified.

S_OK	The current state was successfully retrieved.
E_POINTER	An invalid pointer was specified.
E_UNEXPECTED	The call was not expected (for example, the scripting engine has not yet been loaded or initialized).

S_OK	The given thread was successfully interrupted.
E_POINTER	An invalid pointer was specified.
E_INVALIDARG	An argument was invalid.
E_UNEXPECTED	The call was not expected (for example, the scripting engine has not yet been loaded or initialized).

S_OK	The host site was set successfully.
E_POINTER	An invalid pointer was specified.
E_INVALIDARG	An argument was invalid.
E_FAIL	An unspecified error occurred; the scripting engine was unable to finish initializing the site.
E_UNEXPECTED	The call was not expected (for example, a site was already set).

S_OK	The script successfully entered the given state.
S_FALSE	The method succeeded, but the script was already in the given state.
OLESCRIPT_S_PENDING	The method was queued successfully, but the state hasn't changed yet. When the state changes, the site will be called back through the IActiveScriptSite::OnStateChange method.
E_FAIL	The scripting engine does not support the transition back to the initialized state. The host must discard this scripting engine and create, initialize, and load a new scripting engine to achieve the same effect.
E_UNEXPECTED	The call was not expected (for example, the scripting engine has not yet been loaded or initialized).

IActiveScriptParse methods	Description
InitNew	Initializes the scripting engine.
AddScriptlet	Adds a code scriptlet to the script.
ParseScriptText	Parses the given code scriptlet, adding declarations into the name space and evaluating code as appropriate.

S_OK	The scriptlet was successfully added to the script--the pbstrName parameter contains the scriptlet's name.
OLESCRIPT_E_INVALIDNAME	The default name supplied is invalid in this scripting language.
OLESCRIPT_E_SYNTAX	An unspecified syntax error occurred in the scriptlet.
DISP_E_EXCEPTION	An exception occurred in the parsing of the scriptlet; the pexcepinfo parameter contains information about the exception.
E_UNEXPECTED	The call was not expected (for example, the scripting engine has not yet been loaded or initialized).
E_NOTIMPL	This method is not supported; the scripting engine does not support adding event-sinking scriptlets.
E_POINTER	An invalid pointer was specified.
E_INVALIDARG	An argument was invalid.

S_OK	The scripting engine was successfully initialized.
E_FAIL	An error occurred during initialization.

S_OK	The expression or statement(s) has been evaluated. The pvarResult parameter contains the result, if any.
E_POINTER	An invalid pointer was specified.
E_INVALIDARG	An argument was invalid.
E_UNEXPECTED	The call was not expected (for example, the scripting engine is in the uninitialized or closed state, or the SCRIPTTEXT_ISEXPRESSION flag was set and the scripting engine is in the initialized state).
DISP_E_EXCEPTION	An exception occurred in the processing of the scriptlet. The pexcepinfo parameter contains information about the exception.
OLESCRIPT_E_SYNTAX	An unspecified syntax error occurred in the scriptlet.
E_NOTIMPL	This method is not supported. The scripting engine does not support run-time evaluation of expressions or statements.

IActiveScriptError methods	Description
GetExceptionInfo	Retrieves information about an error.
GetSourcePosition	Retrieves the location in the source code where an error occurred.
GetSourceLineText	Retrieves the line in the source file where an error occurred.

S_OK	The error information was successfully retrieved.
E_FAIL	An error occurred.

S_OK	The line in the source file was successfully retrieved.
E_FAIL	An error occurred.

S_OK	The error location was successfully retrieved.
E_FAIL	An error occurred.

IActiveScriptSite methods	Description
GetLCID	Retrieves the locale identifier that the host uses for displaying user-interface elements.
GetItemInfo	Obtains information about an item that was added to an engine through a call to the IActiveScript::AddNamedItem method.
GetDocVersionString	Retrieves a host-defined string that uniquely identifies the current document version from the host's point of view.
OnScriptTerminate	Informs the host that the script has completed execution.
OnStateChange	Informs the host that the scripting engine has changed states.
OnScriptError	Informs the host that an execution error occurred while the engine was running the script.
OnEnterScript	Informs the host that the scripting engine has begun executing the script code.
OnLeaveScript	Informs the host that the scripting engine has returned from executing script code.

S_OK	The document version string was successfully retrieved. The pstrVersionString parameter contains the string.
E_NOTIMPL	This method is not supported. The scripting engine should assume that the script is in sync with the document.

S_OK	The requested interface pointer was successfully retrieved. The ppunkItem or ppTypeInfo parameter contains the pointer.
E_POINTER	An invalid pointer was specified.
E_INVALIDARG	An argument was invalid.
TYPE_E_ELEMENTNOTFOUND	An item of the specified name was not found.

S_OK	The locale identifier was successfully retrieved. The plcid parameter contains the identifier.
E_POINTER	An invalid pointer was specified.
E_NOTIMPL	This method is not implemented. Use the system-defined locale.

S_OK	The scripting engine should continue running the script as best as possible (perhaps abandoning the processing of this event).
S_FALSE	The scripting engine should continue running the script in the debugger, if a debugger is available. If a debugger is not available, this error should be handled in the same way as E_FAIL.
E_FAIL	The scripting engine should abort execution of the script and return it to the initialized state. In this case, the pexcepinfo parameter obtained from IActiveScriptError::GetExceptionInfo is generally passed to OnScriptTerminate.

IActiveScriptSiteWindow methods	Description
GetWindow	Retrieves the window handle that can act as the owner of a pop-up window that the scripting engine needs to display.
EnableModeless	Causes the host to enable or disable its main window as well as any modeless dialog boxes.

S_OK	The window handle was successfully retrieved.
E_FAIL	An error occurred.

SCRIPTSTATE_UNINITIALIZED	The script has just been created, but has not yet been initialized using an IPersist* interface and IActiveScript::SetScriptSite.
SCRIPTSTATE_INITIALIZED	The script has been initialized, but is not running (connecting to other objects or sinking events) or executing any code. Code can be queried for execution by calling IActiveScriptParse::ParseScriptText.
SCRIPTSTATE_STARTED	The script can execute code, but is not yet sinking the events of objects added by the IActiveScript::AddNamedItem method.
SCRIPTSTATE_CONNECTED	The script is loaded and connected for sinking events.
SCRIPTSTATE_DISCONNECTED	The script is loaded and has a run-time execution state, but is temporarily disconnected from sinking events.
SCRIPTSTATE_CLOSED	The script has been closed. The scripting engine no longer works and returns errors for most methods.