man Net::SNPP (3): Simple Network Pager Protocol Client

SYNOPSIS

use Net::SNPP;
# Constructors
$snpp = Net::SNPP->new('snpphost');
$snpp = Net::SNPP->new('snpphost', Timeout => 60);

NOTE

This module is in a maintenance mode, as I no longer have significant access to SNPP servers to test with. However, to the best of the present maintainer's knowledge, the module works just fine and has been used in many a production environment.

DESCRIPTION

This module implements a client interface to the SNPP protocol, enabling a perl5 application to talk to SNPP servers. This documentation assumes that you are familiar with the SNPP protocol described in RFC1861.

A new Net::SNPP object must be created with the new method. Once this has been done, all SNPP commands are accessed through this object.

EXAMPLES

This example will send a pager message in one hour saying ``Your lunch is ready''

    #!/usr/local/bin/perl -w
    use Net::SNPP;
    $snpp = Net::SNPP->new('snpphost');
    $snpp->send( Pager   => $some_pager_number,
                 Message => "Your lunch is ready",
                 Alert   => 1,
                 Hold    => time + 3600, # lunch ready in 1 hour :-)
               ) || die $snpp->message;
    $snpp->quit;

CONSTRUCTOR

new ( [ HOST, ] [ OPTIONS ] )

This is the constructor for a new Net::SNPP object. "HOST" is the name of the remote host to which a SNPP connection is required.

If "HOST" is not given, then the "SNPP_Host" specified in "Net::Config" will be used.

"OPTIONS" are passed in a hash like fashion, using key and value pairs. Possible options are:

Timeout - Maximum time, in seconds, to wait for a response from the SNPP server (default: 120)

Debug - Enable debugging information

Example:

    $snpp = Net::SNPP->new('snpphost', 
                           Debug => 1,    
                           );

METHODS

Unless otherwise stated all methods return either a true or false value, with true meaning that the operation was a success. When a method states that it returns a value, failure will be returned as undef or an empty list.

reset ()
help (): Request help text from the server. Returns the text or undef upon failure
quit (): Send the QUIT command to the remote SNPP server and close the socket connection.
site ( CMD ): Send a SITE command to the remote SNPP server. site() take a single argument which is the command string to send to the SNPP server.
ping ( PAGER_ID ): Determine if the remote SNPP server is able to contact a given pager ID. (Level 3 command)
noqueue (): Instruct the SNPP server not to queue the two-way request. (Level 3 command)
expire_time ( HOURS ): Cause the paging request to be canceled if it has not been sent in the specified number of hours. (Level 3 command)
read_ack ( TRUEFALSE ): Enable and disable the read acknowledgement notification sent by the pager. (Level 3 command)
reply_type ( TYPE_CODE ): Change the type of reply that the page will send back. Valid options are: NONE, YESNO, SIMREPLY, MULTICHOICE, and TEXT. (Level 3 command)
message_response ( INT TEXT ) (Level 3): Create message responses to deliver with the message. INT is a 2-byte number. The total number of definable responses may be limited by your server. Some server may need you to call reply_type() before specifying responses.
message_status ( MSGID MSGID ) (Level 3): Get the message status from the remote server. Use the Message_Tag and Pass_Code from send_two_way() as the arguments to this method, and if your server supports it, you should be able to retrieve the status of a 2-way message. An array/arraref is returned with the following 5 elements:
[0] Sequence
[1] Date&Time
[2] +/- GMT (if provided by server)
[3] server-specific response text
[4] numeric response code from server (i.e. 860 or 960)
send_two_way () (Level 3): Use this method instead of send() when working in Level 3 of the SNPP protocol. Before using this method, you have to build up your page using the other methods in the module, then use this at the very end to ``submit'' your page. An array/arrayref will be returned with the following 4 elements:
[0] Message_Tag
[1] Pass_Code
[2] server-specific response text
[3] numeric response code from server (i.e. 860 or 960)
NOTE: This is only the SEND command - you have to build the page using various methods from this module before calling this method.

2WAY EXAMPLES

 use Net::SNPP;
 my $snpp = Net::SNPP->new( "snpp.provider.com" );
 $snpp->two_way();
 $snpp->pager_id( 5555555555 );
 $snpp->data( "The sky is falling!\nThe sky is falling!" );
 $snpp->message_response( 1, "Don't Panic" );
 $snpp->message_response( 2, "Panic!" );
 my @result = $snpp->send_two_way();
 $snpp->quit();
 printf "Use these two numbers: \"%s %s\" to check message status.\n",
        $result[0], $result[1];
 __END__
 use Net::SNPP;
 my $snpp = Net::SNPP->new( "snpp.provider.com" );
 my @status = $snpp->message_status( $ARGV[0], $ARGV[1] );
 $snpp->quit;
 printf "User responded with: %s\n", $status[3];

EXPORTS

"Net::SNPP" exports all that "Net::CMD" exports, plus three more subroutines that can bu used to compare against the result of "status". These are :- "CMD_2WAYERROR", "CMD_2WAYOK", and "CMD_2WAYQUEUED".

AUTHOR

Derek J. Balling <[email protected]> ( original version by Graham Barr ) Al Tobey <[email protected]> (since Oct 2003)

COPYRIGHT

$Id: SNPP.pm,v 1.9 2004/01/27 22:18:32 tobeya Exp $