.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.14)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::OpenSRS 3pm"
.TH Net::OpenSRS 3pm "2010-09-16" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::OpenSRS \- Domain registration via the Tucows OpenSRS HTTPS XML API
.SH "Description"
.IX Header "Description"
This is a wrapper interface to the \s-1DNS\s0 portions of the Tucows OpenSRS
\&\s-1HTTPS\s0 \s-1XML\s0 \s-1API\s0.
.PP
The client library distributed by OpenSRS can be difficult to integrate
into a custom environment, and their web interface becomes quickly
tedious with heavy usage. This is a clean and relatively quick library
to perform the most common \s-1API\s0 methods described in the OpenSRS \s-1API\s0
documentation.
.SH "Examples"
.IX Header "Examples"
.Vb 1
\& use Net::OpenSRS;
\&
\& my $key = \*(AqYour_API_Key_From_The_Reseller_Interface\*(Aq;
\& my $srs = Net::OpenSRS\->new();
\&
\& $srs\->environment(\*(Aqlive\*(Aq);
\& $srs\->set_key( $key );
\&
\& $srs\->set_manage_auth( \*(Aqmanage_username\*(Aq, \*(Aqmanage_password\*(Aq );
\&
\& my $cookie = $srs\->get_cookie( \*(Aqspime.net\*(Aq );
\& if ($cookie) {
\&     print "Cookie:  $cookie\en";
\& } else {
\&     print $srs\->last_response() . "\en";
\& }
\&
\& # do a batch of domain locks
\& $srs\->bulk_lock([ \*(Aqexample.com\*(Aq, \*(Aqexample.net\*(Aq, ... ]);
\&
\& # renew a domain
\& my $result = $srs\->renew_domain( \*(Aqexample.com\*(Aq );
\& ...
.Ve
.SH "Notes"
.IX Header "Notes"
.SS "Prerequisites"
.IX Subsection "Prerequisites"
This module requires some setup in the OpenSRS reseller environment
before it will work correctly.
.IP "Reseller account" 4
.IX Item "Reseller account"
You need to have an OpenSRS account, of course.  If you aren't an
OpenSRS reseller, this module will be of limited use to you. :)
.IP "Script \s-1API\s0 network access" 4
.IX Item "Script API network access"
The machine(s) using this module need to have their public \s-1IP\s0 addresses
added to your 'Script \s-1API\s0 allow' list in the OpenSRS web interface.
(You'll only need to do this once, assuming your \s-1IP\s0 doesn't change.)
.IP "\s-1API\s0 key generation" 4
.IX Item "API key generation"
You'll need to pregenerate your \s-1API\s0 keys \- also in the the OpenSRS web
interface.  These keys are used for all reseller \s-1API\s0 authentication.
.SS "Assumptions"
.IX Subsection "Assumptions"
OpenSRS allows for a variety of ways to organize your domains.  Because
of this, writing a 'one size fits all' module is rather difficult.
Instead, we make a few assumptions regarding the way people use their
OpenSRS reseller accounts.
.PP
**** These assumptions will ultimately determine if this module is right for
you!  Please read them carefully! ****
.IP "Management 'master' account." 4
.IX Item "Management 'master' account."
We assume that all domains are under one global management owner
account.  If customers want access to the management interface, we're
operating under the idea that you create subaccounts for them \-
retainting the master account information for your own use.  (If you
aren't doing this, it really makes things easier for you in the long
run.)
.Sp
For example, 'spime.net' is my master management account.  Before doing
any \fIregister_domain()\fR calls, I call master_domain('spime.net') \- then
any transfers or registrations from that point forward are linked to
\&'spime.net'.  If a customer wants access to the \s-1SRS\s0 web management
interface, I can then just create a subaccount for just their domain,
so I retain absolute control \*(-- in the event a customer forgets their
password, I'm covered.
.IP "Usernames" 4
.IX Item "Usernames"
We assume that your management username 'master' account is identical to
your reseller username, and just the passwords differ.
.IP "Default registration info" 4
.IX Item "Default registration info"
We assume you've properly set up default technical contact information,
including your default nameservers, in the OpenSRS reseller web
interface.
.IP "Return codes" 4
.IX Item "Return codes"
Unless otherwise noted, all methods return true on success, false on
failure, and undefined on caller error.
.SS "Default environment"
.IX Subsection "Default environment"
This library defaults to the \s-1TEST\s0 environment. (horizon.)  Many \s-1API\s0
methods don't work in the test environment (\s-1SET\s0 \s-1COOKIE\s0 being the most
notable example, as any \s-1API\s0 method relying on a cookie doesn't work
either.)  Neither does batch processing.  Most everything else should be
ok.  ( See \fIenvironment()\fR )
.SS "The '$c' variable"
.IX Subsection "The '$c' variable"
Many methods require customer information.  I leave the method of
fetching this information entirely to you.  All examples below that show
a \f(CW$c\fR variable expect a hashref (or object) that contain these keys:
.PP
.Vb 11
\&    my $c = {
\&        firstname => \*(AqJohn\*(Aq,
\&        lastname  => \*(AqDoe\*(Aq,
\&        city      => \*(AqPortland\*(Aq,
\&        state     => \*(AqOregon\*(Aq,
\&        country   => \*(AqUS\*(Aq,
\&        address   => \*(Aq555 Someplace Street\*(Aq,
\&        email     => \*(Aqjohn@example.com\*(Aq,
\&        phone     => \*(Aq503\-555\-1212\*(Aq,
\&        company   => \*(Aqn/a\*(Aq
\&    };
.Ve
.SH "Utility methods"
.IX Header "Utility methods"
.IP "\fInew()\fR" 4
.IX Item "new()"
.Vb 1
\& my $srs = Net::OpenSRS\->new();
.Ve
.Sp
Create a new Net::OpenSRS object.  There are no options for this
method.
.IP "\fIdebug_level()\fR" 4
.IX Item "debug_level()"
Setting the debug level will print various pieces of information to
\&\s-1STDERR\s0 when connecting to OpenSRS.  Use this if something isn't working
the way you think it should be.
.IP "0" 4
Disable debugging.
.IP "1" 4
.IX Item "1"
Print current environment, host, and \s-1HTTP\s0 response.
.IP "2" 4
.IX Item "2"
Add \s-1XML\s0 request and response to output.
.IP "3" 4
.IX Item "3"
Add \s-1SSL\s0 debugging to output.
.Sp
Debugging is off by default.  When called without an argument, returns
the current debug level.
.IP "\fIlast_response()\fR" 4
.IX Item "last_response()"
All Net::OpenSRS methods set the last OpenSRS \s-1API\s0 reply in a temporary
variable.  You can view the contents of this variable using the
\&\fIlast_response()\fR method.
.Sp
Note that it is reset on each method call.
.Sp
Returns the last OpenSRS return code and result string, or if passed any
true value, instead returns the full \s-1XML\s0 (parsed into a hashref) of the
last OpenSRS return. (perfect for Data::Dumper)
.Sp
Examples:
   200: Command Successful
   400: Domain example.com does not exist with OpenSRS
.IP "\fIset_manage_auth()\fR" 4
.IX Item "set_manage_auth()"
.Vb 1
\& $srs\->set_manage_auth( $username, $password );
.Ve
.Sp
Set the owner management username and password.  This is used to fetch
cookies, and perform any \s-1API\s0 methods that require the management cookie.
For specifics on this, see the OpenSRS \s-1API\s0 documentation.
.IP "\fIset_key()\fR" 4
.IX Item "set_key()"
Tell the OpenSRS object what secret key to use for authentication.
You can generate a new secret key by using the OpenSRS reseller web
interface.  This key is required to perform any \s-1API\s0 functions.
.Sp
\&\fIset_key()\fR is affected by the current \fIenvironment()\fR.  Calling the
\&\fIset_key()\fR method while in the test environment only sets the key for the
test environment \- likewise for the live environment.  To set a key for
the live environment, you need to call environment('live') \fBfirst\fR.
.IP "\fIenvironment()\fR" 4
.IX Item "environment()"
.Vb 2
\& my $env = $srs\->environment;
\& $srs\->environment(\*(Aqlive\*(Aq);
.Ve
.Sp
Without an argument, returns a string \- either 'test', or 'live',
depending on the environment the object is currently using.
.Sp
The test environment is the default.
.Sp
If passed an argument (either 'test' or 'live') \- switches into the
desired environment.  You will need to \fIset_key()\fR if you were previously
using a different environment, or if you hadn't \fIset_key()\fR yet.
.IP "\fImaster_domain()\fR" 4
.IX Item "master_domain()"
.Vb 2
\& my $master = $srs\->master_domain;
\& $srs\->master_domain(\*(Aqspime.net\*(Aq);
.Ve
.Sp
Without an argument, returns the currently set 'master domain' account.
Otherwise, it sets the master domain.
.Sp
New transfers and registrations are linked under this domain, for
centralized management.  See the 'Assumptions' section, above.
.SH "OpenSRS API methods"
.IX Header "OpenSRS API methods"
.IP "\fIbulk_lock()\fR / \fIbulk_unlock()\fR" 4
.IX Item "bulk_lock() / bulk_unlock()"
Locks or unlocks up to 1000 domains at a time.
.Sp
.Vb 1
\& my $result = $srs\->bulk_lock([ \*(Aqexample.com\*(Aq, \*(Aqexample.net\*(Aq ]);
.Ve
.Sp
Returns remote bulk queue id on successful batch submission.
.IP "\fIcheck_queued_request()\fR" 4
.IX Item "check_queued_request()"
.Vb 1
\& my $result = $srs\->check_queued_request( $queue_id );
.Ve
.Sp
Requires queue id \- returned from batch methods such as \fIbulk_lock()\fR.
Always returns hashref of queue command on success.  
Check \f(CW$srs\fR\->\fIlast_response()\fR for status progress.
.IP "\fIcheck_transfer()\fR" 4
.IX Item "check_transfer()"
.Vb 1
\& my $result = $srs\->check_transfer( \*(Aqexample.com\*(Aq );
.Ve
.Sp
Checks the status of a transfer in progress.  Returns hashref of
\&'contact_email', 'status', and 'last_update_time' for a given domain
transfer.  The 'status' key is always one of the following:
.Sp
.Vb 6
\&        pending_owner  (waiting on owner confirmation)
\&        pending_admin  (waiting on opensrs staff confirmation)
\&        pending_registry  (waiting on register to complete)
\&        completed  (transfer done)
\&        cancelled  (reseller cancelled transfer in progress)
\&        undefined  (no transfer in progress)
.Ve
.Sp
If the domain in question has no transfer in progress \- instead checks
to see if the domain is capable of transfer.  Returns hashref of
\&'transferrable' (boolean) and 'reason' (string).
.IP "\fIget_cookie()\fR" 4
.IX Item "get_cookie()"
OpenSRS management APIs require a cookie to be generated, and sent along
with the \s-1API\s0 request.
.Sp
.Vb 2
\& $cookie = $srs\->get_cookie( \*(Aqexample.com \*(Aq);
\& ($cookie, $expiration_date) = $srs\->get_cookie( \*(Aqexample.com \*(Aq);
.Ve
.Sp
Make sure you've \fIset_manage_auth()\fR before attempting any cookie required
APIs.
.Sp
Returns cookie on success, undefined on error.  (Check error with
\&\fIlast_response()\fR)
.Sp
In array context, returns cookie and expiration date of the domain.
.IP "\fIget_expiring_domains()\fR" 4
.IX Item "get_expiring_domains()"
.Vb 1
\& my $results = $srs\->get_expiring_domains( 60 );
\&
\& Fetch and return OpenSRS hashref of expiring domains, within
\& the specified timeperiod.  (In days.)
\&
\& Time period defaults to 30 days.
.Ve
.IP "\fIis_available()\fR" 4
.IX Item "is_available()"
Hey OpenSRS! Is this domain registered, or is it available?
.Sp
.Vb 1
\& my $result = $srs\->is_available( \*(Aqexample.com \*(Aq);
.Ve
.Sp
Returns true if the domain is available, false if it is already
registered.
.IP "\fIregister_domain()\fR" 4
.IX Item "register_domain()"
.Vb 1
\& my $result = $srs\->register_domain( \*(Aqexample.com\*(Aq, $c );
.Ve
.Sp
Register a new domain.  Default nameserver and tech info used from
OpenSRS settings.
.IP "\fIrenew_domain()\fR" 4
.IX Item "renew_domain()"
.Vb 1
\& my $result = $srs\->renew_domain( \*(Aqexample.com\*(Aq, 1 );
.Ve
.Sp
Renew a domain for a period of time in years. 1 year is the default.
.IP "\fIrevoke_domain()\fR" 4
.IX Item "revoke_domain()"
Revoke a previously registered domain.  This only works if the domain is
still within the grace period as defined by the registrar.
Requires you to have called \fIset_manage_auth()\fR \fBfirst\fR.
.Sp
.Vb 1
\& my $result = $srs\->revoke_domain( \*(Aqexample.com\*(Aq );
.Ve
.Sp
Returns true if the revoke is successful, false otherwise.
Returns undefined on error.
.IP "\fItransfer_domain()\fR" 4
.IX Item "transfer_domain()"
.Vb 1
\& my $result = $srs\->transfer_domain( \*(Aqexample.com\*(Aq, $c );
.Ve
.Sp
Transfer a domain under your control.
Returns true on success, false on failure, and undefined on caller error.
.IP "\fImake_request()\fR" 4
.IX Item "make_request()"
This method is the real workhorse of this module.  If any OpenSRS \s-1API\s0
isn't explicity implemented in this module as a method call (such as
\&\fIget_cookie()\fR, \fIbulk_lock()\fR, etc), you can use \fImake_request()\fR to build and send
the \s-1API\s0 yourself.
.Sp
Examples:
.Sp
.Vb 12
\& my $result = $srs\->make_request(
\&     {
\&         batch   => 1,
\&         action  => \*(Aqsubmit\*(Aq,
\&         object  => \*(Aqbulk_change\*(Aq,
\&         attributes => {
\&             change_type => \*(Aqdomain_lock\*(Aq,
\&             change_items => [ \*(Aqexample.com\*(Aq, \*(Aqexample.net\*(Aq ],
\&             op_type => \*(Aqlock\*(Aq,
\&         }
\&     }
\& );
\&
\& my $result = $srs\->make_request(
\&     {
\&         action     => \*(Aqlookup\*(Aq,
\&         object     => \*(Aqdomain\*(Aq,
\&         attributes => {
\&             domain => \*(Aqexample.com\*(Aq
\&         }
\&     }
\& );
.Ve
.Sp
Returns a hashref containing parsed \s-1XML\s0 results from OpenSRS.
.Sp
Example return:
.Sp
.Vb 12
\& {
\&     \*(Aqprotocol\*(Aq => \*(AqXCP\*(Aq,
\&     \*(Aqobject\*(Aq => \*(AqDOMAIN\*(Aq,
\&     \*(Aqresponse_text\*(Aq => \*(AqDomain taken\*(Aq,
\&     \*(Aqaction\*(Aq => \*(AqREPLY\*(Aq,
\&     \*(Aqresponse_code\*(Aq => \*(Aq211\*(Aq,
\&     \*(Aqattributes\*(Aq => {
\&         \*(Aqstatus\*(Aq => \*(Aqtaken\*(Aq,
\&         \*(Aqmatch\*(Aq => {}
\&     },
\&     \*(Aqis_success\*(Aq => \*(Aq1\*(Aq
\& }
.Ve
.SH "Author"
.IX Header "Author"
Mahlon E. Smith \fImahlon@martini.nu\fR for Spime Solutions Group
\&\fI(www.spime.net)\fR