273
17
www.cod
e
-m
a
g
a
z
in
e
.com
Liv
e
from th
e
W
e
b! Bring th
e
Windows Liv
e
M
e
ss
e
ng
e
r
E
xp
e
ri
e
nc
e
to Your W
e
b Applic
a
tions
NOTE:
A
t
t
h
e
t
ime
of
t
h
is
w
r
i
t
i
n
g,
t
h
e
Messe
n
ge
r
Lib
r
a
r
y
was
s
t
ill
i
n
be
t
a
a
n
d
n
o
t
ye
t
r
eleased.
Fo
r
t
h
e
la
t
es
t
s
t
a
t
u
s
a
n
d
SDK
u
pda
t
es
please
go
t
o
dev.
live.com
/
messe
n
ge
r
.
Using this SDK you can reproduce the messag-
ing functionality of Windows Live Messenger on
the Web or customize it to fi t the business driv-
ers of the hosting Web application. The Messen-
ger Library does not replace the functionality of
the IM control since it does not support anony-
mous conversations, but it does make it possible to
build a rich experience for existing Windows Live
users with some very powerful customization pos-
sibilities.
Why would you want to replicate messenger (cus-
tomized or not) on the Web
?
First and foremost it
defi nitely increases the stickiness of your Web appli-
cation if visitors can interact with their social network
without navigating away from the Web page to open
the messenger client. In particular for full-screen ex-
periences such as online videos or games, accessing
the chat window in place is also a huge convenience.
Another important benefi t is the instant social net-
work that is available through the Windows Live ID
contact list of a signed-in visitor. This simplifi es life
for the visitor since their existing contacts are im-
mediately available to them—rather than building a
new network for the Web application, they have an
instant network in their Windows Live ID contacts.
This also opens the door to interesting possibilities
for the Web application to provide functionality to
interact with that network.
The coming sections will explore the richness of this
SDK, explain how to get set up to use it, and show
you how to use the key features available to your
Web applications that employ it.
D
eveloping with the Messenger Library
The Windows Live Messenger Library is a client-
side library written in JavaScript. Thus, any page in
your Web application that leverages the Messenger
Library must import messenger.js as follows:
<script src="http://settings.messenger.live.com/
api/1.0/messenger.js" type="text/javascript"
language="javascript"></script>
From here, your job is to write code in JavaScript
to access the features and functionality of the li-
brary. For example, to add the SignInControl
from the Messenger Library to a Web page, you
would include both the Messenger Library script
and another script containing a function to load
the control. In the following example, when the
page loads, it calls
A
uthenticateUser() from the
custom JavaScript library, MyMessengerScriptLi-
brary.js:
<body onload="AuthenticateUser()">
<script src="http://settings.messenger.live.com/
api/1.0/messenger.js" type="text/javascript"
{
"status": "[messenger status]",
"icon": {
"height": 16,
"url":
"http://settings.messenger.live.com/static/w13r2
/Conversation/img/[status icon fi lename].gif",
"width": 16
},
"statusText": "[localized messenger status]",
"id": "[messenger id]@apps.messenger.live.com",
"displayName": "[messenger display name]"
}
The best way to work with the JSON response is to
provide a callback script function that can process
the presence details. Lis
t
i
n
g
2 shows an example of
this.
Why display the status of a user visiting your site
?
A
perfect example is a social networking site that uses
Web signup to register users for their own personal
space, and then subsequently stores their messenger
ID to provide a personalized experience for the user.
When they log in to their personal space on the Web,
the application can show their messenger status (us-
ing the presence API) and provide a link to the IM
window (using the IM control). This allows others
visiting their personalized page to chat with them! In
fact, Lis
t
i
n
g
1 shows this in the HTML for the button
representation of the IM control.
K
i
ck
i
t up a
N
otch w
i
th the W
i
ndows
L
i
ve Messenger
L
i
brary
Based on the discussion thus far, you should gather
that the Windows Live Messenger IM Control pro-
vides a quick and easy way for non-developers to en-
able their presence on the Web and is particularly
useful for chatting with anonymous visitors. The
Windows Live Messenger Presence API provides a
way for visitors to log into their Windows Live ID ac-
count and identify themselves to the IM control and
to the host application for personalization. Together
these products enable interaction with a particular
messenger account, specifi ed by the invitee, and al-
low non-Windows Live users to send messages with-
out installing the Windows Live Messenger Client.
The Windows Live Messenger Library extends this
functionality by providing a rich SDK to build a cus-
tomized messenger client on the Web. The features
supported by the Messenger Library include:
A simple sign-in control for authenticating mes-
•
senger accounts.
Access to the signed-in user’s online presence
•
for personalization.
Access to the signed-in user’s contact list and
•
groups to replicate Messenger client functional-
ity on the Web.
A rich API for programmatically interacting
•
with the signed-in user’s contact list and groups;
for sending and receiving messages; and for in-
teracting with conversations.
417
18
www.cod
e
-m
a
g
a
z
in
e
.com
Liv
e
from th
e
W
e
b! Bring th
e
Windows Liv
e
M
e
ss
e
ng
e
r
E
xp
e
ri
e
nc
e
to Your W
e
b Applic
a
tions
The Importance of
Pr
i
vacy Po
l
i
c
i
es
As th
e
y s
a
y: with gr
e
a
t pow
e
r
a
lso com
e
s gr
e
a
t r
e
sponsibility.
Th
e
priv
a
cy policy of th
e
Windows Liv
e
M
e
ss
e
ng
e
r
Libr
a
ry
e
xplicitly forbids th
e
us
e
of th
e
inform
a
tion
a
v
a
il
a
bl
e
through th
e
SDK for SPAM
ov
e
r IM (SPIM).
C
e
rt
a
inly
a
ny
sit
e
s th
a
t misus
e
this pow
e
r
will swiftly b
e
bl
a
cklist
e
d or
b
e
com
e
soci
a
l outc
a
sts.
Thus W
e
b
a
pplic
a
tions th
a
t
l
e
v
e
r
a
g
e
th
e
Windows Liv
e
M
e
ss
e
ng
e
r Libr
a
ry must
provid
e
v
e
ry cl
e
a
r priv
a
cy
polici
e
s
a
nd us
e
e
thic
a
l
busin
e
ss pr
a
ctic
e
s
a
s th
e
y
int
e
r
a
ct with th
e
inform
a
tion
a
v
a
il
a
bl
e
to th
e
m.
Messenger Library. Call those functions from
any Web page in the dependent application.
Copy the .js output of the compiled Script
#
li-
•
brary to the Web application that will use the
library. You can automate this with a post build
step for convenience.
As for the coding experience, the previous code snip-
pet for the JavaScript function named authentica-
teUser() would look like this in the Script
#
library:
namespace MyMessengerScriptLibrary
{
public class Authentication
{
public static void authenticateUser()
{
SignInControl signinControl = new
SignInControl("divSignIn",
"http://.../PrivacyPolicy.htm",
"http://.../Channel.htm", "");
}
}
}
To call this from a Web page, import the Script
#
library JavaScript fi le:
<script
src="App_Scripts\MyMessengerScriptLibrary.js"
type="text/javascript"
language="javascript"></script>
To trigger the authenticateUser() JavaScript function
when a Web page is loaded, you use the fully quali-
fi ed function name which includes the namespace
and class name:
<body onload=
"MyMessengerScriptLibrary.Authentication.
authenticateUser()">
NOTE:
Keep
in
mind
t
ha
t
a
t
t
he
t
ime
of
t
his
w
r
i
t
-
ing,
t
he
Sc
r
ip
t
#
compile
r
changes
Pascal
case
func
t
ion
names
t
o
Camel
case
names.
In this article, all code to work with the Messenger
Library is written in a Script
#
library, and thus will
be illustrated in C
#
using the steps just described.
The compiled JavaScript is ultimately what Web
pages invoke at run time—and given the richness
of the Messenger Library, using Script
#
is the key
to developer productivity. The Windows Live Mes-
senger Library is a substantive library with over 70
classes for building Messenger-enabled applications.
The remainder of this article will discuss three key
scenarios related to working with users and sign in,
contacts, and conversations.
Signing In and Working with
U
sers
To leverage the power of the Messenger Library, you
must fi rst gain access to a user account. The library
includes a single UI component, the SignInControl,
language="javascript">
</script>
<script
src="App_Scripts\MyMessengerScriptLibrary.js"
type="text/javascript" language="javascript">
</script>
<div id="divSignIn">
</div>
</body>
Inside MyMessengerScriptLibrary.js is the following
JavaScript function creating a SignInControl instance
passing the required parameters (to be discussed):
function AuthenticateUser()
{
signinControl = new
Microsoft.Live.Messenger.UI.SignInControl(
'divSignIn',
'http://…/PrivacyPolicy.aspx',
'http://…/Channel.aspx', '');
}
Although Visual Studio 2008 introduces support for
JavaScript debugging, which is fantastic for script
writers, building a complete library of functionality
in JavaScript is usually a cumbersome process given
the lack of rich IntelliSense and lack of knowledge
for the correct syntax. Fortunately, there is a product
called Script
#
that signifi cantly improves your pro-
ductivity for building rich JavaScript functionality for
your ASP.NET applications.
T
urning
C
#
D
evelopers into Scripting Ninjas
with Script#
Client-side scripting is a necessity with today’s AJAX-
enabled applications—and working with the Messen-
ger Library adds yet another reason for developers
to learn JavaScript. The problem is that many server-
side developers fi nd client-side scripting to be some-
thing of a dark art. The coolest thing about Script
#
is
that C
#
developers can implement JavaScript with-
out writing JavaScript!
Script
#
is a C
#
compiler (at the time of this writ-
ing Visual Basic support does not exist) that gen-
erates JavaScript instead of MSIL. When you in-
stall Script
#
, it integrates into the Visual Studio
IDE so that you can write libraries of functions in
C
#
that are then compiled into JavaScript for deploy-
ment with your Web application. Here is a summary
of the steps necessary to create a Script
#
library:
Install Script
#
, which also installs several Visu-
•
al Studio templates for creating script libraries.
Create a new project using the Script
#
Class
•
Library template. For convenience, include this
project in a solution that also contains your
Web application.
Add a reference to Microsoft.Live.Messenger.
•
dll, the core assembly containing the Messenger
Library metadata.
Begin writing C
#
functions to interact with the
•
470
19
www.cod
e
-m
a
g
a
z
in
e
.com
Liv
e
from th
e
W
e
b! Bring th
e
Windows Liv
e
M
e
ss
e
ng
e
r
E
xp
e
ri
e
nc
e
to Your W
e
b Applic
a
tions
tication (see Figu
r
e
7). If they choose to be automati-
cally signed in, Windows Live ID Web Authentication
(http://de
v
.li
v
e.
c
om/li
v
eid) is used to authenticate the
user with the Windows Live ID cookie stored on the
machine.
NOTE:
Windows
Live
ID
Web
Au
t
hen
t
ica
t
ion
is
a
f
r
ee
p
r
oduc
t
you
can
also
employ
in
you
r
Web
applica
t
ions
t
o
au
t
hen
t
ica
t
e
use
r
s
t
o
you
r
si
t
e
using
t
hei
r
Windows
Live
ID
accoun
t
s,
ins
t
ead
of
employing
a
cus
t
om
au
t
hen
t
ica
t
ion
mechanism.
While the SignInControl does provide core function-
ality for authentication, to fully leverage the Messen-
ger Library you will have to write code to interact
with the authentication process. Lis
t
ing
3 includes
the code necessary to create the SignInControl, in-
teract with the authentication process, access the au-
thenticated user’s identity, and, post sign in, access
which handles authentication of users against the
Windows Live ID domain. Once it authenticates the
user, you can gain access to the user identity and in-
teract with the sign-in and sign-out process for that
user. In addition, through the user identity you can ac-
cess many other details related to the user’s Windows
Live ID account—which makes it possible to replicate
the messenger client in a customized Web interface.
To add Windows Live ID sign-in functionality to a
page, create an instance of the SignInControl located
in the Microsoft.Live.Messenger.UI namespace of the
Messenger Library. The control constructor has four
parameters:
con
t
r
olId
•
: The name of the <div> on the page
where the control should be rendered.
p
r
ivacyS
t
a
t
emen
t
U
r
l
•
: The URL of the Web ap-
plication’s privacy policy, explaining how the
application will use the user’s account details.
channelU
r
l
•
: A URL for a page containing
JavaScript for safe cross-site scripting. See fol-
lowing reference for more details on how this
secures communication between third-party
sites and the Windows Live ID domain: http://
m
s
dn2.mi
c
ro
s
oft.
c
om/en-u
s
/librar
y
/bb735305.a
s
p
x
.
ma
r
ke
t
•
: An optional culture code specifying
which culture the control should use to display
text.
You must write the code to create the SignInControl
inside a JavaScript function called by the page (most
likely during load)—as discussed in the previous sec-
tion. The UI representation of the SignInControl is
shown in Figu
r
e
6. The user is presented with a Sign
In button, which sends the user to the Windows Live
ID login page. If the user has never signed in and
saved a Windows Live ID cookie to the machine,
they will be asked to log in as shown in Figu
r
e
6. If
they have previously logged in and allowed their last
authentication to be remembered, the SignInControl
indicates that the user is already signed in.
The fi rst time that the user authenticates to Windows
Live ID with their account, they are provided with
a page where they can adjust their sign-in settings.
Specifi cally, this determines if the user wants to be
automatically or manually signed in for future authen-
About
S
cr
i
pt#
Script# is
a
w
e
ll docum
e
nt
e
d,
w
e
ll m
a
int
a
in
e
d,
a
nd w
e
ll
support
e
d product—
a
nd th
e
b
e
st p
a
rt is th
a
t is it
F
R
E
E
!
Script# w
a
s cr
e
a
t
e
d by Nikhil
Koth
a
ri,
a
softw
a
r
e
a
rchit
e
ct
within th
e
D
e
v
e
lop
e
r Division
a
t Microsoft. At th
e
tim
e
of
this writing, Script# V
e
rsion
4.5.0 h
a
s b
e
e
n r
e
l
e
a
s
e
d
a
nd is
comp
a
tibl
e
with Visu
a
l Studio
2005
a
nd 2008.
You c
a
n downlo
a
d Script#
a
nd
r
e
a
d mor
e
a
bout th
e
product
a
t
this sit
e
:
http://www.ni
k
hil
k
.net/
S
c
riptSharpIntro.a
s
p
x
Figure 6: Th
e
SignIn
C
ontrol
(shown l
e
ft)
a
llows us
e
rs to
log in to th
e
ir Windows Liv
e
a
ccount
a
t th
e
login.liv
e
.com
sit
e
(shown right).
Figure 7: Us
e
rs h
a
v
e
a
n opportunity to confi gur
e
th
e
ir sign-in s
e
ttings with Windows Liv
e
ID. Th
e
W
e
b sit
e
cl
e
a
rly st
a
t
e
s wh
a
t th
e
r
e
qu
e
sting host
a
pplic
a
tion will h
a
v
e
a
cc
e
ss to
a
nd provid
e
s
a
link
to th
e
priv
a
cy policy sp
e
cifi
e
d in th
e
SignIn
C
ontrol constructor.
261
20
www.cod
e
-m
a
g
a
z
in
e
.com
Liv
e
from th
e
W
e
b! Bring th
e
Windows Liv
e
M
e
ss
e
ng
e
r
E
xp
e
ri
e
nc
e
to Your W
e
b Applic
a
tions
interact with messaging conversations with a particu-
lar set of contacts.
Working with
C
ontacts
After a user logs in using the SignInControl, you can
access the user’s contact list through the User in-
stance. The User class exposes three collection prop-
erties to access the user’s contact list:
Con
t
ac
t
s:
•
A ContactCollection containing all
contacts in the list.
AllowedCon
t
ac
t
s:
•
A ContactCollection con-
taining only allowed contacts.
BlockedCon
t
ac
t
s:
•
A ContactCollection con-
taining only blocked contacts.
You can use any of these ContactCollection instances
to access a list of contacts as follows:
foreach (Contact c in userAccount.Contacts){…}
foreach (Contact c in
userAccount.AllowedContacts){…}
foreach (Contact c in
userAccount.BlockedContacts){…}
To organize contacts according to the groups they
are associated with, you can also access a ContactC-
ollection exposed by the Groups property of the User
instance:
user’s account details. Table
1 explains the purpose
of each function shown in the listing.
Essentially, you must hook the SignInControl’s Au-
thenticationCompleted event in order to do anything
useful with the user’s account. This provides you with
access to the user identity, which you can use to create
an instance of the User class from the Microsoft.Live.
Messenger namespace. This class is the root of the
object model for the user’s account details including
account settings, presence, contacts, conversations,
and messaging. Before signing the user in, hook the
SignInCompleted event of the User type so that you
can verify a successful sign in prior to accessing prop-
erties of the user instance. You must also invoke the
SignIn() function for the user instance to complete
the sign-in process. The SignInCompleted event is
fi red once the user completes sign in—passing a result
of Success or Failure.
In Lis
t
ing
3, displayAccountDetails() is called upon
successful sign in to update the page display and show
account information. This listing shows only a subset
of what the code sample illustrates, but Table
2 lists
the type of information accessible through the User
class hierarchy. Most of the functionality in a messen-
ger-enabled application can trace its roots back to the
User class. Beyond sign-in and sign-out functionality,
through this class you can access and modify proper-
ties of the user account such as DisplayName, Dis-
playPictureUrl, Status, and PersonalMessage; access
the contact list; interact with the user’s mailbox to
add Web e-mail functionality to a site; and create and
F
u
n
c
t
i
o
n
N
a
m
e
D
e
s
c
ri
p
t
i
o
n
authenticateUser()
Creates the SignInControl and hooks its AuthenticationCompleted event so that you can
retrieve the user identity during sign in.
signinControl_
AuthenticationCompleted()
Creates an instance of the User from the identity passed in; hooks the SignInCompleted
event so that you can verify the status of the sign in; and invokes the SignIn() function to
complete the sign-in process.
userAccount_SignInCompleted()
Verifi es the success or failure of the sign-in process and, if successful, displays the user
account’s details.
displayAccountDetails()
Accesses the user account’s details through the User object model.
Table 1: Th
e
functions us
e
d to h
a
ndl
e
SignIn
C
ontrol
a
uth
e
ntic
a
tion
a
nd
a
cc
e
ss to us
e
r
a
ccount d
e
t
a
ils.
C
a
t
e
g
o
r
y
D
e
s
c
ri
p
t
i
o
n
Sign in and Sign out
Functions to sign in or sign out and events to interact with the process providing access to the user identity.
Account settings
Properties to interact with account settings related to privacy mode, the existence of a mailbox or special
features such as mobile messaging, and other settings such as the ability to update the display name of the
account.
Account details
Properties to interact with address settings, address capabilities, online status, presence details including
display name and IM address, and the user’s identity.
Contacts
Access to the user’s contacts collection, the ability to add new contacts and access contact details, access to
contact groups, and functionality to send messages to contacts.
Conversations
Functionality supporting creating new conversations with contacts, sending and receiving messages, and
interaction with message generation and formatting.
Table 2: A high-l
e
v
e
l look
a
t th
e
pow
e
rful f
e
a
tur
e
s
a
v
a
il
a
bl
e
through th
e
Us
e
r typ
e
in th
e
Windows Liv
e
M
e
ss
e
ng
e
r Libr
a
ry.
Documents you may be interested
Documents you may be interested