Provided by: libnet-citadel-perl_0.25-1_all bug

NAME

       Net::Citadel - Citadel.org protocol coverage

VERSION

       Version 0.25

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.

   User related
       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
               Highest message number on the system.  Only returned for type "messages".

           SystemUptime
               The uptime for the system formatted 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-2018 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.