Net::SNPP

Net::SNPP(3)          User Contributed Perl Documentation         Net::SNPP(3)



NAME
       Net::SNPP - 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".

SEE ALSO
       Net::Cmd RFC1861

AUTHOR
       Derek J. Balling <dredd@megacity.org> ( original version by Graham Barr
       ) Al Tobey <tobeya@tobert.org> (since Oct 2003)

COPYRIGHT
       Copyright (c) 1995-2001 Graham Barr. (c) 2001-2003 Derek J. Balling.
       All rights reserved. This program is free software; you can
       redistribute it and/or modify it under the same terms as Perl itself.

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



perl v5.28.0                      2004-04-08                      Net::SNPP(3)