You are on page 1of 73

Programming the Microsoft Agent Server Interface

ActiveX Technology for Interactive Software Agents


Last updated: October 1997
(updated info in Accessing Services Using Java)
Microsoft Corporation
Note: !is docu"ent is provided for infor"ationa# purposes on#$ and Microsoft
"a%es no &arranties' eit!er e(pressed or i"p#ied' in t!is docu"ent) !e entire ris%
of t!e use or t!e resu#ts of t!is docu"ent re"ains &it! t!e user)
*nfor"ation in t!is docu"ent is sub+ect to c!ange &it!out notice) Co"panies'
na"es' and data used in e(a"p#es !erein are fictitious un#ess ot!er&ise noted) ,o
part of t!is docu"ent "a$ be reproduced or trans"itted in an$ for" or b$ an$
"eans' e#ectronic or "ec!anica#' for an$ purpose' &it!out t!e e(press &ritten
per"ission of Microsoft Corporation)
Microsoft "a$ !ave patents or pending patent app#ications' trade"ar%s' cop$rig!ts'
or ot!er inte##ectua# propert$ rig!ts covering sub+ect "atter in t!is docu"ent) !e
furnis!ing of t!is docu"ent does not give $ou an$ #icense to t!ese patents'
trade"ar%s' cop$rig!ts' or ot!er inte##ectua# propert$ rig!ts) Microsoft' MS' MS-.OS'
/indo&s' /indo&s ,' and t!e /indo&s #ogo are eit!er registered trade"ar%s or
trade"ar%s of Microsoft Corporation in t!e U)S) and0or ot!er countries) Ot!er
product and co"pan$ na"es "entioned !erein "a$ be t!e trade"ar%s of t!eir
respective o&ners)
Contents
*ntroduction
Adding Microsoft Agent 1unctiona#it$ to 2our App#ication
Loading C!aracter and Ani"ation .ata
Creating a ,otification Sin%
Accessing Services Using Java
3eference
Introduction
Microsoft Agent provides services t!at enab#e $ou to progra" ani"ated c!aracters fro" an
app#ication) !ese services are i"p#e"ented as an OL4 Auto"ation server) OL4 Auto"ation
enab#es an app#ication to contro# anot!er app#ication5s ob+ect progra""atica##$) !is docu"ent
assu"es an understanding of t!e Co"ponent Ob+ect Mode# (COM) and OL4) 1or an
introduction of t!ese services' see t!e 6rogra""ing *nterface Overvie&) Sa"p#e progra"s are
avai#ab#e at t!e Microsoft Agent /eb site at !ttp:00&&&)"icrosoft)co"0&or%s!op0prog0agent0)
Adding Microsoft Agent unctionality to !our A""lication
o access Microsoft Agent services' create an instance of t!e server and re7uest a pointer to a
specific interface t!at t!e server supports using t!e standard COM convention) *n particu#ar'
t!e COM #ibrar$ provides an A6* function' CoCreateInstance' t!at creates an instance of t!e
ob+ect and returns a pointer to t!e re7uested interface of t!e ob+ect) 3e7uest a pointer to t!e
IAgent interface in $our CoCreateInstance ca## or in a subse7uent ca## to #ueryInterface)
!e fo##o&ing code i##ustrates t!is in C0C88:
hRes = CoCreateInstance(CLSID_AgentServer,
NULL,
CLSCTX_SERVER,
IID_IAgent,
(LPVOID !"#Agent!$
*f t!e Microsoft Agent server is running' t!is function connects to t!e server9 ot!er&ise' it starts
up t!e server)
1unctions t!at ta%e pointers to :S3s a##ocate "e"or$ using SysAllocString) *t is t!e ca##er5s
responsibi#it$ to free t!is "e"or$ using SysreeString)
$oading Character and Animation %ata
Once $ou !ave a pointer to t!e IAgent interface' $ou can use t!e $oad "et!od to #oad a
c!aracter and retrieve its I%is"atch interface:
%% Create a var&ant to store the '()) #ath o' the character to )oa*
Var&antIn&t("vPath!$
vPath+vt = VT_,STR$
vPath+-strVa) = S.sA))ocStr&ng(/#0s1Character!$
%% Loa* the character
hRes = #Agent23Loa*(vPath, ")CharID, ")Re4(estID!$
%% 5et &ts ID&s#atch &nter'ace
hRes = #Agent235etCharacter()CharID, "#*Character!$
2ou can t!en use t!is infor"ation to re7uest a pointer to t!e IAgentCharacter:
%% 6(er. 'or IAgentCharacter
hRes = #*Character236(er.Inter'ace(IID_IAgentCharacter, (LPVOID
!"#Character!$
%% Re)ease the ID&s#atch
#*Character23Re)ease(!$
2ou can use t!is interface to access t!e c!aracter5s "et!ods:
%% Sho0 the character+ The '&rst #ara7eter te))s 8&croso't
%% Agent to sho0 the character -. #)a.&ng an an&7at&on+
hRes = #Character23Sho0(9ALSE, ")Re4(estID!$
%% 8a/e the character s#ea/
-s1S#ea/ = S.sA))ocStr&ng(L:;e))o <or)*=:!$
hRes = #Character23S#ea/(-s1S#ea/, NULL, ")Re4(estID!$
S.s9reeStr&ng(-s1S#ea/!$
/!en $ou no #onger need Microsoft Agent services' suc! as &!en $our c#ient app#ication s!uts
do&n' re#ease its interfaces) ,ote t!at re#easing t!e c!aracter interface does not un#oad t!e
c!aracter) Ca## t!e &nload "et!od to do t!is before re#easing t!e IAgent interface:
%% C)ean (#
&' (#Character! >
%% Re)ease the character &nter'ace
#Character23Re)ease(!$
%% Un)oa* the character+ NOTE? re)eas&ng the character
%% &nter'ace *oes NOT 7a/e the character go a0a.+ @o( 7(st
%% ca)) Un)oa*+
#Agent23Un)oa*()CharID!$
A
%% Re)ease the Agent
#Agent23Re)ease(!$
Var&antC)ear("vPath!$
Creating a Notification Sin'
o be notified of events b$ Microsoft Agent' $ou "ust i"p#e"ent t!e IAgentNotifySin'
interface' and create and register an ob+ect of t!at t$pe fo##o&ing COM conventions:
%% Create a not&'&cat&on s&n/
#S&n/ = ne0 AgentNot&'.S&n/$
#S&n/23A**Re'(!$
%% An* reg&ster &t 0&th 8&croso't Agent
hRes = #Agent23Reg&ster((IUn/no0n !#S&n/, ")Not&'.S&n/ID!$
3e"e"ber to unregister $our notification sin% &!en $our app#ication s!uts do&n and re#eases
Microsoft Agent5s interfaces)
Accessing Services &sing (ava
2ou can a#so access Microsoft Agent services fro" a Java; app#et) Man$ of t!e functions
accessib#e t!roug! t!e Microsoft Agent interfaces return va#ues t!roug! para"eters passed b$
reference) *n order to pass t!ese para"eters fro" Java' it is necessar$ to create sing#e-
e#e"ent arra$s in $our code and pass t!e" as para"eters to t!e appropriate function) *f $ou<re
using Microsoft =isua# J88; and !ave run t!e Java $pe Librar$ /i>ard on t!e Microsoft
Agent server' refer to t!e su""ar$)t(t fi#e to revie& &!ic! functions re7uire arra$ argu"ents)
!e procedure is si"i#ar to t!at in C9 $ou use t!e IAgent interface to create an instance of t!e
server' t!en #oad t!e c!aracter:
#r&vate IAgent 7_Agent = n())$
#r&vate IAgentCharacter 7_8er)&nBC = >n())A$
#r&vate &nt 7_8er)&nIDBC = >2DA$
#r&vate &nt 7_Re4(estIDBC = >EA$
#r&vate '&na) Str&ng 7_CharacterPath = :c?FFagentGFFagtchare*FF7er)&n+acs:$
#(-)&c vo&* start(!
>
%% Start the 8&croso't Agent Server
7_Agent = (IAgent! ne0 AgentServer(!$
tr.
>
%% The '&)es#ec #ara7eter o' the Loa* 7etho* &s a
%% CO8 var&ant to acce#t a)ternate Agent *ata #rov&*ers+
%% <e 0ant a stan*ar* #rov&*er so 0e can H(st s#ec&'.
%% the '&)es#ec 'or o(r character+
Var&ant characterPath = ne0 Var&ant(!$
characterPath+#(tStr&ng(7_CharacterPath!$
%% Loa* the character
7_Agent+Loa*(characterPath,
7_8er)&nID,
7_Re4(estID!$
A
!e procedure is s#ig!t#$ different &!en #oading c!aracters fro" a ?6 re"ote #ocation suc!
as a /eb site) *n t!is case t!e $oad "et!od is as$nc!ronous and &i## raise a COM e(ception
of 4@64,.*,A (B(CBBBBBBa)) 2ou &i## need to catc! t!is e(ception and !and#e it correct#$ as
is done in t!e fo##o&ing functions:
%% Constants (se* &n as.nchrono(s character )oa*s
#r&vate '&na) &nt E_PENDIN5 = EGIEEEEEEa$
#r&vate '&na) &nt NOERROR = E$
%% Th&s '(nct&on )oa*s a character 'ro7 the s#ec&'&e* #ath+
%% It correct). han*)es the )oa*&ng o' characters 'ro7
%% re7ote s&tes+
%% Th&s sa7#)e *oesnJt care a-o(t the re4(est &* ret(rne*
%% 'ro7 the Loa* ca))+ Rea) #ro*(ct&on co*e 7&ght (se the
%% re4(est &* an* the Re4(estCo7#)ete ca))-ac/ to chec/ 'or
%% a s(ccess'() character )oa* -e'ore #rocee*&ng+
#(-)&c &nt Loa*Character(Var&ant #ath, &ntBC &*!
>
&nt re4(est&*BC = >2DA$
&nt hRes = E$
tr.
>
%% Loa* the character
7_Agent+Loa*(#ath, &*, re4(est&*!$
A
catch(co7+7s+co7+Co7EGce#t&on e!
>
%% 5et the ;RESULT
hRes = e+get;Res()t(!$

%% I' the error co*e &s E_PENDIN5, 0e ret(rn NOERROR
&' (hRes == E_PENDIN5!
hRes = NOERROR$
A
ret(rn hRes$
A
#(-)&c vo&* start(!
>
&' (Loa*Character(characterPath, 7_8er)&nID! == NOERROR!
>
sto#(!$
ret(rn$
A
%% Other &n&t&a)&1at&on co*e here
+
+
+
A
!en get t!e IAgentCharacter interface t!at enab#es $ou to access its "et!ods:
%% 5et the IAgentCharacter &nter'ace 'or the )oa*e*
%% character -. #ass&ng &ts ID to the Agent server+
7_Agent+5etCharacter(7_8er)&nIDBEC, 7_8er)&n!$
%% Sho0 the character
7_8er)&nBEC+Sho0(9ALSE, 7_Re4(estID!$
%% An* s#ea/ he))o
7_8er)&nBEC+S#ea/(:;e))o <or)*=:, ::, 7_Re4(estID!$
Si"i#ar#$' to be notified of events' $ou "ust i"p#e"ent t!e IAgentNotifySin' interface'
creating and registering an ob+ect of t!at t$pe:
K
%% Dec)are an Agent Not&'. S&n/ so that 0e can get
%% not&'&cat&on ca))-ac/s 'ro7 the Agent server+
#r&vate AgentNot&'.S&n/ 7_S&n/ = n())$
#r&vate &nt 7_S&n/IDBC = >2DA$
#(-)&c vo&* start(!
>
K
%% Create an* reg&ster a not&'. s&n/
7_S&n/ = ne0 AgentNot&'.S&n/(!$
7_Agent+Reg&ster(7_S&n/, 7_S&n/ID!$
K
%% 5&ve o(r not&'. s&n/ access to the character
7_S&n/+SetCharacter(7_8er)&nBEC!$
K
A
*n order to access Microsoft Agent fro" a Java app#et' $ou "ust generate Java c#asses t!at
$ou t!en insta## &it! t!e app#et) 2ou can use t!e =isua# J88 Java $pe Librar$ /i>ard' for
e(a"p#e' to generate t!ese fi#es) *f $ou p#an to !ost t!e app#et on a /eb page' $ou bui#d a
signed Java CA: t!at inc#udes t!e generated c#ass fi#es and t!at do&n#oads &it! t!e page) !e
c#ass fi#es are necessar$ to access t!e Microsoft Agent Server because it is a COM ob+ect t!at
e(ecutes outside of t!e Java sandbo() o #earn "ore about rust-:ased Securit$ for Java' see
!ttp:00&&&)"icrosoft)co"0+ava0securit$0)
)eference
!is reference contains t!e fo##o&ing sections:
*nterfaces
1unctions
4vents
Interfaces
Microsoft Agent defines interfaces t!at a##o& app#ications to access its services' enab#ing an
app#ication to contro# t!e ani"ation of a c!aracter' support user input events' and specif$
output)
A## t!e Microsoft Agent interfaces are defined in !eader ()!) fi#es)
IAgent
IAgent defines an interface t!at a##o&s app#ications to #oad c!aracters' receive events' and
c!ec% t!e current state of t!e Microsoft Agent Server)
Methods in *ta+le ,rder
IAgent Methods %escri"tion
$oad Loads a c!aracter5s data fi#e)
&nload Un#oads a c!aracter5s data fi#e)
)egister 3egisters a notification sin% for t!e c#ient)
&nregister Unregisters a c#ient5s notification sin%)
-etCharacter 3eturns t!e *AgentC!aracter interface for a #oaded c!aracter)
-etSus"ended 3eturns &!et!er t!e server is current#$ suspended)
IAgent::-etCharacter
;RESULT 5etCharacter(
)ong *0CharID %% character ID
!$
3etrieves t!e IAgentCharacter for a #oaded c!aracter)
D 3eturns S@OE to indicate t!e operation &as successfu#)
DwCharID
!e c!aracter5s *.)
IAgent::-etSus"ended
;RESULT 5etS(s#en*e*(
)ong #-S(s#en*e* %% a**ress o' var&a-)e 'or s(s#en*e* ')ag
!$
3etrieves &!et!er t!e Microsoft Agent server is current#$ suspended)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pbSuspended
Address of a variab#e t!at receives 3U4 if t!e Microsoft Agent server is in t!e suspended
state and 1ALS4 if not)
Microsoft Agent #oads in a suspended state &!en a c#ient app#ication atte"pts to start it up
after t!e user !as previous#$ 7uit (b$ c!oosing t!e 4(it co""and on t!e Microsoft Agent
tas%bar icon)) *n t!e suspended state Microsoft Agent !and#es connection re7uests' but returns
fai#ure on an$ ani"ation "et!ods) !erefore' a c!aracter cannot be disp#a$ed in t!is state)
C#ient app#ications can advise users to restart t!e server (b$ c!oosing 3estart on t!e tas%bar
pop-up "enu)' but cannot restart t!e server direct#$)

IAgent::$oad
;RESULT Loa*(
VARIANT vLoa*Le., %% *ata #rov&*er
)ong #*0CharID, %% a**ress o' a var&a-)e 'or character ID
)ong #*0Re4ID %% a**ress o' a var&a-)e 'or re4(est ID
!$
Loads a c!aracter into t!e Characters co##ection)
D 3eturns S@OE to indicate t!e operation &as successfu#)
vLoadKey
A variant datat$pe t!at "ust be one of t!e fo##o&ing:
filespec !e #oca# fi#e #ocation of t!e specified c!aracter5s definition fi#e)
URL !e ?6 address for t!e c!aracter5s definition fi#e)
provider An a#ternate c!aracter definition provider)
pdwCharID
Address of a variab#e t!at receives t!e c!aracter5s *.)
pdwReqID
Address of a variab#e t!at receives t!e $oad re7uest *.)
Microsoft Agent<s data provider supports #oading c!aracter data stored as a sing#e structured
fi#e ()ACS) &it! c!aracter data and ani"ation data toget!er' or as separate c!aracter data
()AC1) and ani"ation ()AA1) fi#es) Aenera##$' use t!e sing#e structured )ACS fi#e to #oad a
c!aracter t!at is stored on a #oca# dis% drive or net&or% and accessed using conventiona# fi#e
protoco# (suc! as U,C pat!na"es)) Use t!e separate )AC1 and )AA1 fi#es &!en $ou &ant to
#oad t!e ani"ation fi#es individua##$ fro" a re"ote site &!ere t!e$ are accessed using ?6
protoco#)
1or )ACS fi#es' using t!e $oad "et!od provides access a c!aracter5s ani"ations) 1or )AC1
fi#es' $ou a#so use t!e Pre"are "et!od to #oad ani"ation data) !e $oad "et!od does not
support do&n#oading )ACS fi#es fro" an ?6 site)
Loading a c!aracter does not auto"atica##$ disp#a$ t!e c!aracter) Use t!e Show "et!od first
to "a%e t!e c!aracter visib#e)
!e vLoadKey para"eter a#so enab#es $ou specif$ $our o&n data provider (t!at &ou#d be
#oaded separate#$) t!at can !ave its o&n "et!ods for #oading ani"ation data) 2ou need to
create a data provider ob+ect on#$ if $ou supp#$ c!aracter data in specia# for"ats)

IAgent::)egister
;RESULT Reg&ster(
IUn/no0n #(n/Not&'.S&n/ %% IUn/no0n a**ress 'or c)&ent not&'&cat&on s&n/
)ong #*0S&n/ID %% a**ress o' the not&'&cat&on s&n/ ID
!$
3egisters a notification sin% for t!e c#ient app#ication)
D 3eturns S@OE to indicate t!e operation &as successfu#)
IUnknown
Address of I&n'nown for $our notification sin% interface)
pdwSinkID
Address of notification sin% *. (used to unregister t!e notification sin%))
2ou need to register $our notification sin% (a#so %no&n as a notif$ sin% or event sin%) to receive
events fro" t!e Microsoft Agent server)
See a#so IAgent::&nregister

IAgent::&n$oad
;RESULT UnLoa*(
)ong *0CharID %%character ID
!$
Un#oads t!e c!aracter data for t!e specified c!aracter fro" t!e Characters co##ection)
D 3eturns S@OE to indicate t!e operation &as successfu#)
dwCharID
!e c!aracter5s *.)
Use t!is "et!od &!en $ou no #onger need a c!aracter' to free up "e"or$ used to store
infor"ation about t!e c!aracter) *f $ou access t!e c!aracter again' use t!e $oad "et!od)
See a#so IAgent::$oad

IAgent::&nregister
;RESULT Unreg&ster(
)ong *0S&n/ID %%not&'&cat&on s&n/ ID
!$
Un#oads t!e c!aracter data for t!e specified c!aracter fro" t!e Characters co##ection)
D 3eturns S@OE to indicate t!e operation &as successfu#)
dwSinkID
!e notification sin% *.)
Use t!is "et!od &!en $ou no #onger need Microsoft Agent services' suc! as &!en $our
app#ication s!uts do&n)
See a#so IAgent::)egister
IAgentCharacter
IAgentCharacter defines an interface t!at a##o&s app#ications to 7uer$ c!aracter properties
and p#a$ ani"ations)
Methods in *ta+le ,rder
IAgentCharacter Methods .escription
-et*isi+le 3eturns &!et!er t!e c!aracter (fra"e) is current#$ visib#e)
SetPosition Sets t!e position of t!e c!aracter fra"e)
-etPosition 3eturns t!e position of t!e c!aracter fra"e)
SetSi.e Sets t!e si>e of t!e c!aracter fra"e)
-etSi.e 3eturns t!e si>e of t!e c!aracter fra"e)
-etName 3eturns t!e na"e of t!e c!aracter)
-et%escri"tion 3eturns t!e description for t!e c!aracter)
-etTTSS"eed 3eturns t!e current S output speed setting for t!e c!aracter)
-etTTSPitch 3eturns t!e current S pitc! setting for t!e c!aracter)
Activate Sets &!et!er a c#ient is active or a c!aracter is top"ost)
IAgentCharacter Methods .escription
SetIdle,n Sets t!e server5s id#e processing)
-etIdle,n 3eturns t!e setting of t!e server5s id#e processing)
Pre"are 3etrieves ani"ation data for t!e c!aracter)
Play 6#a$s a specified ani"ation)
Sto" Stops an ani"ation for a c!aracter)
Sto"All Stops a## ani"ations for a c!aracter)
/ait ?o#ds t!e c!aracter5s ani"ation 7ueue)
Interru"t *nterrupts a c!aracter5s ani"ation)
Show .isp#a$s t!e c!aracter and p#a$s t!e c!aracter5s Showing state
ani"ation)
0ide 6#a$s t!e c!aracter5s 0iding state ani"ation and !ides t!e c!aracter5s
fra"e)
S"ea' 6#a$s spo%en output for t!e c!aracter)
MoveTo Moves t!e c!aracter fra"e to t!e specified #ocation)
-estureAt 6#a$s a gesturing ani"ation based on t!e specified #ocation)
-etMoveCause 3etrieves t!e cause of t!e c!aracter5s #ast "ove)
-et*isi+ilityCause 3etrieves t!e cause of t!e #ast c!ange to t!e c!aracter5s visibi#it$ state)
0as,therClients 3etrieves &!et!er t!e c!aracter !as ot!er current c#ients)
SetSound1ffects,n .eter"ines &!et!er a c!aracter ani"ation5s sound effects p#a$)
-etSound1ffects,n 3etrieves &!et!er a c!aracter5s sound effects setting is enab#ed)
SetName Sets t!e c!aracter5s na"e)
Set%escri"tion Sets t!e c!aracter5s description)
-et12tra%ata 3etrieves additiona# data stored &it! t!e c!aracter)
IAgentCharacter::Activate
;RESULT Act&vate(
short sState, %% to#7ost character or c)&ent sett&ng
!$
Sets &!et!er a c#ient is active or a c!aracter is top"ost)
D 3eturns S@OE to indicate t!e operation &as successfu#)
D 3eturns S@1ALS4 to indicate t!e operation &as not successfu#)
sState
2ou can specif$ t!e fo##o&ing va#ues for t!is para"eter:
B Set as not t!e active c#ient)
1 Set as t!e active c#ient)
F Ma%e t!e top"ost c!aracter)
/!en "u#tip#e c!aracters are visib#e' on#$ one of t!e c!aracters receives speec! input at a
ti"e) Si"i#ar#$' &!en "u#tip#e c#ient app#ications s!are t!e sa"e c!aracter' on#$ one of t!e
c#ients receives "ouse input (for e(a"p#e' Microsoft Agent contro# c#ic% or drag events) at a
ti"e) !e c!aracter set to receive "ouse and speec! input is t!e top"ost c!aracter and t!e
c#ient t!at receives input is t!e c!aracter<s active c#ient) (!e top"ost c!aracter5s &indo& a#so
appears at t!e top of t!e c!aracter &indo&<s >-order)) $pica##$' t!e user deter"ines &!ic!
c!aracter is top"ost b$ e(p#icit#$ se#ecting it) ?o&ever' top"ost activation a#so c!anges &!en
a c!aracter is s!o&n or !idden (t!e c!aracter beco"es or is no #onger top"ost' respective#$))
2ou can a#so use t!is "et!od to e(p#icit#$ "anage &!en $our c#ient receives input directed to
t!e c!aracter' suc! as &!en $our app#ication itse#f beco"es active) 1or e(a"p#e' setting State
to F "a%es t!e c!aracter top"ost' and $our c#ient receives a## "ouse and speec! input events
generated fro" user interaction &it! t!e c!aracter) !erefore' it a#so "a%es $our c#ient t!e
input-active c#ient of t!e c!aracter) ?o&ever' $ou can a#so set t!e active c#ient for a c!aracter
&it!out "a%ing t!e c!aracter top"ost' b$ setting State to 1) !is enab#es $our c#ient to receive
input directed to t!at c!aracter &!en t!e c!aracter beco"es top"ost) Si"i#ar#$' $ou can set
$our c#ient to not be t!e active c#ient (to not receive input) &!en t!e c!aracter beco"es
top"ost' b$ setting State to B) 2ou can deter"ine if a c!aracter !as ot!er current c#ients using
IAgentCharacter::0as,therClients)
Avoid ca##ing t!is "et!od direct#$ after a Show "et!od) Show auto"atica##$ sets t!e input-
active c#ient) /!en t!e c!aracter is !idden' t!e Activate ca## "a$ fai# if it gets processed
before t!e Show "et!od co"p#etes)
*f $ou ca## t!is "et!od to a function' it returns a :oo#ean va#ue t!at indicates &!et!er t!e
"et!od succeeded) Atte"pting to ca## t!is "et!od &it! t!e State para"eter set to F &!en t!e
specified c!aracter is !idden &i## fai#) Si"i#ar#$' if $ou set State to B and $our app#ication is t!e
on#$ c#ient' t!is ca## fai#s because a c!aracter "ust a#&a$s !ave a top"ost c#ient)
See a#so IAgentCharacter::0as,therClients

IAgentCharacter::-estureAt
;RESULT 5est(reAt(
short G, %% G2coor*&nate o' s#ec&'&e* )ocat&on
short ., %% .2coor*&nate o' s#ec&'&e* )ocat&on
)ong #*0Re4ID %% a**ress o' a re4(est ID
!$
6#a$s t!e associated -esturing state ani"ation based on t!e specified #ocation)
D 3eturns S@OE to indicate t!e operation &as successfu#) /!en t!e function returns'
pdwReqID contains t!e *. of t!e re7uest)
x
!e (-coordinate of t!e specified #ocation in pi(e#s' re#ative to t!e screen origin (upper
#eft))
y
!e $-coordinate of t!e specified #ocation in pi(e#s' re#ative to t!e screen origin (upper
#eft))
pdwReqID
Address of a variab#e t!at receives t!e -estureAt re7uest *.)
!e server auto"atica##$ deter"ines and p#a$s t!e appropriate gesturing ani"ation based on
t!e c!aracter5s current position and t!e specified #ocation) /!en using t!e ?6 protoco# to
access c!aracter and ani"ation data' use t!e Pre"are "et!od to ensure t!at t!e ani"ations
are avai#ab#e before ca##ing t!is "et!od)

IAgentCharacter::-et%escri"tion
;RESULT 5etDescr&#t&on(
,STR #-s1Descr&#t&on %% a**ress o' -(''er 'or character *escr&#t&on
!$
3etrieves t!e description of t!e c!aracter)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pbsDescription
!e address of a :S3 t!at receives t!e va#ue of t!e description for t!e c!aracter) A
c!aracter5s description is defined &!en it is co"pi#ed &it! t!e Microsoft Agent C!aracter
4ditor) !e description setting is optiona# and "a$ not be supp#ied for a## c!aracters)

IAgentCharacter::-et12tra%ata
;RESULT 5etEGtraData(
,STR #-s1EGtraData %% a**ress o' -(''er 'or a**&t&ona) character *ata
!$
3etrieves additiona# data stored as part of t!e c!aracter)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pbs!xtraData
!e address of a :S3 t!at receives t!e va#ue of t!e additiona# data for t!e c!aracter) A
c!aracter5s additiona# data is defined &!en it is co"pi#ed &it! t!e Microsoft Agent
C!aracter 4ditor) A c!aracter deve#oper can supp#$ t!is string b$ editing t!e )AC. fi#e for a
c!aracter) !e setting is optiona# and "a$ not be supp#ied for a## c!aracters' nor can t!e
data be defined or c!anged at run ti"e) *n addition' t!e "eaning of t!e data supp#ied is
defined b$ t!e c!aracter deve#oper)
IAgentCharacter::-etIdle,n
;RESULT 5etI*)eOn(
)ong #-On %% a**ress o' &*)e #rocess&ng ')ag
!$
*ndicates t!e auto"atic id#e processing state for a c!aracter)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pb"n
Address of a variab#e t!at receives 3U4 if t!e Microsoft Agent server auto"atica##$ p#a$s
Idling state ani"ations for a c!aracter and 1ALS4 if not)
See a#so IAgentCharacter::SetIdle,n

IAgentCharacter::-etMoveCause
;RESULT 5et8oveCa(se(
)ong #*0Ca(se %% a**ress o' var&a-)e 'or ca(se o' character 7ove
!$
3etrieves t!e cause of t!e c!aracter5s #ast "ove)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pdwCause
Address of a variab#e t!at receives t!e cause of t!e c!aracter5s #ast "ove and &i## be one
of t!e fo##o&ing:
const unsigned short NeverMoved 3 45 C!aracter !as not been "oved)
const unsigned short &serMoved 3 65 User dragged t!e c!aracter)
const unsigned short ProgramMoved 3 75 2our app#ication "oved t!e c!aracter)
const unsigned short ,therProgramMoved 3 85 Anot!er app#ication "oved t!e
c!aracter)
See a#so IAgentNotifySin'::Move
IAgentCharacter::-etName
;RESULT 5etNa7e(
,STR #-s1Na7e %% a**ress o' -(''er 'or character na7e
!$
3etrieves t!e na"e of t!e c!aracter)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pbs#a$e
!e address of a :S3 t!at receives t!e va#ue of t!e na"e for t!e c!aracter) A c!aracter5s
defau#t na"e is defined &!en it is co"pi#ed &it! t!e Microsoft Agent C!aracter 4ditor) !e
na"e setting is optiona# and "a$ not be supported for a## c!aracters) 2ou can a#so set t!e
c!aracter5s na"e using IAgentCharacter:SetName9 !o&ever' t!is c!anges t!e na"e for
a## current c#ients of t!e c!aracter)
See a#so IAgentCharacter::SetName
IAgentCharacter::-etPosition
;RESULT 5etPos&t&on(
)ong #)Le't, %% a**ress o' var&a-)e 'or )e't e*ge o' character
)ong #)To# %% a**ress o' var&a-)e 'or to# e*ge o' character
!$
3etrieves t!e c!aracter5s ani"ation fra"e position)
D 3eturns S@OE to indicate t!e operation &as successfu#)
plLeft
Address of a variab#e t!at receives t!e screen coordinate of t!e c!aracter ani"ation
fra"e5s #eft edge in pi(e#s' re#ative to t!e screen origin (upper #eft))
pl%op
Address of a variab#e t!at receives t!e screen coordinate of t!e c!aracter ani"ation
fra"e5s top edge in pi(e#s' re#ative to t!e screen origin (upper #eft))
4ven t!oug! t!e c!aracter appears in an irregu#ar#$ s!aped region &indo&' t!e #ocation of t!e
c!aracter is based on its rectangu#ar ani"ation fra"e)
See a#so IAgentCharacter::SetPosition' IAgentCharacter::-etSi.e

IAgentCharacter::-etSi.e
;RESULT 5etS&1e(
)ong #)<&*th, %% a**ress o' var&a-)e 'or character 0&*th
)ong #);e&ght %% a**ress o' var&a-)e 'or character he&ght
!$
3etrieves t!e si>e of t!e c!aracter5s ani"ation fra"e)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pl&idth
Address of a variab#e t!at receives t!e &idt! of t!e c!aracter ani"ation fra"e in pi(e#s'
re#ative to t!e screen origin (upper #eft))
pl'ei(ht
Address of a variab#e t!at receives t!e !eig!t of t!e c!aracter ani"ation fra"e in pi(e#s'
re#ative to t!e screen origin (upper #eft))
4ven t!oug! t!e c!aracter appears in an irregu#ar#$ s!aped region &indo&' t!e #ocation of t!e
c!aracter is based on its rectangu#ar ani"ation fra"e)
See a#so IAgent::SetSi.e

IAgentCharacter::-etSound1ffects,n
;RESULT 5etSo(n*E''ectsOn(
)ong #-On %% a**ress o' var&a-)e 'or so(n* e''ects sett&ng
!$
3etrieves &!et!er t!e c!aracter5s sound effects setting is enab#ed)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pb"n
Address of a variab#e t!at receives 3U4 if t!e c!aracter5s sound effects setting is
enab#ed' 1ALS4 if disab#ed)
!e c!aracter<s sound effects setting deter"ines &!et!er sound effects co"pi#ed as a part of
t!e c!aracter are p#a$ed &!en $ou p#a$ an associated ani"ation) !e setting is sub+ect to t!e
user5s g#oba# sound effects setting in
IAgentAudio,ut"utPro"erties::-et&singSound1ffects)
See a#so IAgentCharacter::SetSound1ffects,n'
IAgentAudio,ut"utPro"erties::-et&singSound1ffects

IAgentCharacter::-etTTSPitch
;RESULT 5etTTSP&tch(
)ong #*0P&tch %% a**ress o' var&a-)e 'or character TTS #&tch
!$
3etrieves t!e c!aracter5s S output pitc! setting)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pdw)itch
Address of a variab#e t!at receives t!e c!aracter5s current S pitc! setting in ?ert>)
A#t!oug! $our app#ication cannot &rite t!is va#ue' $ou can inc#ude pitc! tags in $our output te(t
t!at &i## te"porari#$ increase t!e pitc! for a particu#ar utterance) !is "et!od app#ies on#$ to
c!aracters configured for S output) *f t!e speec! s$nt!esis (S) engine is not enab#ed (or
insta##ed) or t!e c!aracter does not support S output' t!is "et!od returns >ero (B))

IAgentCharacter::-etTTSS"eed
;RESULT 5etTTSS#ee*(
)ong #*0S#ee* %% a**ress o' var&a-)e 'or character TTS o(t#(t s#ee*
!$
3etrieves t!e c!aracter5s S output speed setting)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pdwSpeed
Address of a variab#e t!at receives t!e output speed of t!e c!aracter in &ords per "inute)
A#t!oug! $our app#ication cannot &rite t!is va#ue' $ou can inc#ude speed tags in $our output
te(t t!at &i## te"porari#$ speed up t!e output for a particu#ar utterance)
!is propert$ returns t!e current spea%ing output speed setting for t!e c!aracter) 1or
c!aracters using S output' t!e propert$ returns t!e actua# S output for t!e c!aracter) *f
S is not enab#ed or t!e c!aracter does not support S output' t!e setting ref#ects t!e user
setting for output speed)

IAgentCharacter::-et*isi+ilityCause
;RESULT 5etV&s&-&)&t.Ca(se(
)ong #*0Ca(se %% a**ress o' var&a-)e 'or ca(se o' character v&s&-)e state
!$
3etrieves t!e cause of t!e c!aracter5s visib#e state)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pdwCause
Address of a variab#e t!at receives t!e cause of t!e c!aracter5s #ast visibi#it$ state c!ange
and &i## be one of t!e fo##o&ing:
const unsigned short NeverShown 3 45 C!aracter !as not been s!o&n)
const unsigned short &ser0id 3 65 User !id t!e c!aracter)
const unsigned short &serShowed 3 75 User s!o&ed t!e c!aracter)
const unsigned short Program0id 3 85 2our app#ication !id t!e c!aracter)
const unsigned short ProgramShowed 3 95 2our app#ication s!o&ed t!e c!aracter)
const unsigned short ,therProgram0id 3 :5 Anot!er app#ication !id t!e c!aracter)
const unsigned short ,therProgramShowed 3 ;5 Anot!er app#ication s!o&ed t!e
c!aracter)
See a#so IAgentNotifySin'::0ide' IAgentNotifySin'::Show
IAgentCharacter::-et*isi+le
;RESULT 5etV&s&-)e(
)ong #-V&s&-)e %% a**ress o' var&a-)e 'or character V&s&-)e sett&ng
!$
.eter"ines &!et!er t!e c!aracter5s ani"ation fra"e is current#$ visib#e)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pb*isible
Address of a variab#e t!at receives 3U4 if t!e c!aracter5s fra"e is visib#e and 1ALS4 if
!idden)
2ou can use t!is "et!od to deter"ine &!et!er t!e c!aracter5s fra"e is current#$ visib#e) o
"a%e a c!aracter visib#e' use t!e Show "et!od) o !ide a c!aracter' use t!e 0ide "et!od)

IAgentCharacter::0as,therClients
;RESULT ;asOtherC)&ents(
)ong #-;asOtherC)&ents %% a**ress o' var&a-)e 'or 0hether character has
!$ %% other c)&ents
3etrieves &!et!er a c!aracter !as ot!er c#ients)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pb'as"therClients
Address of a variab#e t!at receives 3U4 if t!e c!aracter !as ot!er c#ients and 1ALS4 if
not)
IAgentCharacter::0ide
;RESULT ;&*e(
)ong -9ast, %% #)a. ;&*&ng state an&7at&on ')ag
)ong #*0Re4ID %% a**ress o' re4(est ID
!$
?ides t!e c!aracter)
D 3eturns S@OE to indicate t!e operation &as successfu#) /!en t!e function returns'
pdwReqID contains t!e *. of t!e re7uest)
b+ast
0iding state ani"ation f#ag) *f t!is para"eter is 3U4' t!e 0iding ani"ation does not
p#a$ before t!e c!aracter fra"e is !idden9 if 1ALS4' t!e ani"ation p#a$s)
pdwReqID
Address of a variab#e t!at receives t!e 0ide re7uest *.)
!e server 7ueues t!e ani"ation associated &it! t!e 0ide "et!od in t!e c!aracter5s 7ueue)
!is a##o&s $ou to use it to !ide t!e c!aracter after a se7uence of ot!er ani"ations) 2ou can
p#a$ t!e action i""ediate#$ b$ using t!e Sto" "et!od before ca##ing t!e 0ide "et!od)
/!en using t!e ?6 protoco# to access c!aracter and ani"ation data' use t!e Pre"are
"et!od to ensure t!e avai#abi#it$ of t!e 0iding state ani"ation before ca##ing t!is "et!od)
?iding a c!aracter can a#so resu#t in triggering t!e ActivateIn"ut event of anot!er visib#e
c!aracter)
?idden c!aracters cannot access t!e audio c!anne#) !e server &i## pass bac% a fai#ure status
in t!e )e<uestCom"lete event if $ou generate an ani"ation re7uest and t!e c!aracter is
!idden)
See a#so IAgentCharacter::Show

IAgentCharacter::Interru"t
;RESULT Interr(#t(
)ong *0Re4ID, %% re4(est ID to &nterr(#t
)ong #*0Re4ID %% a**ress o' re4(est ID
!$
*nterrupts t!e specified ani"ation (re7uest) of anot!er c!aracter)
D 3eturns S@OE to indicate t!e operation &as successfu#) /!en t!e function returns'
pdwReqID contains t!e *. of t!e re7uest)
dwReqID
An *. of t!e re7uest to interrupt)
pdwReqID
Address of a variab#e t!at receives t!e Interru"t re7uest *.)
2ou can use t!is "et!od to s$nc up ani"ation bet&een c!aracters) 1or e(a"p#e' if anot!er
c!aracter is in a #ooping ani"ation' t!is "et!od &i## stop t!e #ooping ani"ation and start t!e
ne(t ani"ation in t!e c!aracter5s 7ueue)
Interru"t !a#ts t!e e(isting ani"ation' but does not f#us! t!e c!aracter5s ani"ation 7ueue) *t
starts t!e ne(t ani"ation in t!e c!aracter5s 7ueue) o !a#t and f#us! a c!aracter5s 7ueue' use
t!e Sto" "et!od)
2ou cannot use t!is "et!od to !ave a c!aracter interrupt itse#f because t!e Microsoft Agent
server 7ueues t!e Interru"t "et!od in t!e c!aracter5s ani"ation 7ueue) !erefore' $ou can
on#$ use Interru"t to !a#t t!e ani"ation of anot!er c!aracter $ou !ave #oaded)

IAgentCharacter::MoveTo
;RESULT 8oveTo(
short G, %% G2coor*&nate o' ne0 )ocat&on
short ., %% .2coor*&nate o' ne0 )ocat&on
)ong )S#ee*, %% s#ee* to 7ove the character
)ong #*0Re4ID %% a**ress o' re4(est ID
!$
6#a$s t!e associated Moving state ani"ation and "oves t!e c!aracter fra"e to t!e specified
#ocation)
D 3eturns S@OE to indicate t!e operation &as successfu#) /!en t!e function returns' t!is
variab#e contains t!e *. of t!e re7uest)
x
!e (-coordinate of t!e ne& position in pi(e#s' re#ative to t!e screen origin (upper #eft)) !e
#ocation of a c!aracter is based on t!e upper #eft corner of its ani"ation fra"e)
y
!e $-coordinate of t!e ne& position in pi(e#s' re#ative to t!e screen origin (upper #eft)) !e
#ocation of a c!aracter is based on t!e upper #eft corner of its ani"ation fra"e)
lSpeed
A para"eter specif$ing in "i##iseconds !o& 7uic%#$ t!e c!aracter5s fra"e "oves) !e
reco""ended va#ue is 1BBB) Specif$ing >ero (B) "oves t!e fra"e &it!out p#a$ing an
ani"ation)
pdwReqID
Address of a variab#e t!at receives t!e MoveTo re7uest *.)
/!en using t!e ?6 protoco# to access c!aracter and ani"ation data' use t!e Pre"are
"et!od to ensure t!e avai#abi#it$ of t!e Moving state ani"ations before ca##ing t!is "et!od)
4ven if t!e ani"ation is not #oaded' t!e server sti## "oves t!e fra"e)
See a#so IAgentCharacter::SetPosition

IAgentCharacter::Play
;RESULT P)a.(
,STR -s1An&7at&on, %% na7e o' an an&7at&on
)ong #*0Re4ID %% a**ress o' re4(est ID
!$
6#a$s t!e specified ani"ation)
D 3eturns S@OE to indicate t!e operation &as successfu#) /!en t!e function returns'
pdwReqID contains t!e *. of t!e re7uest)
bs,ni$ation
!e na"e of an ani"ation)
pdwReqID
Address of a variab#e t!at receives t!e Play re7uest *.)
An ani"ation5s na"e is defined &!en t!e c!aracter is co"pi#ed &it! t!e Microsoft Agent
C!aracter 4ditor) :efore p#a$ing t!e specified ani"ation' t!e server atte"pts to p#a$ t!e
)eturn ani"ation for t!e previous ani"ation (if one !as been assigned))
/!en a c!aracter5s ani"ation data is stored on t!e user5s #oca# "ac!ine' $ou can use t!e Play
"et!od and specif$ t!e na"e of t!e ani"ation) /!en using t!e ?6 protoco# to access
ani"ation data' use t!e Pre"are "et!od to ensure t!e avai#abi#it$ of t!e ani"ation before
ca##ing t!is "et!od)
See a#so IAgentCharacter::Pre"are

IAgentCharacter::Pre"are
;RESULT Pre#are(
)ong *0T.#e, %% t.#e o' an&7at&on *ata to )oa*
,STR -s1Na7e, %% na7e o' the an&7at&on
)ong -6(e(e, %% 4(e(e the re4(est
)ong #*0Re4ID %% a**ress o' re4(est ID
!$
3etrieves ani"ation data for a c!aracter)
D 3eturns S@OE to indicate t!e operation &as successfu#) /!en t!e function returns'
pdwReqID contains t!e *. of t!e re7uest)
dw%ype
A va#ue t!at indicates t!e ani"ation data t$pe to #oad t!at "ust be one of t!e fo##o&ing:
const unsigned short P)1PA)1=ANIMATI,N 3 45 A c!aracter5s ani"ation data)
const unsigned short P)1PA)1=STAT1 3 65 A c!aracter5s state data)
const unsigned short P)1PA)1=/A*1 3 7 A c!aracter5s sound fi#e ()/A= or
)L/=) for spo%en output)
bs#a$e
!e na"e of t!e ani"ation or state)
!e ani"ation na"e is based on t!at defined for t!e c!aracter &!en it &as saved using
t!e Microsoft Agent C!aracter 4ditor)
1or states' t!e va#ue can be one of t!e fo##o&ing:
>-esturing? o retrieve a## -esturing state ani"ations)
>-esturing%own? o retrieve -esturing%own ani"ations)
>-esturing$eft? o retrieve -esturing$eft ani"ations)
>-esturing)ight? o retrieve -esturing)ight ani"ations)
>-esturing&"? o retrieve -esturing&" ani"ations)
>0iding? o retrieve t!e 0iding state ani"ations)
>0earing? o retrieve t!e 0earing state ani"ations)
>Idling? o retrieve a## Idling state ani"ations)
>Idling$evel6? o retrieve a## Idling$evel6 ani"ations)
>Idling$evel7? o retrieve a## Idling$evel7 ani"ations)
>Idling$evel8? o retrieve a## Idling$evel8 ani"ations)
>$istening? o retrieve t!e $istening state ani"ations)
>Moving? o retrieve a## Moving state ani"ations)
>Moving%own? o retrieve a## Moving ani"ations)
>Moving$eft? o retrieve a## Moving$eft ani"ations)
>Moving)ight? o retrieve a## Moving)ight ani"ations)
>Moving&"? o retrieve a## Moving&" ani"ations)
>Showing? o retrieve t!e Showing state ani"ations)
>S"ea'ing? o retrieve t!e S"ea'ing state ani"ations)
1or )/A= fi#es' set bs#a$e to t!e U3L or fi#e specification for t!e )/A= fi#e) *f t!e
specification is not co"p#ete' it is interpreted as being re#ative to t!e specification used in
t!e $oad "et!od)
b-ueue
A :oo#ean specif$ing &!et!er t!e server 7ueues t!e Pre"are re7uest) 3U4 7ueues t!e
re7uest and causes an$ ani"ation re7uest t!at fo##o&s it to &ait unti# t!e ani"ation data it
specifies is #oaded) 1ALS4 retrieves t!e ani"ation data as$nc!ronous#$)
pdwReqID
Address of a variab#e t!at receives t!e Pre"are re7uest *.)
2ou can specif$ "u#tip#e ani"ations and states b$ separating t!e" &it! co""as) ?o&ever'
$ou cannot "i( t$pes in t!e sa"e Pre"are state"ent)

IAgentCharacter::Set%escri"tion
;RESULT SetDescr&#t&on(
,STR -s1Descr&#t&on %% character *escr&#t&on
!$
Sets t!e description of t!e c!aracter)
D 3eturns S@OE to indicate t!e operation &as successfu#)
bsDescription
A :S3 t!at sets t!e description for t!e c!aracter) A c!aracter5s defau#t description is
defined &!en it is co"pi#ed &it! t!e Microsoft Agent C!aracter 4ditor) !e description
setting is optiona# and "a$ not be supp#ied for a## c!aracters) 2ou can c!ange t!e
c!aracter5s description using IAgentCharacter::Set%escri"tion9 !o&ever' t!is va#ue is not
persistent (stored per"anent#$)) !e c!aracter5s description reverts to its defau#t setting
&!enever t!e c!aracter is first #oaded b$ a c#ient)
See a#so IAgentCharacter::-et%escri"tion

IAgentCharacter::SetIdle,n
;RESULT SetI*)eOn(
)ong -On %% &*)e #rocess&ng ')ag
!$
Sets auto"atic id#e processing for a c!aracter)
D 3eturns S@OE to indicate t!e operation &as successfu#)
b"n
*d#e processing f#ag) *f t!is para"eter is 3U4' t!e Microsoft Agent auto"atica##$ p#a$s
Idling state ani"ations)
!e server auto"atica##$ sets a ti"e out after t!e #ast ani"ation p#a$ed for a c!aracter) /!en
t!is ti"er5s interva# is co"p#ete' t!e server begins t!e Idling states for a c!aracter' p#a$ing its
associated Idling ani"ations at regu#ar interva#s) *f $ou &ant to "anage t!e Idling state
ani"ations $ourse#f' set t!e propert$ to 1ALS4)
See a#so IAgentCharacter::-etIdle,n
IAgentCharacter::SetName
;RESULT SetNa7e(
,STR -s1Na7e %% character na7e
!$
Sets t!e na"e of t!e c!aracter)
D 3eturns S@OE to indicate t!e operation &as successfu#)
bs#a$e
A :S3 t!at sets t!e c!aracter5s na"e) A c!aracter5s defau#t na"e is defined &!en it is
co"pi#ed &it! t!e Microsoft Agent C!aracter 4ditor) 2ou can c!ange it using
IAgentCharacter::SetName9 !o&ever' t!is c!anges t!e c!aracter na"e for a## current
c#ients of t!e c!aracter) !is propert$ is not persistent (stored per"anent#$)) !e
c!aracter5s na"e reverts to its defau#t na"e &!enever t!e c!aracter is first #oaded b$ a
c#ient)
!e server uses t!e c!aracter5s na"e setting in parts of t!e Microsoft Agent5s interface'
suc! as t!e Co""ands /indo& tit#e &!en t!e c!aracter is input-active and in t!e
Microsoft Agent tas%bar pop-up "enu)
See a#so IAgentCharacter::-etName

IAgentCharacter::SetPosition
;RESULT SetPos&t&on(
)ong )Le't, %% screen coor*&nate o' the )e't e*ge o' character
)ong )To# %% screen coor*&nate o' the to# e*ge o' character
!$
Sets t!e position of t!e c!aracter5s ani"ation fra"e)
D 3eturns S@OE to indicate t!e operation &as successfu#)
lLeft
Screen coordinate of t!e c!aracter ani"ation fra"e5s #eft edge in pi(e#s' re#ative to t!e
screen origin (upper #eft))
l%op
Screen coordinate of t!e c!aracter ani"ation fra"e5s top edge in pi(e#s' re#ative to t!e
screen origin (upper #eft))
4ven t!oug! t!e c!aracter appears in an irregu#ar#$ s!aped region &indo&' t!e #ocation of t!e
c!aracter is based on its rectangu#ar ani"ation fra"e)
Note Un#i%e t!e MoveTo "et!od' t!is function is not 7ueued)
See a#so IAgent::-etPosition

IAgentCharacter::SetSi.e
;RESULT SetS&1e(
)ong )<&*th, %% 0&*th o' the character 'ra7e
)ong );e&ght %% he&ght o' the character 'ra7e
!$
Sets t!e si>e of t!e c!aracter5s ani"ation fra"e)
D 3eturns S@OE to indicate t!e operation &as successfu#)
l&idth
!e &idt! of t!e c!aracter5s ani"ation fra"e in pi(e#s)
l'ei(ht
!e !eig!t of t!e c!aracter5s ani"ation fra"e in pi(e#s)
C!anging t!e c!aracter5s fra"e si>e sca#es t!e c!aracter to t!e si>e set &it! t!is "et!od)
4ven t!oug! t!e c!aracter appears in an irregu#ar#$ s!aped region &indo&' t!e #ocation of t!e
c!aracter is based on its rectangu#ar ani"ation fra"e)
See a#so IAgentCharacter::-etSi.e

IAgentCharacter::SetSound1ffects,n
;RESULT SetSo(n*E''ectsOn(
)ong -On %% character so(n* e''ects sett&ng
!$
.eter"ines &!et!er t!e c!aracter5s sound effects are p#a$ed)
D 3eturns S@OE to indicate t!e operation &as successfu#)
b"n
Sound effects setting) *f t!is para"eter is 3U4' t!e sound effects for ani"ations are
p#a$ed &!en t!e ani"ation p#a$s9 if 1ALS4' sound effects are not p#a$ed)
!is setting deter"ines &!et!er sound effects co"pi#ed as a part of t!e c!aracter are p#a$ed
&!en $ou p#a$ an associated ani"ation) !e setting is sub+ect to t!e user5s g#oba# sound
effects setting in IAgentAudio,ut"utPro"erties::-et&singSound1ffects)
See a#so IAgentCharacter::-etSound1ffects,n'
IAgentAudio,ut"utPro"erties::-et&singSound1ffects

IAgentCharacter::Show
;RESULT Sho0(
)ong -9ast, %% #)a. Sho0&ng state an&7at&on ')ag
)ong #*0Re4ID %% a**ress o' re4(est ID
!$
.isp#a$s a c!aracter)
D 3eturns S@OE to indicate t!e operation &as successfu#) /!en t!e function returns'
pdwReqID contains t!e *. of t!e re7uest)
b+ast
S!o&ing state ani"ation f#ag) *f t!is para"eter is 3U4' t!e Showing state ani"ation
p#a$s after "a%ing t!e c!aracter visib#e9 if 1ALS4' t!e ani"ation does not p#a$)
pdwReqID
Address of a variab#e t!at receives t!e Show re7uest *.)
Avoid setting t!e b+ast para"eter to 3U4 &it!out p#a$ing an ani"ation before!and'
ot!er&ise' t!e c!aracter fra"e "a$ be disp#a$ed' but !ave no i"age to disp#a$) *n particu#ar'
note t!at t!at if $ou ca## MoveTo &!en t!e c!aracter is not visib#e' it does not p#a$ an$
ani"ation) !erefore' if $ou ca## t!e Show "et!od &it! b+ast set to 3U4' no i"age &i## be
disp#a$ed) Si"i#ar#$' if $ou ca## 0ide t!en Show &it! b+ast set to 3U4' t!ere &i## be no visib#e
i"age)
/!en using t!e ?6 protoco# to access c!aracter and ani"ation data' use t!e Pre"are
"et!od to ensure t!e avai#abi#it$ of t!e Showing state ani"ation before ca##ing t!is "et!od)
See a#so IAgentCharacter::0ide

IAgentCharacter::S"ea'
;RESULT S#ea/(
,STR -s1TeGt, %% teGt to s#ea/
,STR -s1URL, %% URL o' a '&)e to s#ea/
)ong #*0Re4ID %% a**ress o' a re4(est ID
!$
Spea%s t!e
D 3eturns S@OE to indicate t!e operation &as successfu#)
bs%ext
!e te(t t!e c!aracter is to spea%)
bsURL
!e U3L (or fi#e specification) of a sound fi#e to use for spo%en output) !is can be a
standard sound fi#e ()/A=) or #inguistica##$ en!anced sound fi#e ()L/=))
pdwReqID
Address of a variab#e t!at receives t!e S"ea' re7uest *.)
o use t!is "et!od &it! a c!aracter configured to spea% using a te(t-to-speec! (S) engine9
si"p#$ provide t!e bs%ext para"eter) 2ou can inc#ude vertica# bar c!aracters (G) in t!e bs%ext
para"eter to designate a#ternative strings' so t!at eac! ti"e t!e server processes t!e "et!od'
it rando"#$ c!oose a different string) Support of S output is defined &!en t!e c!aracter is
co"pi#ed using t!e Microsoft Agent C!aracter 4ditor)
*f $ou &ant to use sound fi#e output for t!e c!aracter' specif$ t!e #ocation for t!e fi#e in t!e
bsURL para"eter) /!en using t!e ?6 protoco# to do&n#oad a sound fi#e' use t!e Pre"are
"et!od to ensure t!e avai#abi#it$ of t!e fi#e before using t!is "et!od) 2ou can use t!e bs%ext
para"eter to specif$ t!e &ords t!at appear in t!e c!aracter5s &ord ba##oon) *f $ou specif$ a
#inguistica##$ en!anced sound fi#e ()L/=) for t!e bsURL para"eter and do not specif$ te(t'
t!e bs%ext para"eter uses t!e te(t stored in t!e fi#e)
!e S"ea' "et!od uses t!e #ast ani"ation p#a$ed to deter"ine &!ic! spea%ing ani"ation to
p#a$) 1or e(a"p#e' if $ou precede t!e S"ea' co""and &it! a Play H-esture)ightI' t!e server
&i## p#a$ -esture)ight and t!en t!e -esture)ight spea%ing ani"ation)
*f $ou ca## S"ea' and t!e audio c!anne# is bus$' t!e c!aracter5s audio output &i## not be !eard'
but t!e te(t &i## disp#a$ in t!e &ord ba##oon) !e &ord ba##oon5s 1na+led propert$ "ust a#so be
3U4 for t!e te(t to disp#a$)
See a#so IAgentCharacter::Play' IAgent@alloon::1na+led' IAgentCharacter::Pre"are

IAgentCharacter::Sto"
;RESULT Sto#(
)ong *0Re4ID %% re4(est ID
!$
Stops t!e specified ani"ation (re7uest) and re"oves it fro" t!e c!aracter5s ani"ation 7ueue)
D 3eturns S@OE to indicate t!e operation &as successfu#)
dwReqID
!e *. of t!e re7uest to stop)
Sto" can a#so be used to !a#t an$ 7ueued Pre"are ca##s)
See a#so IAgentCharacter::Pre"are' IAgentCharacter::Sto"All

IAgentCharacter::Sto"All
;RESULT Sto#A))(!$
)ong )T.#e, %% re4(est t.#e
Stops a## ani"ations (re7uests) and re"oves t!e" fro" t!e c!aracter5s ani"ation 7ueue)
l%ype
A bit fie#d t!at indicates t!e t$pes of re7uests to stop (and re"ove fro" t!e c!aracter5s
7ueue)' co"prised fro" t!e fo##o&ing:

const unsigned long ST,P=T!P1=A$$ 3 425 Stops a## ani"ation
re7uests' inc#uding
non-7ueued Pre"are
re7uests)
const unsigned long ST,P=T!P1=P$A! 3 42444444465 Stops a## Play
re7uests)
const unsigned long ST,P=T!P1=M,*1 3 42444444475 Stops a## Move
re7uests)
const unsigned long ST,P=T!P1=SP1AA 3 42444444495 Stops a## S"ea'
re7uests)
const unsigned long ST,P=T!P1=P)1PA)1 3 424444444B5 Stops a## 7ueued
Pre"are re7uests)
const unsigned long ST,P=T!P1=N,N#&1&1%P)1PA)1 3 42444444645 Stops a## non-
7ueued Pre"are
re7uests)
const unsigned long ST,P=T!P1=*ISI@$1 3 42444444745 Stops a## 0ide or
Show re7uests)
See a#so IAgentCharacter::Sto"

IAgentCharacter::/ait
;RESULT <a&t(
)ong *0Re4ID, %% re4(est ID
)ong #*0Re4ID %% a**ress o' re4(est ID
!$
?o#ds t!e c!aracter5s ani"ation 7ueue at t!e specified ani"ation (re7uest) unti# anot!er
re7uest for anot!er c!aracter co"p#etes)
D 3eturns S@OE to indicate t!e operation &as successfu#)
dwReqID
!e *. of t!e re7uest to &ait for)
pdwReqID
Address of a variab#e t!at receives t!e /ait re7uest *.)
Use t!is "et!od on#$ &!en $ou support "u#tip#e (si"u#taneous) c!aracters and &ant to
se7uence t!eir interaction (as a sing#e c#ient)) (1or a sing#e c!aracter' eac! ani"ation re7uest
is p#a$ed se7uentia##$--after t!e previous re7uest co"p#etes)) *f $ou !ave t&o c!aracters and
&ant one c!aracter5s ani"ation re7uest to &ait unti# t!e ot!er c!aracter5s ani"ation co"p#etes'
set t!e /ait "et!od to t!e ot!er c!aracter5s ani"ation re7uest *.)
IAgentCommands
!e Microsoft Agent server "aintains a #ist of co""ands t!at are current#$ avai#ab#e to t!e
user) !is #ist inc#udes co""ands t!at t!e server defines for genera# interaction' suc! as ?ide
and Microsoft Agent 6roperties' t!e #ist of avai#ab#e (but non-input-active) c#ients' and t!e
co""ands defined b$ t!e current active c#ient) !e first t&o sets of co""ands are g#oba#
co""ands9 t!at is' t!e$ are avai#ab#e at an$ ti"e' regard#ess of t!e input-active c#ient) C#ient-
defined co""ands are avai#ab#e on#$ &!en t!at c#ient is input-active)
3etrieve an IAgentCommands interface b$ 7uer$ing t!e IAgentCharacter interface for
IAgentCommands) 4ac! Microsoft Agent c#ient app#ication can define a co##ection of
co""ands ca##ed a Commands co##ection) o add a Command to t!e co##ection' use t!e Add
or Insert "et!od) A#t!oug! $ou can specif$ a CommandCs properties using IAgentCommand
"et!ods' for opti"u" code perfor"ance' specif$ a## of a Command5s properties in t!e
IAgentCommands::Add or IAgentCommands::Insert "et!ods &!en initia##$ setting t!e
properties for a ne& Command) 2ou can use t!e IAgentCommand "et!ods to 7uer$ or
c!ange t!e propert$ settings)
1or eac! Command in t!e Commands co##ection' $ou can deter"ine &!et!er t!e co""and
appears on t!e c!aracter5s pop-up "enu' in t!e Co""ands /indo&' in bot!' or in neit!er) 1or
e(a"p#e' if $ou &ant a co""and to appear on t!e pop-up "enu for t!e c!aracter' set t!e
co""and5s Ca"tion and *isi+le properties) o disp#a$ t!e co""and in t!e Commands
/indo&' set t!e co""and5s Ca"tion and *oice properties)
A user can access t!e individua# co""ands in $our Co""ands co##ection on#$ &!en $our
c#ient app#ication is input-active) !erefore' $ou &i## t$pica##$ &ant to set t!e Ca"tion and
*oice properties for t!e Commands co##ection ob+ect as &e## as for t!e co""ands in t!e
co##ection' because t!is p#aces an entr$ for $our Commands co##ection on a c!aracter5s pop-up
"enu and in t!e Co""ands /indo&) /!en t!e user s&itc!es to $our c#ient b$ c!oosing its
entr$' t!e server auto"atica##$ "a%es $our c#ient input-active and "a%es t!e Commands in its
co##ection avai#ab#e) !is enab#es t!e server to present and accept on#$ t!e Commands t!at
app#$ to t!e current input-active c#ient5s conte(t) *t a#so serves to avoid Command-na"e
co##isions bet&een c#ients)
/!en a c!aracter5s pop-up "enu is disp#a$ed' c!anges to t!e properties of a Commands
co##ection or t!e co""ands in its co##ection do not appear unti# t!e user redisp#a$s t!e "enu)
?o&ever' &!en open' t!e Co""ands /indo& does disp#a$ c!anges as t!e$ !appen)
IAgentCommands defines an interface t!at a##o&s app#ications to add' re"ove' set' and 7uer$
properties for a Commands co##ection) A Commands co##ection can appear as a co""and in
bot! t!e pop-up "enu and t!e Co""ands /indo& for a c!aracter) o "a%e t!e Commands
co##ection appear' $ou "ust set its Ca"tion propert$) !e fo##o&ing tab#e su""ari>es !o& t!e
properties of a Commands co##ection affect its presentation)
Ca"tion
Pro"erty
*oice
Pro"erty
*isi+le
Pro"erty
A""ears in
CharacterCs Po"D
u" Menu
A""ears in
Commands /indow
2es 2es rue 2es 2es
2es 2es 1a#se ,o 2es
2es ,o rue 2es ,o
2es ,o 1a#se ,o ,o
,o 2es rue ,o ,o
J
,o 2es 1a#se ,o ,o
J
,o ,o rue ,o ,o
,o ,o 1a#se ,o ,o
J
!e co""and is sti## voice-accessib#e) *f t!e c#ient is input-active and !as Commands in its
co##ection' H(co""and undefined)I appears in t!e Co""ands /indo&)
Methods in *ta+le ,rder
IAgentCommands Methods .escription
-etCommand 3etrieves a Command ob+ect fro" t!e Commands co##ection)
-etCount 3eturns t!e va#ue of t!e nu"ber of Commands in a Commands
co##ection)
IAgentCommands Methods .escription
SetCa"tion Sets t!e va#ue of t!e Ca"tion propert$ for a Commands co##ection)
-etCa"tion 3eturns t!e va#ue of t!e Ca"tion propert$ of a Commands co##ection)
Set*oice Sets t!e va#ue of t!e *oice propert$ for a Commands co##ection)
-et*oice 3eturns t!e va#ue of t!e *oice propert$ of a Commands co##ection)
Set*isi+le Sets t!e va#ue of t!e *isi+le propert$ for a Commands co##ection)
-et*isi+le 3eturns t!e va#ue of t!e *isi+le propert$ of a Commands co##ection)
Add Adds a Command ob+ect to a Commands co##ection)
Insert *nserts a Command ob+ect in a Commands co##ection)
)emove 3e"oves a Command ob+ect in a Commands co##ection)
)emoveAll 3e"oves a## Command ob+ects fro" a Commands co##ection)
IAgentCommands::Add
;RESULT A**(
,STR -s1Ca#t&on, %% Ca#t&on sett&ng 'or Co77an*
,STR -s1Vo&ce, %% Vo&ce sett&ng 'or Co77an*
)ong -Ena-)e*, %% Ena-)e* sett&ng 'or Co77an*
)ong -V&s&-)e, %% V&s&-)e sett&ng 'or Co77an*
)ong #*0ID %% a**ress 'or var&a-)e 'or ID
!$
Adds a Command to a Commands co##ection)
D 3eturns S@OE to indicate t!e operation &as successfu#)
bsCaption
A :S3 t!at specifies t!e va#ue of t!e Ca"tion te(t disp#a$ed for a Command in a
Commands co##ection)
bs*oice
A :S3 t!at specifies t!e va#ue of t!e *oice te(t setting for a Command in a Commands
co##ection)
b!nabled
A :oo#ean e(pression t!at specifies t!e 1na+led setting for a Command in a Commands
co##ection) *f t!e para"eter is 3U4' t!e Command is enab#ed and can be se#ected9 if
1ALS4' t!e Command is disab#ed)
b*isible
A :oo#ean e(pression t!at specifies t!e *isi+le setting for a Command in a Commands
co##ection) *f t!e para"eter is 3U4' t!e Command &i## be visib#e in t!e c!aracter5s pop-
up "enu (if t!e Ca"tion propert$ is a#so set))
pdwID
Address of a variab#e t!at receives t!e *. for t!e added Command)
See a#so IAgentCommand::SetCa"tion' IAgentCommand::Set1na+led'
IAgentCommand::Set*isi+le' IAgentCommand::Set*oice' IAgentCommands::Insert'
IAgentCommands::)emove' IAgentCommands::)emoveAll

IAgentCommands::-etCa"tion
;RESULT 5etCa#t&on(
,STR #-s1Ca#t&on %% a**ress o' Ca#t&on teGt 'or Co77an*s co))ect&on
!$
3etrieves t!e Ca"tion for a Commands co##ection)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pbsCaption
!e address of a :S3 t!at receives t!e va#ue of t!e Ca"tion te(t setting disp#a$ed for a
Commands co##ection)
See a#so IAgentCommands::SetCa"tion' IAgentCommands::-et*isi+le'
IAgentCommands::-et*oice

IAgentCommands::-etCommand
;RESULT 5etCo77an*(
)ong *0Co77an*ID, %% Co77an* ID
IUn/no0n ##(n/Co77an* %% a**ress o' IUn/no0n &nter'ace
!$
3etrieves a Command ob+ect fro" t!e Commands co##ection)
D 3eturns S@OE to indicate t!e operation &as successfu#)
dwCo$$andID
!e *. of a Co""and ob+ect in t!e Commands co##ection)
IUnknown
!e address of t!e I&n'nown interface for t!e Command ob+ect)
See a#so IAgentCommand

IAgentCommands::-etCount
;RESULT 5etCo(nt(
)ong #*0Co(nt %% a**ress o' co(nt o' co77an*s
!$
3etrieves t!e nu"ber of Command ob+ects in a Commands co##ection)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pdwCount
Address of a variab#e t!at receives t!e nu"ber of Commands in a Commands co##ection)
pdwCount inc#udes on#$ t!e nu"ber of Commands $ou define in $our Commands co##ection)
Server or ot!er c#ient entries are not inc#uded)

IAgentCommands::-et*isi+le
;RESULT 5etV&s&-)e(
)ong #-V&s&-)e %% a**ress o' V&s&-)e sett&ng 'or Co77an*s co))ect&on
!$
3etrieves t!e va#ue of t!e *isi+le propert$ for a Commands co##ection)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pb*isible
!e address of a variab#e t!at receives t!e va#ue of t!e *isi+le propert$ for a Commands
co##ection)
See a#so IAgentCommands::Set*isi+le' IAgentCommands::SetCa"tion

IAgentCommands::-et*oice
;RESULT 5etVo&ce(
,STR #-s1Vo&ce %% a**ress o' Vo&ce sett&ng 'or Co77an*s co))ect&on
!$
3etrieves t!e va#ue of t!e *oice propert$ for a Commands co##ection)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pbs*oice
!e address of a :S3 t!at receives t!e va#ue of t!e *oice te(t setting for a Commands
co##ection)
See a#so IAgentCommands::Set*oice' IAgentCommands::-etCa"tion'
IAgentCommands::-et*isi+le

IAgentCommands::Insert
;RESULT Insert(
,STR -s1Ca#t&on, %% Ca#t&on sett&ng 'or Co77an*
,STR -s1Vo&ce, %% Vo&ce sett&ng 'or Co77an*
)ong -Ena-)e*, %% Ena-)e* sett&ng 'or Co77an*
)ong -V&s&-)e, %% V&s&-)e sett&ng 'or Co77an*
)ong *0Re'ID, %% re'erence Co77an* 'or &nsert&on
)ong *,e'ore, %% &nsert&on #os&t&on ')ag
)ong #*0ID %% a**ress 'or var&a-)e 'or Co77an* ID
!$
*nserts a Command ob+ect in a Commands co##ection)
D 3eturns S@OE to indicate t!e operation &as successfu#)
bsCaption
A :S3 t!at specifies t!e va#ue of t!e Ca"tion te(t disp#a$ed for t!e Command)
bs*oice
A :S3 t!at specifies t!e va#ue of t!e *oice te(t setting for a Command)
b!nabled
A :oo#ean e(pression t!at specifies t!e 1na+led setting for a Command) *f t!e para"eter
is 3U4' t!e Command is enab#ed and can be se#ected9 if 1ALS4' t!e Command is
disab#ed)
b*isible
A :oo#ean e(pression t!at specifies t!e *isi+le setting for a Command) *f t!e para"eter
is 3U4' t!e Command &i## be visib#e in t!e c!aracter5s pop-up "enu (if t!e Ca"tion
propert$ is a#so set))
dwRefID
!e *. of a Command used as a reference for t!e re#ative insertion of t!e ne&
Command)
d.efore
A :oo#ean e(pression t!at specifies &!ere to p#ace t!e Command) *f t!is para"eter is
3U4' t!e ne& Command is inserted before t!e referenced Command9 if 1ALS4' t!e
ne& Command is p#aced after t!e referenced Command)
pdwID
Address of a variab#e t!at receives t!e *. for t!e inserted Command)
See a#so IAgentCommand::Add' IAgentCommands::)emove'
IAgentCommands::)emoveAll

IAgentCommands::)emove
;RESULT Re7ove(
)ong *0ID %% Co77an* ID
!$
3e"oves t!e specified Command fro" a Commands co##ection)
D 3eturns S@OE to indicate t!e operation &as successfu#)
dwID
!e *. of a Command to re"ove fro" t!e Commands co##ection)
3e"oving a Command fro" a Commands co##ection a#so re"oves it fro" t!e pop-up "enu
and t!e Co""ands /indo& &!en $our app#ication is input-active)
See a#so IAgentCommands::Add' IAgentCommands::Insert'
IAgentCommands::)emoveAll

IAgentCommands::)emoveAll
;RESULT Re7ove(!$
3e"oves a## Commands fro" a Commands co##ection)
D 3eturns S@OE to indicate t!e operation &as successfu#)
3e"oving a## Commands fro" a Commands co##ection a#so re"oves t!e" fro" t!e pop-up
"enu and t!e Co""ands /indo& &!en $our app#ication is input-active) )emoveAll does not
re"ove server or ot!er c#ient<s entries)
See a#so IAgentCommands::Add' IAgentCommands::Insert' IAgentCommands::)emove

IAgentCommands::SetCa"tion
;RESULT SetCa#t&on(
,STR -s1Ca#t&on %% Ca#t&on sett&ng 'or Co77an*s co))ect&on
!$
Sets t!e Ca"tion te(t disp#a$ed for a Commands co##ection)
D 3eturns S@OE to indicate t!e operation &as successfu#)
bsCaption
A :S3 t!at specifies t!e va#ue for t!e Ca"tion propert$ for a Commands co##ection)
A Commands co##ection &it! its Ca"tion propert$ set and its *isi+le propert$ set to 3U4
appears in t!e c!aracter5s pop-up "enu) *f its *oice propert$ is a#so set' it appears in t!e
Co""ands /indo&) *f $ou define co""ands for a Commands co##ection t!at !ave t!eir
Ca"tion' 1na+led' and *oice properties set' $ou t$pica##$ a#so define Ca"tion and *oice
settings for t!e associated Commands co##ection) *f t!e Commands co##ection !as no *oice
or no Ca"tion setting and is current#$ input-active' but t!e Commands in its co##ection !ave
Ca"tion and *oice settings' t!e Commands appear in t!e Commands /indo& tree vie&
under H(undefined co""and)I &!en $our c#ient app#ication beco"es input-active)
See a#so IAgentCommands::-etCa"tion' IAgentCommands::Set*isi+le'
IAgentCommands::Set*oice

IAgentCommands::Set*isi+le
;RESULT SetV&s&-)e(
)ong -V&s&-)e %% the V&s&-)e sett&ng 'or Co77an*s co))ect&on
!$
Sets t!e va#ue of t!e *isi+le propert$ for a Commands co##ection)
D 3eturns S@OE to indicate t!e operation &as successfu#)
b*isible
A :oo#ean va#ue t!at deter"ines t!e *isi+le propert$ of a Commands co##ection) 3U4
sets t!e Commands co##ection5s Ca"tion to be visib#e &!en t!e c!aracter5s pop-up "enu
is disp#a$ed9 1ALS4 does not disp#a$ it)
A Commands co##ection "ust !ave its Ca"tion propert$ set and its *isi+le propert$ set to
3U4 to appear on t!e c!aracter5s pop-up "enu) !e *isi+le propert$ "ust a#so be set to
3U4 for co""ands in t!e co##ection to appear &!en $our c#ient app#ication is input-active)
See a#so IAgentCommands::-et*isi+le' IAgent::SetCa"tion

IAgentCommands::Set*oice
;RESULT SetVo&ce(
,STR -s1Vo&ce %% the Vo&ce sett&ng 'or Co77an* co))ect&on
!$
Sets t!e *oice te(t propert$ for a Command)
D 3eturns S@OE to indicate t!e operation &as successfu#)
bs*oice
A :S3 t!at specifies t!e va#ue for t!e *oice te(t propert$ of a Commands co##ection)
A Commands co##ection "ust !ave its *oice te(t propert$ set to be voice-accessib#e) *t a#so
"ust !ave its Ca"tion propert$ set to appear in t!e Co""ands /indo& and its *isi+le
propert$ set to 3U4 to appear on t!e c!aracter5s pop-up "enu)
!e :S3 e(pression $ou supp#$ can inc#ude s7uare brac%et c!aracters (K L) to indicate
optiona# &ords and vertica# bar c!aracters (G) to indicate a#ternative strings) A#ternates "ust be
enc#osed in parent!eses) 1or e(a"p#e' H(!e##o Kt!ereL G !i)I te##s t!e speec! engine to accept
H!e##o'I H!e##o t!ere'I or H!iI for t!e co""and) 3e"e"ber to inc#ude appropriate spaces
bet&een &ords $ou inc#ude in brac%ets or parent!eses as &e## as ot!er te(t) 3e"e"ber to
inc#ude appropriate spaces bet&een t!e te(t t!at<s in brac%ets or parent!eses and t!e te(t
t!at<s not in brac%ets or parent!eses)
2ou can a#so use an e##ipsis (M) to support word spottin(' t!at is' te##ing t!e speec! recognition
engine to ignore &ords spo%en in t!is position in t!e p!rase (so"eti"es ca##ed (arba(e &ords))
/!en $ou use e##ipses' t!e speec! engine recogni>es on#$ specific &ords in t!e string
regard#ess of &!en spo%en &it! ad+acent &ords or p!rases) 1or e(a"p#e' if $ou set t!is
propert$ to HMc!ec% "ai#MI t!e speec! recognition engine &i## "atc! p!rases #i%e Hp#ease
c!ec% "ai#I or Hc!ec% "ai# p#easeI to t!is co""and) 4##ipses can be used an$&!ere &it!in a
string) ?o&ever' be carefu# using t!is tec!ni7ue as voice settings &it! e##ipses "a$ increase
t!e potentia# of un&anted "atc!es)
/!en defining t!e &ords and gra""ar for $our co""and' a#&a$s "a%e sure t!at $ou inc#ude
at #east one &ord t!at is re7uired9 t!at is' avoid supp#$ing on#$ optiona# &ords) *n addition'
"a%e sure t!at t!e &ord inc#udes on#$ pronounceab#e &ords and #etters) 1or nu"bers' it is
better to spe## out t!e &ord rat!er t!an using t!e nu"eric representation) A#so' o"it an$
punctuation or s$"bo#s) 1or e(a"p#e' instead of Ht!e N1 O1B pi>>aPI' use Ht!e nu"ber one ten
do##ar pi>>aI) *nc#uding non-pronounceab#e c!aracters or s$"bo#s for one co""and "a$
cause t!e speec! engine to fai# to co"pi#e t!e gra""ar for a## $our co""ands) 1ina##$' "a%e
$our voice para"eter as distinct as reasonab#$ possib#e fro" ot!er voice co""ands $ou
define) !e greater t!e si"i#arit$ bet&een t!e voice gra""ar for co""ands' t!e "ore #i%e#$
t!e speec! engine &i## "a%e a recognition error) 2ou can a#so use t!e confidence scores to
better distinguis! bet&een t&o co""ands t!at "a$ !ave si"i#ar or si"i#ar-sounding voice
gra""ar)
!e operation of t!is propert$ depends on t!e state of Microsoft Agent server5s speec!
recognition state) 1or e(a"p#e' if speec! recognition is disab#ed or not insta##ed' t!is function
!as no i""ediate effect) *f speec! recognition is enab#ed during a session' !o&ever' t!e
co""and &i## beco"e accessib#e &!en its c#ient app#ication is input-active)
See a#so IAgentCommands::-et*oice' IAgentCommands::SetCa"tion'
IAgentCommands::Set*isi+le
IAgentCommand
A Command ob+ect is an ite" in a Commands co##ection) !e server provides t!e user
access to $our co""ands $our c#ient app#ication beco"es input active) o retrieve a
Command' ca## IAgentCommands::-etCommand)
IAgentCommand defines an interface t!at a##o&s app#ications to set and 7uer$ properties for
Command ob+ects t!at can appear in a c!aracter5s pop-up "enu and in t!e Co""ands
/indo&) A Command ob+ect is an ite" in a Commands co##ection) !e server provides t!e
user access to $our co""ands &!en $our c#ient app#ication beco"es input active)
A Command "a$ appear in eit!er or bot! t!e c!aracter<s pop-up "enu and t!e Co""ands
/indo&) o appear in t!e pop-up "enu' it "ust !ave a Ca"tion and !ave t!e *isi+le propert$
set to 3U4) !e *isi+le propert$ for its Commands co##ection ob+ect "ust a#so be set to
3U4 for t!e co""and to appear in t!e pop-up "enu &!en $our c#ient app#ication is input-
active) o appear in t!e Co""ands /indo&' a Command "ust !ave its Ca"tion and *oice
properties set)
A c!aracter5s pop-up "enu entries do not c!ange &!i#e t!e "enu is disp#a$ed) *f $ou add or
re"ove Co""ands or c!ange t!eir properties &!i#e t!e c!aracter5s popup "enu is disp#a$ed'
t!e "enu disp#a$s t!ose c!anges &!en redisp#a$ed) ?o&ever' t!e Co""ands /indo& does
disp#a$ c!anges as $ou "a%e t!e")
!e fo##o&ing tab#e su""ari>es !o& t!e properties of a co""and affect its presentation)
Ca"tion
Pro"erty
*oice
Pro"erty
*isi+le
Pro"erty
1na+led
Pro"erty
A""ears in
CharacterCs
Po"Du" Menu
A""ears in
Commands
/indow
2es 2es rue rue ,or"a# 2es
2es 2es rue 1a#se .isab#ed ,o
2es 2es 1a#se rue .oes not appear 2es
2es 2es 1a#se 1a#se .oes not appear ,o
2es ,o rue rue ,or"a# ,o
2es ,o rue 1a#se .isab#ed ,o
2es ,o 1a#se rue .oes not appear ,o
2es ,o 1a#se 1a#se .oes not appear ,o
,o 2es rue rue .oes not appear ,o
J
,o 2es rue 1a#se .oes not appear ,o
,o 2es 1a#se rue .oes not appear ,o
J
,o 2es 1a#se 1a#se .oes not appear ,o
,o ,o rue rue .oes not appear ,o
,o ,o rue 1a#se .oes not appear ,o
,o ,o 1a#se rue .oes not appear ,o
,o ,o 1a#se 1a#se .oes not appear ,o
J
!e co""and is sti## voice-accessib#e)
Aenera##$' if $ou define a Command &it! a *oice setting' $ou a#so define Ca"tion and *oice
settings for its associated Commands co##ection) *f t!e Commands co##ection for a set of
co""ands !as no *oice or no Ca"tion setting and is current#$ input-active' but t!e
Commands !ave Ca"tion and *oice settings' t!e Commands appear in t!e Co""ands
/indo& tree vie& under H(undefined co""and)I &!en $our c#ient app#ication beco"es input-
active)
/!en t!e server receives input t!at "atc!es one of t!e Command ob+ects $ou defined for
$our Commands co##ection' it sends a IAgentNotifySin'::Command event' and passes bac%
t!e *. of t!e co""and as an attribute of t!e IAgent&serIn"ut ob+ect) 2ou can t!en use
conditiona# state"ents to "atc! and process t!e co""and)
Methods in *ta+le ,rder
IAgentCommand Methods %escri"tion
SetCa"tion Sets t!e va#ue for t!e Ca"tion for a Command ob+ect)
-etCa"tion 3eturns t!e va#ue of t!e Ca"tion propert$ of a Command ob+ect)
Set*oice Sets t!e va#ue for t!e *oice te(t for a Command ob+ect)
-et*oice 3eturns t!e va#ue of t!e Ca"tion propert$ of a Command ob+ect)
Set1na+led Sets t!e va#ue of t!e 1na+led propert$ for a Command ob+ect)
-et1na+led 3eturns t!e va#ue of t!e 1na+led propert$ of a Command ob+ect)
Set*isi+le Sets t!e va#ue of t!e *isi+le propert$ for a Command ob+ect)
IAgentCommand Methods %escri"tion
-et*isi+le 3eturns t!e va#ue of t!e *isi+le propert$ of a Command ob+ect)
SetConfidenceThreshold Sets t!e va#ue of t!e Confidence propert$ for a Command ob+ect)
-etConfidenceThreshold 3eturns t!e va#ue of t!e Confidence propert$ of a Command ob+ect)
SetConfidenceTe2t Sets t!e va#ue of t!e ConfidenceTe2t propert$ for a Command ob+ect)
-etConfidenceTe2t 3eturns t!e va#ue of t!e ConfidenceTe2t propert$ of a Command ob+ect)
-etI% 3eturns t!e *. of a Command ob+ect)
IAgentCommand::-etCa"tion
;RESULT 5etCa#t&on(
,STR #-s1Ca#t&on %% a**ress o' Ca#t&on 'or Co77an*
!$
3etrieves t!e Ca"tion for a Command)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pbsCaption
!e address of a :S3 t!at receives t!e va#ue of t!e Ca"tion te(t disp#a$ed for a
Command)
See a#so IAgentCommand::SetCa"tion' IAgentCommand::Set1na+led'
IAgentCommand::Set*isi+le' IAgentCommand::Set*oice' IAgentCommands::Add'
IAgentCommands::Insert

IAgentCommand::-etConfidenceTe2t
;RESULT 5etCon'&*enceTeGt(
,STR #-s1T&#TeGt %% a**ress o' Con'&*enceTeGt sett&ng 'or Co77an*
!$
3etrieves t!e Listening ip te(t previous#$ set for a Command)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pbs%ip%ext
!e address of a :S3 t!at receives t!e va#ue of t!e Listening ip te(t for a Command)
See a#so IAgentCommand::SetConfidenceThreshold'
IAgentCommand::-etConfidenceThreshold' IAgentCommand::SetConfidenceTe2t'
IAgent&serIn"ut::-etItemConfidence

IAgentCommand::-etConfidenceThreshold
;RESULT 5etCon'&*enceThresho)*(
)ong #)Con'&*enceThresho)* %% a**ress o' Con'&*enceThresho)*
!$ %% sett&ng 'or Co77an*
3etrieves t!e va#ue of t!e ConfidenceThreshold propert$ for a Command)
D 3eturns S@OE to indicate t!e operation &as successfu#)
plConfidence%hreshold
!e address of a variab#e t!at receives t!e va#ue of t!e ConfidenceThreshold propert$
for a Co""and)
See a#so IAgentCommand::SetConfidenceThreshold'
IAgentCommand::SetConfidenceTe2t' IAgent&serIn"ut::-etItemConfidence

IAgentCommand::-et1na+led
;RESULT 5etEna-)e*(
)ong #-Ena-)e* %% a**ress o' Ena-)e* sett&ng 'or Co77an*
!$
3etrieves t!e va#ue of t!e 1na+led propert$ for a Command)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pb!nabled
!e address of a variab#e t!at receives 3U4 if t!e Command is enab#ed' or 1ALS4 if it
is disab#ed) A disab#ed Command cannot be se#ected)
See a#so IAgentCommand::SetCa"tion' IAgent::Set*isi+le' IAgentCommand::Set*oice'
IAgentCommands::Add' IAgentCommands::Insert

IAgentCommand::-etI%
;RESULT 5etID(
)ong #*0ID %% a**ress o' ID 'or Co77an*
!$
3etrieves t!e *. for a Command)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pdwID
!e address of a variab#e t!at receives t!e *. of a Command)
See a#so IAgentCommands::Add' IAgentCommands::Insert' IAgentCommands::)emove

IAgentCommand::-et*isi+le
;RESULT 5etV&s&-)e(
)ong #-V&s&-)e %% a**ress o' V&s&-)e sett&ng 'or Co77an*
!$
3etrieves t!e va#ue of t!e *isi+le propert$ for a Command)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pb*isible
!e address of a variab#e t!at receives t!e *isi+le propert$ for a Command)
See a#so IAgentCommand::Set*isi+le' IAgent::SetCa"tion' IAgentCommands::Add'
IAgentCommands::Insert

IAgentCommand::-et*oice
;RESULT 5etVo&ce(
,STR #-s1Vo&ce %% a**ress o' Vo&ce sett&ng 'or Co77an*
!$
3etrieves t!e va#ue of t!e *oice te(t propert$ for a Command)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pbs*oice
!e address of a :S3 t!at receives t!e *oice te(t propert$ for a Command)
A Command &it! its *oice propert$ set and its 1na+led propert$ set to 3U4 &i## be voice-
accessib#e) *f its Ca"tion propert$ is a#so set it appears in t!e Co""ands /indo&) *f its
*isi+le propert$ is set to 3U4' it appears in t!e c!aracter5s pop-up "enu)
See a#so IAgentCommand::Set*oice' IAgentCommands::Add' IAgentCommands::Insert

IAgentCommand::SetCa"tion
;RESULT SetCa#t&on(
,STR -s1Ca#t&on %% Ca#t&on sett&ng 'or Co77an*
!$
Sets t!e Ca"tion te(t disp#a$ed for a Command)
D 3eturns S@OE to indicate t!e operation &as successfu#)
bsCaption
A :S3 t!at specifies t!e te(t for t!e Ca"tion propert$ for a Command)
A Command &it! its Ca"tion propert$ set and its *isi+le propert$ set to 3U4 appears in t!e
c!aracter5s pop-up "enu) *f its *oice propert$ is a#so set' it appears in t!e Co""ands
/indo&) o "a%e it accessib#e' $ou "ust a#so set its 1na+led propert$ to 3U4)
See a#so IAgentCommand::-etCa"tion' IAgentCommand::Set1na+led'
IAgentCommand::Set*isi+le' IAgentCommand::Set*oice' IAgentCommands::Add'
IAgentCommands::Insert

IAgentCommand::SetConfidenceThreshold
;RESULT SetCon'&*enceThresho)*(
)ong )Con'&*ence %% Con'&*ence sett&ng 'or Co77an*
!$
Sets t!e va#ue of t!e Confidence propert$ for a Command)
D 3eturns S@OE to indicate t!e operation &as successfu#)
lConfidence
!e va#ue for t!e Confidence propert$ of a Command)
*f t!e confidence va#ue returned of t!e best "atc! returned in t!e Command event does not
e(ceed t!e va#ue set for t!e ConfidenceThreshold propert$' t!e te(t supp#ied in
SetConfidenceTe2t is disp#a$ed in t!e Listening ip)
See a#so IAgentCommand::-etConfidenceThreshold'
IAgentCommand::SetConfidenceTe2t' IAgent&serIn"ut::-etItemConfidence

IAgentCommand::SetConfidenceTe2t
;RESULT SetCon'&*enceTeGt(
,STR -s1T&#TeGt %% Con'&*enceTeGt sett&ng 'or Co77an*
!$
Sets t!e va#ue of t!e Listening ip te(t for a Command)
D 3eturns S@OE to indicate t!e operation &as successfu#)
bs%ip%ext
A :S3 t!at specifies t!e te(t for t!e ConfidenceTe2t propert$ of a Command)
*f t!e confidence va#ue returned of t!e best "atc! returned in t!e Command event does not
e(ceed t!e va#ue set for t!e ConfidenceThreshold propert$' t!e te(t supp#ied in bs%ip%ext is
disp#a$ed in t!e Listening ip)
See a#so IAgentCommand::SetConfidenceThreshold'
IAgentCommand::-etConfidenceThreshold' IAgentCommand::-etConfidenceTe2t'
IAgent&serIn"ut::-etItemConfidence

IAgentCommand::Set1na+led
;RESULT SetEna-)e*(
)ong -Ena-)e* %% Ena-)e* sett&ng 'or Co77an*
!$
Sets t!e 1na+led propert$ for a Command)
D 3eturns S@OE to indicate t!e operation &as successfu#)
b!nabled
A :oo#ean va#ue t!at sets t!e va#ue of t!e 1na+led setting of a Command) 3U4 enab#es
t!e Command9 1ALS4 disab#es it) A disab#ed Command cannot be se#ected)
A Command "ust !ave its 1na+led propert$ set to 3U4 to be se#ectab#e) *t a#so "ust !ave
its Ca"tion propert$ set and its *isi+le propert$ set to 3U4 to appear in t!e c!aracter5s pop-
up "enu) o "a%e t!e Command appear in t!e Commands /indo&' $ou "ust set its *oice
propert$)
See a#so IAgentCommand::-etCa"tion' IAgentCommand::Set*oice'
IAgentCommands::Add' IAgentCommands::Insert

IAgentCommand::Set*isi+le
;RESULT SetV&s&-)e(
)ong -V&s&-)e %% V&s&-)e sett&ng 'or Co77an*
!$
Sets t!e va#ue of t!e *isi+le propert$ for a Command)
D 3eturns S@OE to indicate t!e operation &as successfu#)
b*isible
A :oo#ean va#ue t!at deter"ines t!e *isi+le propert$ of a Command) 3U4 s!o&s t!e
Command9 1ALS4 !ides it)
A Command "ust !ave its *isi+le propert$ set to 3U4 and its Ca"tion propert$ set to
appear in t!e c!aracter5s pop-up "enu)
See a#so IAgentCommand::-et*isi+le' IAgent::SetCa"tion' IAgentCommands::Add'
IAgentCommands::Insert

IAgentCommand::Set*oice
;RESULT SetVo&ce(
,STR -s1Vo&ce %% vo&ce teGt sett&ng 'or Co77an*
!$
Sets t!e *oice propert$ for a Command)
D 3eturns S@OE to indicate t!e operation &as successfu#)
bs*oice
A :S3 t!at specifies t!e te(t for t!e *oice propert$ of a Command)
A Command "ust !ave its *oice propert$ and 1na+led propert$ set to be voice-accessib#e) *t
a#so "ust !ave its Ca"tion propert$ set to appear in t!e Co""ands /indo&)
!e :S3 e(pression $ou supp#$ can inc#ude s7uare brac%et c!aracters (K L) to indicate
optiona# &ords and vertica# bar c!aracters (G) to indicate a#ternative strings) A#ternates "ust be
enc#osed in parent!eses) 1or e(a"p#e' H(!e##o Kt!ereL G !i)I te##s t!e speec! engine to accept
H!e##o'I H!e##o t!ere'I or H!iI for t!e co""and) 3e"e"ber to inc#ude appropriate spaces
bet&een t!e te(t t!at<s in brac%ets or parent!eses and t!e te(t t!at<s not in brac%ets or
parent!eses)
2ou can a#so use an e##ipsis (M) to support word spottin(' t!at is' te##ing t!e speec! recognition
engine to ignore &ords spo%en in t!is position in t!e p!rase (so"eti"es ca##ed (arba(e &ords))
!erefore' t!e speec! engine recogni>es on#$ specific &ords in t!e string regard#ess of &!en
spo%en &it! ad+acent &ords or p!rases) 1or e(a"p#e' if $ou set t!is propert$ to HMc!ec%
"ai#MI t!e speec! recognition engine &i## "atc! p!rases #i%e Hp#ease c!ec% "ai#I or Hc!ec%
"ai# p#easeI to t!is co""and) 4##ipses can be used an$&!ere &it!in a string) ?o&ever' be
carefu# using t!is tec!ni7ue' because voice settings &it! e##ipses "a$ increase t!e potentia# of
un&anted "atc!es)
/!en defining t!e &ords and gra""ar for $our co""and' a#&a$s "a%e sure t!at $ou inc#ude
at #east one &ord t!at is re7uired9 t!at is' avoid supp#$ing on#$ optiona# &ords) *n addition'
"a%e sure t!at t!e &ord inc#udes on#$ pronounceab#e &ords and #etters) 1or nu"bers' it is
better to spe## out t!e &ord rat!er t!an using t!e nu"eric representation) A#so' o"it an$
punctuation or s$"bo#s) 1or e(a"p#e' instead of Ht!e N1 O1B pi>>aPI' use Ht!e nu"ber one ten
do##ar pi>>aI) *nc#uding non-pronounceab#e c!aracters or s$"bo#s for one co""and "a$
cause t!e speec! engine to fai# to co"pi#e t!e gra""ar for a## $our co""ands) 1ina##$' "a%e
$our voice para"eter as distinct as reasonab#$ possib#e fro" ot!er voice co""ands $ou
define) !e greater t!e si"i#arit$ bet&een t!e voice gra""ar for co""ands' t!e "ore #i%e#$
t!e speec! engine &i## "a%e a recognition error) 2ou can a#so use t!e confidence scores to
better distinguis! bet&een t&o co""ands t!at "a$ !ave si"i#ar or si"i#ar-sounding voice
gra""ar)
!e operation of t!is propert$ depends on t!e state of Microsoft Agent server5s speec!
recognition state) 1or e(a"p#e' if speec! recognition is disab#ed or not insta##ed' t!is function
!as no i""ediate effect) *f speec! recognition is enab#ed during a session' !o&ever' t!e
co""and &i## beco"e accessib#e &!en its c#ient app#ication is input-active)
See a#so IAgentCommand::-et*oice' IAgentCommand::SetCa"tion'
IAgentCommand::Set1na+led' IAgentCommands::Add' IAgentCommands::Insert
IAgent&serIn"ut
/!en a Command event occurs' t!e Microsoft Agent server returns infor"ation t!roug! t!e
&serIn"ut ob+ect) IAgent&serIn"ut defines an interface t!at a##o&s app#ications to 7uer$
t!ese va#ues)
Methods in *ta+le ,rder
IAgent&serIn"ut Methods %escri"tion
-etCount 3eturns t!e nu"ber of co""and a#ternatives returned in a Command
event)
-etItemId 3eturns t!e *. for a specific Command a#ternative)
-etItemConfidence 3eturns t!e va#ue of t!e Confidence propert$ for a specific Command
a#ternative)
-etItemTe2t 3eturns t!e va#ue of *oice te(t for a specific Command a#ternative)
-etAllItem%ata 3eturns t!e data for a## Command a#ternatives)
IAgent&serIn"ut::-etAllItem%ata
;RESULT 5etA))Ite7Data(
VARIANT #*0Ite7In*&ces, %% a**ress o' var&a-)e 'or a)ternat&ve IDs
VARIANT #)Con'&*ences, %% a**ress o' var&a-)e 'or con'&*ence scores
VARIANT #-s1TeGt %% a**ress o' var&a-)e 'or vo&ce teGt
!$
3etrieves t!e data for a## Command a#ternatives passed to an IAgentNotifySin'::Command
ca##bac%)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pdwIte$Indices
Address of a variab#e t!at receives t!e *.s of Commands passed to t!e
IAgentNotifySin'::Command ca##bac%)
plConfidences
Address of a variab#e t!at receives t!e confidence scores for Command a#ternatives
passed to t!e IAgentNotifySin'::Command ca##bac%)
pbs%ext
Address of a variab#e t!at receives t!e voice te(t for Command a#ternatives passed to t!e
IAgentNotifySin'::Command ca##bac%)
*f voice input &as not t!e source for t!e Command' for e(a"p#e' if t!e user se#ected t!e
co""and fro" t!e c!aracter5s pop-up "enu' t!e Microsoft Agent server returns t!e *. of t!e
Command se#ected' &it! a confidence score of 1BB and voice te(t as ,ULL) !e ot!er
a#ternatives return as ,ULL &it! confidence scores of >ero (B) and voice te(t as ,ULL)
See a#so IAgent&serIn"ut::-etItemConfidence' IAgent&serIn"ut::-etItemTe2t'
IAgent&serIn"ut::-etItemI%

IAgent&serIn"ut::-etCount
;RESULT 5etCo(nt(
)ong #*0Co(nt %% a**ress o' a var&a-)e 'or n(7-er o' a)ternat&ves
!$
3etrieves t!e nu"ber of Command a#ternatives passed to an IAgentNotifySin'::Command
ca##bac%)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pdwCount
Address of a variab#e t!at receives t!e count of Commands a#ternatives identified b$ t!e
server)
*f voice input &as not t!e source for t!e co""and' for e(a"p#e' if t!e user se#ected t!e
co""and fro" t!e c!aracter5s pop-up "enu' -etCount returns 1) *f -etCount returns >ero
(B)' t!e speec! recognition engine detected spo%en input but deter"ined t!at t!ere &as no
"atc!ing co""and)

IAgent&serIn"ut::-etItemConfidence
;RESULT 5etIte7Con'&*ence(
)ong *0Ite7In*eG, %% &n*eG o' Co77an* a)ternat&ve
)ong #)Con'&*ence %% a**ress o' con'&*ence va)(e 'or Co77an*
!$
3etrieves t!e confidence va#ue for a Command passed to an IAgentNotifySin'::Command
ca##bac%)
D 3eturns S@OE to indicate t!e operation &as successfu#)
dwIte$Index
!e inde( of a Command a#ternative passed to t!e IAgentNotifySin'::Command
ca##bac%)
plConfidence
Address of a variab#e t!at receives t!e confidence score for a Command a#ternative
passed to t!e IAgentNotifySin'::Command ca##bac%)
*f voice input &as not t!e source for t!e co""and' for e(a"p#e' if t!e user se#ected t!e
co""and fro" t!e c!aracter5s pop-up "enu' t!e Microsoft Agent server returns t!e
confidence va#ue of t!e best "atc! as 1BB and t!e confidence va#ues for a## ot!er a#ternatives
as >ero (B))
See a#so IAgent&serIn"ut::-etItemI%' IAgent&serIn"ut::-etAllItem%ata'
IAgent&serIn"ut::-etItemTe2t

IAgent&serIn"ut::-etItemI%
;RESULT 5etIte7ID(
)ong *0Ite7In*eG, %% &n*eG o' Co77an* a)ternat&ve
)ong #*0Co77an*ID %% a**ress o' a var&a-)e 'or n(7-er o' a)ternat&ves
!$
3etrieves t!e identifier of a Command a#ternative passed to an IAgentNotifySin'::Command
ca##bac%)
D 3eturns S@OE to indicate t!e operation &as successfu#)
dwIte$Index
!e inde( of t!e Command a#ternative passed to t!e IAgentNotifySin'::Command
ca##bac%)
pdwCo$$andID
Address of a variab#e t!at receives t!e *. of a Command)
*f voice input triggers t!e IAgentNotifySin'::Command ca##bac%' t!e server returns t!e *.s
for an$ "atc!ing Commands defined b$ $our app#ication)
See a#so IAgent&serIn"ut::-etItemConfidence' IAgent&serIn"ut::-etItemTe2t'
IAgent&serIn"ut::-etAllItem%ata

IAgent&serIn"ut::-etItemTe2t
;RESULT 5etIte7TeGt(
Long *0Ite7In*eG, %% &n*eG o' Co77an* a)ternat&ve
,STR #-s1TeGt %% a**ress o' vo&ce teGt 'or Co77an*
!$
3etrieves t!e voice te(t for a Command a#ternative passed to t!e
IAgentNotifySin'::Command ca##bac%)
D 3eturns S@OE to indicate t!e operation &as successfu#)
dwIte$Index
!e inde( of a Command a#ternative passed to t!e IAgentNotifySin'::Command
ca##bac%)
pbs%ext
Address of a :S3 t!at receives t!e va#ue of t!e voice te(t for t!e Command)
*f voice input &as not t!e source for t!e co""and' for e(a"p#e' if t!e user se#ected t!e
co""and fro" t!e c!aracter5s pop-up "enu' t!e server returns ,ULL for t!e Command5s
voice te(t)
See a#so IAgent&serIn"ut::-etItemConfidence' IAgent&serIn"ut::-etItemI%'
IAgent&serIn"ut::-etAllItem%ata
IAgentCommand/indow
IAgentCommand/indow defines an interface t!at a##o&s app#ications to set and 7uer$ t!e
properties of t!e Co""ands /indo&) !e Co""ands /indo& is a s!ared resource pri"ari#$
designed for a##o&ing users to vie& voice-enab#ed co""ands) *f speec! recognition is disab#ed
or not insta##ed' t!e Co""ands /indo& is not accessib#e) Atte"pting to set or 7uer$ its
properties &i## resu#t in an error)
Methods in *ta+le ,rder
IAgentCommand/indow
Methods
%escri"tion
Set*isi+le Sets t!e va#ue of t!e *isi+le propert$ of t!e Co""ands /indo&)
-et*isi+le 3eturns t!e va#ue of t!e *isi+le propert$ of t!e Co""ands /indo&)
-etPosition 3eturns t!e position of t!e Co""ands /indo&)
-etSi.e 3eturns t!e si>e of t!e Co""ands /indo&)
IAgentCommand/indow::-etPosition
;RESULT 5etPos&t&on(
)ong #)Le't, %% a**ress o' var&a-)e 'or )e't2e*ge o' Co77an*s <&n*o0
)ong #)To# %% a**ress o' var&a-)e 'or to#2e*ge o' Co77an*s <&n*o0
!$
3etrieves t!e Co""ands /indo&s5 position)
D 3eturns S@OE to indicate t!e operation &as successfu#)
plLeft
Address of a variab#e t!at receives t!e screen coordinate of t!e #eft edge of t!e
Co""ands /indo& in pi(e#s' re#ative to t!e screen origin (upper #eft))
pl%op
Address of a variab#e t!at receives t!e screen coordinate of t!e top edge of t!e
Co""ands /indo& in pi(e#s' re#ative to t!e screen origin (upper #eft))
See a#so IAgentCommand/indow::-etSi.e

IAgentCommand/indow::-etSi.e
;RESULT 5etS&1e(
)ong #)<&*th, %% a**ress o' var&a-)e 'or Co77an*s <&n*o0 0&*th
)ong #);e&ght %% a**ress o' var&a-)e 'or Co77an*s <&n*o0 he&ght
!$
3etrieves t!e current si>e of t!e Co""ands /indo&)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pl&idth
Address of a variab#e t!at receives t!e &idt! of t!e Co""ands /indo& in pi(e#s' re#ative
to t!e screen origin (upper #eft))
pl'ei(ht
Address of a variab#e t!at receives t!e !eig!t of t!e Co""ands /indo& in pi(e#s' re#ative
to t!e screen origin (upper #eft))
See a#so IAgentCommand/indow::-etPosition

IAgentCommand/indow::-et*isi+le
;RESULT 5etV&s&-)e(
)ong #-V&s&-)e %% a**ress o' var&a-)e 'or V&s&-)e sett&ng 'or
!$ %% Co77an*s <&n*o0
.eter"ines &!et!er t!e Co""ands /indo& is visib#e or !idden)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pb*isible
Address of a variab#e t!at receives 3U4 if t!e Co""ands /indo& is visib#e' or 1ALS4 if
!idden)
See a#so IAgentCommand/indow::Set*isi+le

IAgentCommand/indow::Set*isi+le
;RESULT SetV&s&-)e(
)ong -V&s&-)e %% Co77an*s <&n*o0 V&s&-)e sett&ng
!$
Set t!e *isi+le propert$ for t!e Co""ands /indo&)
D 3eturns S@OE to indicate t!e operation &as successfu#)
b*isible
*isi+le propert$ setting) A va#ue of 3U4 disp#a$s t!e Co""ands /indo&9 1ALS4 !ides
it)
!e user can override t!is propert$)
See a#so IAgentCommand/indow::-et*isi+le
IAgentS"eechIn"utPro"erties
IAgentS"eechIn"utPro"erties provides access to t!e speec! recognition properties
"aintained b$ t!e server) Most of t!e properties are read-on#$ for c#ient app#ications' but t!e
user can c!ange t!e" in t!e Microsoft Agent propert$ s!eet) !e Microsoft Agent server on#$
returns va#ues if a co"patib#e speec! engine !as been insta##ed and is enab#ed) Quer$ing
t!ese properties atte"pts to start t!e speec! engine)
Methods in *ta+le ,rder
IAgentS"eechIn"utPro"erties
Methods
%escri"tion
-etInstalled 3eturns &!et!er a co"patib#e speec! recognition engine !as been
insta##ed)
-et1na+led 3eturns &!et!er t!e speec! recognition engine is enab#ed)
-et0otAey 3eturns t!e current %e$ assign"ent of t!e #istening !ot %e$)
-et$CI% 3eturns t!e #oca#e (#anguage) *. of t!e se#ected speec! recognition
engine)
-et1ngine 3eturns t!e *. of t!e se#ected speec! recognition engine)
Set1ngine Sets t!e *. for t!e se#ected speec! recognition engine)
-et$isteningTi" 3eturns &!et!er t!e Listening ip is enab#ed)
IAgentS"eechIn"utPro"erties::-et1na+led
;RESULT 5etEna-)e*(
)ong #-Ena-)e* %% a**ress o' var&a-)e 'or s#eech recogn&t&on eng&ne
!$ %% Ena-)e* sett&ng
3etrieves a va#ue indicating &!et!er t!e insta##ed speec! recognition engine is enab#ed)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pb!nabled
Address of a variab#e t!at receives 3U4 if t!e speec! engine is current#$ enab#ed and
1ALS4 if disab#ed)
*f -etInstalled returns 1ALS4' 7uer$ing t!is setting returns an error)
See a#so IAgentS"eechIn"ut::-etInstalled

IAgentS"eechIn"utPro"erties::-et1ngine
;RESULT 5etEng&ne(
,STR #-s1Eng&ne %% a**ress o' var&a-)e 'or s#eech eng&ne 7o*e ID
!$
3etrieves t!e "ode *. for t!e current se#ected speec! recognition engine)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pbs!n(ine
Address of a :S3 t!at receives a string representation of t!e CLS*. for t!e se#ected
speec! recognition engine)
*f -etInstalled and -et1na+led return 1ALS4' 7uer$ing t!is setting returns an error)
See a#so IAgentS"eechIn"ut::Set1ngine

IAgentS"eechIn"utPro"erties::-et0otAey
;RESULT 5et;otLe.(
,STR #-s1;otCharLe. %% a**ress o' var&a-)e 'or )&sten&ng hot/e.
!$
3etrieves t!e current %e$board assign"ent for t!e speec! input #istening !ot %e$)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pbs'otCharKey
Address of a :S3 t!at receives t!e current !ot %e$ setting used to open t!e audio
c!anne# for speec! input)
*f -etInstalled and -et1na+led return 1ALS4' 7uer$ing t!is setting raises an error)
See a#so IAgentS"eechIn"ut::-et1na+led' IAgentS"eechIn"ut::-etInstalled

IAgentS"eechIn"utPro"erties::-etInstalled
;RESULT 5etInsta))e*(
)ong #-Insta))e* %% a**ress o' var&a-)e 'or s#eech recogn&t&on eng&ne
!$ %% &nsta))at&on ')ag
3etrieves a va#ue indicating &!et!er a speec! recognition engine !as been insta##ed)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pbInstalled
Address of a variab#e t!at receives 3U4 if a co"patib#e speec! recognition engine !as
been insta##ed and 1ALS4 if no engine is insta##ed)
*f -etInstalled and -et1na+led return 1ALS4' 7uer$ing an$ ot!er speec! input properties
returns an error)
See a#so IAgentS"eechIn"ut::-et1na+led

IAgentS"eechIn"utPro"erties::-et$CI%
;RESULT 5etLCID(
LCID #)c&*C(rrent %% a**ress o' var&a-)e 'or )oca)e ID
!$
3etrieves t!e current setting for t!e #oca#e *.)
D 3eturns S@OE to indicate t!e operation &as successfu#)
plcidCurrent
Address of LC*. t!at receives t!e current #oca#e setting) !e #oca#e setting deter"ines t!e
#anguage of t!e speec! recognition engine)
*f -etInstalled and -et1na+led return 1ALS4' 7uer$ing t!is setting returns an error)
See a#so IAgentS"eechIn"ut::-et1na+led' IAgentS"eechIn"ut::-etInstalled

IAgentS"eechIn"utPro"erties::-et$isteningTi"
;RESULT 5etL&sten&ngT&#(
)ong #-L&sten&ngT&# %% a**ress o' var&a-)e 'or )&sten&ng t&# ')ag
!$
3etrieves a va#ue indicating &!et!er t!e Listening ip is enab#ed for disp#a$)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pbInstalled
Address of a variab#e t!at receives 3U4 if t!e Listening ip is enab#ed for disp#a$' or
1ALS4 if t!e Listening ip is disab#ed)
*f -etInstalled and -et1na+led return 1ALS4' 7uer$ing an$ ot!er speec! input properties
returns an error)
See a#so IAgentS"eechIn"ut::-et1na+led' IAgentS"eechIn"ut::-etInstalled

IAgentS"eechIn"utPro"erties::Set1ngine
;RESULT SetEng&ne(
,STR -s1Eng&ne %% s#eech eng&ne 7o*e ID
!$
Sets t!e se#ected speec! recognition engine)
D 3eturns S@OE to indicate t!e operation &as successfu#)
bs!n(ine
A :S3 t!at contains a string representation of t!e CLS*. for t!e desired speec!
recognition "ode (engine))
*f -etInstalled and -et1na+led return 1ALS4' setting t!is propert$ returns an error)
See a#so IAgentS"eechIn"ut::-et1ngine
IAgentAudio,ut"utPro"erties
IAgentAudio,ut"utPro"erties provides access to audio output properties "aintained b$ t!e
Microsoft Agent server) !e properties are read-on#$' but t!e user can c!ange t!e" in t!e
Microsoft Agent propert$ s!eet)
Methods in *ta+le ,rder
IAgentAudio,ut"utPro"erties
Methods
%escri"tion
-et1na+led 3eturns &!et!er audio output is enab#ed)
-et&singSound1ffects 3eturns &!et!er sound-effect output is enab#ed)
IAgentAudio,ut"utPro"erties::-et1na+led
;RESULT 5etEna-)e*(
)ong #-Ena-)e* %% a**ress o' var&a-)e 'or a(*&o o(t#(t Ena-)e* sett&ng
!$
3etrieves a va#ue indicating &!et!er c!aracter speec! output is enab#ed)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pb!nabled
Address of a variab#e t!at receives 3U4 if t!e speec! output is current#$ enab#ed and
1ALS4 if disab#ed)
:ecause t!is setting affects spo%en output (S and sound fi#e) for a## c!aracters' on#$ t!e user
can c!ange t!is propert$ in t!e Microsoft Agent propert$ s!eet)

IAgentAudio,ut"utPro"erties::-et&singSound1ffects
;RESULT 5etUs&ngSo(n*E''ects(
)ong #-Us&ngSo(n*E''ects %% a**ress o' var&a-)e so(n* e''ects o(t#(t
!$ %% sett&ng
3etrieves a va#ue indicating &!et!er sound effects output is enab#ed)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pbUsin(Sound!ffects
Address of a variab#e t!at receives 3U4 if t!e sound effects output is current#$ enab#ed
and 1ALS4 if disab#ed)
Sound effects for a c!aracter5s ani"ation are assigned in t!e Microsoft Agent C!aracter 4ditor)
:ecause t!is setting affects sound effects output for a## c!aracters' on#$ t!e user can c!ange
t!is propert$ in t!e Microsoft Agent propert$ s!eet)
IAgentPro"ertySheet
IAgentPro"ertySheet defines an interface t!at a##o&s app#ications to set and 7uer$ properties
for t!e Microsoft Agent propert$ s!eet (&indo&))
Methods in *ta+le ,rder
IAgentPro"ertySheet
Methods
%escri"tion
-et*isi+le 3eturns &!et!er t!e Microsoft Agent propert$ s!eet is visib#e)
Set*isi+le Sets t!e *isi+le propert$ of t!e Microsoft Agent propert$ s!eet)
-etPosition 3eturns t!e position of t!e Microsoft Agent propert$ s!eet)
-etSi.e 3eturns t!e si>e of t!e Microsoft Agent propert$ s!eet)
-etPage 3eturns t!e current page for t!e Microsoft Agent propert$ s!eet)
SetPage Sets t!e current page for t!e Microsoft Agent propert$ s!eet)
IAgentPro"ertySheet::-etPage
;RESULT 5etPage(
,STR #-s1Page %% a**ress o' var&a-)e 'or c(rrent #ro#ert. #age
!$
3etrieves t!e current page of t!e Microsoft Agent propert$ s!eet)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pbs)a(e
Address of a variab#e t!at receives t!e current page of t!e propert$ s!eet (#ast vie&ed
page if t!e &indo& is not open)) !e para"eter can be one of t!e fo##o&ing:
>S"eech? !e Speec!
3ecognition page)
>,ut"ut? !e Output page)
>Co"yright? !e Cop$rig!t page)
See a#so IAgentPro"ertySheet::SetPage

IAgentPro"ertySheet::-etPosition
;RESULT 5etPos&t&on(
)ong #)Le't, %% a**ress o' var&a-)e 'or )e't e*ge o' #ro#ert. sheet
)ong #)To# %% a**ress o' var&a-)e 'or to# e*ge o' #ro#ert. sheet
!$
3etrieves t!e Microsoft Agent5s propert$ s!eet &indo& position)
D 3eturns S@OE to indicate t!e operation &as successfu#)
plLeft
Address of a variab#e t!at receives t!e screen coordinate of t!e #eft edge of t!e propert$
s!eet in pi(e#s' re#ative to t!e screen origin (upper #eft))
pl%op
Address of a variab#e t!at receives t!e screen coordinate of t!e top edge of t!e propert$
s!eet in pi(e#s' re#ative to t!e screen origin (upper #eft))
See a#so IAgentPro"ertySheet::-etSi.e

IAgentPro"ertySheet::-etSi.e
;RESULT 5etS&1e(
)ong #)<&*th, %% a**ress o' var&a-)e 'or #ro#ert. sheet 0&*th
)ong #);e&ght %% a**ress o' var&a-)e 'or #ro#ert. sheet he&ght
!$
3etrieves t!e si>e of t!e Microsoft Agent propert$ s!eet &indo&)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pl&idth
Address of a variab#e t!at receives t!e &idt! of t!e propert$ s!eet in pi(e#s' re#ative to t!e
screen origin (upper #eft))
pl'ei(ht
Address of a variab#e t!at receives t!e !eig!t of t!e propert$ s!eet in pi(e#s' re#ative to t!e
screen origin (upper #eft))
See a#so IAgentPro"ertySheet::-etPosition

IAgentPro"ertySheet::-et*isi+le
;RESULT 5etV&s&-)e(
)ong #-V&s&-)e %% a**ress o' var&a-)e 'or #ro#ert. sheet
!$ %% V&s&-)e sett&ng
.eter"ines &!et!er t!e Microsoft Agent propert$ s!eet is visib#e or !idden)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pb*isible
Address of a variab#e t!at receives 3U4 if t!e propert$ s!eet is visib#e and 1ALS4 if
!idden)
See a#so IAgentPro"ertySheet::Set*isi+le

IAgentPro"ertySheet::SetPage
;RESULT SetPage(
,STR -s1Page %% c(rrent #ro#ert. #age
!$
Sets t!e current page of t!e Microsoft Agent propert$ s!eet)
D 3eturns S@OE to indicate t!e operation &as successfu#)
bs)a(e
A :S3 t!at sets t!e current page of t!e propert$) !e para"eter can be one of t!e
fo##o&ing)
ES"eechE !e Speec! 3ecognition page)
E,ut"utE !e Output page)
ECo"yrightE !e Cop$rig!t page)
See a#so IAgentPro"ertySheet::-etPage

IAgentPro"ertySheet::Set*isi+le
;RESULT SetV&s&-)e(
)ong -V&s&-)e %% #ro#ert. sheet V&s&-)e sett&ng
!$
Sets t!e *isi+le propert$ for t!e Microsoft Agent propert$ s!eet)
D 3eturns S@OE to indicate t!e operation &as successfu#)
b*isible
=isib#e propert$ setting) A va#ue of 3U4 disp#a$s t!e propert$ s!eet9 a va#ue of 1ALS4
!ides it)
See a#so IAgentPro"ertySheet::-et*isi+le
IAgent@alloon
IAgent@alloon defines an interface t!at a##o&s app#ications to 7uer$ properties for t!e
Microsoft Agent &ord ba##oon)
*nitia# defau#ts for a c!aracter<s &ord ba##oon are set in t!e Microsoft Agent C!aracter 4ditor'
but once t!e app#ication is running' t!e user "a$ override t!e 4nab#ed and font properties) *f a
user c!anges t!e ba##oon5s properties' t!e c!ange affects a## c!aracters)
Methods in *ta+le ,rder
IAgent@alloon Methods %escri"tion
-et1na+led 3eturns &!et!er t!e &ord ba##oon is enab#ed)
-etNum$ines 3eturns t!e nu"ber of #ines disp#a$ed in t!e &ord ba##oon)
-etNumCharsPer$ine 3eturns t!e average nu"ber of c!aracters per #ine disp#a$ed in t!e &ord
ba##oon)
-etontName 3eturns t!e na"e of t!e font disp#a$ed in t!e &ord ba##oon)
-etontSi.e 3eturns t!e si>e of t!e font disp#a$ed in t!e &ord ba##oon)
-etont@old 3eturns &!et!er t!e font disp#a$ed in t!e &ord ba##oon is bo#d)
-etontItalic 3eturns &!et!er t!e font disp#a$ed in t!e &ord ba##oon is ita#ic)
-etontStr'ethru 3eturns &!et!er t!e font disp#a$ed in t!e &ord ba##oon is disp#a$ed as
stri%et!roug!)
-etont&nderline 3eturns &!et!er t!e font disp#a$ed in t!e &ord ba##oon is under#ined)
-etoreColor 3eturns t!e foreground co#or disp#a$ed in t!e &ord ba##oon)
-et@ac'Color 3eturns t!e bac%ground co#or disp#a$ed in t!e &ord ba##oon)
-et@orderColor 3eturns t!e border co#or disp#a$ed in t!e &ord ba##oon)
Set*isi+le Sets t!e &ord ba##oon to be visib#e)
-et*isi+le 3eturns t!e visibi#it$ setting for t!e &ord ba##oon)
SetontName Sets t!e font used in t!e &ord ba##oon)
SetontSi.e Sets t!e font si>e used in t!e &ord ba##oon)
SetontCharSet Sets t!e c!aracter set used in t!e &ord ba##oon)
-etontCharSet 3eturns t!e c!aracter set used in t!e &ord ba##oon)
IAgent@alloon::-et@ac'Color
;RESULT 5et,ac/Co)or(
)ong #),5Co)or %% a**ress o' var&a-)e 'or -ac/gro(n* co)or *&s#)a.e*
!$ %% &n 0or* -a))oon
3etrieves t!e va#ue for t!e bac%ground co#or disp#a$ed in a &ord ba##oon)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pl./Color
!e address of a variab#e t!at receives t!e co#or setting for t!e ba##oon bac%ground)
!e bac%ground co#or used in a c!aracter &ord ba##oon is defined in t!e Microsoft Agent
C!aracter 4ditor) *t cannot be c!anged b$ an app#ication) ?o&ever' t!e user can c!ange t!e
bac%ground co#or of t!e &ord ba##oons for a## c!aracters t!roug! t!e Microsoft Agent propert$
s!eet)
See a#so IAgent@alloon::-etoreColor

IAgent@alloon::-et@orderColor
;RESULT 5et,or*erCo)or (
)ong #),or*erCo)or%% a**ress o' var&a-)e 'or -or*er co)or *&s#)a.e*
!$ %% 'or 0or* -a))oon
3etrieves t!e va#ue for t!e border co#or disp#a$ed for a &ord ba##oon)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pl.orderColor
!e address of a variab#e t!at receives t!e co#or setting for t!e ba##oon border)
!e border co#or for a c!aracter &ord ba##oon is defined in t!e Microsoft Agent C!aracter
4ditor) *t cannot be c!anged b$ an app#ication) ?o&ever' t!e user can c!ange t!e border co#or
of t!e &ord ba##oons for a## c!aracters t!roug! t!e Microsoft Agent propert$ s!eet)
See a#so IAgent@alloon::-et@ac'ColorF IAgent@alloon::-etoreColor

IAgent@alloon::-et1na+led
;RESULT 5etEna-)e*(
)ong #-Ena-)e* %% a**ress o' var&a-)e 'or Ena-)e* sett&ng
!$ %% 'or 0or* -a))oon
3etrieves t!e va#ue of t!e 1na+led propert$ for a &ord ba##oon)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pb!nabled
!e address of a variab#e t!at receives 3U4 &!en t!e &ord ba##oon is enab#ed and
1ALS4 &!en it is disab#ed)
!e Microsoft Agent server auto"atica##$ disp#a$s t!e &ord ba##oon for spo%en output' un#ess it
is disab#ed) !e &ord ba##oon can be disab#ed for a c!aracter in t!e Microsoft Agent C!aracter
4ditor' or for a## c!aracters b$ t!e user' in t!e Microsoft Agent propert$ s!eet) *f t!e user
disab#es t!e &ord ba##oon' t!e c#ient cannot restore it)

IAgent@alloon::-etont@old
;RESULT 5et9ont,o)*(
)ong #-9ont,o)* %% a**ress o' var&a-)e 'or -o)* sett&ng 'or
!$ %% 'ont *&s#)a.e* &n 0or* -a))oon
*ndicates &!et!er t!e font used in a &ord ba##oon is bo#d)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pb+ont.old
!e address of a va#ue t!at receives 3U4 if t!e font is bo#d and 1ALS4 if not bo#d)
!e font st$#e used in a c!aracter &ord ba##oon is defined in t!e Microsoft Agent C!aracter
4ditor) *t cannot be c!anged b$ an app#ication) ?o&ever' t!e user can override t!e font
settings for a## c!aracters t!roug! t!e Microsoft Agent propert$ s!eet)

IAgent@alloon::-etontCharSet
;RESULT 5et9ontCharSet(
short #s9ontCharSet %% character set *&s#)a.e* &n 0or* -a))oon
!$
*ndicates t!e c!aracter set of t!e font disp#a$ed in a &ord ba##oon)
D 3eturns S@OE to indicate t!e operation &as successfu#)
ps+ontCharSet
!e address of a va#ue t!at receives t!e font<s c!aracter set) !e fo##o&ing are so"e co""on
settings for va#ue:
B Standard /indo&sR c!aracters (A,S*))
1 .efau#t c!aracter set)
F !e s$"bo# c!aracter set)
1FC .oub#e-b$te c!aracter set (.:CS) uni7ue to t!e Japanese version of /indo&s)
1F9 .oub#e-b$te c!aracter set (.:CS) uni7ue to t!e Eorean version of /indo&s)
1ST .oub#e-b$te c!aracter set (.:CS) uni7ue to t!e Si"p#ified C!inese version of /indo&s)
1SU .oub#e-b$te c!aracter set (.:CS) uni7ue to t!e raditiona# C!inese version of /indo&s)
FVV 4(tended c!aracters nor"a##$ disp#a$ed b$ .OS app#ications)
1or ot!er c!aracter set va#ues' consu#t t!e Microsoft /inSFR docu"entation)
!e defau#t c!aracter set used in a c!aracter<s &ord ba##oon is defined in t!e Microsoft Agent
C!aracter 4ditor) 2ou can c!ange it using IAgent@alloon::SetontCharSet) ?o&ever' t!e
user can override t!e c!aracter set setting for a## c!aracters using t!e Microsoft Agent propert$
s!eet)
See a#so IAgent@alloon::SetontCharSet
IAgent@alloon::-etontItalic
;RESULT 5et9ontIta)&c(
)ong #-9ontIta)&c %% a**ress o' var&a-)e 'or &ta)&c sett&ng 'or
!$ %% 'ont *&s#)a.e* &n 0or* -a))oon
*ndicates &!et!er t!e font used in a &ord ba##oon is ita#ic)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pb+ontItalic
!e address of a va#ue t!at receives 3U4 if t!e font is ita#ic and 1ALS4 if not ita#ic)
!e font st$#e used in a c!aracter<s &ord ba##oon is defined in t!e Microsoft Agent C!aracter
4ditor) *t cannot be c!anged b$ an app#ication) ?o&ever' t!e user can override t!e font
settings for a## c!aracters t!roug! t!e Microsoft Agent propert$ s!eet)

IAgent@alloon::-etontName
;RESULT 5et9ontNa7e(
,STR #-s19ontNa7e %% a**ress o' var&a-)e 'or 'ont *&s#)a.e*
!$ %% &n 0or* -a))oon

3etrieves t!e va#ue for t!e font disp#a$ed in a &ord ba##oon)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pbs+ont#a$e
!e address of a :S3 t!at receives t!e font na"e disp#a$ed in a &ord ba##oon)
!e defau#t font used in a c!aracter &ord ba##oon is defined in t!e Microsoft Agent C!aracter
4ditor) 2ou can c!ange it &it! IAgent@alloon::SetontName) !e user can override t!e font
setting for a## c!aracters using t!e Microsoft Agent propert$ s!eet)

IAgent@alloon::-etontSi.e
;RESULT 5et9ontS&1e(
)ong #)9ontS&1e %% a**ress o' var&a-)e 'or 'ont s&1e
!$ %% 'or 'ont *&s#)a.e* &n 0or* -a))oon
3etrieves t!e va#ue for t!e si>e of t!e font disp#a$ed in a &ord ba##oon)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pl+ontSie
!e address of a va#ue t!at receives t!e si>e of t!e font)
!e defau#t font si>e used in a c!aracter &ord ba##oon is defined in t!e Microsoft Agent
C!aracter 4ditor) 2ou can c!ange it &it! IAgent@alloon::SetontSi.e) ?o&ever' t!e user can
override a#so t!e font si>e settings for a## c!aracters using t!e Microsoft Agent propert$ s!eet)

IAgent@alloon::-etontStri'ethru
;RESULT 5et9ontStr&/ethr((
)ong #-9ontStr&/ethr( %% a**ress o' var&a-)e 'or str&/ethro(gh sett&ng
!$ %% 'or 'ont *&s#)a.e* &n 0or* -a))oon
*ndicates &!et!er t!e font used in a &ord ba##oon !as t!e stri%et!roug! st$#e set)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pb+ontStrikethru
!e address of a va#ue t!at receives 3U4 if t!e font stri%et!roug! st$#e is set and 1ALS4
if not)
!e font st$#e used in a c!aracter &ord ba##oon is defined in t!e Microsoft Agent C!aracter
4ditor) *t cannot be c!anged b$ an app#ication) ?o&ever' t!e user can override t!e font
settings for a## c!aracters using t!e Microsoft Agent propert$ s!eet)

IAgent@alloon::-etont&nderline
;RESULT 5et9ontUn*er)&ne(
)ong #-9ontUn*er)&ne %% a**ress o' var&a-)e 'or (n*er)&ne sett&ng
!$ %% 'or 'ont *&s#)a.e* &n 0or* -a))oon
*ndicates &!et!er t!e font used in a &ord ba##oon !as t!e under#ine st$#e set)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pb+ontUnderline
!e address of a va#ue t!at receives 3U4 if t!e font under#ine st$#e is set and 1ALS4 if
not)
!e font st$#e used in a c!aracter &ord ba##oon is defined in t!e Microsoft Agent C!aracter
4ditor) *t cannot be c!anged b$ an app#ication) ?o&ever' t!e user can override t!e font
settings for a## c!aracters using t!e Microsoft Agent propert$ s!eet)

IAgent@alloon::-etoreColor
;RESULT 5et9oreCo)or(
)ong #)95Co)or %% a**ress o' var&a-)e 'or 'oregro(n* co)or *&s#)a.e*
!$ %% &n 0or* -a))oon
3etrieves t!e va#ue for t!e foreground co#or disp#a$ed in a &ord ba##oon)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pl+/Color
!e address of a variab#e t!at receives t!e co#or setting for t!e ba##oon foreground)
!e foreground co#or used in a c!aracter &ord ba##oon is defined in t!e Microsoft Agent
C!aracter 4ditor) *t cannot be c!anged b$ an app#ication) ?o&ever' t!e user can override t!e
foreground co#or of t!e &ord ba##oons for a## c!aracters t!roug! t!e Microsoft Agent propert$
s!eet)
See a#so IAgent@alloon::-et@ac'Color

IAgent@alloon::-etNumCharsPer$ine
;RESULT 5etN(7CharsPerL&ne(
)ong #)CharsPerL&ne %% a**ress o' var&a-)e 'or characters #er )&ne
!$ %% *&s#)a.e* &n 0or* -a))oon
3etrieves t!e va#ue for t!e average nu"ber of c!aracters per #ine disp#a$ed in a &ord ba##oon)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pbChars)erLine
!e address of a variab#e t!at receives t!e nu"ber of c!aracters per #ine)
!e Microsoft Agent server auto"atica##$ scro##s t!e #ines disp#a$ed for spo%en output in t!e
&ord ba##oon) !e average nu"ber of c!aracters per #ine for a c!aracter<s &ord ba##oon is
defined in t!e Microsoft Agent C!aracter 4ditor) *t cannot be c!anged b$ an app#ication)
See a#so IAgent@alloon::-etNum$ines

IAgent@alloon::-etNum$ines
;RESULT 5etN(7L&nes(
)ong #-cL&nes %% a**ress o' var&a-)e 'or n(7-er o' )&nes
!$ %% *&s#)a.e* &n 0or* -a))oon
3etrieves t!e va#ue of t!e nu"ber of #ines disp#a$ed in a &ord ba##oon)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pbcLines
!e address of a variab#e t!at receives t!e nu"ber of #ines disp#a$ed)
!e Microsoft Agent server auto"atica##$ scro##s t!e #ines disp#a$ed for spo%en output in t!e
&ord ba##oon) !e nu"ber of #ines for a c!aracter &ord ba##oon is defined in t!e Microsoft
Agent C!aracter 4ditor) *t cannot be c!anged b$ an app#ication)
See a#so IAgent@alloon::-etNumCharsPer$ine
IAgent@alloon::-et*isi+le
;RESULT 5etV&s&-)e(
)ong #-V&s&-)e %% a**ress o' var&a-)e 'or 0or* -a))oon
!$ %% V&s&-)e sett&ng
.eter"ines &!et!er t!e &ord ba##oon is visib#e or !idden)
D 3eturns S@OE to indicate t!e operation &as successfu#)
pb*isible
Address of a variab#e t!at receives 3U4 if t!e &ord ba##oon is visib#e and 1ALS4 if
!idden)
See a#so IAgent@alloon::Set*isi+le
IAgent@alloon::SetontCharSet
;RESULT Set9ontCharSet(
short s9ontCharSet %% character set *&s#)a.e* &n 0or* -a))oon
!$
Sets t!e c!aracter set of t!e font disp#a$ed in t!e &ord ba##oon)
D 3eturns S@OE to indicate t!e operation &as successfu#)
s+ontCharSet
!e c!aracter set of t!e font) !e fo##o&ing are so"e co""on settings for va#ue:
B Standard /indo&s c!aracters (A,S*))
1 .efau#t c!aracter set)
F !e s$"bo# c!aracter set)
1FC .oub#e-b$te c!aracter set (.:CS) uni7ue to t!e Japanese version of /indo&s)
1F9 .oub#e-b$te c!aracter set (.:CS) uni7ue to t!e Eorean version of /indo&s)
1ST .oub#e-b$te c!aracter set (.:CS) uni7ue to t!e Si"p#ified C!inese version of
/indo&s)
1SU .oub#e-b$te c!aracter set (.:CS) uni7ue to t!e raditiona# C!inese version of
/indo&s)
FVV 4(tended c!aracters nor"a##$ disp#a$ed b$ .OS app#ications)
1or ot!er c!aracter set va#ues' consu#t t!e Microsoft /inSF docu"entation)
!e defau#t c!aracter set used in a c!aracter<s &ord ba##oon is defined in t!e Microsoft Agent
C!aracter 4ditor) 2ou can c!ange it &it! IAgent@alloon::SetontCharSet) ?o&ever' t!e user
can override t!e c!aracter set setting for a## c!aracters using t!e Microsoft Agent propert$
s!eet)
See a#so IAgent@alloon::-etontCharSet
IAgent@alloon::SetontName
;RESULT Set9ontNa7e(
,STR -s19ontNa7e %% 'ont *&s#)a.e* &n 0or* -a))oon
!$

Sets t!e font disp#a$ed in t!e &ord ba##oon)
D 3eturns S@OE to indicate t!e operation &as successfu#)
bs+ont#a$e
A :S3 t!at sets t!e font disp#a$ed in t!e &ord ba##oon)
!e defau#t font used in a c!aracter<s &ord ba##oon is defined in t!e Microsoft Agent C!aracter
4ditor) 2ou can c!ange it &it! IAgent@alloon::SetontName) ?o&ever' t!e user can override
t!e font setting for a## c!aracters using t!e Microsoft Agent propert$ s!eet)
See a#so IAgent@alloon::-et*isi+le
IAgent@alloon::SetontSi.e
;RESULT Set9ontS&1e(
)ong )9ontS&1e %% 'ont s&1e *&s#)a.e* &n 0or* -a))oon
!$
Sets t!e si>e of t!e font disp#a$ed in t!e &ord ba##oon)
D 3eturns S@OE to indicate t!e operation &as successfu#)
l+ontSie
!e si>e of t!e font)
!e defau#t font si>e used in a c!aracter<s &ord ba##oon is defined in t!e Microsoft Agent
C!aracter 4ditor) 2ou can c!ange it &it! IAgent@alloon::SetontSi.e) ?o&ever' t!e user can
override t!e font si>e setting for a## c!aracters using t!e Microsoft Agent propert$ s!eet)
See a#so IAgent@alloon::-etontSi.e
IAgent@alloon::Set*isi+le
;RESULT SetV&s&-)e(
)ong -V&s&-)e %% 0or* -a))oon V&s&-)e sett&ng
!$
Sets t!e *isi+le propert$ for t!e &ord ba##oon)
D 3eturns S@OE to indicate t!e operation &as successfu#)
b*isible
=isib#e propert$ setting) A va#ue of 3U4 disp#a$s t!e &ord ba##oon9 a va#ue of 1ALS4
!ides it)
See a#so IAgent@alloon::-et*isi+le1vents
Microsoft Agent provides severa# events for trac%ing user interaction and server states) !is
section describes t!e event "et!ods e(posed b$ t!e IAgentNotifySin' interface)
1vents
Methods in *ta+le ,rder
IAgentNotifySin' %escri"tion
Command Occurs &!en t!e server processes a c#ient-defined co""and)
ActivateIn"utState Occurs &!en a c!aracter beco"es or ceases to be input-active)
)estart Occurs &!en t!e server restarts)
Shutdown Occurs &!en t!e user e(its t!e server)
*isi+leState Occurs &!en t!e c!aracter5s *isi+le state c!anges)
Clic' Occurs &!en a c!aracter is c#ic%ed)
%+lClic' Occurs &!en a c!aracter is doub#e-c#ic%ed)
%ragStart Occurs &!en a user starts dragging a c!aracter)
%ragCom"lete Occurs &!en a user stops dragging a c!aracter)
)e<uestStart Occurs &!en t!e server begins processing a )e<uest ob+ect)
)e<uestCom"lete Occurs &!en t!e server co"p#etes processing a )e<uest ob+ect)
@oo'mar' Occurs &!en t!e server processes a boo%"ar%)
Idle Occurs &!en t!e server starts or ends id#e processing)
Move Occurs &!en a c!aracter !as been "oved)
Si.e Occurs &!en a c!aracter !as been resi>ed)
@alloon*isi+leState Occurs &!en t!e visibi#it$ state of a c!aracter<s &ord ba##oon c!anges)
IAgentNotifySin'::ActivateIn"utState
;RESULT Act&vateIn#(tState(
)ong *0CharID, %% character ID
)ong -Act&vate* %% &n#(t act&vat&on ')ag
!$
,otifies a c#ient app#ication t!at a c!aracter5s input active state c!anged)
D ,o return va#ue)
dwCharID
*dentifier of t!e c!aracter &!ose input activation state c!anged)
b,ctivated
*nput active f#ag) !is :oo#ean va#ue is 3U4 if t!e c!aracter referred to b$ dwCharID
beca"e input active9 and 1ALS4 if t!e c!aracter #ost its input active state)
See a#so IAgentCharacter::SetIn"utActive' IAgentCharacter::-etIn"utActive

IAgentNotifySin':: @alloon*isi+leState
;RESULT ,a))oonV&s&-)eState(
)ong *0CharID, %% character ID
)ong -V&s&-)e %% v&s&-&)&t. ')ag
!$
,otifies a c#ient app#ication &!en t!e visibi#it$ state of t!e c!aracter<s &ord ba##oon c!anges)
D ,o return va#ue)
dwCharID
*dentifier of t!e c!aracter &!ose &ord ba##oon<s visibi#it$ state !as c!anged)
b*isible
=isibi#it$ f#ag) !is :oo#ean va#ue is 3U4 &!en c!aracter<s &ord ba##oon beco"es visib#e9
and 1ALS4 &!en it beco"es !idden)
!is event is sent to a## c#ients of t!e c!aracter)
IAgentNotifySin'::@oo'mar'
;RESULT ,oo/7ar/(
)ong *0,oo/8ar/ID %% -oo/7ar/ ID
!$
,otifies a c#ient app#ication &!en its boo%"ar% co"p#etes)
D ,o return va#ue)
dw.ook0arkID
*dentifier of t!e boo%"ar% t!at resu#ted in triggering t!e event)
/!en $ou inc#ude boo%"ar% tags in a S"ea' "et!od' $ou can trac% &!en t!e$ occur &it! t!is
event)
See a#so IAgentCharacter::S"ea'' Speec! Output ags

IAgentNotifySin'::Clic'
;RESULT C)&c/(
)ong *0CharID, %% character ID
short '0Le.s, %% 7o(se -(tton an* 7o*&'&er /e. state
)ong G, %% G coor*&nate o' 7o(se #o&nter
)ong . %% . coor*&nate o' 7o(se #o&nter
!$
,otifies a c#ient app#ication &!en t!e user c#ic%s a c!aracter)
D ,o return va#ue)
dwCharID
*dentifier of t!e c#ic%ed c!aracter)
fwKeys
A para"eter t!at indicates t!e "ouse button and "odifier %e$ state) !e para"eter can
return an$ co"bination of t!e fo##o&ing:
B(BBB1 Left :utton
B(BB1B Midd#e :utton
B(BBBF 3ig!t :utton
B(BBBT S!ift Ee$ .o&n
B(BBBC Contro# Ee$ .o&n
B(BBFB A#t Ee$ .o&n
(
!e (-coordinate of t!e "ouse pointer in pi(e#s' re#ative to t!e screen origin (upper #eft))
$
!e $-coordinate of t!e "ouse pointer in pi(e#s' re#ative to t!e screen origin (upper #eft))

IAgentNotifySin'::Command
;RESULT Co77an*(
)ong *0Co77an*ID, %% Co77an* ID o' the -est 7atch
IUn/no0n #(n/UserIn#(t %% a**ress o' IAgentUserIn#(t o-Hect
!$
,otifies a c#ient app#ication t!at a Co""and &as se#ected b$ t!e user)
D ,o return va#ue)
dwCo$$andID
*dentifier of t!e best "atc! co""and a#ternative)
punkUserInput
Address of t!e *Un%no&n interface for t!e IAgent&serIn"ut ob+ect)
Use Quer$*nterface to retrieve t!e IAgent&serIn"ut interface)
See a#so IAgent&serIn"ut

IAgentNotifySin'::%+lClic'
;RESULT D-)C)&c/(
)ong *0CharID, %% character ID
short '0Le.s, %% 7o(se -(tton an* 7o*&'&er /e. state
)ong G, %% G coor*&nate o' 7o(se #o&nter
)ong . %% . coor*&nate o' 7o(se #o&nter
!$
,otifies a c#ient app#ication &!en t!e user doub#e-c#ic%s a c!aracter)
D ,o return va#ue)
dwCharID
*dentifier of t!e doub#e-c#ic%ed c!aracter)
fwKeys
A para"eter t!at indicates t!e "ouse button and "odifier %e$ state) !e para"eter can
return an$ co"bination of t!e fo##o&ing:
B(BBB1 Left :utton
B(BB1B Midd#e :utton
B(BBBF 3ig!t :utton
B(BBBT S!ift Ee$ .o&n
B(BBBC Contro# Ee$ .o&n
B(BBFB A#t Ee$ .o&n
(
!e (-coordinate of t!e "ouse pointer in pi(e#s' re#ative to t!e screen origin (upper #eft))
$
!e $-coordinate of t!e "ouse pointer in pi(e#s' re#ative to t!e screen origin (upper #eft))

IAgentNotifySin'::%ragCom"lete
;RESULT DragCo7#)ete(
)ong *0CharID, %% character ID
short '0Le.s, %% 7o(se -(tton an* 7o*&'&er /e. state
)ong G, %% G2coor*&nate o' 7o(se #o&nter
)ong . %% .2coor*&nate o' 7o(se #o&nter
!$
,otifies a c#ient app#ication &!en t!e user stops dragging a c!aracter)
D ,o return va#ue)
dwCharID
*dentifier of t!e dragged c!aracter)
fwKeys
A para"eter t!at indicates t!e "ouse button and "odifier %e$ state) !e para"eter can
return an$ co"bination of t!e fo##o&ing:
B(BBB1 Left :utton
B(BB1B Midd#e :utton
B(BBBF 3ig!t :utton
B(BBBT S!ift Ee$ .o&n
B(BBBC Contro# Ee$ .o&n
B(BBFB A#t Ee$ .o&n
(
!e (-coordinate of t!e "ouse pointer in pi(e#s' re#ative to t!e screen origin (upper #eft))
$
!e $-coordinate of t!e "ouse pointer in pi(e#s' re#ative to t!e screen origin (upper #eft))

IAgentNotifySin'::%ragStart
;RESULT DragStart(
)ong *0CharID, %% character ID
short '0Le.s, %% 7o(se -(tton an* 7o*&'&er /e. state
)ong G, %% G2coor*&nate o' 7o(se #o&nter
)ong . %% .2coor*&nate o' 7o(se #o&nter
!$
,otifies a c#ient app#ication &!en t!e user starts dragging a c!aracter)
D ,o return va#ue)
dwCharID
*dentifier of t!e dragged c!aracter)
fwKeys
A para"eter t!at indicates t!e "ouse button and "odifier %e$ state) !e para"eter can
return an$ co"bination of t!e fo##o&ing:
B(BBB1 Left :utton
B(BB1B Midd#e :utton
B(BBBF 3ig!t :utton
B(BBBT S!ift Ee$ .o&n
B(BBBC Contro# Ee$ .o&n
B(BBFB A#t Ee$ .o&n
x
!e (-coordinate of t!e "ouse pointer in pi(e#s' re#ative to t!e screen origin (upper #eft))
y
!e $-coordinate of t!e "ouse pointer in pi(e#s' re#ative to t!e screen origin (upper #eft))

IAgentNotifySin'::Idle
;RESULT I*)e(
)ong *0CharID, %% character ID
)ong -Start %% start ')ag
!$
,otifies a c#ient app#ication &!en a c!aracter5s Idling state !as c!anged)
D ,o return va#ue)
dwCharID
*dentifier of t!e re7uest t!at started)
bStart
Start f#ag) !is :oo#ean va#ue is 3U4 &!en t!e c!aracter begins id#ing and 1ALS4 &!en
it stops id#ing)
!is event enab#es $ou to trac% &!en t!e Microsoft Agent server starts or stops id#e processing
for a c!aracter)
See a#so IAgentCharacter::-etIdle,n' IAgentCharacter::SetIdle,n
IAgentNotifySin':: Move
;RESULT 8ove(
)ong *0CharID, %% character ID
)ong G, %% G2coor*&nate o' ne0 )ocat&on
)ong ., %% .2coor*&nate o' ne0 )ocat&on
)ong *0Ca(se %% ca(se o' 7ove state
!$
,otifies a c#ient app#ication &!en t!e c!aracter !as been "oved)
D ,o return va#ue)
dwCharID
*dentifier of t!e c!aracter t!at !as been "oved)
x
!e (-coordinate of t!e ne& position in pi(e#s' re#ative to t!e screen origin (upper #eft)) !e
#ocation of a c!aracter is based on t!e upper #eft corner of its ani"ation fra"e)
y
!e $-coordinate of t!e ne& position in pi(e#s' re#ative to t!e screen origin (upper #eft)) !e
#ocation of a c!aracter is based on t!e upper #eft corner of its ani"ation fra"e)
dwCause
!e cause of t!e c!aracter "ove) !e para"eter "a$ be one of t!e fo##o&ing:
const unsigned short NeverMoved 3 45 C!aracter !as not been "oved)
const unsigned short &serMoved 3 65 User dragged t!e c!aracter)
const unsigned short ProgramMoved 3 75 2our app#ication "oved t!e c!aracter)
const unsigned short ,therProgramMoved 3 85 Anot!er app#ication "oved t!e c!aracter)
!is event is sent to a## c#ients of t!e c!aracter)
See a#so IAgentCharacter::-etMoveCause' IAgentCharacter::MoveTo
IAgentNotifySin'::)e<uestCom"lete
;RESULT Re4(estCo7#)ete(
)ong *0Re4(estID, %% re4(est ID
)ong hrStat(s %% stat(s co*e
!$
,otifies a c#ient app#ication &!en a re7uest co"p#etes)
D ,o return va#ue)
dwRequestID
*dentifier of t!e re7uest t!at started)
hrStatus
Status code) !is para"eters returns t!e status code for t!e re7uest)
!is event enab#es $ou to trac% &!en a 7ueued "et!od co"p#etes)
See a#so IAgentNotifySin'::)e<uestStart' IAgent::$oad' IAgentCharacter::-estureAt'
IAgentCharacter::0ide' IAgentCharacter::Interru"t' IAgentCharacter::MoveTo'
IAgentCharacter::Pre"are' IAgentCharacter::Play' IAgentCharacter::Show'
IAgentCharacter::S"ea'' IAgentCharacter::/ait

IAgentNotifySin'::)e<uestStart
;RESULT Re4(estStart(
)ong *0Re4(estID %% re4(est ID
!$
,otifies a c#ient app#ication &!en a re7uest begins)
D ,o return va#ue)
dwRequestID
*dentifier of t!e re7uest t!at started)
!is event enab#es $ou to trac% &!en a 7ueued re7uest begins)
See a#so IAgentNotifySin'::)e<uestCom"lete' IAgent::$oad'
IAgentCharacter::-estureAt' IAgentCharacter::0ide' IAgentCharacter::Interru"t'
IAgentCharacter::MoveTo' IAgentCharacter::Pre"are' IAgentCharacter::Play'
IAgentCharacter::Show' IAgentCharacter::S"ea'' IAgentCharacter::/ait

IAgentNotifySin'::)estart
;RESULT Restart(!$
,otifies a c#ient app#ication t!at t!e Microsoft Agent server restarted)
D ,o return va#ue)
See a#so IAgentNotifySin'::Shutdown

IAgentNotifySin'::Shutdown
;RESULT Sh(t*o0n(!$
,otifies a c#ient app#ication t!at t!e Microsoft Agent server s!ut do&n)
D ,o return va#ue)
!is event fires on#$ &!en t!e user e(p#icit#$ c!ooses t!e 4(it co""and on t!e pop-up "enu
of t!e Microsoft Agent tas%bar icon) 3e7uests sent after t!e server s!uts do&n &i## fai#)
See a#so IAgentNotifySin'::)estart
IAgentNotifySin':: Si.e
;RESULT S&1e(
)ong *0CharID, %% character ID
)ong )<&*th, %% ne0 0&*th
)ong );e&ght, %% ne0 he&ght
!$
,otifies a c#ient app#ication &!en t!e c!aracter !as been resi>ed)
D ,o return va#ue)
dwCharID
*dentifier of t!e c!aracter t!at !as been resi>ed)
l&idth
!e &idt! of t!e c!aracter<s ani"ation fra"e in pi(e#s)
l'ei(ht
!e !eig!t of t!e c!aracter<s ani"ation fra"e in pi(e#s)
!is event is sent to a## c#ients of t!e c!aracter)
See a#so IAgentCharacter::-etSi.e' IAgentCharacter::SetSi.e

IAgentNotifySin'::*isi+leState
;RESULT V&s&-)eState(
)ong *0CharID, %% character ID
)ong -V&s&-)e, %% v&s&-&)&t. ')ag
)ong *0Ca(se, %% ca(se o' v&s&-)e state
!$
,otifies a c#ient app#ication &!en t!e visibi#it$ state of t!e c!aracter c!anges)
D ,o return va#ue)
dwCharID
*dentifier of t!e c!aracter &!ose visibi#it$ state is c!anged)
b*isible
=isibi#it$ f#ag) !is :oo#ean va#ue is 3U4 &!en c!aracter beco"es visib#e and 1ALS4
&!en t!e c!aracter beco"es !idden)
dwCause
Cause of #ast c!ange to t!e c!aracter5s visibi#it$ state) !e para"eter "a$ be one of t!e
fo##o&ing:
const unsigned short NeverShown 3 45 C!aracter !as not been s!o&n)
const unsigned short &ser0id 3 65 User !id t!e c!aracter)
const unsigned short &serShowed 3 75 User s!o&ed t!e c!aracter)
const unsigned short Program0id 3 85 2our app#ication !id t!e c!aracter)
const unsigned short ProgramShowed 3 95 2our app#ication s!o&ed t!e
c!aracter)
const unsigned short ,therProgram0id 3 :5 Anot!er app#ication !id t!e
c!aracter)
const unsigned short ,therProgramShowed 3 ;5 Anot!er app#ication s!o&ed t!e
c!aracter)
See a#so IAgentCharacter::-et*isi+le' IAgentCharacter::Set*isi+le'
IAgentCharacter::-et*isi+ilityCause

You might also like