Provided by: libvuser-google-api-perl_1.0.1-1_all bug

NAME

       VUser::Google::ProvisioningAPI::V1_0 - Perl module that implements version 1.0 of the
       Google Apps for Your Domain Provisioning API

SYNOPSIS

         use VUser::Google::ProvisioningAPI;
         my $google = new VUser::Google::ProvisioningAPI($domain,$admin,$password);

         $google->CreateAccount($userName, $firstName, $lastName, $password);
         $google->RetrieveAccount($userName);

REQUIREMENTS

       VUser::Google::ProvisioningAPI requires the following modules to be installed:

       •   "LWP::UserAgent"

       •   "HTTP::Request"

       •   "Encode"

       •   "XML::Simple"

DESCRIPTION

       VUser::Google::ProvisioningAPI provides a simple interface to the Google Apps for Your
       Domain Provisioning API.  It uses the "LWP::UserAgent" module for the HTTP transport, and
       the "HTTP::Request" module for the HTTP request and response.

   Examples
       For a complete description of the meaning of the following methods, see the Google API
       documentation referenced in the SEE ALSO section.

               #create the object
               $google = new Google:ProvisioningAPI($domain,$admin,$password) || die "Cannot create google object";

               print 'Module version: ' . $google->VERSION . "\nAPI Version: " . $google->version() . "\n";

               #create a hosted account
               if( $google->CreateAccount( $userName, $firstName, $lastName, $password ) )
               {
                       print "Account created!\N";
               }

               #add email services to the account
               $google->UpdateAccountEmail($userName);

               #retrieving account data
               if($google->RetrieveAccount($userName))
               {
                       print 'Username: ' . $google->{result}->{RetrievalSection}->{userName} . "\n";
                       print 'firstName: ' . $google->{result}->{RetrievalSection}->{firstName} . "\n";
                       print 'lastName: ' . $google->{result}->{RetrievalSection}->{lastName} . "\n";
                       print 'accountStatus: ' . $google->{result}->{RetrievalSection}->{accountStatus} . "\n";

               }

               #see what the result hash after a request looks like
               use Data::Dumper;
               print Dumper($google->{result});

               #delete an account
               $ret = DeleteAccount($userName);

               #accessing the HTML data as it was received from the Google servers:
               print $google->replyheaders();
               print $google->replycontent();

CONSTRUCTOR

       new ( $domain, $admin, $adminpassword )

       This is the constructor for a new VUser::Google::ProvisioningAPI object.  $domain is the
       domain name registered with Google Apps For Your Domain, $admin is an account in the above
       domain that has the right to manage that domain, and $adminpassword is the password for
       that account.

       Note that the constructor will NOT attempt to perform the 'ClientLogin' call to the Google
       Provisioning API (see below).  Authentication happens automatically when the first API
       call is performed. The token will be remembered for the duration of the object, and will
       be automatically refreshed as needed.  If you want to verify that you can get a valid
       token before performing any operations, follow the constructor with a call to
       IsAuthenticated() as such:

               print "Authentication OK\n" unless not $google->IsAuthenticated();

METHODS

       Below are all the methods available on the object. For the Google API specific methods,
       see the Google API documentation for more details.  When a request is properly handled by
       Google's API engine, the webpost to the API succeeds. This results in a valid page being
       returned. The content of this page then defines whether the request succeeded or not.  All
       pages returing the 'Success(2000)' status code will result in the API method succeeding,
       and returning a 1. All failures return 0.  Please see the section below on how to access
       the result data, and how to determine the reasons for errors.

       If the web post fails (as determined by the "HTTP::Request" method IsSuccess() ), the
       method returns 0, and the {reason} hash is set to a descriptive error.  You can then
       examine the raw data to get an idea of what went wrong.

   Checking Authentication
       IsAuthenticated()

           will check if the object has been able to authenticate with Google's api engine, and
           get an authentication ticket.  Returns 1 if successful, 0 on failure. To see why it
           may fail, see the $@ variable, and the $google->{results}->{reason} hash, and parse
           the returned page (see the 'content' and 'header' variables.)

   Methods to Create/Retrieve/Delete
       'Hosted account' methods

       CreateAccountEmail(  $userName, $firstName, $lastName, $password, $quota )

           Creates a hosted account with email services in your domains name space.  The first 4
           arguments are required. The $quota argument is optional. If $quota is given, the
           <quota> tag will be sent with the request, otherwize is will be omitted.  See the
           Google API docs for the API call for more details.

       CreateAccount(  $userName, $firstName, $lastName, $password )

           Creates a hosted account in your domains name space. This account does NOT have email
           services by default.  You need to call UpdateAccountEmail() to add email services.
           NOTE: this API call may be discontinued! See CreateAccountEmail() for a replacement.

       UpdateAccount( $username, $firstName, $lastName, $password )

           $username is the mandatory name of the hosted account. The remaining paramaters are
           optional, and can be set to 'undef' if you do not wish to change them Eg. to change
           the password on an account, call this as;

               UpdateAccount( $username, undef, undef, 'newpassword' );

           to change names only, you would call it as such:

               UpdateAccount( $username, 'newfirstname', 'newlastname', undef );

       UpdateAccountEmail( $userName )

           Adds email services to a hosted account created with CreateAccount().  NOTE: this API
           call may be discontinued! See CreateAccountEmail() for a replacement.

       UpdateAccountStatus( $userName, $status )

           $status is either 'locked' or 'unlocked'

       RetrieveAccount( $userName )

       DeleteAccount( $userName )

       RenameAccount( $oldName, $newName, $alias )

           $alias is either '1' or '0'

           WARNING: this method is derived from the Python sample code provided by Google: (Ie.
           this may not work yet) "Username change. Note that this feature must be explicitly
           enabled by the domain administrator, and is not enabled by default.  Args:

               oldname: user to rename newname: new username to set for the user alias: if 1,
               create an alias of oldname for newname"

       'Alias' methods

       CreateAlias( $userName, $alias )

       RetrieveAlias( $userName );

       DeleteAlias( $alias );

       'Mailing List' methods

       CreateMailingList( $mailingListName )

       UpdateMailingList( $mailingListName, $userName, $listOperation )

           $listOperation is either 'add' or 'remove'

       RetrieveMailingList( $mailingListName )

       DeleteMailingList( $mailingListName )

   Methods to set/get variables
       After creating the object you can get/set the administrator account and set the password
       with these methods.  Note this will cause a re-authentication next time a Google API
       method is called.

       admin( $admin )

           set the administrative user, and will return administator username.

       password( $string )

           set the password, returns an empty string

   Miscelleaneous statistics methods
       There are a few methods to access some statistics data that is collected while the object
       performing Google API calls.

       authtime()

           returns the time of last authentication, as generated by the time() function

       ctime()

           returns the create time of the object, as generated by the time() function

       rtime()

           returns the time of the most recent request, as generated by the time() function

       logins()

           returns the number of API logins that have been performed

       requests()

           returns the numbers of API requests that have been submitted to Google

       success()

           returns the numbers of successful api request performed

       And finally,

       version()

           returns a string with the api version implemented. This is currently '1.0'

ACCESSING RESULTING DATA

       Valid return data from Google is parsed into a hash named 'result', available through the
       object. In this hash you can find all elements as returned by Google.  This hash is
       produced by XML::Simple. See the Google API documentation in the SEE ALSO section for
       complete details.  Some of the more useful elements you may need to look at are:

               $google->{result}->{reason}             #this typically has the textual reason for a failure
               $google->{result}->{extendedMessage}    #a more extensive description of the failure reason may be here
               $google->{result}->{result}             #typically empty!
               $google->{result}->{type}               #should be same of query type, eg 'Account', 'Alias', 'MailingList'

       The retrieval section contains data when you are querying. Here is what this section looks
       like when you call the RetrieveAccount method:

               $google->{result}->{RetrievalSection}->{firstName}
               $google->{result}->{RetrievalSection}->{lastName}
               $google->{result}->{RetrievalSection}->{accountStatus}
               $google->{result}->{RetrievalSection}->{aliases}->{alias}
               $google->{result}->{RetrievalSection}->{emailLists}->{emailList}

       To see the structure of the result hash, use the Data::Dumper module as such:

               use Data::Dumper;
               print Dumper($google->{result});

ACCESSING RAW GOOGLE POST AND RESULT DATA

       The data from the most recent post to the Google servers is available. You can access it
       as:

               print $google->requestcontent();

       The most recent received HTML data is stored in two parts, the headers and the content.
       Both are strings. They can be accessed as such:

               print $google->replyheaders();
               print $google->replycontent();

       Note the headers are new-line separated and can easily be parsed:

               foreach my $headerline ( split/\n/, $g->replyheaders() )
               {
                       my ($header, $value) = split/:/, $headerline;
               }

EXPORT

       None by default.

SEE ALSO

       The official Google documentation can be found at
       http://code.google.com/apis/apps-for-your-domain/google_apps_provisioning_api_v1.0_reference.html

       For support, see the Google Group at
       http://groups.google.com/group/apps-for-your-domain-apis

       For additional support specific to this modules, email me at johan at reinalda dot net.

AUTHOR

       Johan Reinalda, johan at reinalda dot net

COPYRIGHT AND LICENSE

       Copyright (C) 2006 by Johan Reinalda, johan at reinalda dot net

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself, either Perl version 5.8.5 or, at your option, any later version of
       Perl 5 you may have available.

       If you make useful modification, kindly consider emailing then to me for inclusion in a
       future version of this module.