.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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 >0, 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 "VUser::Google::ApiProtocol 3pm"
.TH VUser::Google::ApiProtocol 3pm "2021-01-09" "perl v5.32.0" "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"
VUser::Google::ApiProtocol \- Base class for implementation of the Google APIs
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
This class is not meant to be used directly. Instead use
VUser::Google::ApiProtocol::V2_0.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SH "MEMBERS"
.IX Header "MEMBERS"
These are the members of the ApiProtocol class. You get and set the values
by using the method of the same name. For example:
.PP
.Vb 2
\& # Get the domain from the ApiProtocol object
\& my $domain = $google\->domain;
\& 
\& # Set the domain
\& $google\->domain(\*(Aqmyappsdomain.com\*(Aq);
.Ve
.PP
Most of the member can be set when the object is created with \f(CW\*(C`new()\*(C'\fR.
.PP
.Vb 3
\& my $google = VUser::ApiProtocol\->new(
\&     domain => \*(Aqmyappsdomain.com\*(Aq
\& );
.Ve
.PP
\&\fBNote:\fR VUser::Google::ApiProtocol is not meant to be used directly.
Please see the version specific subclasses, such as
VUser::Google::ApiProtocol::V2_0, to create a usable object.
.SS "Read-write Members"
.IX Subsection "Read-write Members"
.IP "admin" 4
.IX Item "admin"
The administrative user. This user must have be set as an admin in the
Google Apps control panel. Also, be sure to log into the Google Apps control
panel once with this user to accept all of the legal garbage or you will
see intermittent auth errors.
.IP "debug" 4
.IX Item "debug"
Turn on debugging output.
.IP "domain" 4
.IX Item "domain"
The Google Apps domain to work on.
.IP "password" 4
.IX Item "password"
The plain text password of the admin user.
.IP "refresh_token" 4
.IX Item "refresh_token"
If set to a true value, \f(CW\*(C`Login()\*(C'\fR will refresh the authentication token
even if it's not necessary.
.SS "Read-only members"
.IX Subsection "Read-only members"
.IP "authtime" 4
.IX Item "authtime"
The unix timestamp of the last authentication.
.IP "authtoken" 4
.IX Item "authtoken"
The authentication token retrieved from Google on a successful login.
The token is only valid for 24 hours.
.IP "reply_headers" 4
.IX Item "reply_headers"
The \s-1HTTP\s0 headers of the last reply
.IP "reply_content" 4
.IX Item "reply_content"
The \s-1HTTP\s0 content of the last reply
.IP "result" 4
.IX Item "result"
The resulting hash from the last reply data as parsed by XML::Simple
.IP "useragent" 4
.IX Item "useragent"
The user agent VUser::Google::ApiProtocol uses when talking to Google. It
is set to the \fIclassname/version\fR. For example,
\&\fIVUser::Google::ApiProtocol::V2_0/0.25\fR.
.SH "METHODS"
.IX Header "METHODS"
.SS "new (%defaults)"
.IX Subsection "new (%defaults)"
Create a new ApiProtocol object. Any read-write member may be set in the
call to \f(CW\*(C`new()\*(C'\fR.
.SS "Login"
.IX Subsection "Login"
Login to the Google \s-1API.\s0 \f(CW\*(C`Login()\*(C'\fR takes no parameters. Instead, you
must set the \f(CW\*(C`domain\*(C'\fR, \f(CW\*(C`admin\*(C'\fR, and \f(CW\*(C`password\*(C'\fR members, then call
\&\f(CW\*(C`Login()\*(C'\fR.
.PP
\&\f(CW\*(C`Login()\*(C'\fR will use the existing authentication token if it exists and
hasn't yet timed out. You may force it to do a full re-authentication by
setting \f(CW\*(C`refresh_token\*(C'\fR to a true value before calling \f(CW\*(C`Login()\*(C'\fR.
.SS "IsAuthenticated"
.IX Subsection "IsAuthenticated"
Returns true if the \fBobject\fR thinks that it has already authenticated and
the token hasn't timed out and a false value otherwise.
.PP
\&\fBNote:\fR \f(CW\*(C`IsAuthenticated()\*(C'\fR only knows if there's an authtoken and if
it's still fresh. It may be possible for Google to decide that a token
is not valid which \f(CW\*(C`IsAuthenticated()\*(C'\fR cannot check.
.ie n .SS "Request ($method, $url[, $body])"
.el .SS "Request ($method, \f(CW$url\fP[, \f(CW$body\fP])"
.IX Subsection "Request ($method, $url[, $body])"
Sends an \s-1API\s0 request to Google.
.PP
\&\f(CW$method\fR is the \s-1HTTP\s0 method to use, e.g. \fI\s-1GET\s0\fR, \fI\s-1POST\s0\fR, etc. \fBNote:\fR
Many of the \s-1API\s0 calls use different methods. Double check the \s-1API\s0 docs to
make sure you are using the correct method.
.PP
\&\f(CW$url\fR is the url to use to make the \s-1API\s0 call. The URLs are defined in 
the \s-1API\s0 docs.
.PP
\&\f(CW$body\fR is the \s-1XML\s0 specific action. Again, see the \s-1API\s0 docs for the
specific format for each \s-1API\s0 call. \f(CW$body\fR is not needed when the method
is \fI\s-1GET\s0\fR or \fI\s-1DELETE\s0\fR.
.SS "dprint ($message)"
.IX Subsection "dprint ($message)"
Prints \f(CW$message\fR to \s-1STDERR\s0 if \f(CW\*(C`debug\*(C'\fR is set to a true value.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
XML::Simple
.SH "AUTHOR"
.IX Header "AUTHOR"
Randy Smith <perlstalker@vuser.org>
.SH "LICENSE"
.IX Header "LICENSE"