.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::Citadel 3pm"
.TH Net::Citadel 3pm "2013-06-05" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::Citadel \- Citadel.org protocol coverage
.SH "VERSION"
.IX Header "VERSION"
Version 0.20
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&  use Net::Citadel;
\&  my $c = new Net::Citadel (host => \*(Aqcitadel.example.org\*(Aq);
\&  $c\->login (\*(AqAdministrator\*(Aq, \*(Aqgoodpassword\*(Aq);
\&  my @floors = $c\->floors;
\&
\&  eval {
\&     $c\->assert_floor (\*(AqLevel 6 (Management)\*(Aq);
\&  }; warn $@ if $@;
\&
\&  $c\->retract_floor (\*(AqLevel 6 (Management)\*(Aq);
\&
\&  $c\->logout;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Citadel is a \*(L"turnkey open-source solution for email and collaboration\*(R" (this is as far as marketing
can go :\-). The main component is the \fIcitadel server\fR. To communicate with it you can use either
a web interface, or \- if you have to automate things \- with a protocol
.PP
.Vb 1
\&   L<http://www.citadel.org/doku.php?id=documentation:appproto:start>
.Ve
.PP
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.
.SH "CONSTANTS"
.IX Header "CONSTANTS"
.SS "Configuration"
.IX Subsection "Configuration"
.IP "\s-1CITADEL_PORT\s0" 4
.IX Item "CITADEL_PORT"
The constant \f(CW$CITADEL_PORT\fR is equal to \f(CW504\fR, which is the \s-1IANA\s0 standard Citadel port.
.SS "Result Codes"
.IX Subsection "Result Codes"
.IP "\s-1LISTING_FOLLOWS\s0" 4
.IX Item "LISTING_FOLLOWS"
The result code \f(CW$LISTING_FOLLOWS\fR is equal to \f(CW100\fR and is used by the Citadel
server to indicate that after the server response, the server will output a
listing of some sort.
.IP "\s-1CIT_OK\s0" 4
.IX Item "CIT_OK"
The result code \f(CW$CIT_OK\fR is equal to \f(CW200\fR and is used by the Citadel
server to indicate that the requested operation succeeded.
.IP "\s-1MORE_DATA\s0" 4
.IX Item "MORE_DATA"
The result code \f(CW$MORE_DATA\fR is equal to \f(CW300\fR and is used by the Citadel server
to indicate that the requested operation succeeded but that another command is
required to complete it.
.IP "\s-1SEND_LISTING\s0" 4
.IX Item "SEND_LISTING"
The result code \f(CW$SEND_LISTING\fR is equal to \f(CW400\fR 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.
.IP "\s-1ERROR\s0" 4
.IX Item "ERROR"
The result code \f(CW$ERROR\fR is equal to \f(CW500\fR 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.
.IP "\s-1BINARY_FOLLOWS\s0" 4
.IX Item "BINARY_FOLLOWS"
The result code \f(CW$BINARY_FOLLOWS\fR is equal to \f(CW600\fR and is used by the Citadel server to
indicate that after this line, read \f(CW\*(C`n\*(C'\fR bytes. (<Cn> follows after a blank)
.IP "\s-1SEND_BINARY\s0" 4
.IX Item "SEND_BINARY"
The result code \f(CW$SEND_BINARY\fR is equal to \f(CW700\fR and is used by the Citadel server to
indicate that \f(CW\*(C`n\*(C'\fR bytes of binary data can now be sent. (\f(CW\*(C`n\*(C'\fR follows after a blank.
.IP "\s-1START_CHAT_MODE\s0" 4
.IX Item "START_CHAT_MODE"
The result code \f(CW$START_CHAT_MODE\fR is equal to \f(CW800\fR and is used by the Citadel
server to indicate that the system is in chat mode now. Every line sent will be
broadcasted.
.IP "\s-1ASYNC_MSG\s0" 4
.IX Item "ASYNC_MSG"
The result code \f(CW$ASYC_MSG\fR is equal to \f(CW900\fR and is used by the Citadel
server to indicate that there is a page waiting that needs to be fetched.
.SS "Room Access"
.IX Subsection "Room Access"
.IP "\s-1PUBLIC\s0" 4
.IX Item "PUBLIC"
The room access code \f(CW$PUBLIC\fR is equal to \f(CW0\fR and is used to indicate that a
room is to have public access.
.IP "\s-1PRIVATE\s0" 4
.IX Item "PRIVATE"
The room access code \f(CW$PRIVATE\fR is equal to \f(CW1\fR and is used to indicate that a
room is to have private access.
.IP "\s-1PRIVATE_PASSWORD\s0" 4
.IX Item "PRIVATE_PASSWORD"
The room access code \f(CW$PRIVATE_PASSWORD\fR is equal to \f(CW2\fR and is used to indicate
that a room is to have private access using a password.
.IP "\s-1PRIVATE_INVITATION\s0" 4
.IX Item "PRIVATE_INVITATION"
The room access code \f(CW$PRIVATE_INVITATION\fR is equal to \f(CW3\fR and is used to indicate
that a room is to have private access by invitation.
.IP "\s-1PERSONAL\s0" 4
.IX Item "PERSONAL"
The room access code \f(CW$PERSONAL\fR is equal to \f(CW4\fR and is used to indicate
that a room is to be a private mailbox only for a particular user.
.SS "User related"
.IX Subsection "User related"
.IP "\s-1DELETED_USER\s0" 4
.IX Item "DELETED_USER"
The room access code \f(CW$DELETED_USER\fR is equal to \f(CW0\fR.
.IP "\s-1NEW_USER\s0" 4
.IX Item "NEW_USER"
The User related constant \f(CW$NEW_USER\fR is equal to \f(CW1\fR.
.IP "\s-1PROBLEM_USER\s0" 4
.IX Item "PROBLEM_USER"
The User related constant \f(CW$PROBLEM_USER\fR is equal to \f(CW2\fR.
.IP "\s-1LOCAL_USER\s0" 4
.IX Item "LOCAL_USER"
The User related constant \f(CW$LOCAL_USER\fR is equal to \f(CW3\fR.
.IP "\s-1NETWORK_USER\s0" 4
.IX Item "NETWORK_USER"
The User related constant \f(CW$NETWORK_USER\fR is equal to \f(CW4\fR.
.IP "\s-1PREFERRED_USER\s0" 4
.IX Item "PREFERRED_USER"
The User related constant \f(CW$PREFERRED_USER\fR is equal to \f(CW5\fR.
.IP "\s-1AIDE_USER\s0" 4
.IX Item "AIDE_USER"
The User related constant \f(CW$AIDE\fR user is equal to \f(CW6\fR.
.SH "INTERFACE"
.IX Header "INTERFACE"
.SS "Constructor"
.IX Subsection "Constructor"
\&\f(CW\*(C`$c = new Net::Citadel (host =\*(C'\fR \f(CW$ctdl_host\fR)>
.PP
The constructor creates a handle to the citadel server (and creates the \s-1TCP\s0
connection). It uses the following named parameters:
.ie n .IP "\fIhost\fR (default: ""localhost"")" 4
.el .IP "\fIhost\fR (default: \f(CWlocalhost\fR)" 4
.IX Item "host (default: localhost)"
The hostname (or \s-1IP\s0 address) where the citadel server is running. Defaults
to \f(CW\*(C`localhost\*(C'\fR.
.ie n .IP "\fIport\fR (default: $CITADEL_PORT)" 4
.el .IP "\fIport\fR (default: \f(CW$CITADEL_PORT\fR)" 4
.IX Item "port (default: $CITADEL_PORT)"
The port where the citadel server is running. Defaults to the standard Citadel
port number \f(CW504\fR.
.PP
The constructor will croak if no connection can be established.
.SS "Methods"
.IX Subsection "Methods"
\fIAuthentication\fR
.IX Subsection "Authentication"
.IP "\fIlogin\fR" 4
.IX Item "login"
\&\fI\f(CI$c\fI\fR\->login (\fI\f(CI$user\fI\fR, \fI\f(CI$pwd\fI\fR)
.Sp
Logs in this user, or will croak if that fails.
.IP "\fIlogout\fR" 4
.IX Item "logout"
\&\fI\f(CI$c\fI\fR\->logout
.Sp
Well, logs out the current user.
.PP
\fIFloors\fR
.IX Subsection "Floors"
.IP "\fIfloors\fR" 4
.IX Item "floors"
\&\fI\f(CI@floors\fI\fR = \fI\f(CI$c\fI\fR\->floors
.Sp
Retrieves a list (\s-1ARRAY\s0) of known floors. Each entry is a hash reference with the name, the number
of rooms in that floor and the index as \s-1ID\s0. The index within the array is also the \s-1ID\s0 of the floor.
.IP "\fIassert_floor\fR" 4
.IX Item "assert_floor"
\&\fI\f(CI$c\fI\fR\->assert_floor (\fI\f(CI$floor_name\fI\fR)
.Sp
Creates the floor with the name provided, or if it already exists simply returns. This only croaks if
there are insufficient privileges.
.IP "\fIretract_floor\fR" 4
.IX Item "retract_floor"
\&\fI\f(CI$c\fI\fR\->retract_floor (\fI\f(CI$floor_name\fI\fR)
.Sp
Retracts a floor with this name. croaks if that fails because of insufficient privileges. Does
not croak if the floor did not exist.
.Sp
\&\fB\s-1NOTE\s0\fR: 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.
.IP "\fIrooms\fR" 4
.IX Item "rooms"
\&\fI\f(CI@rooms\fI\fR = \fI\f(CI$c\fI\fR\->rooms (\fI\f(CI$floor_name\fI\fR)
.Sp
Retrieves the rooms on that given floor.
.PP
\fIRooms\fR
.IX Subsection "Rooms"
.IP "\fIassert_room\fR" 4
.IX Item "assert_room"
\&\fI\f(CI$c\fI\fR\->assert_room (\fI\f(CI$floor_name\fI\fR, \fI\f(CI$room_name\fI\fR, [ \fI\f(CI$room_attributes\fI\fR ])
.Sp
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.
.Sp
The optional room attributes are provided as hash with the following fields
.RS 4
.ie n .IP """access"" (default: ""PUBLIC"")" 4
.el .IP "\f(CWaccess\fR (default: \f(CWPUBLIC\fR)" 4
.IX Item "access (default: PUBLIC)"
One of the constants \f(CW\*(C`PUBLIC\*(C'\fR, \f(CW\*(C`PRIVATE\*(C'\fR, \f(CW\*(C`PRIVATE_PASSWORD\*(C'\fR, \f(CW\*(C`PRIVATE_INVITATION\*(C'\fR or
\&\f(CW\*(C`PERSONAL\*(C'\fR.
.ie n .IP """password"" (default: empty)" 4
.el .IP "\f(CWpassword\fR (default: empty)" 4
.IX Item "password (default: empty)"
.PD 0
.ie n .IP """default_view"" (default: empty)" 4
.el .IP "\f(CWdefault_view\fR (default: empty)" 4
.IX Item "default_view (default: empty)"
.RE
.RS 4
.RE
.IP "\fIretract_room\fR" 4
.IX Item "retract_room"
.PD
\&\fI\f(CI$c\fI\fR\->retract_room (\fI\f(CI$floor_name\fI\fR, \fI\f(CI$room_name\fI\fR)
.Sp
\&\fB\s-1NOTE\s0\fR: Not implemented yet.
.PP
\fIUsers\fR
.IX Subsection "Users"
.IP "\fIcreate_user\fR" 4
.IX Item "create_user"
\&\fI\f(CI$c\fI\fR\->create_user (\fI\f(CI$username\fI\fR, \fI\f(CI$password\fI\fR)
.Sp
Tries to create a user with name and password. Fails if this user already exists (or some other
reason).
.IP "\fIchange_user\fR" 4
.IX Item "change_user"
\&\fI\f(CI$c\fI\fR\->change_user (\fI\f(CI$user_name\fI\fR, \fI\f(CI$aspect\fI\fR => \fI\f(CI$value\fI\fR)
.Sp
Changes certain aspects of a user. Currently understood aspects are
.RS 4
.ie n .IP """password"" (string)" 4
.el .IP "\f(CWpassword\fR (string)" 4
.IX Item "password (string)"
.PD 0
.ie n .IP """access_level"" (0..6, constants available)" 4
.el .IP "\f(CWaccess_level\fR (0..6, constants available)" 4
.IX Item "access_level (0..6, constants available)"
.RE
.RS 4
.RE
.IP "\fIremove_user\fR" 4
.IX Item "remove_user"
.PD
\&\fI\f(CI$c\fI\fR\->remove_user (\fI\f(CI$name\fI\fR)
.Sp
Removes the user (actually sets level to \f(CW\*(C`DELETED_USER\*(C'\fR).
.PP
\fIMiscellaneous\fR
.IX Subsection "Miscellaneous"
.IP "\fIcitadel_echo\fR" 4
.IX Item "citadel_echo"
\&\fI\f(CI$c\fI\fR\->citadel_echo (\fI\f(CI$string\fI\fR)
.Sp
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.
.IP "\fIcitadel_info\fR" 4
.IX Item "citadel_info"
\&\f(CW$info_aref\fR = \fI\f(CI$c\fI\fR\->\fIcitadel_info()\fR
.Sp
Sends the \f(CW\*(C`INFO\*(C'\fR 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:
.Sp
.Vb 5
\& my $c = new Net::Citadel (host => $host_name);
\& my $info_aref = $c\->citadel_info;
\& foreach $line (@{$info_aref}) {
\&    print $line;
\& }
.Ve
.Sp
For more details about the server information lines that are returned, see the
\&\f(CW\*(C`INFO\*(C'\fR entry at <http://www.citadel.org/doku.php/documentation:appproto:connection>.
.IP "\fIcitadel_mrtg\fR" 4
.IX Item "citadel_mrtg"
\&\f(CW%mrtg_hash\fR = \fI\f(CI$c\fI\fR\->citadel_mrtg($type)
.Sp
Sends the \f(CW\*(C`MRTG\*(C'\fR command to the Citadel server. It expects a type of either
\&\f(CW\*(C`users\*(C'\fR or \f(CW\*(C`messages\*(C'\fR to be passed to it and returns a hash containing the
information from the server.
.RS 4
.ie n .IP "ActiveUsers Number of active users on the system.  Only returned for type ""users""." 4
.el .IP "ActiveUsers Number of active users on the system.  Only returned for type \f(CWusers\fR." 4
.IX Item "ActiveUsers Number of active users on the system.  Only returned for type users."
.PD 0
.IP "ConnectedUsers" 4
.IX Item "ConnectedUsers"
.PD
Number of connected users on the system.  Only returned for type \f(CW\*(C`users\*(C'\fR.
.IP "HighMsg" 4
.IX Item "HighMsg"
Higest message number on the system.  Only returned for type \f(CW\*(C`messages\*(C'\fR.
.IP "SystemUptime" 4
.IX Item "SystemUptime"
The uptime for the system formated as days, hours, minutes.
.IP "SystemName" 4
.IX Item "SystemName"
Human readable name of the Citadel system.
.RE
.RS 4
.RE
.IP "\fIcitadel_time\fR" 4
.IX Item "citadel_time"
\&\fI\f(CI$t\fI\fR = \fI\f(CI$c\fI\fR\->citadel_time
.Sp
Gets the current system time and time zone offset from \s-1UTC\s0 in \s-1UNIX\s0 timestamp format from the Citadel server.
.Sp
\&\f(CW\*(C`TODO\*(C'\fR: Rewrite function to return the unpacked parameters as a hash upon success.
.SH "TODOs"
.IX Header "TODOs"
\&\- Decent \s-1GUI\s0 using Mason + \s-1AJAX\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.Vb 1
\&   L<http://www.citadel.org/doku.php?id=documentation:appproto:app_proto>
.Ve
.SH "AUTHORS"
.IX Header "AUTHORS"
Robert Barta, <drrho@cpan.org>
Robert James Clay, <jame@rocasa.us>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2007\-2008 by Robert Barta
Copyright (C) 2012\-2013 by Robert James Clay
.PP
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.