Interaction with the base ProtoWrap wrapper

It should be as easy as possible for the administrator to set up the wrapper for any given service or to modify its behavior. Thus, the commands issued should be kept to a bare minimum.

The first thing to include in a Perl program to be able to call the wrapper will be the proper use directive:

use ProtoWrap;

This will only call the base wrapper class (described in this chapter). To call a specific derived class, please refer to sections 3.5 and 3.6.

This way, we import all the wrapper's components into our program, and we are ready to fire a socket. Let us say we want to wrap an imap2 connection - imap2 is not implemented as a wrapper class in the sample classes included in chapter 4, but we want to protect the daemon from buffer overflows. The computer handling that particular service has assigned to it the IP address 192.168.0.1, and will listen to the default imap2 port, 143. We expect connections to be established very frequently, so the best strategy will be to run in standalone mode. We will limit lines to 100 characters, more than enough to receive imap2 commands. All text sent over 100 characters will be silently dropped.

We now have all the information we need to create a new wrapper object. We do it by calling the new method for the wrapper:

my $imap2=ProtoWrap->new( 
'standalone' => 1,  
'destType' => 'ip',  
'listenPort' => 143,  
'destAddr' => '192.168.0.1',  
'destPort' => 143,  
'maxLineLength' => 100,  
loglevel => 2 
);

This way, the object has been created and is ready to start doing real work. Before starting it, it is advisable to check whether initialization was successful. If a needed parameter was omitted or an unexpected parameter was given, ProtoWrap will refuse to create an object, returning with undef instead of an object. Thus, we need to do this test:

if (not defined $imap2) { 
die('imap2 wrapper could not be started');

}

Now, the wrapper should be started. This is done with the startServer method:

$imap2->startServer() or warn 'Can\'t start wrapper';

That's all, we now have a working and listening wrapper listening to port 143 for a connection, ready to forward it to our server. The ProtoWrap process forks. The parent process should remain as a running process after starting the wrapper in order to be able later to control it (i.e. kill it, modify its properties), so it should be put to wait. It is strongly recommended to use a passive waiting function, such as sleep(), because the parent will not be doing anything from now on. An exception handler can be added to wake up and do different things should a specific signal (such as SIGHUP, used to restart a daemon process) be recieved.

There should also be a way to stop a running wrapper, be it in order to reconfigure or restart it, or to temporarily suspend the service at the system administrator's request. We do this by issuing:

$imap2->stopServer;

Although Perl handles garbage collection by itself, it is also useful and good practice to have a DESTROY method. Perl automatically calls the DESTROY method when the last reference to an object ceases to exist. Thus, when the object no longer serves its purpose, we can destroy it simply with :

$imap2 = undef;

There are other methods which can give information on or modify the wrapper's operation at runtime. They are:

%imapProperties = $imap2->getProp;

returns in the hash %imapProperties the actual values of all the object's attributes. This method is mainly for debugging purposes.

$imap2->set_maxLineLength($newValue);

changes the value of maxLineLength to the value contained in $newValue.

$imap2->set_logLevel($newValue)

changes the logLevel value to the value contained in $newValue.

$imap2->version()

returns ProtoWrap's version number.