ActiveX Scripting Hosts

ActiveX Scripting Hosts


When implementing an ActiveX™ Scripting host, you can safely assume that a scripting engine will only call the IActiveScriptSite interface in the context of the base thread as long as the host does the following:

These rules are automatically followed by all single-threaded hosts. The restricted model described above is intentionally loose enough to allow a host to abort a stuck script by calling IActiveScript::InterruptScriptThread from another thread (initiated by a CTRL+BREAK handler or the like), or to duplicate a script in a new thread using IActiveScript::Clone.

Also, none of these restrictions apply to a host that chooses to implement a free-threaded IActiveScriptSite interface and a free-threaded object model. Such a host can use the IActiveScript interface from any thread, without restriction.

Scripting Host Reference

The following interfaces are specific to Microsoft® ActiveX™ Scripting hosts:

IActiveScriptSite

The host must create a site for the ActiveX Scripting engine by implementing the IActiveScriptSite interface. 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. Microsoft 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.

Methods in Vtable Order
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 Called when 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.

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

Retrieves a host-defined string that uniquely identifies the current document version. 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.

If E_NOTIMPL is returned, 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 the IActiveScript::AddNamedItem method.

pstrName
[in] The name associated with the item, as specified in the IActiveScript::AddNamedItem method.
dwReturnMask
[in] A bit mask specifying what information about the item should be returned. The scripting engine should request the minimum amount of information possible 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:
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 IUnknown::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 in the IActiveScript::AddNamedItem method.
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 the IDispatch::GetIDsOfNames method. Note that the ITypeInfo interface retrieved describes the item's coclass (TKIND_COCLASS) because the object may support multiple interfaces and event interfaces. If the item supports the IProvideMultipleTypeInfo interface, the ITypeInfo interface retrieved is the same as the index zero ITypeInfo that would be obtained using the IProvideMultipleTypeInfo::GetInfoOfIndex method.

This method retrieves only the information indicated by the dwReturnMask parameter; this improves performance. For example, if an ITypeInfo interface is not needed for an item, it is simply not specified in dwReturnMask.

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 generated by the engine appear in the appropriate language.

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

If this method returns E_NOTIMPL, the system-defined locale identifier should be used.

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 IActiveScriptSite::OnEnterScript before executing the event, and must call the IActiveScriptSite::OnLeaveScript method after executing the event but before returning to the object that fired the event. Calls to this method can be nested. Every call to this method requires a corresponding call to IActiveScriptSite::OnLeaveScript.

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 calling application 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 the IActiveScriptSite::OnEnterScript method before executing the event, and must call IActiveScriptSite::OnLeaveScript after executing the event before returning to the object that fired the event. Calls to this method can be nested. Every call to IActiveScriptSite::OnEnterScript requires a corresponding call to this method.

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.
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 the IActiveScriptSite::OnStateChange method, with the SCRIPTSTATE_INITIALIZED flag set, is completed. This 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.

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 the IActiveScript::GetScriptState method for a description of the states.

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.

Methods in Vtable Order
GetWindow Retrieves the window handle that can act as the owner of a pop-up window that the scripting engine must display.
EnableModeless Causes the host to enable or disable its main window as well as any modeless dialog boxes.

IActiveScriptSiteWindow::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 the IOleInPlaceFrame::EnableModeless method.

Calls to this method can be nested.

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

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

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

This method is similar to the IOleWindow::GetWindow method.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.