Developer's arena TRex::SendRecv::nullRecv

NAME

TRex::SendRecv::nullRecv - message retrieval internal API

SYNOPSIS

    use TRex::SendRecv::nullRecv;

DESCRIPTION

This documentation is about the internal TRex API for messaging protocols implementers, and TRex::SendRecv::nullRecv is the reference implementation just for the ones that hadle messages receiving (truly TRex::SendRecv::nullRecv is used when no receive protocol is specified when using TRex::SendRecv, the send and receive messages API).

This one allows to extend TRex sending/receiving capabilities to any protocol without modifying TRex core code.

First sight

Each messaging protocol, basically, needs an initialization (new) followed by message sending (send) and finally protocol ending (close). Based on these generic assumptions, the methods names to be used are the ones enclosed in parenthesis : new(), send() and close().

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 values passed are the host name ($hostname) and hash parameters

Usage :

  use TRex::SendRecv::nullRecv;

  my $handler = TRex::SendRecv::nullRecv->new( $hostName, 
                                               Timeout => 100,
                                               Port => 666,
                                               Error => \$errorString );

  die "Crashhhh in new(), Error --> $errorString !!!\n"
      if ( ! defined $handler );

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

• Timeout: Maximum time, in seconds, to wait for a response from the incoming and outgoing messages server
  
• Port : the port number to be used for connection
  
• Error : a scalar reference to an error string. It can already contain some information, so don't assign a string to it in case of an error, append the error message to the beginning
  

capabilities()

Retreves the service capabilities as a string, whose format is defined as follows (adapted from IMAP protocol, RFC3501) :

The CAPABILITY response occurs as a result of a CAPABILITY command. The capability listing contains a space-separated listing of capability names that the server supports.

A capability name which begins with ``AUTH='' indicates that the server supports that particular authentication mechanism :

• The LOGINDISABLED capability indicates that no authentication mechanism is required
  
• The USERPASSWORD capabilities indicates that a USER and PASSWORD attributes must be passed to auth()
  
• Other AUTH capabilities not listed here MUST carry the attributes that must be passed to auth() following the auth name and separated by comma. Example : AUTH=DUALPASS,PASSWORD,CALCULATED_PASSWORD indicates that DUALPASS is the authentication name and that PASSWORD and CALCULATED_PASSWORD must be passed to auth().
  

The supported capabilities by TRex core are :

• UIDL : supports individual message identification (e.g. the POP3 message identification mechanism)
  
• DELETE : the messages can be deleted from the repository. In case that the receiving protocol is one from IM (Instant Messaging) then messages are just retrieved as they arrive, so the DELETE capability is not present in IM protocolos. Instead in POP3 or IMAP where messages are located in a repository, retieved and after probably deleted, then this capability MUST be present.
  

The calling party (TRex::Sendecv) WILL ignore any unknown capability names.

Example: AUTH=USERPASSWORD DELETE

Usage :

  use TRex::SendRecv::nullRecv;

  my $cap = $handler->capabilities();
  die "Crashhhh in capabilities(), Error --> $errorString !!!\n"
      if ( ! $cap );

recv(%)

Retreves messages for the passed credentials via auth(). The values passed are the host name ($hostname) and hash parameters

Usage :

  use TRex::SendRecv::nullRecv;

  my $handler = TRex::SendRecv::nullRecv->new( \$messageText, 
                                               From => 'victor@my.domain',
                                               To => 'myself@home.domain',
                                               Cc => 'eugenia@her.domain',
                                               Bcc => 'none@nowhere' );

  die "Crashhhh in new(), Error --> $errorString !!!\n"
      if ( ! defined $handler );

Developer's arena TRex::SendRecv::nullRecv