ActiveX Scripting

8/13/2019 ActiveX Scripting

1/37

1

OverviewThis document introduces a new way to add scripting and OLE Automationcapabilities to programs such as applications or servers. With the advent of

Microsoft Active! "cripting# hosts can call upon disparate scripting enginesfrom multiple sources and vendors to perform scripting between components. Theimplementation 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 hoststhat rely on Active "cripting to use arbitrary language (bac' ends.(

TermsThe following list contains definitions of the scripting)related terms used in this

document.

Term Definition

code object 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 obect is an OLE &omponent Obect

Model /&OM0 obect supporting OLE Automation so that the

host or other nonscript entity can manipulate the code obect.

named item An OLE &OM obect /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.

script 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.

scripting engine The OLE obect that processes scripts. A scripting engine

implements IActiveScriptand# optionally#

IActiveScriptParse .

scripting host The application or program that owns the Active "cripting

engine. The host implements IActiveScriptSiteand#

optionally# IActiveScriptSiteWindow.

scriptlet A portion of a script that gets attached to an obect throughIActiveScriptParse . The aggregate collection of scriptlets is

the script.

script language The language in which a script is written /for e%ample#

*+"cript0 and the semantics of that language.

ActiveX Scripting


2/37

ActiveX Scripting

ActiveX Scripting BackgroundActive "cripting components fall into two categories3 Active "cripting hosts andActive "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 hostsinclude3

Microsoft 4nternet E%plorer

4nternet authoring tools

Tarantula56ibraltar /server)based scripting0

"hell

Active "cripting engines can be developed for any language or run)timeenvironment# 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 Automationwrapper for Active "cripting is provided. 1owever# a host that uses this wrapper

obect to instantiate the scripting engine does not have the control over the run)timename 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 anauthoring environment so that non)authoring hosts /such as browsers and viewers0

and script engines /for e%ample# *+"cript0 can be 'ept lightweight.

Basic ArchitectureThe following illustration shows the interaction between an Active "cripting hostand an Active "cripting engine.


3/37

ActiveX Scripting 3

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 ProjectThe host loads a proect or document. /This step is notparticular to Active "cripting# but is included here for completeness.0

: Create the Active! Scripting "ngineThe host calls CoCreateInstancetocreate a new Active "cripting engine# specifying the class identifier /&L"420 ofthe specific scripting engine to use. 8or e%ample# the 1TML browsing componentof 4nternet E%plorer receives the scripting engine;s class identifier through theC#SID$attribute of the 1TML tag.

? #oad the Script4f the script contents have been persisted# the host calls thescript engine;s IPersist*%%#oadmethod to feed it the script storage# stream# or

property bag. Otherwise# the host uses IPersist*%%Init&eworIActiveScriptParse%%Init&ewto create a null script. A host that maintains ascript as te%t can use IActiveScriptParse%%ParseScriptTe'tto feed the scriptingengine the te%t of the script# after calling Init&ew.

@ Add Items8or each top)level named item /such as pages and forms0 importedinto the scripting engine;s name space# the host callsIActiveScript%%Add&amedItemto 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&amedItemto add sublevel named items /such as controls on an 1TML page0 rather# theengine indirectly obtains sublevel items from top)level items by using the host;sIT(peInfoand IDispatchinterfaces.

B )un the ScriptThe host causes the engine to start running the script by passingthe SC)IPTSTAT"C+&&"CT"Dvalue to IActiveScript%%SetScriptState.This call would li'ely perform any scripting engine construction wor'# includingstatic bindings# hoo'ing up to events /see below0# and e%ecuting code similar to a

scripted (main,-( function.

C .et Item InformationEach time the script engine needs to associate a symbolwith a top)level item# it calls the IActiveScriptSite%%.etItemInfomethod# whichreturns information about the given item.


4/37

ActiveX Scripting

D /oo0 1p "vents+efore starting the actual script# the scripting engine connectsto the events of all the relevant obects through the IConnectionPointinterface

and other methods.

Invo0e Properties and 2ethodsAs the script runs# the scripting engine realiFesreferences to methods and properties on named obects throughIDispatch%%Invo0eor other standard OLE binding mechanisms.

ActiveX Scripting EngineTo write an Active "cripting engine# write an OLE &OM obect that supports the

following interfaces.

Interface )e3uired4 Description

IActiveScript Ges +asic scripting ability.

IPersist* Ges. At least one of the

following /see note below0.

-ersistence support.

IPersistStorage DATA${url}synta% for +56"CTtag.

IPersistStreamInit "ame as above# as well as

DATA$"string-encoded byte stream"

synta% for +56"CTtag.

IPersistPropert(5ag PA)A2$synta% for +56"CTtag.

IActiveScriptParse Ho Ability to add script te%t# evaluate

e%pressions# and so on.

"upport for the IActiveScriptParse interface is optional however# if it is not

supported# the script engine must implement one of the IPersist*interfaces in orderto load a given script.

&ertain interpreted script languages /for e%ample# *+"cript0 running in specific hostenvironments /for e%ample# 4nternet E%plorer0 may rarely /or never0 be called uponto save or restore a script state through IPersist*. 4nstead# IActiveScriptParseisused by calling IActiveScriptParse%%Init&ewto create a blan' script# then scriptletsare added and connected to events with IActiveScriptParse%%AddScriptletandgeneral code is added via IActiveScriptParse%%ParseScriptTe't. Honetheless# ascripting engine should fully implement at least one IPersist*scheme /preferably

IPersistStreamInit0# because other host applications may try to ma'e use of them.

Note:


5/37

ActiveX Scripting 5

egistr! StandardAn Active "cripting engine can identify itself using component categories.Active "cripting currently defines two component categories3

Categor( Description

CATIDActiveScript 4ndicates that the class identifiers /&L"42s0 are

Active "cripting engines that support# at a

minimum# IActiveScriptand a persistence

mechanism /IPersistStorage #

IPersistStreamInit # or IPersistPropert(5ag 0.

CATIDActiveScriptParse 4ndicates that the &L"42s are Active "cripting

engines that support# at a minimum#

IActiveScriptand IActiveScriptParse .

Although IActiveScriptParseis not a true persistence mechanism# it does supportan Init&ewmethod that is functionally e7uivalent to IPersist*%%Init&ew.

Script Engine StatesAt any given time# an Active "cripting engine can be in one of several states.

State Description

uninitiali7ed The script has not been initialiFed or loaded using an IPersist*

interface# or does not have an IActiveScriptSiteset. The

scripting engine is generally not usable from this state until the

host ta'es steps to initialiFe the engine.

initiali7ed The script has been initialiFed with an IPersist*interface and

has an IActiveScriptSiteset# but is not connected to hostobects 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 startedstate.

started The transition from the initiali7edstate to startedstate causes

the engine to e%ecute any code that was 7ueued in the

initiali7edstate. The engine can e%ecute code while in the

startedstate# but it is not connected to events of the obects

added through IActiveScript%%Add&amedItem . The enginecan e%ecute code by calling the IDispatchinterface 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 SetScriptStatewith the

SC)IPTSTAT"C+&&"CT"D value may cause the script


6/37


7/37

ActiveX Scripting "

A #ord A$out Threading+ecause an Active "cripting engine can be used in many environments# it isimportant 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 usethreading# such as a typical application# should not be burdened with threadingmanagement. Active "cripting achieves this balance by restricting the ways a

free)threaded scripting engine can call bac' to the host# freeing hosts from thisburden.

%or Scripting Engine &mp'ementers"cripting engines used on servers are typically implemented as free)threading &OM

obects. This means that methods on IActiveScriptand its associated interfacescan 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 obects.0 "ynchroniFation is the responsibility of the scripting engine. 8or

scripting engines that are not internally reentrant# or for language models that are


8/37

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 IActiveScriptis free)threaded generally implies that

IActiveScriptSiteand the host;s obect model should be free)threaded as well. This

would ma'e implementation of the host 7uite difficult# particularly in the commoncase where the host is a single)threaded Windows)based application with single)

threaded or apartment)model Active controls in its obect model. 8or this reason#the following constraints are placed on the scripting engine;s use of

IActiveScriptSite3

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 IActiveScriptand its derivatives# through the e%posed scriptingengine;s dispatch obect# or through a Windows message indirectly from an eventsource in the host;s obect model0.

The script site is never called from within the conte%t of a simple thread state

control method /for e%ample# InterruptScriptThread0 or from the Clonemethod.

%or Scripting (ost &mp'ementersA host can safely assume that an engine will call IActiveScriptSiteonly in theconte%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 InterruptScriptThreadand Clone.

&all the scripting engine;s dispatch obect only in the base thread.

Ensure that the message loop runs in the base thread if a window handle is

provided.

Ensure that obects in the host;s obect 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,+JEAKhandler or the li'e0# or to duplicate a script in a new

thread using Clone.


9/37

ActiveX Scripting )

Also note that none of these restrictions apply to a host that chooses to implement a

free)threaded IActiveScriptSiteand a free)threaded obect model. "uch a host canuse IActiveScriptfrom any thread# without restriction.

Script Thread E*ecution StatesEach script thread can be in one of the following e%ecution states3

State Description

&otInScript 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.

)unning The thread is currently e%ecuting script code.

&nter+aces and ,ethods

&ActiveScriptThe scripting engine must implement the IActiveScriptinterface in order to be anActive "cripting engine.

2ethods in 8table +rder

4In'nownmethods Description

9uer(Interface Jeturns pointers to supported interfaces.

Add)ef 4ncrements the reference count.

)elease 2ecrements the reference count.

4Active"criptmethods Description

SetScriptSite 4nforms the scripting engine of the

IActiveScriptSitesite provided by the host.

.etScriptSite Jetrieves the site obect associated with the

Active "cripting engine.

SetScriptState -uts the scripting engine into the given state.

.etScriptState Jetrieves the current state of the scripting engine.

Close &auses the scripting engine to abandon any

currently loaded script# lose its state# and release

any interface pointers it has to other obects# thusentering a closedstate.

Add&amedItem Adds the name of a root)level item to the scripting

engine;s name space.

AddT(pe#ib Adds a type library to the name space for the

script.


10/37

ActiveX Scripting

.etScriptDispatch Jetrieves the IDispatchinterface for the methods

and properties associated with the running script

itself.

.etCurrentScriptThreadID Jetrieves a scripting)engine)defined identifier for

the currently e%ecuting thread.

.etScriptThreadID Jetrieves a scripting)engine)defined identifier for

the thread associated with the given Microsoft

Win?: thread.

.etScriptThreadState Jetrieves the current state of a script thread.

InterruptScriptThread 4nterrupts the e%ecution of a running script thread.

Clone &lones the current scripting engine /minus any

current e%ecution state0# returning a loaded#

unsited scripting engine in the current thread.

&ActiveScript::AddNamed&temHRESULT AddNamedItem(

LPCOLESTR pstrName, // address of item name

DWORD d!"a#s // 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 obect with properties and methods# an event source# or both.

pstrNamein Address of a buffer that contains the name of the item as viewed from thescript. The name must be uni7ue and persistable.

dwFlagsin 8lags associated with item. &an be a combination of these values3

8alue 2eaning

SC)IPTIT"2ISP")SIST"&T 4ndicates that the item should be saved if

the scripting engine is saved. "imilarly#

setting this flag indicates that a transition

bac' to the initiali7edstate should retain

the item;s name and type information /the

scripting engine must# however# release all

pointers to interfaces on the actual obect0.

SC)IPTIT"2ISS+1)C" 4ndicates that the item sources events that

the script can sin'. &hildren /properties of

the obect that are in themselves obects0can 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.


11/37

ActiveX Scripting 11

SC)IPTIT"2IS8ISI5#" 4ndicates that the item;s name is available

in the name space of the script# allowing

access to the properties# methods# andevents of the item. +ecause by convention

the properties of the item include the item;s

children# all child obect properties and

methods /and their children# recursively0

will be accessible.

SC)IPTIT"2.#+5A#2"25")S 4ndicates that the item is a collection of

global properties and methods associated

with the script. Hormally# a scripting

engine would ignore the obect 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 itsmembers 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.

SC)IPTIT"2&+C+D" 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. 8ore%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.

SC)IPTIT"2C+D"+: 4ndicates that the named item represents a

code)only obect# and that the host has no

I1n0nownto be associated with this

code)only obect. The host only has a name

for this obect. 4n obect)oriented

languages such as &,,# this flag would

create a class. Hot all languages support

this flag.

eturns

"NOK The named item was successfully added to the

script;s name space.

ENIHE-E&TE2 The call was not e%pected /for e%ample# the

scripting engine has not yet been loaded or


12/37

ActiveX Scripting

initialiFed0.

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

"ee also IActiveScriptSite%%.etItemInfo

&ActiveScript::AddT!pe-i$HRESULT AddT&peLi'(

RE!UID #)idT&peLi', // LI*ID of t&pe "i'rar&

DWORD d+a, // maor -ersion n)m'er

DWORD d+in, // minor -ersion n)m'er

DWORD d!"a#s // 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.

guidTypeLibin L4+42 of the type library to add.

dwMajin Maor version number.

dwMinin Minor version number.

dwFlags

in Option flags. &an be SC)IPTT:P"#I5ISC+&T)+# # which indicatesthat the type library describes an Active control used by the host.

eturns

"NOK The specified type library was successfully added.



initialiFed0.

TG-ENEN&AHTLOA2L4+JAJG The specified type library could not be loaded.

EN4H*AL42AJ6 An argument was invalid.

&ActiveScript::.'oneHRESULT C"one(

IA.ti-eS.ript pps.ript // re.ei-es pointer to IA.ti-eS.ript

$%


13/37


&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 scriptingengine should be identical to the state the original scripting engine would be in if it

were transitioned bac' to the initiali7edstate.

ppscriptout Address of a variable that receives a pointer to the IActiveScriptinterface ofthe unsited# cloned scripting engine. The host must create a site and callSetScriptSiteon the new scripting engine before it will be in the initiali7edstateand# therefore# usable.

The Clonemethod is an optimiFation of IPersist*%%Save# CoCreateInstance# andIPersist*%%#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 scriptingengine. Hamed items are duplicated in the cloned scripting engine# but specificobect pointers for each item are forgotten and are obtained with .etItemInfo. This

allows an identical obect model with per)thread entry points /an apartment model0to be used.

This method is used for multithreaded server hosts that can run multiple instances ofthe 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 anew 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 obects or to IActiveScriptSite.

eturns

"NOK The scripting engine was successfully cloned.

ENHOT4M-L The Clonemethod is not supported.

EN-O4HTEJ An invalid pointer was specified.



initialiFed0.

"ee also IActiveScript%%SetScriptSite# IActiveScriptSite#

IActiveScriptSite%%.etItemInfo

&ActiveScript::.'oseHRESULT 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 obects# thus entering a closed

state. Event sin's# immediately e%ecuted script te%t# and macro invocations that arealready in progress are completed before the state changes /use

InterruptScriptThread to cancel a running script thread0. This method must be


14/37

ActiveX Scripting

called by the creating host before it calls )eleaseto prevent circular reference

problems.

eturns

"NOK The script was successfully closed.

"N8AL"E The method succeeded# but the script was already

closed.

OLE"&J4-TN"N-EH24H6 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.


scripting engine was already in the closedstate0.

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

&ActiveScript::/et.urrentScriptThread&0HRESULT 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)controlmethods such as InterruptScriptThread .

pstidThreadout Address of a variable that receives the script thread identifier associated withthe current thread. The interpretation of this identifier is left to the scriptingengine# but it can be ust a copy of the Windows thread identifier. 4f the Win?:thread terminates# this identifier becomes unassigned and can subse7uently beassigned to another thread.



eturns

"NOK The identifier was successfully retrieved.


"ee also IActiveScript%%InterruptScriptThread# IActiveScriptSite

&ActiveScript::/etScript0ispatchHRESULT etS.riptDispat.0(


15/37


LPCOLESTR pstrItemName // address of item name

IDispat.0 ppdisp // re.ei-es IDispat.0 pointer

$%

Jetrieves the IDispatchinterface for the methods and properties associated withthe running script itself.

pstrItemNamein Address of a buffer that contains the name of the item for which the callerneeds the associated dispatch obect. 4f this parameter is HILL# the dispatchobect contains as its members all of the global methods and properties defined bythe script. Through the IDispatchinterface and the associated IT(peInfointerface# the host can invo'e script methods or view and modify script variables.

ppdispout Address of a variable that receives a pointer to the obect associated with the

script;s global methods and properties. 4f the scripting engine does not supportsuch an obect# HILL is returned.

+ecause methods and properties can be added by calling IActiveScriptParse# theIDispatchinterface returned by this function can dynamically support new methods

and properties. "imilarly# IDispatch%%.etT(peInfoshould return a new# uni7ueIT(peInfowhen methods and properties are added. Hote# however# that languageengines must not change the IDispatchinterface in a way that is incompatible with

any previous IT(peInfointerface returned. That implies# for e%ample# that24"-42s will never be reused.

eturns

"NOK The dispatch obect for the script was successfully

retrieved.

"N8AL"E The scripting engine does not support a dispatch

obect theppdispparameter is set to HILL.



initialiFed0.



&ActiveScript::/etScriptSiteHRESULT etS.riptSite(

RE!IID iid, // interfa.e identifier -oid pp-SiteO'e.t // address of 0ost site interfa.e

$%

Jetrieves the site obect associated with the Active "cripting engine.


16/37

ActiveX Scripting

iidin 4dentifier of the re7uested interface.

pp!itebjectout Address of the location that receives the interface pointer to the host;s siteobect.

eturns

"NOK The site obect was successfully retrieved.

"N8AL"E Ho site has been setpp!itebjectis set to

HILL.



ENHO4HTEJ8A&E The specified interface is not supported.

&ActiveScript::/etScriptStateHRESULT 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 fromnon)base threads without resulting in a non)base callout to host obects or to

IActiveScriptSite.

pssout Address of a variable that receives a value defined in the SC)IPTSTAT"enumeration. The value indicates the current state of the scripting engineassociated with the calling thread.

eturns

"NOK The state information was successfully retrieved.


"ee also IActiveScriptSite# SC)IPTSTAT"

&ActiveScript::/etScriptThread&0HRESULT etS.riptT0readID(

DWORD dWin12T0readID, // Win12 t0read identifier

SCRIPTTHREADID pstidT0read // 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 threade%ecution control methods such as InterruptScriptThread .


17/37

ActiveX Scripting 1"

dw#in$%ThreadI&in Thread identifier of a running Win?: thread in the current process. Ise the

.etCurrentScriptThreadIDfunction to retrieve the thread identifier of thecurrently e%ecuting thread.

pstidThreadout Address of a variable that receives the script thread identifier associated withthe given Win?: thread. The interpretation of this identifier is left to the scriptingengine# but it can be ust a copy of the Windows thread identifier. Hote that if theWin?: thread terminates# this identifier becomes unassigned and maysubse7uently be assigned to another thread.

This method can be called from non)base threads without resulting in a non)basecallout to host obects or to IActiveScriptSite.

eturns

"NOK The identifier was successfully retrieved.




initialiFed0.

"ee also IActiveScript%%InterruptScriptThread# IActiveScriptSite

&ActiveScript::/etScriptThreadStateHRESULT etS.riptT0readState(

SCRIPTTHREADID stidT0read, // identifier of s.ript t0read

SCRIPTTHREADSTATE pstsState // re.ei-es state f"a#

$%

Jetrieves the current state of a script thread.

stidThreadin 4dentifier of the thread for which the state is desired# or one of the followingspecial thread identifiers3

8alue 2eaning

SC)IPTT/)"ADIDC1))"&T The currently e%ecuting thread.

SC)IPTT/)"ADID5AS" The base thread that is# the thread in which

the scripting engine was instantiated.

psts!tateout Address of a variable that receives the state of the indicated thread. The stateis indicated by one of the named constant values defined by theSC)IPTT/)"ADSTAT"enumeration. 4f this parameter does not identify thecurrent thread# the state may change at any time.


18/37

ActiveX Scripting



eturns

"NOK The current state was successfully retrieved.




initialiFed0.

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

&ActiveScript::&nterruptScriptThreadHRESULT Interr)ptS.riptT0read(

SCRIPTTHREADID stidT0read, // identifier of t0read

.onst E3CEPIN!O pe4.epinfo, // re.ei-es error information

DWORD d!"a#s

$%

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 scriptthat 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 obects or toIActiveScriptSite.

stidThread

in Thread identifier of the thread to interrupt# or one of the following specialthread identifier values3

8alue 2eaning

SC)IPTT/)"ADIDC1))"&T The currently e%ecuting thread.

SC)IPTT/)"ADID5AS" The base thread that is# the thread in which

the scripting engine was instantiated.

SC)IPTT/)"ADIDA## 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


19/37

ActiveX Scripting 1)

dwFlagsin Option flags associated with the interruption. &an be one of these values3

SC)IPTI&T"))1PTD"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 caller

that is# the event source or macro invo'er.

eturns

"NOK The given thread was successfully interrupted.





initialiFed0.

"ee also IActiveScript%%SetScriptState# IActiveScriptSite

&ActiveScript::SetScriptSiteHRESULT SetS.riptSite(

IA.ti-eS.riptSite pS.riptSite // address of 0ost s.ript site

$%

4nforms the scripting engine of the IActiveScriptSitesite provided by the host.This method must be called before any other IActiveScriptmethods can be used.

p!cript!itein Address of the host)supplied script site to be associated with this instance ofthe scripting engine. The site must be uni7uely assigned to this scripting engineinstance it cannot be shared with other scripting engines.

eturns

"NOK The host site was set successfully.



EN8A4L An unspecified error occurred the scriptingengine was unable to finish initialiFing the site.

ENIHE-E&TE2 The call was not e%pected /for e%ample# a site was

already set0.

"ee also IActiveScriptSite


20/37

ActiveX Scripting

&ActiveScript::SetScriptStateHRESULT 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 obects or to

IActiveScriptSite.

ssin "ets the scripting engine to the given state. &an be one of the values definedin the SC)IPTSTAT"enumeration3

SC)IPTSTAT"I&ITIA#I


21/37

ActiveX Scripting 1

Ise InterruptScriptThreadto cancel a running script thread without waiting for

current events# and so on# to finish running.

SC)IPTSTAT"STA)T"D

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 IDispatchinterface

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 initiali7edstate#

the scripting engine should transition through the startedstate# performing the

necessary actions# before entering the connectedstate 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 orphysically/calling 1nadviseon the appropriate

connection points0. Jeturning to the connectedstate reverses this process. 4f this is a

transition from the initiali7edstate# the scripting engine should transition through

the startedstate# performing the necessary actions# before entering the disconnected

state. Event sin's that are in progress are completed before the state changes /use

InterruptScriptThreadto 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 The script successfully entered the given state.

"N8AL"E The method succeeded# but the script was already

in the given state.

OLE"&J4-TN"N-EH24H6 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%%+nStateChangemethod.

EN8A4L The scripting engine does not support the

transition bac' to the initiali7edstate. The host

must discard this scripting engine and create#

initialiFe# and load a new scripting engine to

achieve the same effect.


scripting engine has not yet been loaded orinitialiFed0.

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


22/37

ActiveX Scripting

IActiveScriptSite# IActiveScriptSite%%.etItemInfo#

IActiveScriptSite%%+nStateChange# SC)IPTSTAT"

&ActiveScript2arse4f the Active "cripting engine allows raw te%t code scriptlets to be added to thescript# or allows e%pression te%t to be evaluated at run time# it implements

IActiveScriptParse. 8or interpreted scripting languages that have no independentauthoring environment# such as *isual +asic "cript# this provides an alternate

mechanism /other than IPersist*0 to get script code into the scripting engine# and toattach script fragments to various obect events.






4Active"cript-arsemethods Description

Init&ew 4nitialiFes the scripting engine.

AddScriptlet Adds a code scriptlet to the script.

ParseScriptTe't -arses the given code scriptlet# adding

declarations into the name space and evaluating

code as appropriate.

&ActiveScript2arse::AddScript'etHRESULT 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 berestored under the host;s control# rather than through IPersist*. The primary

e%amples are 1TML scripting languages that allow scriptlets of code embedded in


23/37

ActiveX Scripting 3

the 1TML document to be attached to intrinsic events /for e%ample#

+&C#IC>$?button@te't$"'it? 0.

pstr&e(aultNamein Address of a default name to associate with the scriptlet. 4f the scriptlet doesnot contain naming information /as in the +&C#IC>e%ample above0# this namewill be used to identify the scriptlet. 4f this parameter is HILL# the scriptingengine manufactures a uni7ue name# if necessary.

pstr)odein Address of the scriptlet te%t to add. The interpretation of this string dependson the scripting language.

pstrItemNamein Address of a buffer that contains the item name associated with this scriptlet.This parameter# in addition topstr!ubItemName# identifies the obect for whichthe scriptlet is an event handler.

pstr!ubItemNamein Address of a buffer that contains the name of a subobect of the named itemwith which this scriptlet is associated this name must be found in the nameditem;s type information. This parameter is HILL if the scriptlet is to be associatedwith the named item instead of a subitem. This parameter# in addition to

pstrItemName# identifies the specific obect for which the scriptlet is an eventhandler.

pstr*entNamein Address of a buffer that contains the name of the event for which the scriptletis an event handler.

pstr*nd&elimiterin Address of the end)of)scriptlet delimiter. When pstr)odeis parsed from a

stream of te%t# the host typically uses a delimiter# such as two single 7uotationmar's /(0# to detect the end of the scriptlet. This parameter specifies the delimiterthat the host used# allowing the scripting engine to provide some conditional

primitive preprocessing /for e%ample# replacing a single 7uotation mar' ; withtwo single 7uotation mar's for use as a delimiter0. E%actly how /and if0 thescripting 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 ofthe scriptlet.

dwFlagsin 8lags associated with the scriptlet. &an be a combination of the followingvalues3

8alue 2eaning

SC)IPTT"!TIS8ISI5#" 4ndicates that the script te%t should be visible

/and# therefore# callable by name0 as a globalmethod in the name space of the script.

SC)IPTT"!TISP")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*%%Save 0# or if the scripting engine is


24/37

ActiveX Scripting

reset by way of a transition bac' to the

initiali7edstate.

pbstrNameout 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 nameprovided inpstr&e(aultName# or a uni7ue name synthesiFed by the scriptingengine.

pe'cepin(oout -ointer to a structure containing e%ception information. This structureshould be filled in if 24"-NENE&E-T4OH is returned.

eturns

"NOK The scriptlet was successfully added to the script

$thepbstrNameparameter contains the

scriptlet;s name.

OLE"&J4-TNEN4H*AL42HAME The default name supplied is invalid in this

scripting language.

OLE"&J4-TNEN"GHTA An unspecified synta% error occurred in the

scriptlet.

24"-NENE&E-T4OH An e%ception occurred in the parsing of the

scriptlet thepe'cepin(o parameter contains

information about the e%ception.



initialiFed0.

ENHOT4M-L This method is not supported the scripting engine

does not support adding event)sin'ing scriptlets.



&ActiveScript2arse::&nitNewHRESULT InitNe(-oid$%

4nitialiFes the scripting engine.

+efore the scripting engine can be used# one of the following methods must becalled3 IPersist*%%#oad# IPersist*%%Init&ew# or IActiveScriptParse%%Init&ew.

The semantics of this method are identical to IPersistStreamInit%%Init&ew# in thatthis method tells the scripting engine to initialiFe itself. Hote that it is not valid to

call both Init&ewand #oad# nor is it valid to call Init&ewor #oadmore thanonce.


25/37

ActiveX Scripting 5

eturns

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

&ActiveScript2arse::2arseScriptTe*tHRESULT ParseS.riptTe4t(

LPCOLESTR pstrCode, // address of s.ript"et te4t

LPCOLESTR pstrItemName, // address of item name

IUn6non p)n6Conte4t, // address of de')##in# .onte4t

LPCOLESTR pstrEndDe"imiter, // address of end5of5s.ript"et de"imiter

DWORD d!"a#s, // s.ript"et f"a#s

7ARIANT p-arRes)"t, // address of ')ffer for res)"ts

E3CEPIN!O pe4.epinfo // address of ')ffer for error data

$%

-arses the given code scriptlet# adding declarations into the name space andevaluating code as appropriate.

pstr)odein Address of the scriptlet te%t to evaluate. The interpretation of this stringdepends on the scripting language.

pstrItemNamein Address of the item name that gives the conte%t in which the scriptlet is to beevaluated. 4f this parameter is HILL# the code is evaluated in the scriptingengine;s global conte%t.

pun+)onte't

in Address of conte%t obect. This obect is reserved for use in a debuggingenvironment# where such a conte%t may be provided by the debugger to representan active run)time conte%t. 4f this parameter is HILL# the engine uses

pstrItemNameto identify the conte%t.

pstr*nd&elimiterin Address of the end)of)scriptlet delimiter. When pstr)odeis parsed from astream of te%t# the host typically uses a delimiter# such as two single 7uotationmar's /(0# to detect the end of the scriptlet. This parameter specifies the delimiterthat the host used# allowing the scripting engine to provide some conditional

primitive preprocessing /for e%ample# replacing a single 7uotation mar' ; withtwo single 7uotation mar's for use as a delimiter0. E%actly how /and if0 thescripting 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 ofthe scriptlet.

dwFlagsin 8lags associated with the scriptlet. &an be a combination of these values3

8alue 2eaning

SC)IPTT"!TIS"!P)"SSI+& 4f the distinction between a computational

e%pression and a statement is important but


26/37

ActiveX Scripting

syntactically ambiguous in the script

language# this flag specifies that the scriptlet

is to be interpreted as an e%pression# ratherthan 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"!TISP")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*%%Save 0# or if the scripting engine is

reset by way of a transition bac' to the

initiali7edstate.

SC)IPTT"!TIS8ISI5#" 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.

par,esultout Address of a buffer that receives the results of scriptlet processing# or HILLif the caller e%pects no result /that is# the SC)IPTT"!TIS"!P)"SSI+&value is not set0.

pe'cepin(oout Address of a structure that receives e%ception information. This structure isfilled if ParseScriptTe'treturns 24"-NENE&E-T4OH.

4f the scripting engine is in the initiali7edstate# no code will actually be evaluatedduring this call rather# such code is 7ueued and e%ecuted when the scripting engine

is transitioned into /or through0 the startedstate. +ecause e%ecution is not allowedin the initiali7edstate# it is an error to call this method with the

SC)IPTT"!TIS"!P)"SSI+&flag when in the initiali7edstate.

The scriptlet can be an e%pression# a list of statements# or anything allowed by thescript language. 8or e%ample# this method is used in the evaluation of the 1TML


27/37

ActiveX Scripting "


ENIHE-E&TE2 The call was not e%pected /for e%ample# thescripting engine is in the uninitiali7edor closed

state# or the SC)IPTT"!TIS"!P)"SSI+&

flag was set and the scripting engine is in the

initiali7edstate0.

24"-NENE&E-T4OH An e%ception occurred in the processing of the

scriptlet. Thepe'cepin(oparameter contains

information about the e%ception.

OLE"&J4-TNEN"GHTA An unspecified synta% error occurred in the

scriptlet.

ENHOT4M-L This method is not supported. The scripting

engine does not support run)time evaluation of

e%pressions or statements.

&ActiveScriptErrorAn obect implementing this interface is passed to

IActiveScriptSite%%+nScript"rrorwhenever the scripting engine encounters an

unhandled error. The host then calls methods on this obect to obtain informationabout the error that occurred.






4Active"criptErrormethods Description

.et"'ceptionInfo Jetrieves information about an error.

.etSourcePosition Jetrieves the location in the source code where an

error occurred.

.etSource#ineTe't Jetrieves the line in the source file where an error

occurred.

&ActiveScriptError::/etE*ception&n+oHRESULT etE4.eptionInfo(

E3CEPIN!O pe4.epinfo // str).t)re for e4.eption information

$%

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


28/37

ActiveX Scripting

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

eturns

"NOK The error information was successfully retrieved.

EN8A4L An error occurred.

&ActiveScriptError::/etSource-ineTe*tHRESULT 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!ourceLineout Address of a buffer that receives the line of source code in which the erroroccurred.

eturns

"NOK The line in the source file was successfully

retrieved.


&ActiveScriptError::/etSource2osition

HRESULT etSo)r.ePosition( DWORD pdSo)r.eConte4t, // .onte4t .oo6ie

ULON p)"LineN)m'er, // "ine n)m'er of error

LON pi.0C0arPosition // .0ara.ter position of error

$%

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

pdw!ource)onte'tout Address of a variable that receives a coo'ie that identifies the conte%t. Theinterpretation of this parameter depends on the host application.

pulLineNumberout Address of a variable that receives the line number in the source file wherethe error occurred.

pich)harositionout Address of a variable that receives the character position in the line wherethe error occurred.


29/37

ActiveX Scripting )

eturns

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

&ActiveScriptSiteThe host must create a site for the Active "cripting engine by implementingIActiveScriptSite. Isually# this site will be associated with the container of all the

obects that are visible to the script /for e%ample# the Active controls0. Typically#this container will correspond to the document or page being viewed. 4nternetE%plorer# for e%ample# would create such a container for each 1TML page being

displayed. Each Active control /or other automation obect0 on the page# and thescripting engine itself# would be enumerable within this container.






4Active"cript"itemethods Description

.et#CID Jetrieves the locale identifier that the host uses for

displaying user)interface elements.

.etItemInfo Obtains information about an item that was added

to an engine through a call to the

IActiveScript%%Add&amedItem method..etDoc8ersionString Jetrieves a host)defined string that uni7uely

identifies the current document version from the

host;s point of view.

+nScriptTerminate 4nforms the host that the script has completed

e%ecution.

+nStateChange 4nforms the host that the scripting engine has

changed states.

+nScript"rror 4nforms the host that an e%ecution error occurred

while the engine was running the script.

+n"nterScript 4nforms the host that the scripting engine has

begun e%ecuting the script code.

+n#eaveScript 4nforms the host that the scripting engine hasreturned from e%ecuting script code.

&ActiveScriptSite::/et0ocersionStringHRESULT etDo.7ersionStrin#(


30/37

ActiveX Scripting

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

$%

Jetrieves a host)defined string that uni7uely identifies the current document versionfrom the host;s point of view. 4f the related document has changed outside the scopeof 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 recompilethe ne%t time the script is loaded.

pstr.ersion!tringout Address of the host)defined document version string.

eturns

"NOK The document version string was successfully

retrieved. Thepstr.ersion!tringparameter

contains the string.ENHOT4M-L This method is not supported. The scripting

engine should assume that the script is in sync

with the document.

&ActiveScriptSite::/et&tem&n+oHRESULT IA.ti-eS.riptSite88etItemInfo(

LPCOLESTR pstrName, // address of item name

DWORD dRet)rn+as6, // 'it mas6 for information retrie-a"

IUn6non pp)n6Item, // address of pointer to item9s IUn6non

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.

pstrNamein The name associated with the item# as specified inIActiveScript%%Add&amedItem.

dw,eturnMas+in A bit mas' specifying what information about the item should be returned.The scripting engine should re7uest the minimum needed information becausesome of the return parameters /for e%ample# IT(peInfo0 can ta'e considerabletime to load or generate. &an be a combination of the following values3

8alue 2eaning

SC)IPTI&=+I1&>&+W& Jeturn the I1n0nowninterface for this item.

SC)IPTI&=+IT:P"I&=+ Jeturn the IT(peInfointerface for this item.

ppun+Itemout Address of a variable that receives a pointer to the I1n0nowninterfaceassociated with the given item. The scripting engine can use the 9uer(Interface


31/37


method to obtain the IDispatchinterface for the item. This parameter receivesHILL if dw,eturnMas+does not include the SC)IPTI&=+I1&>&+W&

value. Also# it receives HILL if there is no obect associated with the item namethis mechanism is used to create a simple class when the named item was addedwith the SC)IPTIT"2C+D"+: flag set.

ppTypeIn(oout Address of a variable that receives a pointer to the IT(peInfointerfaceassociated with the item. This parameter receives HILL if dw,eturnMas+doesnot include the SC)IPTI&=+IT:P"I&=+value# or if type information is notavailable for this item. 4f type information is not available# the obect cannotsource events# and name binding must be realiFed withIDispatch%%.etIDs+f&ames. Hote that this IT(peInfodescribes the coclass/T>I&DC+C#ASS0 because the obect may support multiple interfaces andevent interfaces. 4f the item supports the IProvide2ultipleT(peInfointerface#the IT(peInfointerface corresponds to the IT(peInfoof 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(peInfointerface is not needed for an item.

eturns

"NOK The re7uested interface pointer was successfully

retrieved. Theppun+ItemorppTypeIn(oparameter

contains the pointer.



TG-ENENELEMEHTHOT8OIH2 An item of the specified name was not found.

"ee also IActiveScript%%Add&amedItem

&ActiveScriptSite::/et-.&0HRESULT 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)interfaceelements surfaced by the engine appear in the appropriate language. 4f this method

returns ENHOT4M-L# the system)defined locale identifier should be used.

plcidout Address of a variable that receives the locale identifier for user)interfaceelements displayed by the scripting engine.


32/37

ActiveX Scripting

eturns

"NOK The locale identifier was successfully retrieved.Theplcidparameter contains the identifier.


ENHOT4M-L This method is not implemented. Ise the system)

defined locale.

&ActiveScriptSite::OnEnterScriptHRESULT 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 obect that then fires an eventhandled by the scripting engine# the scripting engine must call +n"nterScriptbefore e%ecuting the event# and must call +n#eaveScriptafter e%ecuting the event

but before returning to the obect that fired the event. &alls to this method can benested. Every call to +n"nterScriptre7uires a corresponding call to

+n#eaveScript.

eturns

"NOK The method succeeded.

"ee also IActiveScriptSite%%+n#eaveScript

&ActiveScriptSite::On-eaveScriptHRESULT 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 obect that then firesan event handled by the scripting engine# the scripting engine must call

+n"nterScriptbefore e%ecuting the event# and must call +n#eaveScript aftere%ecuting the event before returning to the obect that fired the event. &alls to thismethod can be nested. Every call to +n"nterScriptre7uires a corresponding call

to +n#eaveScript.

eturns

"NOK The method was successful.

"ee also IActiveScriptSite%%+n"nterScript


33/37


&ActiveScriptSite::OnScriptError

HRESULT IA.ti-eS.riptSite88OnS.riptError( IA.ti-eS.riptErrorpase // address of error interfa.e

$%

4nforms the host that an e%ecution error occurred while the engine was running thescript.

pasein Address of the error obect;s IActiveScript"rrorinterface. A host can usethis 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.

"N8AL"E 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.

EN8A4L The scripting engine should abort e%ecution of the

script and return it to the initiali7edstate. 4n this

case# thepe'cepin(o parameter obtained from

IActiveScript"rror%%.et"'ceptionInfois

generally passed to +nScriptTerminate.

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

&ActiveScriptSite::OnScriptTerminateHRESULT 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.

par,esultin Address of a variable that contains the script result# or HILL if the script

produced no result.

pe'cepin(oin Address of an "!C"PI&=+structure that contains e%ception informationgenerated 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


34/37

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 maynever be called.

eturns


&ActiveScriptSite::OnState.hangeHRESULT 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!tatein *alue that indicates the new script state. "ee IActiveScript%%.etScriptStatefor a description of the states.

eturns


"ee also IActiveScript%%.etScriptState

&ActiveScriptSite#indowThis interface is implemented by hosts that support a user interface on the same

obect as IActiveScriptSite. 1osts that do not support a user interface# such asservers# would not implement the IActiveScriptSiteWindow interface. The

scripting engine accesses this interface by calling 9uer(Interfacefrom

IActiveScriptSite.






4Active"cript"iteWindowmethods Description

.etWindow Jetrieves the window handle that can act as theowner of a pop)up window that the scripting

engine needs to display.

"nable2odeless &auses the host to enable or disable its main

window as well as any modeless dialog bo%es.


35/37


&ActiveScriptSite::Ena$'e,ode'essHRESULT 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 modelessdialog bo%es.

(*nablein 8lag that# if TJIE# enables the main window and modeless dialogs or# if8AL"E# disables them.

This method is identical to I+leInPlace=rame%%"nable2odeless .

&alls to this method can be nested.

eturns

"NOK The method was successful.


&ActiveScriptSite::/et#indowHRESULT etWindo(

HWND p0nd // 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.

phwndout Address of a variable that receives the window handle.

This method is similar to I+leWindow%%.etWindow.

eturns

"NOK The window handle was successfully retrieved.


Enumerations

S.&2TSTATEt&pedef en)m ta#SCRIPTSTATE :

SCRIPTSTATE;UNINITIALI,

SCRIPTSTATE;INITIALI


36/37

ActiveX Scripting

SCRIPTSTATE;CONNECTED = 2,

SCRIPTSTATE;DISCONNECTED = 1,

SCRIPTSTATE;CLOSED =

B SCRIPTSTATE%

&ontains named constant values that specify the state of a scripting engine. Thisenumeration is used by the IActiveScript%%.etScriptState#

IActiveScript%%SetScriptState# and IActiveScriptSite%%+nStateChangemethods.

E'ements

SC)IPTSTAT"1&I&ITIA#I


37/37

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

ActiveX Scripting

Documents

Transcript of ActiveX Scripting