NAME¶
Net::Citadel - Citadel.org protocol coverage
VERSION¶
Version 0.20
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.
Result Codes¶
- LISTING_FOLLOWS
- The result code $LISTING_FOLLOWS is equal to 100 and is used by the
Citadel server to indicate that after the server response, the server will
output a listing of some sort.
- CIT_OK
- The result code $CIT_OK is equal to 200 and is used by the Citadel server
to indicate that the requested operation succeeded.
- MORE_DATA
- The result code $MORE_DATA is equal to 300 and is used by the Citadel
server to indicate that the requested operation succeeded but that another
command is required to complete it.
- SEND_LISTING
- The result code $SEND_LISTING is equal to 400 and is used by the Citadel
server to indicate that the requested operation is progressing and it is
now expecting zero or more lines of text.
- ERROR
- The result code $ERROR is equal to 500 and is used by the Citadel server
to indicate that the requested operation failed. The second and third
digits of the error code and/or the error message following it describes
why.
- BINARY_FOLLOWS
- The result code $BINARY_FOLLOWS is equal to 600 and is used by the Citadel
server to indicate that after this line, read "n" bytes.
(<Cn> follows after a blank)
- SEND_BINARY
- The result code $SEND_BINARY is equal to 700 and is used by the Citadel
server to indicate that "n" bytes of binary data can now be
sent. ("n" follows after a blank.
- START_CHAT_MODE
- The result code $START_CHAT_MODE is equal to 800 and is used by the
Citadel server to indicate that the system is in chat mode now. Every line
sent will be broadcasted.
- ASYNC_MSG
- The result code $ASYC_MSG is equal to 900 and is used by the Citadel
server to indicate that there is a page waiting that needs to be
fetched.
Room Access¶
- PUBLIC
- The room access code $PUBLIC is equal to 0 and is used to indicate that a
room is to have public access.
- PRIVATE
- The room access code $PRIVATE is equal to 1 and is used to indicate that a
room is to have private access.
- PRIVATE_PASSWORD
- The room access code $PRIVATE_PASSWORD is equal to 2 and is used to
indicate that a room is to have private access using a password.
- PRIVATE_INVITATION
- The room access code $PRIVATE_INVITATION is equal to 3 and is used to
indicate that a room is to have private access by invitation.
- PERSONAL
- The room access code $PERSONAL is equal to 4 and is used to indicate that
a room is to be a private mailbox only for a particular user.
- DELETED_USER
- The room access code $DELETED_USER is equal to 0.
- NEW_USER
- The User related constant $NEW_USER is equal to 1.
- PROBLEM_USER
- The User related constant $PROBLEM_USER is equal to 2.
- LOCAL_USER
- The User related constant $LOCAL_USER is equal to 3.
- NETWORK_USER
- The User related constant $NETWORK_USER is equal to 4.
- PREFERRED_USER
- The User related constant $PREFERRED_USER is equal to 5.
- AIDE_USER
- The User related constant $AIDE user is equal to 6.
INTERFACE¶
Constructor¶
"$c = new Net::Citadel (host =" $ctdl_host)>
The constructor creates a handle to the citadel server (and creates the TCP
connection). It uses the following named parameters:
- host (default: "localhost")
- The hostname (or IP address) where the citadel server is running. Defaults
to "localhost".
- port (default: $CITADEL_PORT)
- The port where the citadel server is running. Defaults to the standard
Citadel port number 504.
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
- "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
- 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_info
- $info_aref = $c->citadel_info()
Sends the "INFO" command to the Citadel server and returns the
lines it receives from that as a reference to an array. An example of
getting and then displaying the server information lines the following:
my $c = new Net::Citadel (host => $host_name);
my $info_aref = $c->citadel_info;
foreach $line (@{$info_aref}) {
print $line;
}
For more details about the server information lines that are returned, see
the "INFO" entry at
<http://www.citadel.org/doku.php/documentation:appproto:connection>.
- citadel_mrtg
- %mrtg_hash = $c->citadel_mrtg($type)
Sends the "MRTG" command to the Citadel server. It expects a type
of either "users" or "messages" to be passed to it and
returns a hash containing the information from the server.
- ActiveUsers Number of active users on the system. Only returned for type
"users".
- ConnectedUsers
- Number of connected users on the system. Only returned for type
"users".
- HighMsg
- Higest message number on the system. Only returned for type
"messages".
- SystemUptime
- The uptime for the system formated as days, hours, minutes.
- SystemName
- Human readable name of the Citadel system.
- 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) 2007-2008 by Robert Barta Copyright (C) 2012-2013 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.