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

NAME

       Net::SNPP::Server - SNPP server library

DESCRIPTION

       An object interface for creating SNPP servers.  Almost everything you need to create your very own SNPP server is here in this module.
       There is a callback() method that can replace default function with your own.  them.  Any SNPP command can be overridden or new/custom ones
       can be created using custom_command().  To disable commands you just don't want to deal with, use disable_command().

SYNOPSIS

       There may be a synopsis here someday ...

METHODS

       new()
	   Create a Net::SNPP::Server object listening on a port.  By default, it only listens on the localhost (127.0.0.1) - specify MultiHomed
	   to listen on all addresses or LocalAddr to listen on only one.

	    my $svr = Net::SNPP::Server->new(
	       Port	  => port to listen on
	       BindTo	  => interface address to bind to
	       MultiHomed => listen on all interfaces if true (and BindTo is unset)
	       Listen	  => how many simultaneous connections to handle (SOMAXCONN)
	       # the following two options are only used by handle_client()
	       MaxErrors  => maximum number of errors before disconnecting client
	       Timeout	  => timeout while waiting for data (uses SIGARLM)
	    );

       client()
	   Calls accept() for you and returns a client handle.	This method will block if there is no waiting client.  The handle returned is a
	   subclass of IO::Handle, so all IO::Handle methods should work.
	    my $client = $server->client();

       ip()
	   Return the IP address associated with a client handle.
	    printf "connection from %s", $client->ip();

       socket()
	   Returns the raw socket handle.  This mainly exists for use with select() or IO::Select.
	    my $select = IO::Select->new();
	    $select->add( $server->socket() );

       connected()
	   For use with a client handle.  True if server socket is still alive.

       shutdown()
	   Shuts down the server socket.
	    $server->shutdown(2);

       callback()
	   Insert a callback into Server.pm.
	    $server->callback( 'process_page', &my_function );
	    $server->callback( 'validate_pager_id', &my_function );
	    $server->callback( 'validate_pager_pin', &my_function );
	    $server->callback( 'write_log',    &my_function );
	    $server->callback( 'create_id_and_pin', &my_function );

	   process_page( $PAGER_ID, \%PAGE, @RESULTS )
	     $PAGER_ID = [
		0 => retval of validate_pager_id
		1 => retval of validate_pager_pin ] $PAGE = {
		mess => $,
		responses => [], }

	   validate_pager_id( PAGER_ID )
	     The return value of this callback will be saved as the pager id that is passed to the process_page callback as the first list element
	     of the first argument.

	   validate_pager_pin( VALIDATED_PAGER_ID, PIN )
	     The value returned by this callback will be saved as the second list element in the first argument to process_page.  The PAGER_ID
	     input to this callback is the output from the validate_pager_id callback.

	     NOTE: If you really care about the PIN, you must use this callback.  The default callback will return 1 if the pin is not set.

	   write_log
	     First argument is a Unix syslog level, such as "warning" or "info."  The rest of the arguments are the message.  Return value is
	     ignored.

	   create_id_and_pin
	     Create an ID and PIN for a 2way message.

       custom_command()
	   Create a custom command or override a default command in handle_client().  The command name must be 4 letters or numbers.  The second
	   argument is a coderef that should return a text command, i.e. "250 OK" and some "defined" value to continue the client loop.  +++If no
	   value is set, the client will be disconnected after executing your command.+++ If you need MSTA or KTAG, this is the hook you need to
	   implement them.

	   The subroutine will be passed the command arguments, split on whitespace.

	    sub my_MSTA_sub {
	       my( $id, $password ) = @_;
	       # ...
	       return "250 OK", 1;
	    }
	    $server->custom_command( "MSTA", &my_MSTA_sub );

       disable_command()
	   Specify a command to disable in the server.	This is useful, for instance, if you don't want to support level 3 commands.
	    $server->disable_command( "2WAY", "550 2WAY not supported here" );

	   The second argument is an optional custom error message.  The default is:
	    "500 Command Not Implemented, Try Again"

       handle_client()
	   Takes the result of $server->client() and takes care of parsing the user input.   This should be quite close to being rfc1861 compli-
	   ant.  If you specified Timeout to be something other than 0 in new(), SIGARLM will be used to set a timeout.  If you use this, make
	   sure to take signals into account when writing your code.  fork()'ing before calling handle_client is a good way to avoid interrupting
	   code that shouldn't be interrupted.

       forked_server()
	   Creates a server in a forked process.  The return value is an array (or arrayref depending on context) containing a read-only pipe and
	   the pid of the new process.	Pages completed will be written to the pipe as a semicolon delimited array.
	    my($pipe,$pid) = $server->forked_server();
	    my $line = $pipe->getline();
	    chomp( $line );
	    my( $pgr, $pgr, %pagedata ) = split( /;/, $line );

AUTHOR

       Al Tobey <tobeya@tobert.org>

       Some ideas from Sendpage::SNPPServer
	Kees Cook <cook@cpoint.net> http://outflux.net/

TODO

       Add more hooks for callbacks

       Implement the following level 2 and level 3 commands

	4.5.1 LOGIn <loginid> [password]
	4.5.3 LEVEl <ServiceLevel>
	4.5.5 COVErage <AlternateArea>
	4.5.7 CALLerid <CallerID>
	4.6.3 EXPTag <hours>
	4.6.5 ACKRead <0|1>
	4.6.6 RTYPe <Reply_Type_Code>

SEE ALSO

       Net::Cmd Socket

perl v5.8.8							    2008-02-04						    Net::SNPP::Server(3pm)