NAME
Net::Citadel - Citadel.org protocol coverage
VERSION
Version 0.10
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
L<http://www.citadel.org/doku.php?id=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.
CONSTANTS
Configuration
- CITADEL_PORT
-
The constant $CITADEL_PORT is equal to
504, which is the IANA standard Citadel port.
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 croak if no connection can be established.
Methods
Authentication
- login
-
$c->login ($user, $pwd)
Logs in this user, or will croak 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 croaks if there are insufficient privileges.
- retract_floor
-
$c->retract_floor ($floor_name)
Retracts a floor with this name. croaks if that fails because of insufficient privileges. Does not croak 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
- 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
- remove_user
-
$c->remove_user ($name)
Removes the user (actually sets level to
DELETED_USER).
Miscellaneous
- citadel_echo
-
$c->citadel_echo ($string)
Tests a connection to the Citadel server by sending a message string to it and then checking to see if that same string is echoed back.
- citadel_time
-
$t = $c->citadel_time
Gets the current system time and time zone offset from UTC in UNIX timestamp format from the Citadel server.
TODO: Rewrite function to return the unpacked parameters as a hash upon success.
TODOs
- Decent GUI using Mason + AJAX
SEE ALSO
L<http://www.citadel.org/doku.php?id=documentation:appproto:app_proto>AUTHORS
Robert Barta, <drrho@cpan.org> Robert James Clay, <jame@rocasa.us>
COPYRIGHT AND LICENSE
Copyright (C) 200[78] by Robert Barta Copyright (C) 2012 by Robert James Clay
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.