.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::OpenID::Yadis 3pm"
.TH Net::OpenID::Yadis 3pm "2016-02-13" "perl v5.22.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::OpenID::Yadis \- Perform Yadis discovery on URLs
.SH "VERSION"
.IX Header "VERSION"
version 1.20
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Net::OpenID::Yadis;
\&
\&  my $disc = Net::OpenID::Yadis\->new(
\&      consumer => $consumer, # Net::OpenID::Consumer object
\&  );
\&
\&  my $xrd = $disc\->discover("http://id.example.com/") or Carp::croak($disc\->err);
\&
\&  print $disc\->identity_url;       # Yadis URL (Final URL if redirected)
\&  print $disc\->xrd_url;            # Yadis Resourse Descriptor URL
\&
\&  foreach my $srv (@$xrd) {        # Loop for Each Service in Yadis Resourse Descriptor
\&    print $srv\->priority;          # Service priority (sorted)
\&    print $srv\->Type;              # Identifier of some version of some service (scalar, array or array ref)
\&    print $srv\->URI;               # URI that resolves to a resource providing the service (scalar, array or array ref)
\&    print $srv\->extra_field("Delegate","http://openid.net/xmlns/1.0");
\&                                   # Extra field of some service
\&  }
\&
\&  # If you are interested only in OpenID. (either 1.1 or 2.0)
\&  my $xrd = $self\->services(
\&    \*(Aqhttp://specs.openid.net/auth/2.0/signon\*(Aq,
\&    \*(Aqhttp://specs.openid.net/auth/2.0/server\*(Aq,
\&    \*(Aqhttp://openid.net/signon/1.1\*(Aq,
\&  );
\&
\&  # If you want to choose random server by code\-ref.
\&  my $xrd = $self\->services(sub{($_[int(rand(@_))])});
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides an implementation of the Yadis protocol, which does
XRDS-based service discovery on URLs.
.PP
This module was originally developed by \s-1OHTSUKA\s0 Ko-hei as Net::Yadis::Discovery,
but was forked and simplified for inclusion in the core OpenID Consumer package.
.PP
This simplified version is tailored for the needs of Net::OpenID::Consumer; for other
uses, Net::Yadis::Discovery is probably a better choice.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.ie n .IP """new""" 4
.el .IP "\f(CWnew\fR" 4
.IX Item "new"
my \f(CW$disc\fR = Net::OpenID::Yadis\->new([ \f(CW%opts\fR ]);
.Sp
You can set the \f(CW\*(C`consumer\*(C'\fR in the constructor.  See the corresponding
method description below.
.SH "EXPORT"
.IX Header "EXPORT"
This module exports three constant values to use with discover method.
.ie n .IP """YR_GET""" 4
.el .IP "\f(CWYR_GET\fR" 4
.IX Item "YR_GET"
If you set this, module check Yadis \s-1URL\s0 start from \s-1HTTP GET\s0 request. This is the default.
.ie n .IP """YR_XRDS""" 4
.el .IP "\f(CWYR_XRDS\fR" 4
.IX Item "YR_XRDS"
If you set this, this module consider Yadis \s-1URL\s0 as Yadis Resource Descriptor \s-1URL.\s0
If not so, an error is returned.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "$disc\->\fBconsumer\fR($consumer)" 4
.el .IP "\f(CW$disc\fR\->\fBconsumer\fR($consumer)" 4
.IX Item "$disc->consumer($consumer)"
.PD 0
.ie n .IP "$disc\->\fBconsumer\fR" 4
.el .IP "\f(CW$disc\fR\->\fBconsumer\fR" 4
.IX Item "$disc->consumer"
.PD
Get or set the Net::OpenID::Consumer object that this object is associated with.
.ie n .IP "$disc\->\fBdiscover\fR($url,[$request_method])" 4
.el .IP "\f(CW$disc\fR\->\fBdiscover\fR($url,[$request_method])" 4
.IX Item "$disc->discover($url,[$request_method])"
Given a user-entered \f(CW$url\fR (which could be missing http://, or have
extra whitespace, etc), returns either array/array ref of Net::OpenID::Yadis::Service
objects, or undef on failure.
.Sp
\&\f(CW$request_method\fR is optional, and if set this, you can change the \s-1HTTP\s0
request method of fetching Yadis \s-1URL.\s0
See \s-1EXPORT\s0 to know the value you can set, and default is \s-1YR_HEAD.\s0
.Sp
If this method returns undef, you can rely on the following errors
codes (from \f(CW$csr\fR\->\fBerrcode\fR) to decide what to present to the user:
.RS 4
.IP "xrd_parse_error" 8
.IX Item "xrd_parse_error"
.PD 0
.IP "xrd_format_error" 8
.IX Item "xrd_format_error"
.IP "too_many_hops" 8
.IX Item "too_many_hops"
.IP "no_yadis_document" 8
.IX Item "no_yadis_document"
.IP "url_fetch_err" 8
.IX Item "url_fetch_err"
.IP "empty_url" 8
.IX Item "empty_url"
.IP "url_gone" 8
.IX Item "url_gone"
.RE
.RS 4
.RE
.ie n .IP "$disc\->\fBxrd_objects\fR" 4
.el .IP "\f(CW$disc\fR\->\fBxrd_objects\fR" 4
.IX Item "$disc->xrd_objects"
.PD
Returns array/array ref of Net::OpenID::Yadis objects.
It is same what could be got by discover method.
.ie n .IP "$disc\->\fBidentity_url\fR" 4
.el .IP "\f(CW$disc\fR\->\fBidentity_url\fR" 4
.IX Item "$disc->identity_url"
Returns Yadis \s-1URL.\s0
If not redirected, it is same with the argument of discover method.
.ie n .IP "$disc\->\fBxrd_url\fR" 4
.el .IP "\f(CW$disc\fR\->\fBxrd_url\fR" 4
.IX Item "$disc->xrd_url"
Returns Yadis Resource Descriptor \s-1URL.\s0
.ie n .IP "$disc\->\fBservers\fR($protocol,$protocol,...)" 4
.el .IP "\f(CW$disc\fR\->\fBservers\fR($protocol,$protocol,...)" 4
.IX Item "$disc->servers($protocol,$protocol,...)"
.PD 0
.ie n .IP "$disc\->\fBservers\fR($protocol=>[$version1,$version2],...)" 4
.el .IP "\f(CW$disc\fR\->\fBservers\fR($protocol=>[$version1,$version2],...)" 4
.IX Item "$disc->servers($protocol=>[$version1,$version2],...)"
.ie n .IP "$disc\->\fBservers\fR($protocol,....,$code_ref);" 4
.el .IP "\f(CW$disc\fR\->\fBservers\fR($protocol,....,$code_ref);" 4
.IX Item "$disc->servers($protocol,....,$code_ref);"
.PD
Filter method of xrd_objects.
.Sp
If no option is defined, returns same result with xrd_objects method.
.Sp
protocol names or Type URLs are given, filter only given protocol.
Two or more protocols are given, return and results of filtering.
.Sp
Sample:
  \f(CW$disc\fR\->servers(\*(L"openid\*(R",\*(L"http://lid.netmesh.org/sso/1.0\*(R");
.Sp
If reference of version numbers array is given after protocol names,
filter only given version of protocol.
.Sp
Sample:
  \f(CW$disc\fR\->servers(\*(L"openid\*(R"=>['1.0','1.1'],\*(L"lid\*(R"=>['1.0']);
.Sp
If you want to use version numbers limitation with type \s-1URL,\s0 you can use
\&\ever as place holder of version number.
.Sp
Sample:
  \f(CW$disc\fR\->servers(\*(L"http://lid.netmesh.org/sso/\ever\*(R"=>['1.0','2.0']);
.Sp
If code reference is given as argument , you can make your own filter rule.
code reference is executed at the last of filtering logic, like this:
.Sp
.Vb 1
\&  @results = $code_ref\->(@temporary_results)
.Ve
.Sp
Sample: If you want to filter OpenID server and get only first one:
  ($openid_server) = \f(CW$disc\fR\->servers(\*(L"openid\*(R",sub{$_[0]});
.ie n .IP "$disc\->\fBerr\fR" 4
.el .IP "\f(CW$disc\fR\->\fBerr\fR" 4
.IX Item "$disc->err"
Returns the last error, in form \*(L"errcode: errtext\*(R"
.ie n .IP "$disc\->\fBerrcode\fR" 4
.el .IP "\f(CW$disc\fR\->\fBerrcode\fR" 4
.IX Item "$disc->errcode"
Returns the last error code.
.ie n .IP "$disc\->\fBerrtext\fR" 4
.el .IP "\f(CW$disc\fR\->\fBerrtext\fR" 4
.IX Item "$disc->errtext"
Returns the last error text.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This module is Copyright (c) 2006 \s-1OHTSUKA\s0 Ko-hei.
All rights reserved.
.PP
You may distribute under the terms of either the \s-1GNU\s0 General Public
License or the Artistic License, as specified in the Perl \s-1README\s0 file.
.SH "WARRANTY"
.IX Header "WARRANTY"
This is free software. \s-1IT COMES WITHOUT WARRANTY OF ANY KIND.\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Yadis website:  <http://yadis.org/>
.PP
Net::OpenID::Yadis::Service
.PP
Net::OpenID::Consumer
.SH "AUTHORS"
.IX Header "AUTHORS"
Based on Net::Yadis::Discovery by \s-1OHTSUKA\s0 Ko-hei <nene@kokogiko.net>
.PP
Martin Atkins <mart@degeneration.co.uk>