| [vhffs-dev] [521] Added some documentation. |
[ Thread Index |
Date Index
| More vhffs.org/vhffs-dev Archives
]
Revision: 521
Author: beuss
Date: 2007-03-21 08:45:01 +0000 (Wed, 21 Mar 2007)
Log Message:
-----------
Added some documentation.
Modified Paths:
--------------
branches/vhffs_4.1/vhffs-api/src/Vhffs/Group.pm
branches/vhffs_4.1/vhffs-api/src/Vhffs/Object.pm
branches/vhffs_4.1/vhffs-api/src/Vhffs/Services/Httpd.pm
branches/vhffs_4.1/vhffs-api/src/Vhffs/Stats.pm
branches/vhffs_4.1/vhffs-api/src/Vhffs/User.pm
Modified: branches/vhffs_4.1/vhffs-api/src/Vhffs/Group.pm
===================================================================
--- branches/vhffs_4.1/vhffs-api/src/Vhffs/Group.pm 2007-03-21 08:44:31 UTC (rev 520)
+++ branches/vhffs_4.1/vhffs-api/src/Vhffs/Group.pm 2007-03-21 08:45:01 UTC (rev 521)
@@ -51,28 +51,6 @@
=head2 METHODS
-=head3 new($main, $groupname, $owner[, $gid])
-
-Create a new group.
-
-=over
-
-=item $main is an instance of Vhffs::Main.
-
-=item $groupname is the groupname.
-It must be composed of small letters and digit
-only an must be at least 3 characters long.
-
-=item $owner is the uid of the group owner.
-
-=item $gid is the group id (not mandatory)
-
-=back
-
-=head2 FUNCTIONS
-
-TODO
-
=cut
sub new
@@ -205,6 +183,16 @@
}
+=pod
+
+=head2 create
+
+ my $group = Vhffs::Group::create($main, $groupname, $owner_uid, $gid, $description)
+
+Create in DB and return a fully functional group.
+
+=cut
+
sub create {
return old_create(@_) if($_[0]->isa('Vhffs::Group'));
my ($main, $groupname, $owner_uid, $gid, $description) = @_;
Modified: branches/vhffs_4.1/vhffs-api/src/Vhffs/Object.pm
===================================================================
--- branches/vhffs_4.1/vhffs-api/src/Vhffs/Object.pm 2007-03-21 08:44:31 UTC (rev 520)
+++ branches/vhffs_4.1/vhffs-api/src/Vhffs/Object.pm 2007-03-21 08:45:01 UTC (rev 521)
@@ -36,23 +36,17 @@
=head1 DESCRIPTION
The Vhffs::Object type is the base of each Vhffs::Services::*, Vhffs::User
-or Vhffs::Group objects. So, you never have to create an instance of Vhffs::Object
-, this class is only use as a super-class for services (or user or group).
+or Vhffs::Group objects. So, you never have to create an instance of Vhffs::Object,
+this class is only used as a super-class for services (or user or group).
-So, the method of Vhffs::Object can be applied to all class which inherit of it.
-Commonly, you can have all the history of an object with a method, get the status
+So, the methods of Vhffs::Object can be applied to all classes which inherit of it.
+You can have all the history of an object with a method, get the status
of a service, ...
This type stored informations about state, history, owner group/user.
=head1 METHODS
-=head2 new( Vhffs::Main , 1 , '401')
-
-Create an instance of Vhffs::Object. Typically, this method is onvoked is the new method of inherited class. It creates an object, with a fixed object-id (arg 2) and the owner from uid (arg3).
-The first argument is a Vhffs::Main object.
-Return undef if failed.
-
=cut
@@ -161,14 +155,28 @@
}
}
-=head2 Vhffs::Object::create(Vhffs::Main, owner_uid, description, state)
+=head2 create
-Create and return a new object.
-owner_uid can be undef (should be used only for user creation).
-state can be undef, if it is, object will be waiting for validation or
-waiting for creation depending on wether moderation is active or not.
-Returned object is a fully created object, no need to fetch it.
+ my $object = Vhffs::Object::create($main, [$owner_uid, $description, $state, $type])
+Create (in database) and return a new object.
+
+=over 4
+
+=item C<$main>: C<Vhffs::Main> instance
+
+=item C<$owner_uid>: UID of the owner.
+
+=item C<$description>: Description of the object
+
+=item C<$state>: state of the object. Can be undef, if it is, object will be
+waiting for validation or waiting for creation depending on wether
+moderation is active or not.
+
+=item C<$type>: Object's type (C<Vhffs::Constants::TYPE_*>)
+
+=back
+
=cut
sub create {
@@ -515,6 +523,17 @@
return undef;
}
+=pod
+
+=head2 get_by_oid
+
+ my $obj = Vhffs::Object::get_by_oid($main, $oid);
+
+Fetches an object using its object ID. Returned object is
+fully functional.
+
+=cut
+
sub get_by_oid
{
my ($vhffs, $oid) = @_;
Modified: branches/vhffs_4.1/vhffs-api/src/Vhffs/Services/Httpd.pm
===================================================================
--- branches/vhffs_4.1/vhffs-api/src/Vhffs/Services/Httpd.pm 2007-03-21 08:44:31 UTC (rev 520)
+++ branches/vhffs_4.1/vhffs-api/src/Vhffs/Services/Httpd.pm 2007-03-21 08:45:01 UTC (rev 521)
@@ -391,7 +391,7 @@
my $sql;
my $sth;
- my $objs;
+ my $objs = [];
my $result;
my $tmp;
Modified: branches/vhffs_4.1/vhffs-api/src/Vhffs/Stats.pm
===================================================================
--- branches/vhffs_4.1/vhffs-api/src/Vhffs/Stats.pm 2007-03-21 08:44:31 UTC (rev 520)
+++ branches/vhffs_4.1/vhffs-api/src/Vhffs/Stats.pm 2007-03-21 08:45:01 UTC (rev 521)
@@ -30,27 +30,54 @@
# POSSIBILITY OF SUCH DAMAGE.
-#Vhffs::ACL written by sod` <dieu AT gunnm DOT org>
+=pod
-# This software is free software, please read LICENCE file
+=head1 NAME
+
+Vhffs:Stats - Provide statistics on Vhffs Platform
+
+=head1 SYNOPSIS
+
+ my $main = init Vhffs::Main(...);
+
+ my $stats = new Vhffs::Stats($main);
+ my $lstcount = $stats->get_lists_in_moderation;
+
+ # Add some lists here...
+ # ...
+
+ $stats->refresh(); # Flush cache
+ my $newlstcount = $stats->get_lists_in_moderation;
+
+
+=head1 METHODS
+
+=cut
+
+
package Vhffs::Stats;
-#General perl modules
-use base qw(Vhffs::Object);
use strict;
-#Vhffs specific modules
+use base qw(Vhffs::Object);
use Vhffs::Constants;
+=pod
+=head2 new
+
+ my $stats = new Vhffs::Stats($main);
+
+Creates a new Vhffs::Stats instance. C<$main> is
+the C<Vhffs::Main> instance used to get database
+connection.
+
+=cut
sub new
{
- my $this;
- my $self;
-
my ( $class , $main ) = @_;
- $this = {};
+ my $this = {};
$this->{'main'} = $main;
@@ -58,14 +85,40 @@
bless( $this , $class );
}
+=pod
-sub fetch
-{
- my ($package, $file, $line) = caller();
- warn("You are calling Vhffs::Stats::fetch, this is useless, this method does nothing, just ask for the stats you need using get_xxxx (from $package - $file:$line");
- return 1;
+=head2 refresh
+
+ $stats->refresh();
+
+When you call a C<get_xxxx> method, data
+are fetched from database and cached. If you
+want to flush the cache, call C<refresh>.
+
+There are very few cases where this method should
+be used.
+
+=cut
+
+sub refresh {
+ my $self = shift;
+ foreach(keys(%{$self})) {
+ next if($_ eq 'main' || $_ eq 'db');
+ delete $self->{$_}
+ }
}
+=pod
+
+=head2 get_lists_totalsubs
+
+ my $count = $stats->get_lists_totalsubs();
+
+Returns the count of mailing list subscribers on
+the platform.
+
+=cut
+
sub get_lists_totalsubs
{
my $self = shift;
@@ -76,8 +129,17 @@
return $self->{lists}{totalsubs};
}
+=pod
+=head2 get_lists_in_moderation
+ my $count = $stats->get_lists_in_moderation();
+
+Returns the count of mailing lists waiting for
+moderation.
+
+=cut
+
sub get_lists_in_moderation
{
my $self = shift;
@@ -88,6 +150,16 @@
return $self->{lists}{awaiting_validation};
}
+=pod
+
+=head2 get_lists_in_activated
+
+ my $count = $stats->get_lists_activated();
+
+Returns the count of mailing lists currently activated.
+
+=cut
+
sub get_lists_activated
{
my $self = shift;
@@ -98,6 +170,16 @@
return $self->{lists}{activated};
}
+=pod
+
+=head2 get_lists_total
+
+ my $count = $stats->get_lists_total();
+
+Returns the total count of mailing lists (activated or not).
+
+=cut
+
sub get_lists_total
{
my $self = shift;
@@ -344,3 +426,5 @@
1;
+
+
Modified: branches/vhffs_4.1/vhffs-api/src/Vhffs/User.pm
===================================================================
--- branches/vhffs_4.1/vhffs-api/src/Vhffs/User.pm 2007-03-21 08:44:31 UTC (rev 520)
+++ branches/vhffs_4.1/vhffs-api/src/Vhffs/User.pm 2007-03-21 08:45:01 UTC (rev 521)
@@ -38,7 +38,48 @@
#You can manage user with Unix.
#libnss-postgresql must be used with it to have an account on a machine with the database
+=pod
+=head1 NAME
+
+Vhffs::User - Vhffs Interface to handle *NIX users
+
+=head1 SYNOPSIS
+
+ use Vhffs::Main;
+ $vhffs = init Vhffs::Main;
+ $user = Vhffs::User::get_by_username( $vhffs , "myuser" );
+ if( defined $user )
+ {
+ print "User exists\n";
+ }
+ else
+ {
+ print "User does not exists\n";
+ }
+ ...
+ $user = Vhffs::User::create( $vhffs, 'myuser', 'apassword', 0, 'myuser@xxxxxxxxx');
+ if( defined $user )
+ {
+ print "User created";
+ }
+ else
+ {
+ print "User error\n";
+ }
+ ...
+ print "Username: $user->get_username";
+ ...
+ if( $user->commit > 0 )
+ {
+ print "Update user status : succesfull\n";
+ }
+
+=head1 METHODS
+
+=cut
+
+
use base qw(Vhffs::Object);
use strict;
use DBI;
@@ -194,8 +235,10 @@
=pod
-Vhffs::User::check_username($username)
+=head2 check_username
+ print 'Username valid' if(Vhffs::User::check_username($username));
+
returns false if username is not valid (length not between 3 and 12, name not
composed of alphanumeric chars)
@@ -207,6 +250,18 @@
}
+=pod
+
+=head2 create
+
+ my $u = Vhffs::User::create($main, $username, $password, $admin,
+ $mail, $firstname, $lastname, $city, $zipcode,
+ $country, $address, $gpg_key);
+
+Create in DB and return a fully functional user.
+
+=cut
+
sub create {
# for compatibility until complete refactoring
if($_[0]->isa('Vhffs::User')) {
@@ -944,148 +999,12 @@
__END__
-=head1 NAME
-
-Vhffs::User - Vhffs Interface to handle *NIX users
-
-=head1 SYNOPSIS
-
- use Vhffs::Main;
- $vhffs = init Vhffs::Main;
- $user = Vhffs::User::get_by_username( $vhffs , "myuser" );
- if( defined $user )
- {
- print "User exists\n";
- }
- else
- {
- print "User does not exists\n";
- }
- ...
- $user = Vhffs::User::create( $vhffs, 'myuser', 'apassword', 0, 'myuser@xxxxxxxxx');
- if( defined $user )
- {
- print "User created";
- }
- else
- {
- print "User error\n";
- }
- ...
- print "Username: $user->get_username";
- ...
- if( $user->commit > 0 )
- {
- print "Update user status : succesfull\n";
- }
-
-=head1 METHODS
-
-I<FIXME : This sections isn't up to date>
-
-For each method, returns 1 if success, 0 otherwise. If the method should returns a reference, returns undef if fails.
-
-new( Vhffs::Main , "username" , "uid" ) : instanciate a new user
-
-exists( ) : return 1 if the user exists, 0 otherwise
-
-fetch( ) : fetch informations for this user from the database. You have to call fetch before working on the user
-
-get_all_unix_users( ) - static method : returns a hashref with all unix users. Hashkey is the username
-
-get_all_users( ) - static method : returns a hashref with all users. Hashkey is the username
-
-add_group( Vhffs::Group ) : add a user in a group. Returns 1 if success, 0 otherwise
-
-create( ) : create the user. Returns 1 if success, 0 otherwise
-
-commit( ) : commit changes on the current instance on the database
-
-delete( ) : delete the user from the platform
-
-send_mail( $subject , $content ) : send a mail to the user. The subject of the mail is the first argument, the second if the content of the mail
-
-generate_password( ) : generate a new password for this user. Returns the password.
-
-get_username( )
-
-get_firstname( )
-
-get_lastname( )
-
-get_city( )
-
-get_country( )
-
-get_gpg( )
-
-get_zipcode( )
-
-get_home( )
-
-get_password( ) : returns the encrypted password
-
-set_password( $clear ) : set a new password. New password is given in the argument
-
-get_uid( )
-
-get_gid( )
-
-get_lang( )
-
-get_mail( )
-
-get_group( )
-
-get_address( )
-
-get_shell( )
-
-set_username( $name )
-
-set_firstname( $firstname )
-
-set_lastname( $lastname )
-
-set_city( $city )
-
-set_country( $country )
-
-set_gpg( $gpg )
-
-set_zipcode( $zc )
-
-set_admin( 1 or 0 )
-
-set_mail( $mail )
-
-set_address( )
-
-set_shell( )
-
-is_admin( ) : returns 1 if the user is admin 0 otherwise
-
-is_moderator( ) : returns 1 if the user is moderator 0 otherwise
-
-get_name_by_uid( $uid ) : returns the name that correspond to the uid given in parameter. Return "nobody" if no user own this uid
-
-getall( Vhffs::Main , $state , $name )
-
-get_last_users( ) : returns an array with the last 10 users
-
-get_groups( ) : returns a arrayred with the groups of the user
-
-have_groups( ) : returns 0 if user don't have groups, else returns the number of groups, returns < 0 if an error occured
-
-
-
-
-
-
=head1 SEE ALSO
Vhffs::Group , Vhffs::Main , Vhffs::Constants
-=head1 AUTHOR
+=head1 AUTHORS
Julien Delange <julien at tuxfamily dot org>
+
+Sebastien Le Ray <beuss at tuxfamily dot org>