/ 
AnyEvent-MSN-0.001
River stage zero No dependents
/ AnyEvent::MSN

NAME

AnyEvent::MSN - Exactly what you're expecting...

Synopsis

use AnyEvent::MSN;
my $msn = AnyEvent::MSN->new(
    passport => 'you@hotmail.com',
    password => 'sekrit',
    on_im => sub { # Simiple echo bot
        my ($msn, $head, $body) = @_;
        $msn->im($head->{From}, $body)
    }
);
AnyEvent->condvar->recv;

Description

TODO

Methods

Well, the public bits anyway...

new
my $msn = AnyEvent::MSN->new(passport => 'you@hotmail.com', password => 'password');

This constructs a new AnyEvent::MSN object. Required parameters are:

passport

This is an email address.

Microsoft calls them passports in some documentation but I'm leaning towards the less odd 'username' for this in a future version of the API. Just... keep that in mind.

password

It's... your password.

Optional parameters to new include...

status

This will be used as your initial online status and must be one of the following:

NLN

Make the client appear Online (after logging in) and send and receive notifications about buddies.

This is the default.

FLN

Make the client Offline. If the client is already online, offline notifications will be sent to users on the RL. No message activity is allowed. In this state, the client can only synchronize the lists as described above.

HDN

Make the client appear Hidden/Invisible. If the client is already online, offline notifications will be sent to users on the RL. The client will appear as Offline to others but can receive online/offline notifications from other users, and can also synchronize the lists. Clients cannot receive any instant messages in this state.

BSY

Make the client appear Busy. This is a sub-state of NLN.

IDL

Make the client appear Idle. This is a sub-state of NLN.

BRB

Make the client say they'll Be Right Back. This is a sub-state of NLN.

AWY

Make the client appear to be Away from their computer. This is a sub-state of NLN.

PHN

Makes the client appear to be on the Phone. This is a sub-state of NLN.

LUN

Makes the client appear to be out to Lunch. This is a sub-state of NLN.

friendlyname

This sets the display or friendly name for the client. This is what your friends see on their buddylists.

personalmessage

This is the short message typically shown below the friendly name.

no_autoconnect

Normally, AnyEvent::MSN->new( ... ) automatically initiates the client login stage. If this is set to a true value, that doesn't happen and you'll need to call "connect" in connec yourself.

on_connect

This is callback is triggered when we have completed the login stage but before we set our initial status.

on_im

This callback is triggered when we receive an instant message. It is passed the raw headers (which contain a 'From' value) and the actual message.

on_nudge

This callback is triggered when we recieve a nudge. The callback is passed the raw headers (which contain a 'From' value).

on_error

This callback is triggered when we meet any sort of error. This callback is passed a texual message for display and an optional second argument which indicates that this is a fatal error.

connect

Initiates the logon process. You should only need to call this if you passed no_autoconnect => 1 to the constructor.

im
$msn->im('buddy@hotmail.com', 'oh hai!');

This sends an instant message.

c<im( ... )> supports a third parameter, a string to indicate how the message shoud be displayed. The default is FN=Segoe%20UI; EF=; CO=0; CS=1; PF=0. Uh, let's break that down a little.

The message format specifies the font (FN), effect (EF), color (CO), character set (CS) and pitch and family (PF) used for rendering the text message.

The value of the Format element is a string of the following key/value pairs:

FN

Specifies a font name. The font name must be URL-encoded. For example, to have a font of "MS Sans Serif", you would have to specify FN=MS%20Sans%20Serif. Font names are not case-sensitive and only spaces should be URL-encoded. URL-encoding other characters such as numbers and letters cause unpredictable results in other clients.

According to MS, if the receiving client does not have the specified font, it should make judgment based on the PF and CS parameters. Basically, the client should select whichever available font supports the character set specified in CS and is closest to the category specified in PF. If those parameters are not present, the client should just use a default font.

EF

Specifies optional style effects. Possible effects are bold, italic, underline, and strikethrough. Each effect is referred to by its first letter. For example, to make bold-italic text, include the parameter EF=IB or EF=BI. The order does not matter. Any unknown effects are to be ignored. If there are no effects, just leave the parameter value blank.

CO

Specifies a font color. The value of the CO field is a six-character hex BGR (Note that this is blue-green-red, the reverse of the standard RGB order seen in HTML) string. The first two characters represent a hex number from 00 to ff for the intensity of blue, the second two are for green, and the third two are for red. For example, to make a full red color, send CO=0000ff.

Again, this should be in BGR; the reverse of the standard RGB order seen in HTML.

CS

Character sets are identified in the CS parameter with one or two hexadecimal digits (leading zeros are dropped by the official client and are ignored if present), representing the numerical value Windows uses for the character set. The following table shows the full list of the predefined character sets that are included with the Microsoft® Windows® operating system.

Val Description
-------------------------------------------------------------------------
00  ANSI characters
01  Font is chosen based solely on name and size. If the described font is
    not available on the system, you should substitute another font.
02  Standard symbol set
4d  Macintosh characters
80  Japanese shift-JIS characters
81  Korean characters (Wansung)
82  Korean characters (Johab)
86  Simplified Chinese characters (China)
88  Traditional Chinese characters (Taiwan)
a1  Greek characters
a2  Turkish characters
a3  Vietnamese characters
b1  Hebrew characters
b2  Arabic characters
ba  Baltic characters
cc  Cyrillic characters
de  Thai characters
ee  Sometimes called the "Central European" character set, this includes
    diacritical marks for Eastern European countries
ff  Depends on the codepage of the operating system

You should not assume that clients receiving your messages understand all character sets. This character set is arbitrary, but it is advisable to make it the one that causes the most characters to be displayed correctly.

PF

The PF family defines the category that the font specified in the FN parameter falls into. This parameter is used by the receiving client if it does not have the specified font installed. The value is a two-digit hexadecimal number. If you're familiar with the Windows APIs, this value is the PitchAndFamily value in RichEdit and LOGFONT.

The first digit of the value represents the font family. Below is a list of numbers for the first digit and the font families they represent.

First Digit     Description
-------------------------------------------------------------------------
0_              Specifies a generic family name. This name is used when
                information about a font does not exist or does not
                matter. The default font is used.
1_              Specifies a proportional (variable-width) font with
                serifs. An example is Times New Roman.
2_              Specifies a proportional (variable-width) font without
                serifs. An example is Arial.
3_              Specifies a Monospace font with or without serifs.
                Monospace fonts are usually modern; examples include Pica,
                Elite, and Courier New.
4_              Specifies a font that is designed to look like
                handwriting; examples include Script and Cursive.
5_              Specifies a novelty font. An example is Old English.

The second digit represents the pitch of the font — in other words, whether it is monospace or variable-width.

Second Digit    Description
-------------------------------------------------------------------------
_0              Specifies a generic font pitch. This name is used when
                information about a font does not exist or does not
                matter. The default font pitch is used.
_1              Specifies a fixed-width (Monospace) font. Examples are
                Courier New and Bitstream Vera Sans Mono.
_2              Specifies a variable-width (proportional) font. Examples
                are Times New Roman and Arial.

Below are some PF values and example fonts that fit the category.

Examples of PF Value    Description
-------------------------------------------------------------------------
12                      Times New Roman, MS Serif, Bitstream Vera Serif
22                      Arial, Verdana, MS Sans Serif, Bitstream Vera Sans
31                      Courier New, Courier
42                      Comic Sans MS
nudge
$msn->nudge('buddy@hotmail.com');

This sends a nudge to the other person. It's called nudge in the protocol itself and in pidgin but in the the official client it's called 'Attention' and may (depending on the buddy's settings) make the IM window giggle around the screen for a second. ...which, I suppose, won the contest for the most annoying behaviour they could come up with.

Notes

This is where random stuff will go. The sorts of things which may make life somewhat easier for you but are easily skipped.

TODO

These are things I have plans to do with AnyEvent::MSN but haven't found the time to complete them. If you'd like to help or have a suggestion for new feature, see the project pages on GitHub.

P2P Transfers

MSNP supports simple file transfers, handwritten IMs, voice chat, and even webcam sessions through the P2P protocol. The protocol changed between MSNP18 and MSNP21 and I'll need to implement both. ...I'll get to it eventually.

Group Chat

MSNP21 redefinied the switchboard concept including how group chat sessions are initiated and handled.

Internal State Cleanup

Things like the address book are very difficult to use because (for now) I simply store the parsed XML Microsoft sends me.

Correct Client Capabilities

They (and a few other properties) are all hardcoded values taken from MSN 2011 right now.

See Also

Net::MSN
MSN::PersonalMessage
POE::Component::Client::MSN
Net::Msmgr::Session

Author

Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/

CPAN ID: SANKO

License and Legal

Copyright (C) 2011 by Sanko Robinson <sanko@cpan.org>

This program is free software; you can redistribute it and/or modify it under the terms of The Artistic License 2.0. See the LICENSE file included with this distribution or notes on the Artistic License 2.0 for clarification.

When separated from the distribution, all original POD documentation is covered by the Creative Commons Attribution-Share Alike 3.0 License. See the clarification of the CCA-SA3.0.

Some protocol descriptions taken from text Copyright 2011, Microsoft.

Neither this module nor the Author is affiliated with Microsoft.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 1225:

Non-ASCII character seen before =encoding in 'Microsoft®'. Assuming UTF-8