Net::SNPP(3pm)

💖 Net::SNPP — the manual page, but make it make sense 💖

okay bestie, gather round, because we're talking about Net::SNPP, the Simple Network Pager Protocol Client from the Net::SNPP(3pm) manual under User Contributed Perl Documentation. yes, pagers. yes, they're still a thing in weird enterprise places. no cap. let's go 🫶

---

✨ SYNOPSIS ✨

use Net::SNPP;

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

---

🚨 NOTE 🚨

So this module is in a maintenance mode era of its life, because the current maintainer literally doesn't have significant access to SNPP servers to test with anymore 😭. BUT. To the best of the present maintainer's knowledge, it works just fine and has been used in many a production environment. iconic behavior honestly 👑

---

🌸 DESCRIPTION 🌸

This module implements a client interface to the SNPP protocol, which means a perl5 application can talk to SNPP servers. the manual assumes you already know the SNPP protocol as described in RFC1861 — iykyk, if you don't, go read it first, bestie 📖

You have to create a new Net::SNPP object with the new method. Once that's done, all SNPP commands are accessed through this object. one object, every command, main character energy ✨

---

🍓 EXAMPLES 🍓

okay so this example sends a pager message in one hour that says "Your lunch is ready". so thoughtful of you 💅

#!/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. slay 🌐

If HOST is not given, then the SNPP_Host specified in Net::Config will be used. so if you're lazy, it's got you.

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. so like, always check, bestie 😤

• reset ()
• help () — Request help text from the server. Returns the text or undef upon failure.

ngl, the page lists reset () right above help () with no description of its own — that's just how it is in the docs, don't come for me 🙈

• quit () — Send the QUIT command to the remote SNPP server and close the socket connection. the goodbye kiss 💋
• site ( CMD ) — Send a SITE command to the remote SNPP server. site() takes 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. so like, order matters, be careful 🧚
• 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. don't skip the build-up, it's the whole plot 📝

---

💜 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. (yes, "bu" — that's a typo in the original and I am not fixing it, that's history 🫶)

These are: CMD_2WAYERROR, CMD_2WAYOK, and CMD_2WAYQUEUED. memorize them, they're the vibe check for your status codes ⭐

---

👑 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 $

---

and that's the whole thing, bestie 🦋 this was Net::SNPP, delivered as Net::SNPP(3pm) — documented for perl v5.36.0, dated 2022-10-13. periodt 💅✨