The ActiveX Scripting Site Object

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 OLE Controls). Typically, this container will correspond to the document or page being viewed. The Internet Explorer (IE), for example, would create such a container for each HTML page being displayed. Each OLE Control (or other OLE Automation object) on the page, and the scripting engine itself, would be enumerable within this container.

IActiveScriptSite


interface IActiveScriptSite : IUnknown
  {
  HRESULT GetLCID([out] LCID *plcid);
  HRESULT GetItemInfo(
      [in]  LPCOLESTR   pstrName,
      [in]  DWORD       dwReturnMask,
      [out] IUnknown  **ppunkItem, 
      [out] ITypeInfo **ppTypeInfo);
  HRESULT GetDocVersionString([out] BSTR *pstrVersionString);
  HRESULT OnScriptTerminate([in] VARIANT *pvarResult, [in] EXCEPINFO *pexcepinfo);
  HRESULT OnStateChange([in] SCRIPTSTATE ssScriptState);
  HRESULT OnScriptError([in] IActiveScriptError *pase);
  HRESUT    OnEnterScript();
  HRESULT   OnLeaveScript();
  };

GetLCID


HRESULT IActiveScriptSite::GetLCID([out] LCID *plcid);

Retrieves the internationalization locale ID associated for the host's UI. This allows error strings and other UI surfaced by the scripting engine to appear in the appropriate language for the end user. If this method returns E_NOTIMPL, the system LCID should be used.

plcid: The returned language ID for UI displayed by the scripting engine.

Returns

S_OK Success, lcid contains the appropriate LCID.
E_POINTER An invalid pointer was passed.
E_NOTIMPL Use the sytem LCID.

GetItemInfo


HRESULT IActiveScriptSite::GetItemInfo(
  [in]  LPCOLESTR   pstrName,
  [in]  DWORD       dwReturnMask,
  [out] IUnknown  **ppunkItem, 
  [out] ITypeInfo **ppTypeInfo);

Allows the scripting engine to obtain information about an item added with IActiveScript::AddNamedItem(). Note that if the associated bit for each out parameter pointer is not set in dwReturnMask, the respective result is not returned. This improves performance, for example, in the case where an ITypeInfo is not needed for an item.

pstrName

The name associated with the item, as specified in IActiveScript::AddNamedItem().

dwReturnMask

A bit mask specifying what information about the item should be returned. The scripting engine should take care to request the minimum needed information because some of the return parameters (for example, ITypeInfo) may take considerable time to load or generate.

SCRIPTINFO_IUNKNOWN	Return the IUnknown for this item.
SCRIPTINFO_ITYPEINFO	Return the ITypeInfo for this item.

ppunkItem

The IUnknown associated with the item. The scripting engine can QueryInterface() for IDispatch through this. NULL is returned if SCRIPTINFO_IUNKNOWN is not set in dwReturnMask. A NULL is also returned when there is no object to be associated with the name; this mechanism is used to create a simple class when the named item was added with the SCRIPTITEM_CODEONLY flag set.

ppTypeInfo

The ITypeInfo associated with the item. NULL is returned if SCRIPTINFO_ITYPEINFO is not set in dwReturnMask. NULL is also returned if type information is not available for this item. In this case, the object cannot source events, and name binding must be realized with IDispatch::GetIDsOfNames(). Note that this ITypeInfo describes the coclass (TKIND_COCLASS), since the object may support multiple interfaces and event interfaces. If the item supports IProvideMultipleTypeInfo, then this ITypeInfo corresponds to the ITypeInfo of index zero obtained from IProvideMultipleTypeInfo::GetInfoOfIndex().

Returns

S_OK Success, the relevant out parameters have been set.
E_POINTER An invalid pointer was passed.
E_INVALIDARG An invalid argument was passed.
TYPE_E_ELEMENTNOTFOUND An item of the specified name was not found.

GetDocVersionString


HRESULT IActiveScriptSite::GetDocVersionString([out] BSTR *pbstrVersionString);

Returns 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 may choose to save this along with its persisted state, forcing a recompile the next time the script is loaded.

pstrVersionString: The host-defined document version string.

Returns

S_OK Success, the document version string is returned in pstrVersionString.
E_NOTIMPL The method is not supported. The scripting engine should assume that the script is in synch with the document.

OnScriptTerminate


HRESULT IActiveScriptSite::OnScriptTerminate(
  [in] VARIANT   *pvarResult,
  [in] EXCEPINFO *pexcepinfo);

Informs the host that the script has completed execution. This method is called before OnStateChange(SCRIPTSTATE_INITIALIZED) is completed. It can be used to return completion status/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.

pvarResult: Pointer to where the script result is stored, or NULL if the script produced no result.
pexcepinfo: Pointer to a structure containing exception information generated at script termination, or NULL if no exception was generated.

Returns

S_OK Success.

OnStateChange


HRESULT IActiveScriptSite::OnStateChange([in] SCRIPTSTATE ssScriptState);

Informs the host that the scripting engine has changed states.

ssScriptState: The new script state. See IActiveScript::GetScriptState() for a description of the states.

Returns

S_OK Success.

OnScriptError


HRESULT IActiveScriptSite::OnScriptError([in] IActiveScriptError*pase);

This method is called when an execution error occurs while running the script.

pase: An object from which error information associated with the error condition can be obtained.

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, then this should be treated just like E_FAIL.
E_FAIL The scripting engine should abort execution of the script and return it to a initialized state. In this case, the pexcepinfo obtained from IActiveScriptError::GetExceptionInfo() is generally passed on to OnScriptTerminate().

OnEnterScript


HRESULT IActiveScriptSite::OnEnterScript();

Called whenever the scripting engine begins to execute script code. This must be called by the scripting engine on every entry or re-entry 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 before returning to the object that fired the event. Calls can nest. For every OnEnterScript() there must eventually be an OnLeaveScript().

OnLeaveScript


HRESULT IActiveScriptSite::OnLeaveScript();

Called whenever the scripting engine returns from executing script code. This must be called by the scripting engine 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 can nest. For every OnEnterScript() there must eventually be an OnLeaveScript().

IActiveScriptSiteWindow

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


interface IActiveScriptSiteWindow : IUnknown
  {
  HRESULT GetWindow([out] HWND *phwnd);
  HRESULT EnableModeless([in] BOOL fEnable);
  };

GetWindow


HRESULT IActiveScriptSite::GetWindow([out] HWND *phwnd);

Returns a window that can act as the owner of a pop-up window the scripting engine wishes to display. This method is similar to IOleWindow::GetWindow().

phwnd: Specifies a window that can act as the owner window for pop-ups.

Returns

S_OK Success.
E_FAIL An error occurred.

EnableModeless


HRESULT IActiveScriptSite::EnableModeless([in] BOOL fEnable);

Causes the host to enable or disable its main window as well as any modeless dialog boxes. This method is identical to IOleInPlaceFrame::EnableModeless().

fEnable: Specifies whether the modeless dialogs are to be enabled (TRUE) or disabled (FALSE). Calls nest.

Returns

S_OK Success.
E_FAIL An error occurred.

(*) Certain interpreted script languages (for example, VBScript) running in specific host environments (for example, Internet Explorer) may rarely (or never) be called upon to save or restore a script state via IPersist*. Instead, IActiveScriptParse is used by calling IActiveScriptParse::InitNew() to create a blank script, then scriptlets are added and connected to events with IActiveScriptParse::AddScriptlet() and general code is added via IActiveScriptParse::ParseScriptText(). Nonetheless, a scripting engine should fully implement at least one IPersist* scheme (preferably IPersistStreamInit), as other host applications may try to make use of them.

(**) Unfortunately, this also means that the scripting engine must be implemented as an in-process server, since OLE does not currently support interprocess marshaling of free-threaded objects.

(***)For more information, see A Word About Threading.

S_OK	Success, lcid contains the appropriate LCID.
E_POINTER	An invalid pointer was passed.
E_NOTIMPL	Use the sytem LCID.

S_OK	Success, the relevant out parameters have been set.
E_POINTER	An invalid pointer was passed.
E_INVALIDARG	An invalid argument was passed.
TYPE_E_ELEMENTNOTFOUND	An item of the specified name was not found.

S_OK	Success, the document version string is returned in pstrVersionString.
E_NOTIMPL	The method is not supported. The scripting engine should assume that the script is in synch with the document.

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, then this should be treated just like E_FAIL.
E_FAIL	The scripting engine should abort execution of the script and return it to a initialized state. In this case, the pexcepinfo obtained from IActiveScriptError::GetExceptionInfo() is generally passed on to OnScriptTerminate().