[vuser] r583 committed - Documentation updates

[codesite...@google.com]

Revision: 583
Author: perlstalker
Date: Sat Nov 28 21:52:13 2009
Log: Documentation updates
http://code.google.com/p/vuser/source/detail?r=583

Modified:
/VUser-Google-ProvisioningAPI/trunk/lib/VUser/Google/Provisioning/V2_0.pm

=======================================
---
/VUser-Google-ProvisioningAPI/trunk/lib/VUser/Google/Provisioning/V2_0.pm
Sat Nov 28 20:23:58 2009
+++
/VUser-Google-ProvisioningAPI/trunk/lib/VUser/Google/Provisioning/V2_0.pm
Sat Nov 28 21:52:13 2009
@@ -380,3 +380,293 @@
1;

__END__
+
+=head1 NAME
+
+VUser::Google::Provisioning::V2_0 - Support for version 2.0 of the Google
Provisioning API
+
+=head1 SYNOPSIS
+
+ use VUser::Google::ApiProtocol::V2_0;
+ use VUser::Google::Provisioning::V2_0;
+
+ my $google = VUser::Google::ApiProtocol::V2_0->new(
+ domain => 'example.com',
+ admin => 'admin_user',
+ password => 'secret',
+ );
+
+ my $api = VUser::Google::Provisioning::V2_0->new(
+ google => $google,
+ );
+
+ ## Create user
+ my $new_user = $api->CreateUser(
+ userName => 'fflintstone',
+ givenName => 'Fred',
+ familyName => 'Flintstone',
+ password => 'I<3Wilma',
+ );
+
+ ## Retrieve a user
+ my $user = $api->RetrieveUser('fflintstone');
+
+ ## Retrieve all userr
+ my @users = $api->RetrieveAllUsers();
+
+ ## Update a user
+ my $updated = $api->UpdateUser(
+ userName => 'fflintstone',
+ givenName => 'Fredrock',
+ familyName => 'FlintStone',
+ suspended => 1,
+ quota => 2048,
+ );
+
+ ## Change password
+ $updated = $api->ChangePassword('fflintstone', 'new-pass');
+
+ $updated = $api->ChangePassword(
+ 'fflintstone',
+ '51eea05d46317fadd5cad6787a8f562be90b4446',
+ 'SHA-1',
+ );
+
+ $updated = $api->ChangePassword(
+ 'fflintstone',
+ 'd27117a019717502efe307d110f5eb3d',
+ 'MD5',
+ );
+
+ ## Delete a user
+ my $rc = $api->DeleteUser('fflintstone');
+
+=head1 DESCRIPTION
+
+VUser::Google::Provisioning::V2_0 provides support for managing users
+using version 2.0 of the Google Provisioning API.
+
+In order to use the Google Provisioning API, you must turn on API support
+from the Google Apps for Your Domain control panel. The user that is
+used to create the VUser::Google::ApiProtocol object must have
administrative
+privileges on the domain.
+
+B<Note:> It's a good idea to log into the web control panel at least once
+as the API user in order to accept the the terms of service and admin
terms.
+If you don't, you'll get intermittent authentication errors when trying to
+use the API.
+
+=head2 METHODS
+
+Unless stated otherwise, these methods will die() if there is an API error.
+
+=head3 CreateUser
+
+CreateUser() takes a hash of create options and returns a
+VUser::Google::Provisioning::UserEntry object if the account
+was created. CreateUser() will die() if there is an error.
+
+The keys of the hash are:
+
+=over
+
+=item userName (required)
+
+The user name of the account to create
+
+=item givenName (required)
+
+The user's given name
+
+=item familyName (required)
+
+The user's family name
+
+=item password (required)
+
+The user's password. If hashFunctionName is also set, this is
+the base16-encoded hash of the password. Otherwise, this is the
+user's plaintext password.
+
+Google required that passwords be, at least, six characters.
+
+=item hashFunctionName
+
+hashFunctionName must be I<SHA-1> or I<MD5>. If this is set,
+password is the base16-encoded password hash.
+
+=item quota
+
+The user's quota in MB.
+
+Not all domains will be allowed to set users'
+quotas. If that's the case, creation will still succeed but the
+quota will be set to the default for your domain.
+
+=item changePasswordAtNextLogin
+
+If set to a true value, e.g. C<1>, the user will be required to
+change their password the next time they login in. This is the default.
+You may turn this off by setting changePasswordAtNextLogin to C<0>.
+
+=back
+
+=head3 RetrieveUser
+
+ my $user = $api->RetrieveUser('fflintstone');
+
+Retrieves a specified user by the user name. RetieveUser will return a
+VUser::Google::Provisioning::UserEntry if the user exists and undef
+if it doesn't.
+
+=head3 RetrieveUsers
+
+ my @users = ();
+
+ my %results = $api->RetrieveUsers();
+ @users = @{ $results{entries} };
+
+ while ($results{next}) {
+ %results = $api->RetrieveUsers($results{next});
+ push @users, @{ $results{entries} };
+ }
+
+Fetches one page of users starting at a given user name. Currently,
+a page is defined as 100 users. This is useful if you plan on
+paginating the results yourself or if you have a very large number
+of users.
+
+The returned result is a hash with the following keys:
+
+=over
+
+=item entries
+
+A list reference containing the user accounts. Each entry
+is a VUser::Google::Provisioning::UserEntry object.
+
+=item next
+
+The user name for the start of the next page. This will be
+undefined (C<undef>) if there are no more pages.
+
+=back
+
+See RetrieveAllUsers() if you want
+to fetch all of the accounts at once.
+
+=head3 RetrievePageOfUsers
+
+This is a synonym for RetrieveUsers()
+
+=head3 RetrieveAllUsers
+
+ my @users = $api->RetrieveAllUsers();
+
+Get a list of all the users for the domain. The entries in the
+list are VUser::Google::Provisioning::UserEntry objects.
+
+=head3 UpdateUser
+
+ my $updated = $api->UpdateUser(
+ userName => 'fflintstone',
+ givenName => 'Fred',
+ # ... other options
+ );
+
+Updates an account. UpdateUser takes the same options as CreateUser() but
+only userName is required.
+
+UpdateUser() cannot be used to rename an account. See RenameUser().
+
+=head3 RenameUser
+
+This has not yet been implemented.
+
+=head3 DeleteUser
+
+ my $rc = $api->DeleteUser('fflintstone');
+
+Deletes a given user. Returns true if the delete succeded and dies
+if there was an error.
+
+=head3 ChangePassword
+
+ $updated = $api->ChangePassword('fflintstone', 'new-pass');
+
+ $updated = $api->ChangePassword(
+ 'fflintstone',
+ '51eea05d46317fadd5cad6787a8f562be90b4446',
+ 'SHA-1',
+ );
+
+ $updated = $api->ChangePassword(
+ 'fflintstone',
+ 'd27117a019717502efe307d110f5eb3d',
+ 'MD5',
+ );
+
+Change a users password.
+
+ChangePassword takes the user name, password and, optionally, a
+hash function name. If the hash function name is set, the password,
+is the base16-encoded password, otherwise it is the clear text password.
+
+Accepted values for the has function name are I<MD5> and I<SHA-1>.
+
+There is no difference between using this and using UpdateUser to change
+the user's password.
+
+=head1 SEE ALSO
+
+=over
+
+=item *
+
+VUser::Google::Provisioning
+
+=item *
+
+VUser::Google::ApiProtocol::V2_0
+
+=item *
+
+VUser::Google::EmailSettings::V2_0
+
+=item *
+
+http://code.google.com/apis/apps/gdata_provisioning_api_v2.0_developers_protocol.html
+
+item *
+
+http://code.google.com/apis/apps/gdata_provisioning_api_v2.0_reference.html
+
+=back
+
+=head1 BUGS
+
+Bugs may be reported at http://code.google.com/p/vuser/issues/list.
+
+=head1 AUTHOR
+
+Randy Smith <perls...@vuser.org>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright (C) 2009 Randall Smith
+
+This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License
+as published by the Free Software Foundation; either version 2
+of the License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
USA.
+
+=cut