
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.
The following interfaces are specific to Microsoft® ActiveX Scripting hosts:
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. |
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.
If E_NOTIMPL is returned, the scripting engine should assume that the script is in sync with the document.
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.
| S_OK | Success. |
| E_INVALIDARG | An argument was invalid. |
| E_POINTER | An invalid pointer was specified. |
| TYPE_E_ELEMENTNOTFOUND | An item of the specified name was not found. |
| SCRIPTINFO_IUNKNOWN | Return the IUnknown interface for this item. |
| SCRIPTINFO_ITYPEINFO | Return the ITypeInfo interface for this item. |
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.
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.
| S_OK | Success. |
| E_NOTIMPL | This method is not implemented. Use the system-defined locale. |
| E_POINTER | An invalid pointer was specified. |
If this method returns E_NOTIMPL, the system-defined locale identifier should be used.
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.
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.
HRESULT IActiveScriptSite::OnScriptError(
IActiveScriptError *pase // address of error interface
);
Informs the host that an execution error occurred while the engine was running the script.
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.
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.
HRESULT IActiveScriptSite::OnStateChange(
SCRIPTSTATE ssScriptState // new state of engine
);
Informs the host that the scripting engine has changed states.
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. |
HRESULT IActiveScriptSite::EnableModeless(
BOOL fEnable // enable flag
);
Causes the host to enable or disable its main window as well as any modeless dialog boxes.
This method is identical to the IOleInPlaceFrame::EnableModeless method.
Calls to this method can be nested.
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.
This method is similar to the IOleWindow::GetWindow method.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.