Developer's arena TRex::SendRecv

NAME

TRex::SendRecv - provides message sending and retrieval

SYNOPSIS

    use TRex::SendRecv;

DESCRIPTION

This module is intended as an abstraction layer presented to the core for any messaging system (e-mail, instant messaging, pager, etc.) to make it indepenmdent of any subyacent technology. One example this one is the many e-mail sending and retrieving technologies (e.g. POP3 to receive and SMTP to deliver messages), where are presented as a unique method for sending and receiving, but each implementation is quite different.

First sight

We only define here the basic functionality, just to make it simple to use and flexible and dynamic in the background

Based on these generic assumptions, the next methods will be used:

• new: initiates the relationship between the program and the message handling mechanism
  
• open: creates the relationship with the subyacent protocols
  
• close: closes the relationship with the subyacent protocols and the message handling mechanism
  
• retrieve: reads the next incoming messages
  
• send: sends a message
  
• delete: deletes the passed message (only in the incoming message server)
  

Implementation details

As explained, each object has methods (open, close, retrieve, send, etc.) to manipulate data in the data storage, whose interface (and usage) is defined in the following paragraphs.

Returned values

A note, before starting with the methods, is that all methods return a non-zero value to signal an error, and zero when the operation was successful.

The non-zero value, indicating an error, varies for each method except for the value ``1''. When this is returned, it means that an ``unspecified error'' has occured. This is also used when an error has occurred, and it has not corresponding error number assigned or belongs to an internal one.

METHODS

new(%)

This is the constructor, and returns a new handler. A value ``undef'' is returned in case a constructor founds problems. The corresponding new() method for each protocol interface only should set init parameters, and make not connection with the server.

Usage :

  use TRex::SendRecv;

  my $errMsg;  ## Error messages

  my $handler = TRex::SendRecv->new( url => YIM://messenger.yahoo.com:2219,
                                     Timeout => 100,
                                     Error => \$errMsg );
  die "Crashhhh new(), with error $errMsg !!!\n"  if ( ! defined $handler );

As you can see some parameters can be passed to new(). This one is a list of them :

• Timeout: Maximum time, in seconds, to wait for a response from the incoming and outgoing messages server (If you specify Timeout is equivalent to specify the same value for TimeoutRecv and TimeoutSend). The default is 120 seconds.
  
• TimeoutRecv: Maximum time, in seconds, to wait for a response from the incoming messages server
  
• TimeoutSend: Maximum time, in seconds, to wait for a response from the outgoing messages server
  
• url: protocol://name:port of the server to connect for messages retrieval and sending.(If you specify url is equivalent to specify the same value for urlRecv and urlSend). The default is smtp://localhost:25 for sending and pop3://localhost:110 for receiving.
  
• urlRecv: protocol://name:port of the server to connect for incoming messages retrieval
  
• urlSend: protocol://name:port of the server to connect for outgoing messages sending
  
• errMsg : reference to a scalar for error message retrieval
  

close()

Closes the relationship with the subyacent protocols and the message handling mechanism

Usage :

  use TRex::SendRecv;

  die "Crashhhh close(), with error $errMsg !!!\n"
      if ( ! $handler->close() );

open()

Initiates the connection with the subyacent protocols

The code returned are the ones specified in the ``Returned values'', plus :

• the value ``E_OPEN'' in case fails to open the send or receive module
  

Usage :

  use TRex::SendRecv;

  my $handler = TRex::SendRecv->open();
  die "Crashhhh open(), with error $errMsg !!!\n"
      if ( ! $handler->open() );

capabilities()

Queries the subyecent protocol implementations about its capabilities. A capabilities hash is returned (whose reference is passed as ``capa'' parameter) in which one key for each present capability is returned, plus an AUTH key containing one key for each valid authentication method pointing to an array containing the parameters to be passed to the auth() method.

Example: a receive protocol supporting UIDL and USERPASSWORD auth method and a sending protocol allowing a new auth mechanism (NEW) using three parameters to authenticate (USER1, PASS2 Y PASS3) and the MIME capability will conform the next capabilities hash :

         $capa->{'Recv'}->{'UIDL'} 
         $capa->{'Recv'}->{'AUTH'}->{'LOGINDISABLED'}
         $capa->{'Send'}->{'MIME'} 
         $capa->{'Send'}->{'AUTH'}->{'NEW'}->['USER1','PASS2','PASS3']

The code returned are the ones specified in the ``Returned values'', plus :

• the value ``E_CAPA'' in case fails to open the send or receive module
  
• the value ``E_HASH'' in case the capabilities hash reference is not passed as parameter
  

Usage :

  use TRex::SendRecv;

  my %capa; ## Capabilities hash

  my $handler = TRex::SendRecv->capabilities( capa => \%capa);
  die "Crashhhh capabilities(), with error $errMsg !!!\n"
      if ( ! $handler->capabilities() );

Developer's arena TRex::SendRecv