Net::Msmgr - Microsoft Network Chat Client Toolkit
This is the documentation for $Revision: 0.16 $
use Net::Msmgr; use Net::Msmgr::Sesssion; use Net::Msmgr::User; our $session = new Net::Msmgr::Session; our $user = new Net::Msmgr::User ( user => 'username@msn.com', password => 'my_password' ) ; $session->user($user); $session->login_handler( sub { shift->Logout } ) ; $session->connect_handler ( ... ) ; $session->Login;
This is a set of perl modules for encapsulating interactions with the Microsoft Network "Messenger" chat system. You might use it to develop clients, or robots. The components are, this module, Net::Msmgr, which contains some non-object helper routines (mostly the authentication chain for using MSNP8 (Protocol version 8) and a handful of manifest constants for debugging.
Other modules include:
Encapsulates the entirety of a session.
Holds user authentication credentials.
Used to hold command objects sent to or received from the servers.
Used to encapsulate server connections.
Derived from Net::Msmgr::Connection
A higher level view of conversation - contains (but is not) a Switchboard
Pure base class from which all of the others are derived. Direct from the perltoot manpage.
The entire protocol consists of a series of discrete messages that are passed between the client and the various servers that make up the system. Messages come in a variety of broad classes (Normal, Asyncronous, and Payload), and those are subdivided into more specific types (Transfer Requests, Chat Messages, State Change Notifications.)
There are three servers you will deal with during a basic session, the Dispatch Server, which is a meta server to distribute inbound sessions, the Notification Server, which will hold a single connection for the life of the session, and Switchboard Servers, which you will hold as many connections as you have chat groups active.
Technically, there is no difference between the Dispatch Server and the Notification Server, except that the Dispatch Server will (historically) always refer you to a Notification Server. There is nothing in the protocol to prohibit a Notification Server from ALSO refering you to a third Notification Server, although this author has never seen that happen.
Because of this, we tend to think of the DS and the NS as dissimilar entities, but there is no need for them to be so, and in the interest of flexibility they are treated the same. There is no limit, besides end-user patience to how many XFR messages you can receive.
This is the first-base server. Your minimum action here is to request a session, and act on the instructions from the server.
This is the center of your session, and when you have connected here, most (other) clients, and this library will consider you "connected" to MSN Chat.
To send or receive messages from other clients, there must be a connection to one or more Switchboard Servers. Each one of these connections is a 'party line', and all users currently connected to the same session (referenced by what the library calls a $ssid Switchboard Session ID) will see all messages sent by any user. The number of users that can be attached to a SSID appears to be reaosonably unlimited (on the order of dozens).
Here is a quick summary of all of the messages used in this library between the client and the servers.
Optionally sent from client to DS / NS for protocol version negotiation.
Optionally sent from client to DS / NS, asking what Encryption Technique to use. In MSNP7 and lower, it is always MD5. MSNP8 uses a different technique, but does not use this command to negotiate it. Go figure.
Used in two variants from client to server as part of the login procedure, in a slightly different variant from server to client as part of that same procedure, and again later during the authentication with Switchboard Servers.
Used in one variant from server to client as part of the login procedure, referring you from DS to NS. Used again later from client to server to request a connection to a switchboard server.
Sent from client to server to alter your 'presence' (online, out to lunch, etc.)
Sent from server to client in response to your first change to online status, with a list of visible users already on the system.
Optionally sent from client to server to request a download of all of your user lists.
Part of the bundle of information sent from server to client, it advises the client of a user-set preference for dealing with new users. It is stored on the server, but not acted on in any way. Can be sent as a command to the server to alter this setting.
Part of the bundle of information sent from server to client as part of a SYN. Used by the server to determine behavior if an unkonwn user attempts to invite you to a switchboard session.
Sent from server to client during SYN, and sent from client to server to change the settings. Designed to hold telephone numbers on the server in URI-encoded strings, and a few variants to hold some mobile device preferences.
Sent from server to client during SYN, and in resposne to a LST command. One variant for each of the four lists (Allow, Block, Forward and Reverse) the server maintains for each client.
Sent from client to server to add a user to a list. Echoed from server to client with new list serial-number. The server maintains this serial-number, such that the client may cache the list locally.
Sent from client to server to remove a user from a list.
Sent from client to server to change the Friendly Name associated with a user in your lists. Also used to change your own friendly name.
Sent from DS/NS server to client at login, and sometimes for administrative (shutdown) messages. Also, the core of what this protocol is about - sending messages to other users and receiving messages from other users via Switchboard Servers.
Sent from client to switchboard server in resposne to a switchboard invitation.
Sent from switchboard to client upon connection to a switchboard server informing client of other users attached to that switchboard session.
Sent from client to switchboard to invite another user to join the switchboard session.
Async command sent from client to NS/DS/SB server to terminate their session.
Async command sent from NS to client to advise of another user coming online.
Async command sent from NS to client to advise of another user going offline.
Async command sent from client to NS to make sure it is still there.
Async command sent from NS to client to acknowledge its presence.
Async command sent from NS to client to advise of another user inviting you to a Switchboard Session.
Async command sent from SB to client to advise of another user joining a Switchboard Session.
Async command sent from SB to client to advise of another user leaving a Switchboard Session.
Commands sent in the protocols come in three (and a theoretically possible fourth) variants. This library refers to them as Normal, Async, and Payload.
The vast bulk of commands are Normal, and each one is tagged with a numeric identifier by the client. This identifier will be used by the server to correlate its responses to your requests. This library does not currently verify any of these transaction identifiers (TRIDs), but does send each command with a unique monotonically-increasing number. Library users can feel free to use the TRID in Normal messages as a unique identifier, within the rules of the protocol. (That is: Sometimes a single Normal command from client to server will result in many related responses, all of which will contain the TRID of that single request).
Another block of commands are those sent from server to client in resposne to asyncronous events, such as users in your Forward List changing their status, invitations by other users to Switchboard Sessions, and users joining and leaving Switchboard Sessions.
The final type of command is that which contains message data. This library only (currently) supports one, the MSG command, which is used to encapsulate messages from server to client, and peer to peer.
The library user is responsible for dealing with non-blocking IO, and there are several ways you might do this. If you are writing a Perl/Tk you would probably use fileevent, or you might want to use Joshua Pritikin's Event package (which I use), or you can roll your own with select and poll. You could even use alarm and signals to periodically sweep all of the inbound sessions.
To help you with this, there are a pair of handlers in the Net::Msmgr::Session object, $session->connect_handler, and $session->disconnect_handler - which are called just after the TCP connect() call and just before the TCP close() call respectively.
Each of these will be called with a single pointer to the Net::Msmgr::Connection object.
It is the users' responsibility to call $connection->_recv_message whenever input is available on $connection->socket.
With Tk this would be something like
sub Connect_handler { my $connection = shift; $mainwindow->fileevent($connection->socket, 'readable', sub { $connection->_recv_message }); } $session->connect_hanlder(\&Connect_handler); $session->Login; MainLoop;
Under Joshua Pritikin's Event package, you might use
our %watcher; sub ConnectHandler { my ($connection) = @_; my $socket = $connection->socket; $watcher{$connection} = Event->io(fd => $socket, cb => [ $connection , '_recv_message' ], poll => 're', desc => 'recv_watcher', repeat => 1); } sub DisconnectHandler { my $connection = shift; $watcher{$connection}->cancel; } $session->connect_handler(\&ConnectHandler); $session->disconnect_handler(\&DisconnectHandler);
A third handler Net::Msmgr::Session::switchboard_handler() will be called with a Net::Msmgr::Connection object and an ssid for each switchboard session you are invited to, or instantiate through Net::Msmgr::Session::ui_new_switchboard().
1 POD Error
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head1'
To install Net::Msmgr, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::Msmgr
CPAN shell
perl -MCPAN -e shell install Net::Msmgr
For more information on module installation, please visit the detailed CPAN module installation guide.