NAME¶
Net::Citadel - Citadel.org protocol coverage
SYNOPSIS¶
use Net::Citadel;
my $c = new Net::Citadel (host => 'citadel.example.org');
$c->login ('Administrator', 'goodpassword');
my @floors = $c->floors;
eval {
$c->assert_floor ('Level 6 (Management)');
}; warn $@ if $@;
$c->retract_floor ('Level 6 (Management)');
$c->logout;
DESCRIPTION¶
Citadel is a "turnkey open-source solution for email and
collaboration" (this is as far as marketing can go :-). The main
component is the
citadel server. To communicate with it you can use
either a web interface, or - if you have to automate things - with a protocol
http://www.citadel.org/doku.php/documentation:appproto:start
This package tries to do a bit of abstraction (more could be done) and handles
some of the protocol handling. The basic idea is that the application using
the package deals with Citadel's objects: rooms, floors, users.
INTERFACE¶
Constructor¶
The constructor creates a handle to the citadel server (and creates the TCP
connection). It expects the following named parameters:
- host (default: "localhost")
- The hostname (or IP address) where the citadel server is
running on. Defaults to "localhost".
- port (default: "CITADEL_PORT")
- The port there.
The constructor will die if no connection can be established.
Methods¶
Authentication
- login
- $c->login
($user, $pwd)
Logs in this user, or will die if that fails.
- logout
- $c->logout
Well, logs out the current user.
Floors
- floors
- @floors =
$c->floors
Retrieves a list (ARRAY) of known floors. Each entry is a hash reference
with the name, the number of rooms in that floor and the index as ID. The
index within the array is also the ID of the floor.
- assert_floor
- $c->assert_floor
($floor_name )
Creates the floor with the name provided, or if it already exists simply
returns. This only dies if there are insufficient privileges.
- retract_floor
- $c->retract_floor
($floor_name )
Retracts a floor with this name. Dies if that fails because of insufficient
privileges. Does not die if the floor did not exist.
NOTE: Citadel server (v7.20) seems to have the bug that you cannot
delete an empty floor without restarting the server. Not much I can do
here about that.
- rooms
- @rooms =
$c->rooms ( $floor_name)
Retrieves the rooms on that given floor.
Rooms
- assert_room
- $c->assert_room
($floor_name , $room_name, [
$room_attributes ])
Creates the room on the given floor. If the room already exists there,
nothing else happens. If the floor does not exist, it will complain.
The optional room attributes are provided as hash with the following
fields
- "access" (default: "PUBLIC")
- One of the constants "PUBLIC",
"PRIVATE", "PRIVATE_PASSWORD",
"PRIVATE_INVITATION" or "PERSONAL".
- "password" (default: empty)
- "default_view" (default: empty)
- retract_room
- $c->retract_room
($floor_name , $room_name)
NOTE: Not implemented yet.
Users
- create_user
- $c->create_user
($username , $password)
Tries to create a user with name and password. Fails if this user already
exists (or some other reason).
- change_user
- $c->change_user
($user_name , $aspect =>
$value)
Changes certain aspects of a user. Currently understood aspects are
- "password" (string)
- "access_level" (0..6, constants available)
- remove_user
- $c->remove_user
($name )
Removes the user (actually sets level to "DELETED_USER").
Miscellaneous
- echo
- $c->echo
($string)
Tests the connection.
- time
- $t = $c->time
Gets the UNIX time from the server.
"TODO": timezone handling
TODOs¶
- Decent GUI using Mason + AJAX
SEE ALSO¶
http://www.citadel.org/doku.php/documentation:appproto:app_proto
AUTHOR¶
Robert Barta, <drrho@cpan.org>
COPYRIGHT AND LICENSE¶
Copyright (C) 200[78] by Robert Barta
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.8 or, at your option,
any later version of Perl 5 you may have available.