Android jChat 1.

3
User Guide
Last update: 26-January-2009
Authors: Danilo Gotta
Stefano Semeria
Tiziana Trucco
Marco Ughetti
1
Contents
Last update: 26-January-2009..............................................................................................1
Authors: ....................................................................................................................... 1
Danilo Gotta.................................................................................................................................. 1
Stefano Semeria........................................................................................................................... 1
i!iana ru""o.............................................................................................................................. 1
#ar"o $%hetti............................................................................................................................... 1
&ontents........................................................................................................................................... 2
'ntrodu"tion...................................................................................................................................... (
Android )&hat 1.( setup.................................................................................................................... (
Settin% the phone num*er............................................................................................................. (
&ustomi!in% the G+S lo"ation pro,ider......................................................................................... (
Laun"hin% JAD- main "ontainer................................................................................................... .
$sin% Android )&hat 1.(.................................................................................................................... 6
&onne"tin% to JAD-..................................................................................................................... 6
/no0in% )&hat 1.( ta*s..................................................................................................................... 1
he &onta"t ta*............................................................................................................................ 1
he map ta*................................................................................................................................. 9
+i"2in% "onta"ts............................................................................................................................. 10
'ntera"tin% 0ith "onta"ts................................................................................................................. 10
Sendin% an S#S to one or more "onta"ts...................................................................................11
&allin% a "onta"t......................................................................................................................... 11
Startin% a "hat session................................................................................................................ 12
$sin% the status *ar to *ro0se "hat sessions.............................................................................12
&losin% a "hat session................................................................................................................ 1(
&ompilin% and si%nin% )&hat........................................................................................................... 1.
3A4................................................................................................................................................ 1.
L-GAL '5367#A'65.................................................................................................................. 18
erms and &onditions of use...................................................................................................... 18
Limited use................................................................................................................................. 18
Dis"laimer................................................................................................................................... 18
'nformation from you................................................................................................................... 18
La0 and Jurisdi"tion................................................................................................................... 18
2
Introduction
)&hat appli"ation is an a%ent *ased '#-style appli"ation for Android 9 *ased on JAD-
:http:;;)ade.tila*."om<.
't allo0s the user to "ommuni"ate 0ith any other "onta"t ha,in% the same soft0are runnin% and
"onne"ted to the same JAD- platform. $sers "an send te=t '# in a "hat li2e 0ay9 "all a "onta"t *y
phone or e,en send an S#S to a "onta"t.
#oreo,er9 the position of ea"h "onta"t "an *e seen on the map at any time and it is "ontinuously
updated.
)&hat 1.( has *een tested on the first Android phone: the #o*ile G1 phone.
Android jChat 1! setup
'n order to *e a*le to start and use the )&hat 1.( appli"ation9 a fe0 "onfi%uration steps are
re>uired.
"etting the phone nu#$er
)&hat 1.( appli"ation uses the phone num*er as the a%ent 'D of ea"h "onta"t. ?hen runnin% of the
real phone the appli"ation tries to retrie,e the real phone num*er usin% the Android A+'. 'f for
some reason the phone num*er "annot *e retrie,ed it must *e set usin% the Jade Settin% dialo%
:see &onne"tin% to JAD-<
Due to some A+' "han%es from Android SD/ 0.9 to 1.09 phone num*er "ustomi!ation is no more
possi*le on the emulator. 'n this "ase9 )&hat 1.( uses the emulator default telephone num*er and
appends a random inte%er to ensure the uni>ueness 0hen usin% multiple instan"es of the phone
emulator.
Custo#i%ing the &'" (ocation pro)ider
)&hat 1.( allo0s to a user to see *oth his position and his "onta"t@s on a map. o do so9 a mo"2ed
G+S lo"ation pro,ider is used. )&hat 1.( used a mo"2ed G+S ser,i"e runnin% on the phone.
Sin"e Android SD/ 1.0 remo,ed the A+' used *y the lo"ation pro,ider ser,i"e9 this solution is no
more appli"a*le.
o send "ustom tra"2s to )&hat 1.( you "an use the "ustom Lo"ation+ro,ider tool that is pro,ided
under /tools dire"tory in the sour"e tree.
+lease note that this tool is a standard J2S- appli"ation usin% Ja,a 1.. and s0t9 0hi"h has *een
0ritten usin% the same li*raries used *y the ddms tool pro,ided 0ith Android SD/.
(
Aou "an easily *uild and run this ne0 tool *y usin% ant 0ith the pro,ided build.xml
Figure 1
o do so9 you ha,e to:
Go to <JCHAT-SOURCES-BASEDIR>\tools\LocationControlTool folder on a
"ommand shell
-dit the *uild.properties file9 settin% android-sdk-folder property to the path of your
Android 1.0 SD/
ype ant at the shell prompt
Aou should *e a*le to see the Lo"ation&ontrol tool G$'.
Laun"h an emulator. As soon as the emulator "onne"ts to ad*9 you should *e a*le to see it
in the Available Devices panel.
&li"2 on the emulator i"on in Available Devices panel.
&li"2 on the Load KML and "hoose a /#L tra"2 file to import. Aou should no0 *e a*le to
see all the positions in the tra"2. Please note that the KML parser only looks for data
inside <coordinates> tag inside <MultiGeometry> element. Any other data shall e
ignored!
Aou are a*le to set Loop #ode :lo"ations 0ill *e fired from *e%innin% to end and *a"2
fore,er< *y "li"2in% the Loo! "ode ena#led "he"2*o=.
Aou are a*le to set the delay in millise"onds *et0een the firin% of t0o "onse"uti,e positions
in the tra"29 *y settin% it in the "he"2*o=
'f you press the $la% Ro&te *utton9 the default %ps pro,ider on the emulator shall *e%in
to re"ei,e position updates. 'f you start )&hat9 you should *e a*le to see you o0n position
"han%in% o,er time in the map ta*.
B
Aou are a*le to stop the update anytime *y pressin% Sto! Ro&te *utton. Aou are also
free to laun"h a se"ond emulator instan"e and send updates to it *y "li"2in% on its i"on in
A'aila#le De'ices and repeatin% the pro"edure. Aou should *e a*le to handle multiple
emulator instan"es 0ith different data playin% at the same time.
'f you "lose the tool 0indo09 all the runnin% updates shall *e stopped.
Launching JA*+ #ain container
o *e a*le to run )&hat 1.(9 a JAD- Leap main "ontainer must *e laun"hed.
A JAD- Leap "ontainer #$S *e runnin% 0hen )&hat 1.( "onne"ts to it9 other0ise the appli"ation
0ill han%.
hese are the steps that should *e e=e"uted:
1. Do0nload the last JAD--Leap sour"es from http:;;)ade.tila*."om
2. $npa"2 the sour"es some0here
(. Cuild JAD- Leap for J2S- follo0in% the instru"tion pro,ided 0ith JAD- sour"es. 'f the
*uild is su""essful9 a JadeLeap.jar file is a,aila*le.
B. Laun"h a JAD- Leap main "ontainer9 to%ether 0ith JAD- 7#A G$' issuin% the follo0in%
"ommand
java -cp <PATH_TO_JADE_LEAP>\JadeLeap.jar -Djade_domain_df_autocleanup=true
jade.Boot -gui
+lease note that the option -Djade_domain_df_autocleanup=true is ne"essary to "orre"tly
"leanup the D3 a%ent.
.
Using Android jChat 1!
Connecting to JA*+
he first step for usin% )&hat 1.( is the "onne"tion to a JAD- Leap main "ontainer runnin% on a
host ma"hine :lo"al or remote<. Please note that "differently from #$hat 1.%& efore connecting
to 'ade the screen (ill appear lack. )he G*+ ,-ALL ecome .isile only after a successful
connection to 'ade Leap.
he default host ma"hine and the port for the main "ontainer are spe"ified on strin%s.=ml file durin%
"ompilation :this is the default ,alue<.

Figure /
o "han%e these settin%s perform the follo0in% steps :see 3i%ure 1<:
1. +ress the MENU 2ey on the emulator
2. &hoose Settings
(. 'nsert the needed settin%s :host and port and phone number if empty<. Aou are also a*le
to sele"t the desired lo"ation pro,ider :on a real phone you "an use the G+S or the net0or2
if G+S is not a,aila*le9 on the emulator )ust sele"t %ps for the mo"2ed pro,ider<. 7emem*er
that the lo"alhost address on Android emulator is 10.0.2.2. )&hat 1.( shall no0 remem*er
the settin%s you "hoose in the Jade &onne"tion settin%s menu storin% them as a
preferen"e9 so you don@t ha,e to enter them any time you laun"h the appli"ation
B. +ress Close *utton
.. +ress the MENU 2ey on the emulator
6. &hoose Connect to Jade!
6
'f runnin% on a real phone remem*er that your host must *e ,isi*le throu%h the net0or2 used
:(G or 0ifi<.
'f the "onne"tion to Jade platform is su""essful you should *e a*le to see the ne0 a%ent
runnin% on Android emulator into Jade 7emote A%ent #ana%ement G$'.
Figure 0
he name of the ne0 a%ent should *e the same as the phone num*er of the phone.
8
,no-ing jChat 1! ta$s
he main s"reen is di,ided into t0o different ta*s9 pro,idin% "onta"ts information in different ,isual
0ays.
.he Contact ta$
Figure 1
he "onta"t ta* "ontains a list of all "urrently a,aila*le "onta"ts.
Any "onta"t "an *e online :"onne"ted to our JAD- Leap platform< or offline.
6nline "onta"ts are sho0n in *lue9 0hile offline "onta"ts are sho0n in red.
3or ea"h online "onta"t the distan"e in 2m *et0een the phone o0ner and the "onta"t is sho0n.
1
.he #ap ta$

Figure 2
he map ta* sho0s the position of ea"h online "onta"t on a map and "ontinuously updates their
position.
-a"h "onta"t is ,isi*le as a pin of different "olors: the phone o0ner "an see his o0n position as a
yello0 pin9 0hile others "onta"ts are sho0n as *lue pins.
#aps "an *e seen *oth in traditional map mode and in satellite mode: the user is a*le to s0it"h
*et0een the t0o modes usin% the s0it"h *utton pla"ed ri%ht a*o,e the map.
9
'ic/ing contacts
o *e a*le to "ommuni"ate 0ith others9 users must first sele"t "onta"ts :Dpi"2in%E<.
Aou "an pi"2 one or more "onta"ts in *oth "onta"t ta* and map ta*.
'n "onta"t ta*9 you ha,e to "li"2 on the "he"2*o= *eside ea"h "onta"t. 'n map ta* you simply "li"2
on the pin representation of the "onta"t.

Figure 3
+lease note that "onta"t sele"tion is lo"al to the map :you "annot *e%in sele"tin% "onta"t in a ta*9
then s0it"h to the other ta* and "ontinue sele"tion<.
After "onta"ts sele"tion9 you "an de"ide ho0 to intera"t *y pressin% for some se"onds the emulator
sele"tion *utton and "hoosin% the desired option from the "onte=t menu that 0ill popup.
Interacting -ith contacts
$sers "an "ommuni"ate 0ith "onta"ts in three 0ays: S#S9 phone "alls or "hat sessions.
10
"ending an "M" to one or #ore contacts
After "hoosin% to send an S#S messa%e9 user 0ill *e redire"ted to the S#S sendin% s"reen.
6*,iously a messa%e "an *e sent to more than one "onta"t at the same time.
Figure 4
Fere he 0ill *e a*le to enter the messa%e te=t and to send it.
#essa%e shall *e split into "hun2s if too lon% and sent to the desired "onta"t;s.
+lease note that at the moment the emulator does not support S#S sendin% emulation9 so nothin%
shall *e re"ei,ed. he S#S sendin% pro"ess is mo"2ed and it al0ays su""eeds. S#S sendin%
pro"ess is real on the G1 hard0are.
Ca((ing a contact
'f you "hoose to "all a "onta"t9 the "allin% s"reen shall appear and the "all shall start.
Figure 5
6*,iously9 the phone "all is totally mo"2ed on the emulator 0hile it is a real phone "all on the G1.
11
'f you try to "all more than one "onta"t at the same time :*y sele"tin% many "onta"ts and "hoosin%
Call from "onte=t menu< a messa%e shall appear 0arnin% that only one "onta"t "an *e "alled at
the same time.
"tarting a chat session
?e define chat session as a %roup of t0o or more "onta"ts tal2in% to%ether.
A "hat session "an *e started *y the phone o0ner :*y sele"tin% "onta"ts and "hoosin% Chat from
the "onte=t menu< or *y another "onta"t that 0ants to tal2 0ith the phone o0ner himself.

Figure 6
'f the user "hooses to start a "hat session9 the "hat s"reen shall appear. 'n this s"reen you 0ill *e
a*le to see the list of the other session parti"ipants9 to enter a te=t messa%e9 to send it and to see
a list of all the "on,ersation messa%es 0ith timin%s.
Using the status $ar to $ro-se chat sessions
?hene,er a "hat messa%e is re"ei,ed from another "onta"t9 a toast notifi"ation is sho0n and a
persistent notifi"ation is added to the status *ar. Also startin% a ne0 session adds a ne0 persistent
notifi"ation.
'n this 0ay the user "an s0it"h *et0een many different on%oin% "on,ersations *y usin% the status
*ar.
12
Figure 1%
hese are the re>uired steps:
1. Drop do0n the Android status *ar. he list of a"ti,e sessionsG notifi"ations shall appear.
+lease note that you@ll ha,e a notifi"ation for ea"h on%oin% "hat session9 it does not matter
0ho started the "on,ersation.
2. &hoose the session you@re interested in and "li"2 on its notifi"ation.
(. A ne0 "hat session shall start :or the session s0it"hes to the ne0 one if a "hat session 0as
already opened<
-a"h time a "on,ersation notifi"ation is sele"ted the "hat session is redra0n.
C(osing a chat session
o "lose a "hat session9 simply press the "ross *utton ne=t to the send *utton in the "hat s"reen.
Figure 11
1(
+lease note that the emulator@s BACK 2ey 0ill simply "lose the "hat s"reen *ut the session 0ill
remain open :all "on,ersation messa%es 0ill *e 2ept< and the user 0ill *e a*le to restore it *y
"hoosin% the notifi"ation on the status *ar.
After "hoosin% the "ross *utton the session 0ill *e remo,ed and all pre,iously sent messa%es 0ill
*e lost.
&1 speci0ic notes
All the sele"tion operations must *e performed *y tou"hin% the s"reen de,i"e. he lon% press
e,ent for sho0in% the &all;&hat;S#S menu must *e performed *y pressin% a sele"ted name for a
lon% time in the "onta"ts ta* and *y pressin% the tra"2*all in the map ta*.
Figure 1/
-nterin% te=t re>uires a rotation of the s"reen for usin% the 4?-7A 2ey*oard :G1 has no ,irtual
2ey*oard<.
?hen s"reen is rotated9 the hei%ht a,aila*le for lists of elements :messa%e list in the "hat or
"onta"ts list in the &onta"t ta*< is redu"ed.
Figure 10
'f you 0ant to see the full list "ontents9 you ha,e to s"roll *y mo,in% your fin%er up or do0n on the
s"reen.
1B
Co#pi(ing and signing jChat
'n order to "ompile )&hat you ha,e to "reate a ne0 Android +ro)e"t usin% -"lipse9 assumin% that
you ha,e installed the AD plu%in in your -"lipse en,ironment. $sin% the ne0 Android +ro)e"t
0i!ard9 sele"t the 7$reate from e8isting source9 and set the Location field to the dire"tory
0here you do0nloaded )&hat :i.e. &:Hmypro)e"tsH)&hat<. 3or further details on ho0 to "reate an
Android pro)e"t "an *e found on the Android site :http:;;"ode.%oo%le."om;android;inde=.html<.
After the pro)e"t has *een "reated9 you must set the follo0in% dependen"ies:
Pro#ectProperties'a.a :uild Path: sele"t the Liraries ta* then Add ;8ternal 'A<s
and mo,e to the )&hat dire"tory sele"t into the li* dire"tory the JadeLeapAndroid.)ar li*rary.
)&hat uses the #apIie0 in order to a""ess the Goo%le #aps data9 so 0e re%istered the #D.
fin%erprint of our de*u% "ertifi"ate9 used to si%n the )&hat appli"ation9 to o*tain a #aps A+' /ey.
hen the #aps A+' 2ey referen"e has *een added in the )&hat;res;layout;homepa%e.=ml in the
#apIie0 de"laration. ?hen you run or de*u% your appli"ation9 AD si%ns the .ap2 0ith the de*u%
"ertifi"ate and installs it on the emulator;phone. So if you 0ant to ena*le your )&hat pro)e"t to
a""ess the Goo%le #aps data you ha,e to:
7e%ister your de*u% "ertifi"ate to the Goo%le #aps ser,i"e follo0in% the instru"tions
pro,ided at the Android site :http:;;"ode.%oo%le."om;android;inde=.html< and then set your
#aps A+' /ey into the #apIie0 de"laration in Jyour+athK;)&hat;res;layout;homepa%e.=ml.
1A2
1.
Q: Can I have different instances of the emulator running jChat ?
A: 'f you 0ant to run different )&hat instan"es you still should use the "ommand:
emulator data <PATH_TO_IMAGE>\userdata2.img
Q: I launch the alication but !hen I choose Connect to "ade from the menu# the alication
hangs$ %h&?
A: +ro*a*ly you for%ot to laun"h a JAD- Leap main "ontainer. A main "ontainer is needed for the
appli"ation to start.
Q: 'ometimes I got a message sa&ing ()rror sending broadcast null* !hen closing the alication$
%h&?
A: his seems to *e a 2no0n *u% of Android emulator 0hen shuttin% do0n the lo"ation update.
16
L+&AL I3145MA.I43
.er#s and Conditions o0 use
)&hat is an open sour"e pro)e"t supported *y ele"om 'talia S.p.A. :Dele"om 'taliaE<.
Li#ited use
he ele"om 'talia lo%o displayed on this 0e*site is the property of ele"om 'talia: it "annot *e
used 0ithout the prior 0ritten "onsent of ele"om 'talia S.p.A.. he ele"om 'talia name or any
trademar2 in"ludin% the trademar2 -L-&6# 'AL'A "annot *e in"orporated into an 'nternet
Address 0ithout the prior 0ritten "onsent of ele"om 'talia S.p.A..
*isc(ai#er
he information on this 0e*site is pro,ided in %ood faith and ele"om 'talia *elie,es it to *e
a""urate. ele"om 'talia 0ill not under any "ir"umstan"es *e lia*le for any loss of in"ome9 profit9
*usiness9 "ontra"ts or %ood0ill or any indire"t or finan"ial loss suffered *y a party9 0hether arisin%
in "ontra"t9 ne%li%en"e or other0ise. he information on this 0e*site may in"lude typo%raphi"al
errors. 'nformation may *e "han%ed or updated 0ithout noti"e. ele"om 'talia may also ma2e
impro,ements and;or "han%es in the se"tions of this 0e*site 0ithout noti"e.
In0or#ation 0ro# you
Any materials sent to ele"om 'talia9 for e=ample *y e-mail or ,ia ?orld ?ide ?e* pa%es9 shall *e
deemed not "onfidential. ele"om 'talia shall ha,e no o*li%ation of any 2ind 0ith respe"t to su"h
materials and ele"om 'talia shall *e free to reprodu"e9 use9 dis"lose9 display9 transform9 "reate
deri,ati,e 0or2s and distri*ute the materials to others 0ithout limitation. 3urther9 ele"om 'talia
shall *e free to use any ideas9 "on"epts9 2no0-ho0 or te"hni>ues "ontained in su"h materials for
any purpose 0hatsoe,er9 in"ludin% *ut not limited to9 de,elopin%9 manufa"turin% and mar2etin%
produ"ts in"orporatin% su"h materials. Aou 0arrant that su"h materials are fit to pu*li"ation and
you a%ree to indemnify ele"om 'talia if any third party ta2es a"tion a%ainst ele"om 'talia in
relation to su"h materials.
La- and Jurisdiction
3or any dispute arisin% from these terms and "onditions and a"ti,ities "o,ered thereto the &ourt of
#ilan9 'taly9 shall ha,e not e="lusi,e )urisdi"tion and the 'talian la0s shall apply ele"om 'talia
nonetheless reser,es the ri%ht to ta2e le%al pro"eedin%s in "ountry other than 'taly9 to prote"t its
interests or to enfor"e its ri%hts 0hene,er it deems it appropriate to do so.
18