view release on metacpan or  search on metacpan

lib/AnyEvent/MSN.pm  view on Meta::CPAN

raw headers (which contain a 'From' value).

=item C<on_error>

This callback is triggered when we meet any sort of non-fatal error. This
callback is passed a texual message for display.

=item C<on_fatal_error>

This callback is triggered when we meet an error which prevents normal client
operations. This could be a major SOAP error or even an unexpected disconnect.
This callback is passed a textual message for display.

=item C<on_user_notification>

    ...
    on_user_notification => sub { my ($s, $head, $presence) = @_; ... }
    ...

This callback is triggered when a contact updates their public information.
Simple Online/Offline status changes are included in this as well as friendly
name changes and current media (now playing) status.

=back

=item connect

Initiates the logon process. You should only need to call this if you passed
C<no_autoconnect =E<gt> 1> to L<the constructor|/new>.

=item im

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

This sends an instant message.

C<send_message( ... )> supports a third parameter, a string to indicate how
the message shoud be displayed. The default is
C<FN=Segoe%20UI; EF=; CO=0; CS=1; PF=0>. Uh, we break that down a little in
L<the notes|/"Text Format"> below.

=item 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 jiggle on
screen for a second. ...which, I suppose, won the contest for the most
annoying behaviour they could come up with.

=item add_contact

    $msn->add_contact('silas@live.com');   # Temporary
    $msn->add_contact('mark@hotmail.com'); # Persistant

This adds a buddy to your temporary list of contacts.

'Add List' command, uses XML to identify each contact, and works as a payload
message. Each ADL command may contain up to 150 contacts (a payload of roughly
7500 bytes). The format of the payload looks like this:
<ml l="1">
    <d n="domain">
        <c n="email" l="3" t="1" />
    </d>
</ml>
Elements:
ml: the meaning of l is unknown (thought to mean initial listing due to the
    fact that it is only sent in the initial ADL)
d (domain): contacts are grouped by domain, where n is the domain name (the
    part after the @ symbol in the email address)
c (contact): n is the name or the part before the @ symbol in the email
    address, l is the list bit flag (i.e. 1 for FL, 2 for AL, 4 for BL) and t
    is the contact type (1 for a Passport, 4 for a mobile phone, other values
    are still unknown)
Note: you can send all your contacts in just one ADL command by putting
    multiple 'd' elements (with the sub-elements of course) for each contact
    e.g.:
<ml l="1">
    <d n="domain1">
        <c n="email1" l="3" t="1" />
    </d>
    <d n="domain2">
        <c n="email2" l="5" t="4" />
    </d>
</ml>
Sending ADL to the server:
>>> ADL (TrId) (PayloadLength)\r\n
Then send your payload:
>>> <ml l="1"><d n="domain"><c n="email" l="3" t="1" /></d></ml>
The payload must not contain any 'whitespace' characters (i.e. returns, tabs or spaces) between tags or at the beginning or end, or the server will reply with error 240 or 241.
The server responds to a successful ADL command with:
ADL (TrId) OK
Initial ADL listing
Once the client has retrieved the contact list with a new set of SOAP requests (see MSNP13:Contact_List), it will send the information about the contacts on the list to the server with an ADL command. In this ADL, the <ml> node often seems to contain...
You must include everyone on your Forward List (FL), Allow List (AL) and Block List (BL). If you don't, anyone you fail to include will be removed from their respective lists. Also note that the official client does not include contacts on the RL and...
You MUST send your privacy settings (BLP command), then ADL and finally your display name (PRP command) in that order or the server will ignore your ADL. These are retrieved using the ABFindAll SOAP request.
After receiving ADL (TrId) OK, you must set your initial presence (CHG command). If you send CHG before ADL, the servers will not dispatch your presence to other clients.

=item remove_buddy

    $msn->remove_buddy('buddy@hotmail.com');

The remove contacts from your lists. Note that you may only remove people from
the FL, AL and BL using this command (which makes sense, seeing as you can
also only add people to the FL, AL and BL with the L<add_contact|/add_contact>
command). Also note that the contact will not be removed from your server-side
address book - for this, you will have to use the ABContactDelete SOAP
request. ...which we don't support yet.

=back

=head1 Notes

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

=head2 Online Status

Your online status not only affects your appearance on other's buddylists, but
can change how your buddies are shown.