ActiveX Scripting

Overview
This document introduces a new way to add scripting and OLE Automation capabilities to programs such as applications or servers. With the advent of Microsoft Active ! "cripting# hosts can call upon disparate scripting engines from multiple sources and vendors to perform scripting between components. The implementation of the script itself$language# synta%# persistent format# e%ecution model# and so on$is left to the script vendor. &are has been ta'en to allow hosts that rely on Active "cripting to use arbitrary language (bac' ends.(

Terms
The following list contains definitions of the scripting)related terms used in this document.
Term code object Definition An instance created by the scripting engine that is associated with a named item# such as the module behind a form in *isual +asic# or a &,, class associated with a named item. -referably# this code ob.ect is an OLE &omponent Ob.ect Model /&OM0 ob.ect supporting OLE Automation so that the host or other nonscript entity can manipulate the code ob.ect. An OLE &OM ob.ect /preferably one that supports OLE Automation0 that the host deems interesting to the script. E%amples include the 1TML -age and +rowser in a Web browser# and the 2ocument and 2ialogs in Microsoft Word. The data that ma'es up the (program( that the scripting engine runs. A script is any e%ecutable blob# including a piece of te%t# a bloc' of pcode# or even machine)specific e%ecutable byte codes. A host loads a script into the scripting engine through one of the IPersist* interfaces or through the IActiveScriptParse interface. The OLE ob.ect that processes scripts. A scripting engine implements IActiveScript and# optionally# IActiveScriptParse . The application or program that owns the Active "cripting engine. The host implements IActiveScriptSite and# optionally# IActiveScriptSiteWindow. A portion of a script that gets attached to an ob.ect through IActiveScriptParse . The aggregate collection of scriptlets is the script. The language in which a script is written /for e%ample# *+"cript0 and the semantics of that language.

named item

script

scripting engine

scripting host

scriptlet

script language

ActiveX Scripting

ActiveX Scripting Background

Active "cripting components fall into two categories3 Active "cripting hosts and Active "cripting engines. A host creates a scripting engine and calls on the engine to run the scripts. E%amples of e%isting and potential Active "cripting hosts include3

Microsoft 4nternet E%plorer 4nternet authoring tools Tarantula56ibraltar /server)based scripting0 "hell

Active "cripting engines can be developed for any language or run)time environment# including3

Microsoft *isual +asic for Applications /*+A0 Microsoft *isual +asic "cripting Edition /*+"cript0 -erl Lisp# "cheme

To ma'e implementation of the host as fle%ible as possible# an OLE Automation wrapper for Active "cripting is provided. 1owever# a host that uses this wrapper ob.ect to instantiate the scripting engine does not have the control over the run)time name space# the persistence model# and so on# that it would have if it used Active "cripting directly. The Active "cripting design isolates the interface elements re7uired only in an authoring environment so that non)authoring hosts /such as browsers and viewers0 and script engines /for e%ample# *+"cript0 can be 'ept lightweight.

Basic Architecture
The following illustration shows the interaction between an Active "cripting host and an Active "cripting engine.

ActiveX Scripting

8ollowing is a description of the steps involved in the interaction between the host and engine /the actual nesting of the function calls is omitted for clarity03
9 Create a Project The host loads a pro.ect or document. /This step is not particular to Active "cripting# but is included here for completeness.0 : Create the Active! Scripting "ngine The host calls CoCreateInstance to create a new Active "cripting engine# specifying the class identifier /&L"420 of the specific scripting engine to use. 8or e%ample# the 1TML browsing component of 4nternet E%plorer receives the scripting engine;s class identifier through the C#SID$ attribute of the 1TML <O+=E&T> tag. ? #oad the Script 4f the script contents have been persisted# the host calls the script engine;s IPersist*%%#oad method to feed it the script storage# stream# or property bag. Otherwise# the host uses IPersist*%%Init&ew or IActiveScriptParse%%Init&ew to create a null script. A host that maintains a script as te%t can use IActiveScriptParse%%ParseScriptTe't to feed the scripting engine the te%t of the script# after calling Init&ew. @ Add Items 8or each top)level named item /such as pages and forms0 imported into the scripting engine;s name space# the host calls IActiveScript%%Add&amedItem to create an entry in the engine;s name space. This step is not necessary if top)level named items are already part of the persistent state of the script loaded in step ?. A host does not use Add&amedItem to add sublevel named items /such as controls on an 1TML page0A rather# the engine indirectly obtains sublevel items from top)level items by using the host;s IT(peInfo and IDispatch interfaces. B )un the Script The host causes the engine to start running the script by passing the SC)IPTSTAT"*C+&&"CT"D value to IActiveScript%%SetScriptState . This call would li'ely perform any scripting engine construction wor'# including static bindings# hoo'ing up to events /see below0# and e%ecuting code similar to a scripted (main,-( function. C .et Item Information Each time the script engine needs to associate a symbol with a top)level item# it calls the IActiveScriptSite%%.etItemInfo method# which returns information about the given item.

Note:

ActiveX Scripting

D /oo0 1p "vents +efore starting the actual script# the scripting engine connects to the events of all the relevant ob.ects through the IConnectionPoint interface and other methods. E Invo0e Properties and 2ethods As the script runs# the scripting engine realiFes references to methods and properties on named ob.ects through IDispatch%%Invo0e or other standard OLE binding mechanisms.

ActiveX Scripting Engine

To write an Active "cripting engine# write an OLE &OM ob.ect that supports the following interfaces.
Interface IActiveScript IPersist* )e3uired4 Ges Ges. At least one of the following /see note below0. IPersistStorage IPersistStreamInit Description +asic scripting ability. -ersistence support. DATA$ {url} synta% for +56"CT tag. "ame as above# as well as DATA$ "string-encoded byte stream" synta% for +56"CT tag. PA)A2$ synta% for +56"CT tag. Ability to add script te%t# evaluate e%pressions# and so on.

IPersistPropert(5ag IActiveScriptParse Ho

"upport for the IActiveScriptParse interface is optionalA however# if it is not supported# the script engine must implement one of the IPersist* interfaces in order to load a given script.
&ertain interpreted script languages /for e%ample# *+"cript0 running in specific host environments /for e%ample# 4nternet E%plorer0 may rarely /or never0 be called upon to save or restore a script state through IPersist*. 4nstead# IActiveScriptParse is used by calling IActiveScriptParse%%Init&ew to create a blan' script# then scriptlets are added and connected to events with IActiveScriptParse%%AddScriptlet and general code is added via IActiveScriptParse%%ParseScriptTe't. Honetheless# a scripting engine should fully implement at least one IPersist* scheme /preferably IPersistStreamInit0# because other host applications may try to ma'e use of them.

ActiveX Scripting

egistr! Standard
An Active "cripting engine can identify itself using component categories. Active "cripting currently defines two component categories3
Categor( CATID*ActiveScript Description 4ndicates that the class identifiers /&L"42s0 are Active "cripting engines that support# at a minimum# IActiveScript and a persistence mechanism /IPersistStorage# IPersistStreamInit# or IPersistPropert(5ag 0. 4ndicates that the &L"42s are Active "cripting engines that support# at a minimum# IActiveScript and IActiveScriptParse .

CATID*ActiveScriptParse

Although IActiveScriptParse is not a true persistence mechanism# it does support an Init&ew method that is functionally e7uivalent to IPersist*%%Init&ew.

Script Engine States

At any given time# an Active "cripting engine can be in one of several states.
State uninitiali7ed Description The script has not been initialiFed or loaded using an IPersist* interface# or does not have an IActiveScriptSite set. The scripting engine is generally not usable from this state until the host ta'es steps to initialiFe the engine. The script has been initialiFed with an IPersist* interface and has an IActiveScriptSite set# but is not connected to host ob.ects and sin'ing events. Hote that this state simply means that IPersist*%%#oad# IPersist*%%Init&ew # or IActiveScriptParse%%Init&ew has been completed# and IActiveScript%%SetScriptSite has been called. The engine cannot run code in this mode. The engine 7ueues code that the host passes to it through IActiveScriptParse%%ParseScriptTe't # and e%ecutes the code after transitioning to the started state. The transition from the initiali7ed state to started state causes the engine to e%ecute any code that was 7ueued in the initiali7ed state. The engine can e%ecute code while in the started state# but it is not connected to events of the ob.ects added through IActiveScript%%Add&amedItem . The engine can e%ecute code by calling the IDispatch interface obtained from IActiveScript%%.etScriptDispatch# or by calling IActiveScriptParse%%ParseScriptTe't . 4t is possible that further bac'ground initialiFation /progressive loading0 is still ongoing# and that calling SetScriptState with the SC)IPTSTAT"*C+&&"CT"D value may cause the script

initiali7ed

started

ActiveX Scripting to bloc' until initialiFation is complete. connected disconnected The script is loaded and connected for sin'ing events from host ob.ects. The script is loaded and has a run)time state# but is temporarily disconnected from sin'ing events from host ob.ects. This state is distinguished from the initiali7ed state in that the transition to this state does not cause the script to reset# the run)time state of the script is not reset# and a script initialiFation procedure is not e%ecuted. The script has been closed. The scripting engine no longer wor's and returns errors for most methods.

closed

The following illustration shows the relationships between the various scripting engine states# and shows the methods that cause transitions from one state to another.

The following illustration shows the actions that the scripting engine performs during the various state transitions.

ActiveX Scripting

"

A #ord A$out Threading

+ecause an Active "cripting engine can be used in many environments# it is important to 'eep its e%ecution model as fle%ible as possible. 8or e%ample# a server) based host may have a multithreaded design that it needs to preserve while using Active "cripting in an efficient manner. At the same time# a host that does not use threading# such as a typical application# should not be burdened with threading management. Active "cripting achieves this balance by restricting the ways a free)threaded scripting engine can call bac' to the host# freeing hosts from this burden.

%or Scripting Engine &mp'ementers

"cripting engines used on servers are typically implemented as free)threading &OM ob.ects. This means that methods on IActiveScript and its associated interfaces can be called from any thread in the process# without marshaling. /Infortunately# this also means that the scripting engine must be implemented as an in)process server# because OLE does not currently support interprocess marshaling of free) threaded ob.ects.0 "ynchroniFation is the responsibility of the scripting engine. 8or scripting engines that are not internally reentrant# or for language models that are

ActiveX Scripting

not multithreaded# synchroniFation could be as simple as serialiFing access to the scripting engine with a mute%. Of course certain methods# such as InterruptScriptThread# should not be serialiFed in this way# so that a stuc' script can be terminated from another thread. The fact that IActiveScript is free)threaded generally implies that IActiveScriptSite and the host;s ob.ect model should be free)threaded as well. This would ma'e implementation of the host 7uite difficult# particularly in the common case where the host is a single)threaded Windows)based application with single) threaded or apartment)model Active controls in its ob.ect model. 8or this reason# the following constraints are placed on the scripting engine;s use of IActiveScriptSite 3

The script site is always called in the conte%t of a host thread. That is# the scripting engine never calls the script site in the conte%t of a thread that it created# but only from within a scripting engine method that was called from the host /directly through IActiveScript and its derivatives# through the e%posed scripting engine;s dispatch ob.ect# or through a Windows messageA indirectly from an event source in the host;s ob.ect model0. The script site is never called from within the conte%t of a simple thread state control method /for e%ample# InterruptScriptThread 0 or from the Clone method.

%or Scripting (ost &mp'ementers

A host can safely assume that an engine will call IActiveScriptSite only in the conte%t of the base thread# as long as the host obeys the following rules3

&hoose a base thread /generally the thread that contains the message loop0. 4nstantiate the scripting engine in the base thread. &all scripting engine methods only from the base thread# e%cept where specifically allowed# as in the cases of InterruptScriptThread and Clone. &all the scripting engine;s dispatch ob.ect only in the base thread. Ensure that the message loop runs in the base thread if a window handle is provided. Ensure that ob.ects in the host;s ob.ect model only source events in the base thread.

Hote that 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 stuc' script by calling InterruptScriptThread from another thread /initiated by a &TJL,+JEAK handler or the li'e0# or to duplicate a script in a new thread using Clone.

ActiveX Scripting

Also note that none of these restrictions apply to a host that chooses to implement a free)threaded IActiveScriptSite and a free)threaded ob.ect model. "uch a host can use IActiveScript from any thread# without restriction.

Script Thread E*ecution States

Each script thread can be in one of the following e%ecution states3
State &otInScript Description The thread is not currently running in a script /sin'ing a scripted event# processing ParseScriptTe't # or being called through a global script function published through .etScriptDispatch0. The thread is currently e%ecuting script code.

)unning

&nter+aces and ,ethods

&ActiveScript
The scripting engine must implement the IActiveScript interface in order to be an Active "cripting engine. 2ethods in 8table +rder
4In'nown methods 9uer(Interface Add)ef )elease 4Active"cript methods SetScriptSite .etScriptSite SetScriptState .etScriptState Close Description Jeturns pointers to supported interfaces. 4ncrements the reference count. 2ecrements the reference count. Description 4nforms the scripting engine of the IActiveScriptSite site provided by the host. Jetrieves the site ob.ect associated with the Active "cripting engine. -uts the scripting engine into the given state. Jetrieves the current state of the scripting engine. &auses the scripting engine to abandon any currently loaded script# lose its state# and release any interface pointers it has to other ob.ects# thus entering a closed state. Adds the name of a root)level item to the scripting engine;s name space. Adds a type library to the name space for the script.

Add&amedItem AddT(pe#ib

ActiveX Scripting .etScriptDispatch Jetrieves the IDispatch interface for the methods and properties associated with the running script itself. Jetrieves a scripting)engine)defined identifier for the currently e%ecuting thread. Jetrieves a scripting)engine)defined identifier for the thread associated with the given Microsoft Win?: thread. Jetrieves the current state of a script thread. 4nterrupts the e%ecution of a running script thread. &lones the current scripting engine /minus any current e%ecution state0# returning a loaded# unsited scripting engine in the current thread.

.etCurrentScriptThreadID .etScriptThreadID

.etScriptThreadState InterruptScriptThread Clone

&ActiveScript::AddNamed&tem
HRESULT AddNamedItem( LPCOLESTR pstrName, DWORD d !"a#s $% // address of item name // item f"a#s

Adds the name of a root)level item to the scripting engine;s name space. A root) level item is an ob.ect with properties and methods# an event source# or both. pstrName LinM Address of a buffer that contains the name of the item as viewed from the script. The name must be uni7ue and persistable. dwFlags LinM 8lags associated with item. &an be a combination of these values3
8alue SC)IPTIT"2*ISP")SIST"&T 2eaning 4ndicates that the item should be saved if the scripting engine is saved. "imilarly# setting this flag indicates that a transition bac' to the initiali7ed state should retain the item;s name and type information /the scripting engine must# however# release all pointers to interfaces on the actual ob.ect0. 4ndicates that the item sources events that the script can sin'. &hildren /properties of the ob.ect that are in themselves ob.ects0 can also source events to the script. This is not recursive# but it provides a convenient mechanism for the common case# for e%ample# of adding a container and all of its member controls.

SC)IPTIT"2*ISS+1)C"

ActiveX Scripting SC)IPTIT"2*IS8ISI5#"

11

4ndicates 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. +ecause by convention the properties of the item include the item;s children# all child ob.ect properties and methods /and their children# recursively0 will be accessible. 4ndicates that the item is a collection of global properties and methods associated with the script. Hormally# a scripting engine would ignore the ob.ect name /other than for the purpose of using it as a coo'ie for IActiveScriptSite%%.etItemInfo# or for resolving e%plicit scoping0 and e%pose its members as global variables and methods. This allows the host to e%tend the library /run)time functions and so on0 available to the script. 4t is left to the scripting engine to deal with name conflicts /for e%ample# when two SC)IPTIT"2*.#+5A#2"25")S items have methods of the same name0# although an error should not be returned because of this situation. 4ndicates 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. 8or e%ample# without this flag being set# *+"cript will create a separate module for the named item# and &,, might create a separate wrapper class for the named item. 4ndicates that the named item represents a code)only ob.ect# and that the host has no I1n0nown to be associated with this code)only ob.ect. The host only has a name for this ob.ect. 4n ob.ect)oriented languages such as &,,# this flag would create a class. Hot all languages support this flag.

SC)IPTIT"2*.#+5A#2"25")S

SC)IPTIT"2*&+C+D"

SC)IPTIT"2*C+D"+&#:

eturns
"NOK ENIHE -E&TE2 The named item was successfully added to the script;s name space. The call was not e%pected /for e%ample# the scripting engine has not yet been loaded or

ActiveX Scripting initialiFed0. EN-O4HTEJ EN4H*AL42AJ6 An invalid pointer was specified. An argument was invalid.

"ee also IActiveScriptSite%%.etItemInfo

&ActiveScript::AddT!pe-i$
HRESULT AddT&peLi'( RE!(UID #)idT&peLi', DWORD d +a,, DWORD d +in, DWORD d !"a#s $% // // // // LI*ID of t&pe "i'rar& ma,or -ersion n)m'er minor -ersion n)m'er option f"a#s

Adds a type library to the name space for the script. This is similar to the ;include directive in &5&,,. 4t 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 LinM L4+42 of the type library to add. dwMaj LinM Ma.or version number. dwMin LinM Minor version number. dwFlags LinM Option flags. &an be SC)IPTT:P"#I5*ISC+&T)+# # which indicates that the type library describes an Active control used by the host.

eturns
"NOK ENIHE -E&TE2 The specified type library was successfully added. The call was not e%pected /for e%ample# the scripting engine has not yet been loaded or initialiFed0. The specified type library could not be loaded. An argument was invalid.

TG-ENEN&AHTLOA2L4+JAJG EN4H*AL42AJ6

&ActiveScript::.'one
HRESULT C"one( IA.ti-eS.ript //pps.ript $% // re.ei-es pointer to IA.ti-eS.ript

ActiveX Scripting

13

&lones the current scripting engine /minus any current e%ecution state0# 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 bac' to the initiali7ed state. ppscript LoutM 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 initiali7ed state and# therefore# usable. The Clone method is an optimiFation of IPersist*%%Save# CoCreateInstance# and IPersist*%%#oad# 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. Hamed items are duplicated in the cloned scripting engine# but specific ob.ect pointers for each item are forgotten and are obtained with .etItemInfo. This allows an identical ob.ect model with per)thread entry points /an apartment model0 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 ENHOT4M-L# 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 ob.ects or to IActiveScriptSite .

eturns
"NOK ENHOT4M-L EN-O4HTEJ ENIHE -E&TE2 The scripting engine was successfully cloned. The Clone method is not supported. An invalid pointer was specified. The call was not e%pected /for e%ample# the scripting engine has not yet been loaded or initialiFed0.

"ee also IActiveScript%%SetScriptSite # IActiveScriptSite # IActiveScriptSite%%.etItemInfo

&ActiveScript::.'ose
HRESULT C"ose(-oid$%

&auses the scripting engine to abandon any currently loaded script# lose its state# and release any interface pointers it has to other ob.ects# thus entering a closed state. Event sin's# immediately e%ecuted script te%t# and macro invocations that are already in progress are completed before the state changes /use InterruptScriptThread to cancel a running script thread0. This method must be

ActiveX Scripting

called by the creating host before it calls )elease to prevent circular reference problems.

eturns
"NOK "N8AL"E OLE"&J4-TN"N-EH24H6 The script was successfully closed. The method succeeded# but the script was already closed. The method was 7ueued successfully# but the state hasn;t changed yet. When the state changes# the site will be called bac' on IActiveScriptSite%%+nStateChange. The call was not e%pected /for e%ample# the scripting engine was already in the closed state0.

ENIHE -E&TE2

"ee also IActiveScript%%InterruptScriptThread# IActiveScriptSite%%+nStateChange

&ActiveScript::/et.urrentScriptThread&0
HRESULT (etC)rrentS.riptT0readID( SCRIPTTHREADID /pstidT0read // re.ei-es s.riptin# t0read identifier $%

Jetrieves a scripting)engine)defined identifier for the currently e%ecuting thread. The identifier can be used in subse7uent calls to script thread e%ecution)control methods such as InterruptScriptThread. pstidThread LoutM 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 .ust a copy of the Windows thread identifier. 4f the Win?: thread terminates# this identifier becomes unassigned and can subse7uently be assigned to another thread. This method can be called from non)base threads without resulting in a non)base callout to host ob.ects or to IActiveScriptSite .

eturns
"NOK EN-O4HTEJ The identifier was successfully retrieved. An invalid pointer was specified.

"ee also IActiveScript%%InterruptScriptThread# IActiveScriptSite

&ActiveScript::/etScript0ispatch
HRESULT (etS.riptDispat.0(

ActiveX Scripting
LPCOLESTR pstrItemName IDispat.0 //ppdisp $% // address of item name // re.ei-es IDispat.0 pointer

15

Jetrieves the IDispatch interface for the methods and properties associated with the running script itself. pstrItemName LinM Address of a buffer that contains the name of the item for which the caller needs the associated dispatch ob.ect. 4f this parameter is HILL# the dispatch ob.ect contains as its members all of the global methods and properties defined by the script. Through the IDispatch interface and the associated IT(peInfo interface# the host can invo'e script methods or view and modify script variables. ppdisp LoutM Address of a variable that receives a pointer to the ob.ect associated with the script;s global methods and properties. 4f the scripting engine does not support such an ob.ect# HILL is returned. +ecause methods and properties can be added by calling IActiveScriptParse# the IDispatch interface returned by this function can dynamically support new methods and properties. "imilarly# IDispatch%%.etT(peInfo should return a new# uni7ue IT(peInfo when methods and properties are added. Hote# however# that language engines must not change the IDispatch interface in a way that is incompatible with any previous IT(peInfo interface returned. That implies# for e%ample# that 24"-42s will never be reused.

eturns
"NOK "N8AL"E ENIHE -E&TE2 The dispatch ob.ect for the script was successfully retrieved. The scripting engine does not support a dispatch ob.ectA the ppdisp parameter is set to HILL. The call was not e%pected /for e%ample# the scripting engine has not yet been loaded or initialiFed0. An invalid pointer was specified. An argument was invalid.

EN-O4HTEJ EN4H*AL42AJ6

&ActiveScript::/etScriptSite
HRESULT (etS.riptSite( RE!IID iid, -oid //pp-SiteO',e.t $% // interfa.e identifier // address of 0ost site interfa.e

Jetrieves the site ob.ect associated with the Active "cripting engine.

ActiveX Scripting

iid
LinM 4dentifier of the re7uested interface.

pp !ite"bject LoutM Address of the location that receives the interface pointer to the host;s site ob.ect.

eturns
"NOK "N8AL"E EN-O4HTEJ EN4H*AL42AJ6 ENHO4HTEJ8A&E The site ob.ect was successfully retrieved. Ho site has been setA pp !ite"bject is set to HILL. An invalid pointer was specified. An argument was invalid. The specified interface is not supported.

&ActiveScript::/etScriptState
HRESULT (etS.riptState( SCRIPTSTATE /pss // address of str).t)re for state information $%

Jetrieves 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 ob.ects or to IActiveScriptSite . pss
LoutM Address of a variable that receives a value defined in the SC)IPTSTAT" enumeration. The value indicates the current state of the scripting engine associated with the calling thread.

eturns
"NOK EN-O4HTEJ The state information was successfully retrieved. An invalid pointer was specified.

"ee also IActiveScriptSite # SC)IPTSTAT"

&ActiveScript::/etScriptThread&0
HRESULT (etS.riptT0readID( DWORD d Win12T0readID, SCRIPTTHREADID /pstidT0read $% // Win12 t0read identifier // re.ei-es s.riptin# t0read identifier

Jetrieves a scripting)engine)defined identifier for the thread associated with the given Win?: thread. This identifier can be used in subse7uent calls to script thread e%ecution control methods such as InterruptScriptThread.

ActiveX Scripting

1"

dw#in$%ThreadI& LinM Thread identifier of a running Win?: thread in the current process. Ise the .etCurrentScriptThreadID function to retrieve the thread identifier of the currently e%ecuting thread. pstidThread LoutM Address of a variable that receives the script thread identifier associated with the given Win?: thread. The interpretation of this identifier is left to the scripting engine# but it can be .ust a copy of the Windows thread identifier. Hote that if the Win?: thread terminates# this identifier becomes unassigned and may subse7uently be assigned to another thread. This method can be called from non)base threads without resulting in a non)base callout to host ob.ects or to IActiveScriptSite .

eturns
"NOK EN-O4HTEJ ENIHE -E&TE2 The identifier was successfully retrieved. An invalid pointer was specified. The call was not e%pected /for e%ample# the scripting engine has not yet been loaded or initialiFed0.

"ee also IActiveScript%%InterruptScriptThread# IActiveScriptSite

&ActiveScript::/etScriptThreadState
HRESULT (etS.riptT0readState( SCRIPTTHREADID stidT0read, SCRIPTTHREADSTATE /pstsState $% // identifier of s.ript t0read // re.ei-es state f"a#

Jetrieves the current state of a script thread. stidThread LinM 4dentifier of the thread for which the state is desired# or one of the following special thread identifiers3
8alue SC)IPTT/)"ADID*C1))"&T SC)IPTT/)"ADID*5AS" 2eaning The currently e%ecuting thread. The base threadA that is# the thread in which the scripting engine was instantiated.

psts!tate LoutM 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 SC)IPTT/)"ADSTAT" enumeration. 4f this parameter does not identify the current thread# the state may change at any time.

ActiveX Scripting

This method can be called from non)base threads without resulting in a non)base callout to host ob.ects or to IActiveScriptSite .

eturns
"NOK EN-O4HTEJ ENIHE -E&TE2 The current state was successfully retrieved. An invalid pointer was specified. The call was not e%pected /for e%ample# the scripting engine has not yet been loaded or initialiFed0.

"ee also IActiveScriptSite # SC)IPTT/)"ADSTAT"

&ActiveScript::&nterruptScriptThread
HRESULT Interr)ptS.riptT0read( SCRIPTTHREADID stidT0read, .onst E3CEPIN!O /pe4.epinfo, DWORD d !"a#s $% // identifier of t0read // re.ei-es error information

4nterrupts the e%ecution of a running script thread /an event sin'# an immediate e%ecution# or a macro invocation0. This method can be used to terminate a script that is stuc' /for e%ample# in an infinite loop0. 4t can be called from non)base threads without resulting in a non)base callout to host ob.ects or to IActiveScriptSite . stidThread LinM Thread identifier of the thread to interrupt# or one of the following special thread identifier values3
8alue SC)IPTT/)"ADID*C1))"&T SC)IPTT/)"ADID*5AS" SC)IPTT/)"ADID*A## 2eaning The currently e%ecuting thread. The base threadA that is# the thread in which the scripting engine was instantiated. All threads. The interrupt is applied to all script methods currently in progress. Hote that unless the caller has re7uested that the script be disconnected# by calling SetScriptState with the SC)IPTSTAT"*DISC+&&"CT"D or SC)IPTSTAT"*I&ITIA#I<"D flag# the ne%t scripted event causes script code to run again.

pe'cepin(o LinM Address of an "!C"PI&=+ structure that receives error information associated with the error condition.

ActiveX Scripting

1)

dwFlags LinM Option flags associated with the interruption. &an be one of these values3
SC)IPTI&T"))1PT*D"51. 4f supported# enter the scripting engine;s debugger at the current script e%ecution point. SC)IPTI&T"))1PT*)AIS""!C"PTI+& 4f supported by the scripting engine;s language# let the script handle the e%ception. Otherwise# the script method is aborted and the error code is returned to the callerA that is# the event source or macro invo'er.

eturns
"NOK EN-O4HTEJ EN4H*AL42AJ6 ENIHE -E&TE2 The given thread was successfully interrupted. An invalid pointer was specified. An argument was invalid. The call was not e%pected /for e%ample# the scripting engine has not yet been loaded or initialiFed0.

"ee also IActiveScript%%SetScriptState # IActiveScriptSite

&ActiveScript::SetScriptSite
HRESULT SetS.riptSite( IA.ti-eS.riptSite /pS.riptSite $% // address of 0ost s.ript site

4nforms the scripting engine of the IActiveScriptSite site provided by the host. This method must be called before any other IActiveScript methods can be used. p!cript!ite LinM Address of the host)supplied script site to be associated with this instance of the scripting engine. The site must be uni7uely assigned to this scripting engine instanceA it cannot be shared with other scripting engines.

eturns
"NOK EN-O4HTEJ EN4H*AL42AJ6 EN8A4L ENIHE -E&TE2 The host site was set successfully. An invalid pointer was specified. An argument was invalid. An unspecified error occurredA the scripting engine was unable to finish initialiFing the site. The call was not e%pected /for e%ample# a site was already set0.

"ee also IActiveScriptSite

ActiveX Scripting

&ActiveScript::SetScriptState
HRESULT SetS.riptState( SCRIPTSTATE ss // identifier of ne $% state

-uts 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 ob.ects or to IActiveScriptSite . ss
LinM "ets the scripting engine to the given state. &an be one of the values defined in the SC)IPTSTAT" enumeration3
SC)IPTSTAT"*I&ITIA#I<"D Jeturns the scripting engine bac' to the initiali7ed state from the started# connected# or disconnected state. +ecause languages can vary widely in semantics# scripting engines are not re7uired to support this state transition. Engines that support IActiveScript%%Clone must# however# support this state transition. 1osts must prepare for this transition and ta'e the appropriate action3 )elease the current scripting engine# create a new scripting engine# and call #oad or Init&ew /and possibly also call ParseScriptTe't 0. Ise of this transition should be considered an optimiFation of the above steps. Hote that any information the scripting engine has obtained about the names of Hamed 4tems and the type information describing Hamed 4tems remains valid. +ecause languages vary widely# defining the e%act semantics of this transition is difficult. At a minimum# the scripting engine must disconnect from all events# and release all of the SC)IPTI&=+*I1&>&+W& pointers obtained by calling IActiveScriptSite%%.etItemInfo. The engine must refetch these pointers after the script is run again. The scripting engine should also reset the script bac' to an initial state that is appropriate for the language. *+"cript# for e%ample# resets all variables and retains any code added dynamically by calling IActiveScriptParse with the SC)IPTT"!T*ISP")SIST"&T flag set. Other languages may need to retain current values /such as Lisp because there is no code5data separation0 or reset to a well)'nown state /this includes languages with statically initialiFed variables0. These languages may or may not retain code added by calling IActiveScriptParse . Hote that the transition to the started state should have the same semantics /that is# it should leave the scripting engine in the same state0 as calling IPersist*%%Save to save the scripting engine# and then calling IPersist*%%#oad to load a new scripting engineA these actions should have the same semantics as IActiveScript%%Clone. "cripting 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. 2uring this transition to the started state# the scripting engine will disconnect from event sin's after the appropriate destructors# and so on# are e%ecuted in the script. To avoid having these destructors e%ecuted# the host can first move the script into the disconnected state before moving into the started state.

ActiveX Scripting Ise InterruptScriptThread to cancel a running script thread without waiting for current events# and so on# to finish running. SC)IPTSTAT"*STA)T"D

11

The transition to this mode causes any code that was 7ueued during the initiali7ed state to be e%ecuted. 8rom this state# script code can be e%ecuted# for e%ample# by calling IActiveScriptParse%%ParseScriptTe't or by calling the IDispatch interface obtained from IActiveScript%%.etScriptDispatch. The transition to this state is also the appropriate time to e%ecute routines such as a main,-)li'e script routine# if appropriate for the script language. SC)IPTSTAT"*C+&&"CT"D &auses the script to connect to events. 4f this is a transition from the initiali7ed state# the scripting engine should transition through the started state# performing the necessary actions# before entering the connected state and connecting to events. SC)IPTSTAT"*DISC+&&"CT"D &auses the script to disconnect from event sin's. This can be done either logically /ignoring events received0 or physically /calling 1nadvise on the appropriate connection points0. Jeturning to the connected state reverses this process. 4f this is a transition from the initiali7ed state# the scripting engine should transition through the started state# performing the necessary actions# before entering the disconnected state. Event sin's that are in progress are completed before the state changes /use InterruptScriptThread to cancel a running script thread0. The script;s e%ecution state is maintained. 8or e%ample# an 1TML browser may put the scripting engine into this state when a scripted 1TML page is moved into the LJI cache# before the page is actually destroyed.

eturns
"NOK "N8AL"E OLE"&J4-TN"N-EH24H6 The script successfully entered the given state. The method succeeded# but the script was already in the given state. The method was 7ueued successfully# but the state hasn;t changed yet. When the state changes# the site will be called bac' through the IActiveScriptSite%%+nStateChange method. The scripting engine does not support the transition bac' to the initiali7ed state. The host must discard this scripting engine and create# initialiFe# and load a new scripting engine to achieve the same effect. The call was not e%pected /for e%ample# the scripting engine has not yet been loaded or initialiFed0.

EN8A4L

ENIHE -E&TE2

"ee also IActiveScript%%Clone# IActiveScript%%.etScriptDispatch# IActiveScript%%InterruptScriptThread# IActiveScriptParse%%ParseScriptTe't#

ActiveX Scripting

IActiveScriptSite # IActiveScriptSite%%.etItemInfo# IActiveScriptSite%%+nStateChange# SC)IPTSTAT"

&ActiveScript2arse
4f the Active "cripting engine allows raw te%t code scriptlets to be added to the script# or allows e%pression te%t to be evaluated at run time# it implements IActiveScriptParse. 8or interpreted scripting languages that have no independent authoring environment# such as *isual +asic "cript# this provides an alternate mechanism /other than IPersist* 0 to get script code into the scripting engine# and to attach script fragments to various ob.ect events. 2ethods in 8table +rder
4In'nown methods 9uer(Interface Add)ef )elease 4Active"cript-arse methods Init&ew AddScriptlet ParseScriptTe't Description Jeturns pointers to supported interfaces. 4ncrements the reference count. 2ecrements the reference count. Description 4nitialiFes the scripting engine. Adds a code scriptlet to the script. -arses the given code scriptlet# adding declarations into the name space and evaluating code as appropriate.

&ActiveScript2arse::AddScript'et
HRESULT AddS.ript"et( LPCOLESTR pstrDefa)"tName, // address of defa)"t name of s.ript"et LPCOLESTR pstrCode, // address of s.ript"et te4t LPCOLESTR pstrItemName, // address of item name LPCOLESTR pstrS)'ItemName, // address of s)'item name LPCOLESTR pstrE-entName, // address of e-ent name LPCOLESTR pstrEndDe"imiter , // address of end5of5s.ript"et de"imiter DWORD d !"a#s, // s.ript"et f"a#s *STR /p'strName, // address of a.t)a" name of s.ript"et E3CEPIN!O /pe4.epinfo // address of e4.eption 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 e%amples are 1TML scripting languages that allow scriptlets of code embedded in

ActiveX Scripting

13

the 1TML document to be attached to intrinsic events /for e%ample# +&C#IC>$?button@ te't$A"'itA?0. pstr&e(aultName LinM Address of a default name to associate with the scriptlet. 4f the scriptlet does not contain naming information /as in the +&C#IC> e%ample above0# this name will be used to identify the scriptlet. 4f this parameter is HILL# the scripting engine manufactures a uni7ue name# if necessary. pstr)ode LinM Address of the scriptlet te%t to add. The interpretation of this string depends on the scripting language. pstrItemName LinM Address of a buffer that contains the item name associated with this scriptlet. This parameter# in addition to pstr!ubItemName # identifies the ob.ect for which the scriptlet is an event handler. pstr!ubItemName LinM Address of a buffer that contains the name of a subob.ect of the named item with which this scriptlet is associatedA this name must be found in the named item;s type information. This parameter is HILL if the scriptlet is to be associated with the named item instead of a subitem. This parameter# in addition to pstrItemName# identifies the specific ob.ect for which the scriptlet is an event handler. pstr* entName LinM Address of a buffer that contains the name of the event for which the scriptlet is an event handler. pstr*nd&elimiter LinM Address of the end)of)scriptlet delimiter. When pstr)ode is parsed from a stream of te%t# the host typically uses a delimiter# such as two single 7uotation mar's /(0# 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 e%ample# replacing a single 7uotation mar' L;M with two single 7uotation mar's for use as a delimiter0. E%actly how /and if0 the scripting engine ma'es use of this information depends on the scripting engine. "et this parameter to HILL if the host did not use a delimiter to mar' the end of the scriptlet. dwFlags LinM 8lags associated with the scriptlet. &an be a combination of the following values3
8alue SC)IPTT"!T*IS8ISI5#" 2eaning 4ndicates that the script te%t should be visible /and# therefore# callable by name0 as a global method in the name space of the script. 4ndicates that the code added during this call should be saved if the scripting engine is saved /for e%ample# through a call to IPersist*%%Save0# or if the scripting engine is

SC)IPTT"!T*ISP")SIST"&T

ActiveX Scripting reset by way of a transition bac' to the initiali7ed state.

pbstrName LoutM The actual name used to identify the scriptlet. This will be# in order of preference3 a name e%plicitly specified in the scriptlet te%t# the default name provided in pstr&e(aultName # or a uni7ue name synthesiFed by the scripting engine. pe'cepin(o LoutM -ointer to a structure containing e%ception information. This structure should be filled in if 24"-NENE &E-T4OH is returned.

eturns
"NOK The scriptlet was successfully added to the script $the pbstrName parameter contains the scriptlet;s name. The default name supplied is invalid in this scripting language. An unspecified synta% error occurred in the scriptlet. An e%ception occurred in the parsing of the scriptletA the pe'cepin(o parameter contains information about the e%ception. The call was not e%pected /for e%ample# the scripting engine has not yet been loaded or initialiFed0. This method is not supportedA the scripting engine does not support adding event)sin'ing scriptlets. An invalid pointer was specified. An argument was invalid.

OLE"&J4-TNEN4H*AL42HAME OLE"&J4-TNEN"GHTA 24"-NENE &E-T4OH

ENIHE -E&TE2

ENHOT4M-L EN-O4HTEJ EN4H*AL42AJ6

&ActiveScript2arse::&nitNew
HRESULT InitNe (-oid$%

4nitialiFes the scripting engine. +efore the scripting engine can be used# one of the following methods must be called3 IPersist*%%#oad# IPersist*%%Init&ew# or IActiveScriptParse%%Init&ew. The semantics of this method are identical to IPersistStreamInit%%Init&ew# in that this method tells the scripting engine to initialiFe itself. Hote that it is not valid to call both Init&ew and #oad# nor is it valid to call Init&ew or #oad more than once.

ActiveX Scripting

15

eturns
"NOK EN8A4L The scripting engine was successfully initialiFed. An error occurred during initialiFation.

&ActiveScript2arse::2arseScriptTe*t
HRESULT ParseS.riptTe4t( LPCOLESTR pstrCode, LPCOLESTR pstrItemName, IUn6no n /p)n6Conte4t, LPCOLESTR pstrEndDe"imiter, DWORD d !"a#s, 7ARIANT /p-arRes)"t, E3CEPIN!O /pe4.epinfo $% // // // // // // // address of s.ript"et te4t address of item name address of de')##in# .onte4t address of end5of5s.ript"et de"imiter s.ript"et f"a#s address of ')ffer for res)"ts address of ')ffer for error data

-arses the given code scriptlet# adding declarations into the name space and evaluating code as appropriate. pstr)ode LinM Address of the scriptlet te%t to evaluate. The interpretation of this string depends on the scripting language. pstrItemName LinM Address of the item name that gives the conte%t in which the scriptlet is to be evaluated. 4f this parameter is HILL# the code is evaluated in the scripting engine;s global conte%t. pun+)onte't LinM Address of conte%t ob.ect. This ob.ect is reserved for use in a debugging environment# where such a conte%t may be provided by the debugger to represent an active run)time conte%t. 4f this parameter is HILL# the engine uses pstrItemName to identify the conte%t. pstr*nd&elimiter LinM Address of the end)of)scriptlet delimiter. When pstr)ode is parsed from a stream of te%t# the host typically uses a delimiter# such as two single 7uotation mar's /(0# 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 e%ample# replacing a single 7uotation mar' L;M with two single 7uotation mar's for use as a delimiter0. E%actly how /and if0 the scripting engine ma'es use of this information depends on the scripting engine. "et this parameter to HILL if the host did not use a delimiter to mar' the end of the scriptlet. dwFlags LinM 8lags associated with the scriptlet. &an be a combination of these values3
8alue SC)IPTT"!T*IS"!P)"SSI+& 2eaning 4f the distinction between a computational e%pression and a statement is important but

ActiveX Scripting syntactically ambiguous in the script language# this flag specifies that the scriptlet is to be interpreted as an e%pression# rather than as a statement or list of statements. +y default# statements are assumed unless the correct choice can be determined from the synta% of the scriptlet te%t. SC)IPTT"!T*ISP")SIST"&T 4ndicates that the code added during this call should be saved if the scripting engine is saved /for e%ample# through a call to IPersist*%%Save0# or if the scripting engine is reset by way of a transition bac' to the initiali7ed state. 4ndicates that the script te%t should be visible /and# therefore# callable by name0 as a global method in the name space of the script.

SC)IPTT"!T*IS8ISI5#"

p ar,esult LoutM Address of a buffer that receives the results of scriptlet processing# or HILL if the caller e%pects no result /that is# the SC)IPTT"!T*IS"!P)"SSI+& value is not set0. pe'cepin(o LoutM Address of a structure that receives e%ception information. This structure is filled if ParseScriptTe't returns 24"-NENE &E-T4OH. 4f the scripting engine is in the initiali7ed state# no code will actually be evaluated during this callA rather# such code is 7ueued and e%ecuted when the scripting engine is transitioned into /or through0 the started state. +ecause e%ecution is not allowed in the initiali7ed state# it is an error to call this method with the SC)IPTT"!T*IS"!P)"SSI+& flag when in the initiali7ed state. The scriptlet can be an e%pression# a list of statements# or anything allowed by the script language. 8or e%ample# this method is used in the evaluation of the 1TML <"&J4-T> tag# which allows statements to be e%ecuted as the 1TML page is being constructed# rather than .ust compiling them into the script state. The code passed to this method must be a valid# complete portion of code. 8or e%ample# in *+"cript it is illegal to call this method once with Sub =oo,'- and then a second time with "nd 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.

eturns
"NOK The e%pression or statement/s0 has been evaluated. The p ar,esult parameter contains the result# if any. An invalid pointer was specified.

EN-O4HTEJ

ActiveX Scripting EN4H*AL42AJ6 ENIHE -E&TE2 An argument was invalid.

1"

The call was not e%pected /for e%ample# the scripting engine is in the uninitiali7ed or closed state# or the SC)IPTT"!T*IS"!P)"SSI+& flag was set and the scripting engine is in the initiali7ed state0. An e%ception occurred in the processing of the scriptlet. The pe'cepin(o parameter contains information about the e%ception. An unspecified synta% error occurred in the scriptlet. This method is not supported. The scripting engine does not support run)time evaluation of e%pressions or statements.

24"-NENE &E-T4OH

OLE"&J4-TNEN"GHTA ENHOT4M-L

&ActiveScriptError
An ob.ect implementing this interface is passed to IActiveScriptSite%%+nScript"rror whenever the scripting engine encounters an unhandled error. The host then calls methods on this ob.ect to obtain information about the error that occurred. 2ethods in 8table +rder
4In'nown methods 9uer(Interface Add)ef )elease 4Active"criptError methods .et"'ceptionInfo .etSourcePosition .etSource#ineTe't Description Jeturns pointers to supported interfaces. 4ncrements the reference count. 2ecrements the reference count. Description Jetrieves information about an error. Jetrieves the location in the source code where an error occurred. Jetrieves the line in the source file where an error occurred.

&ActiveScriptError::/etE*ception&n+o
HRESULT (etE4.eptionInfo( E3CEPIN!O /pe4.epinfo $% // str).t)re for e4.eption information

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

ActiveX Scripting

pe'cepin(o LoutM Address of an "!C"PI&=+ structure that receives error information.

eturns
"NOK EN8A4L The error information was successfully retrieved. An error occurred.

&ActiveScriptError::/etSource-ineTe*t
HRESULT (etSo)r.eLineTe4t( *STR /p'strSo)r.eLine // address of ')ffer for so)r.e "ine $%

Jetrieves the line in the source file where an error occurred while a scripting engine was running a script. pbstr!ourceLine LoutM Address of a buffer that receives the line of source code in which the error occurred.

eturns
"NOK EN8A4L The line in the source file was successfully retrieved. An error occurred.

&ActiveScriptError::/etSource2osition
HRESULT (etSo)r.ePosition( DWORD /pd So)r.eConte4t, ULON( /p)"LineN)m'er, LON( /pi.0C0arPosition $% // .onte4t .oo6ie // "ine n)m'er of error // .0ara.ter position of error

Jetrieves the location in the source code where an error occurred while the scripting engine was running a script. pdw!ource)onte't LoutM Address of a variable that receives a coo'ie that identifies the conte%t. The interpretation of this parameter depends on the host application. pulLineNumber LoutM Address of a variable that receives the line number in the source file where the error occurred. pich)har-osition LoutM Address of a variable that receives the character position in the line where the error occurred.

ActiveX Scripting

1)

eturns
"NOK EN8A4L The error location was successfully retrieved. An error occurred.

&ActiveScriptSite
The host must create a site for the Active "cripting engine by implementing IActiveScriptSite . Isually# this site will be associated with the container of all the ob.ects that are visible to the script /for e%ample# the Active controls0. Typically# this container will correspond to the document or page being viewed. 4nternet E%plorer# for e%ample# would create such a container for each 1TML page being displayed. Each Active control /or other automation ob.ect0 on the page# and the scripting engine itself# would be enumerable within this container. 2ethods in 8table +rder
4In'nown methods 9uer(Interface Add)ef )elease 4Active"cript"ite methods .et#CID .etItemInfo Description Jeturns pointers to supported interfaces. 4ncrements the reference count. 2ecrements the reference count. Description Jetrieves the locale identifier that the host uses for displaying user)interface elements. Obtains information about an item that was added to an engine through a call to the IActiveScript%%Add&amedItem method. Jetrieves a host)defined string that uni7uely identifies the current document version from the host;s point of view. 4nforms the host that the script has completed e%ecution. 4nforms the host that the scripting engine has changed states. 4nforms the host that an e%ecution error occurred while the engine was running the script. 4nforms the host that the scripting engine has begun e%ecuting the script code. 4nforms the host that the scripting engine has returned from e%ecuting script code.

.etDoc8ersionString

+nScriptTerminate +nStateChange +nScript"rror +n"nterScript +n#eaveScript

&ActiveScriptSite::/et0oc3ersionString
HRESULT (etDo.7ersionStrin#(

ActiveX Scripting
*STR /p'str7ersionStrin# $% // address of do.)ment -ersion strin#

Jetrieves a host)defined string that uni7uely identifies the current document version from the host;s point of view. 4f the related document has changed outside the scope of Active "cripting /as in the case of an 1TML page being edited with Hote-ad0# the scripting engine can save this along with its persisted state# forcing a recompile the ne%t time the script is loaded. pstr.ersion!tring LoutM Address of the host)defined document version string.

eturns
"NOK The document version string was successfully retrieved. The pstr.ersion!tring parameter contains the string. This method is not supported. The scripting engine should assume that the script is in sync with the document.

ENHOT4M-L

&ActiveScriptSite::/et&tem&n+o
HRESULT IA.ti-eS.riptSite88(etItemInfo( LPCOLESTR pstrName, // address of item name DWORD d Ret)rn+as6, // 'it mas6 for information retrie-a" IUn6no n //pp)n6Item, // address of pointer to item9s IUn6no n IT&peInfo //ppT&peInfo // address of pointer to item9s IT&peInfo $%

Allows the scripting engine to obtain information about an item added with IActiveScript%%Add&amedItem. pstrName LinM The name associated with the item# as specified in IActiveScript%%Add&amedItem. dw,eturnMas+ LinM A bit mas' specifying what information about the item should be returned. The scripting engine should re7uest the minimum needed information because some of the return parameters /for e%ample# IT(peInfo0 can ta'e considerable time to load or generate. &an be a combination of the following values3
8alue SC)IPTI&=+*I1&>&+W& SC)IPTI&=+*IT:P"I&=+ 2eaning Jeturn the I1n0nown interface for this item. Jeturn the IT(peInfo interface for this item.

ppun+Item LoutM Address of a variable that receives a pointer to the I1n0nown interface associated with the given item. The scripting engine can use the 9uer(Interface

ActiveX Scripting

31

method to obtain the IDispatch interface for the item. This parameter receives HILL if dw,eturnMas+ does not include the SC)IPTI&=+*I1&>&+W& value. Also# it receives HILL if there is no ob.ect associated with the item nameA this mechanism is used to create a simple class when the named item was added with the SC)IPTIT"2*C+D"+&#: flag set.

ppTypeIn(o LoutM Address of a variable that receives a pointer to the IT(peInfo interface associated with the item. This parameter receives HILL if dw,eturnMas+ does not include the SC)IPTI&=+*IT:P"I&=+ value# or if type information is not available for this item. 4f type information is not available# the ob.ect cannot source events# and name binding must be realiFed with IDispatch%%.etIDs+f&ames. Hote that this IT(peInfo describes the coclass /T>I&D*C+C#ASS0 because the ob.ect may support multiple interfaces and event interfaces. 4f the item supports the IProvide2ultipleT(peInfo interface# the IT(peInfo interface corresponds to the IT(peInfo of inde% Fero obtained from IProvide2ultipleT(peInfo%%.etInfo+fInde'. This method retrieves only the information indicated by the dw,eturnMas+ parameter. This improves performance# for e%ample# in the case where an IT(peInfo interface is not needed for an item.

eturns
"NOK The re7uested interface pointer was successfully retrieved. The ppun+Item or ppTypeIn(o parameter contains the pointer. An invalid pointer was specified. An argument was invalid. An item of the specified name was not found.

EN-O4HTEJ EN4H*AL42AJ6 TG-ENENELEMEHTHOT8OIH2

"ee also IActiveScript%%Add&amedItem

&ActiveScriptSite::/et-.&0
HRESULT (etLCID( LCID /p".id // address of -aria'"e for "an#)a#e identifier $%

Jetrieves 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. 4f this method returns ENHOT4M-L# the system)defined locale identifier should be used. plcid LoutM Address of a variable that receives the locale identifier for user)interface elements displayed by the scripting engine.

ActiveX Scripting

eturns
"NOK EN-O4HTEJ ENHOT4M-L The locale identifier was successfully retrieved. The plcid parameter contains the identifier. An invalid pointer was specified. This method is not implemented. Ise the system) defined locale.

&ActiveScriptSite::OnEnterScript
HRESULT OnEnterS.ript(-oid$%

4nforms the host that the scripting engine has begun e%ecuting the script code. The scripting engine must call this method on every entry or reentry into the scripting engine. 8or e%ample# if the script calls an ob.ect that then fires an event handled by the scripting engine# the scripting engine must call +n"nterScript before e%ecuting the event# and must call +n#eaveScript after e%ecuting the event but before returning to the ob.ect that fired the event. &alls to this method can be nested. Every call to +n"nterScript re7uires a corresponding call to +n#eaveScript.

eturns
"NOK The method succeeded.

"ee also IActiveScriptSite%%+n#eaveScript

&ActiveScriptSite::On-eaveScript
HRESULT IA.ti-eS.riptSite88OnLea-eS.ript(-oid$%

4nforms the host that the scripting engine has returned from e%ecuting script code. The scripting engine must call this method before returning control to a caller that entered the scripting engine. 8or e%ample# if the script calls an ob.ect that then fires an event handled by the scripting engine# the scripting engine must call +n"nterScript before e%ecuting the event# and must call +n#eaveScript after e%ecuting the event before returning to the ob.ect that fired the event. &alls to this method can be nested. Every call to +n"nterScript re7uires a corresponding call to +n#eaveScript.

eturns
"NOK The method was successful.

"ee also IActiveScriptSite%%+n"nterScript

ActiveX Scripting

33

&ActiveScriptSite::OnScriptError
HRESULT IA.ti-eS.riptSite88OnS.riptError( IA.ti-eS.riptError/pase // address of error interfa.e $%

4nforms the host that an e%ecution error occurred while the engine was running the script. pase LinM Address of the error ob.ect;s IActiveScript"rror interface. A host can use this interface to obtain information about the e%ecution error.

eturns
"NOK The scripting engine should continue running the script as best as possible /perhaps abandoning the processing of this event0. The scripting engine should continue running the script in the debugger# if a debugger is available. 4f a debugger is not available# this error should be handled in the same way as EN8A4L. The scripting engine should abort e%ecution of the script and return it to the initiali7ed state. 4n this case# the pe'cepin(o parameter obtained from IActiveScript"rror%%.et"'ceptionInfo is generally passed to +nScriptTerminate.

"N8AL"E

EN8A4L

"ee also IActiveScript"rror # IActiveScript"rror%%.et"'ceptionInfo

&ActiveScriptSite::OnScriptTerminate
HRESULT OnS.riptTerminate( 7ARIANT /p-arRes)"t, // address of s.ript res)"ts E3CEPIN!O /pe4.epinfo // address of str).t)re it0 e4.eption information $%

4nforms the host that the script has completed e%ecution. p ar,esult LinM Address of a variable that contains the script result# or HILL if the script produced no result. pe'cepin(o LinM Address of an "!C"PI&=+ structure that contains e%ception information generated when the script terminated# or HILL if no e%ception was generated. The scripting engine calls this method before the call to +nStateChange/SC)IPTSTAT"*I&ITIA#I<"D0 is completed. The +nScriptTerminate method can be used to return completion status and results to

ActiveX Scripting

the host. Hote that many script languages# which are based on sin'ing events from the host# have life spans that are defined by the host. 4n this case# this method may never be called.

eturns
"NOK The method succeeded.

&ActiveScriptSite::OnState.hange
HRESULT IA.ti-eS.riptSite88OnStateC0an#e( SCRIPTSTATE ssS.riptState // ne state of en#ine $%

4nforms the host that the scripting engine has changed states. ss!cript!tate LinM *alue that indicates the new script state. "ee IActiveScript%%.etScriptState for a description of the states.

eturns
"NOK The method succeeded.

"ee also IActiveScript%%.etScriptState

&ActiveScriptSite#indow
This interface is implemented by hosts that support a user interface on the same ob.ect as IActiveScriptSite . 1osts that do not support a user interface# such as servers# would not implement the IActiveScriptSiteWindow interface. The scripting engine accesses this interface by calling 9uer(Interface from IActiveScriptSite . 2ethods in 8table +rder
4In'nown methods 9uer(Interface Add)ef )elease 4Active"cript"iteWindow methods .etWindow Description Jeturns pointers to supported interfaces. 4ncrements the reference count. 2ecrements the reference count. Description Jetrieves the window handle that can act as the owner of a pop)up window that the scripting engine needs to display. &auses the host to enable or disable its main window as well as any modeless dialog bo%es.

"nable2odeless

ActiveX Scripting

35

&ActiveScriptSite::Ena$'e,ode'ess
HRESULT IA.ti-eS.riptSite88Ena'"e+ode"ess( *OOL fEna'"e // ena'"e f"a# $%

&auses the host to enable or disable its main window as well as any modeless dialog bo%es. (*nable LinM 8lag that# if TJIE# enables the main window and modeless dialogs or# if 8AL"E# disables them. This method is identical to I+leInPlace=rame%%"nable2odeless . &alls to this method can be nested.

eturns
"NOK EN8A4L The method was successful. An error occurred.

&ActiveScriptSite::/et#indow
HRESULT (etWindo ( HWND /p0 nd // address of -aria'"e for $% indo 0and"e

Jetrieves the handle of a window that can act as the owner of a pop)up window that the scripting engine needs to display. phwnd LoutM Address of a variable that receives the window handle. This method is similar to I+leWindow%%.etWindow.

eturns
"NOK EN8A4L The window handle was successfully retrieved. An error occurred.

Enumerations
S. &2TSTATE
t&pedef en)m ta#SCRIPTSTATE : SCRIPTSTATE;UNINITIALI<ED = >, SCRIPTSTATE;INITIALI<ED = ?, SCRIPTSTATE;STARTED = @,

ActiveX Scripting
SCRIPTSTATE;CONNECTED SCRIPTSTATE;DISCONNECTED SCRIPTSTATE;CLOSED B SCRIPTSTATE% = 2, = 1, = A

&ontains named constant values that specify the state of a scripting engine. This enumeration is used by the IActiveScript%%.etScriptState # IActiveScript%%SetScriptState # and IActiveScriptSite%%+nStateChange methods.

E'ements
SC)IPTSTAT"*1&I&ITIA#I<"D The script has .ust been created# but has not yet been initialiFed using an IPersist* interface and IActiveScript%%SetScriptSite . The script has been initialiFed# but is not running /connecting to other ob.ects or sin'ing events0 or e%ecuting any code. &ode can be 7ueried for e%ecution by calling IActiveScriptParse%%ParseScriptTe't . The script can e%ecute code# but is not yet sin'ing the events of ob.ects added by the IActiveScript%%Add&amedItem method. The script is loaded and connected for sin'ing events. The script is loaded and has a run)time e%ecution state# but is temporarily disconnected from sin'ing events. The script has been closed. The scripting engine no longer wor's and returns errors for most methods.

SC)IPTSTAT"*I&ITIA#I<"D

SC)IPTSTAT"*STA)T"D

SC)IPTSTAT"*C+&&"CT"D SC)IPTSTAT"*DISC+&&"CT"D

SC)IPTSTAT"*C#+S"D

"ee also IActiveScript%%.etScriptState # IActiveScript%%SetScriptState # IActiveScriptSite%%+nStateChange

S. &2TT( EA0STATE
t&pedef en)m ta#SCRIPTTHREADSTATE : SCRIPTTHREADSTATE;NOTINSCRIPT = >, SCRIPTTHREADSTATE;RUNNIN( = @ B SCRIPTTHREADSTATE%

&ontains named constant values that specify the state of a thread in a scripting engine. This enumeration is used by the IActiveScript%%.etScriptThreadState method.

ActiveX Scripting

3"

E'ements
SC)IPTT/)"ADSTAT"*&+TI&SC)IPT The specified thread is not currently servicing a scripted event# processing immediately e%ecuted script te%t# or running a script macro. SC)IPTT/)"ADSTAT"*)1&&I&. The specified thread is actively servicing a scripted event# processing immediately e%ecuted script te%t# or running a script macro.

"ee also IActiveScript%%.etScriptThreadState