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)
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