NAME

Net::Msmgr::Connection

SYNOPSIS

 use Net::Msmgr::Connection;

 my $session = Net::Msmgr::Sesssion->new(....);
 my $connection = new Net::Msmgr::Connection;

 $connection->nserver( ip-address or hostname );
 $connection->nsport( 1863 );   # default port #
 $connection->name('Descriptive Name'); # used in debugging output
 $connection->session($session);        # associate with a session
 $connection->debug($debugflags);       # lots of options here
 $connection->connect;                  # open the connection
    

DESCRIPTION

Net::Msmgr::Connection is the encapsulation for a connection to an Net::Msmgr Dispatch Server, Notification Server, or Switchboard Server. It will instantiate Event watchers to empty the transmit queue as messages are sent through it, and dispatch messages as they are received from the network, calling a list of per-message handlers.

CONSTRUCTOR

 my $connection = new Net::Msmgr::Connection( ... );

        - or -

 my $connection = Net::Msmgr::Command->new( ... );

 Constructor parameters are:

nserver (optional)

The server to connect to. Defaults to messenger.hotmail.com, which is the current Dispatch Server.

nsport (optional)

The port to connect to. All transfer messages from the network will include a port, and you ought to honor them, but they appear to currently always be 1863, which is the default.

name (optional)

A descriptive name. It will show up from time to time in some debugging output. It defaults to 'Dispatch Server', which correlates to the default IP address.

session (mandatory)

Correlates the connection to the Net::Msmgr::Session in which it lives.

debug (optional)

See the manpage for Net::Msmgr.pm for the full list of debug flags and their meanings.

INSTANCE METHODS

$connection->shutdown;

Sends an 'OUT' message to the associated server, and marks the connection for closure.

$connection->close;

Immediately close this connection.

$connection->add_handler( $handler, @classes )

For each message in any of @classes, call the handler associated with $handler.

Message Handlers can be registered for each of the inbound messages. All message handlers are called with at least one parameter, the Net::Msmgr::Command object encapsulating the message. Optionally, you can at registration time add extra parameters to that list.

Handlers look like 'methodname' which will turn into a $session->methodname($command); If handler is an array ref, the first element is a session handler, and the following elements will be passed as the second through nth parameters to that handler. A handler 'nonmethod' exists to allow you to call arbitrary code.

An example:

  my $code = sub { my ($c,$t) = @_; print STDERR $t , $c->as_text } ; 
  $ns->add_handler( [ 'nonmethod', $code, 'test_handler' ] , 'QNG' );

$connection->connect;

Opens the connection, and sets up the Event watchers.