Net::Citadel(3pm)

📦
version 0.25 · 2 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

💖 NAME 💖

Net::Citadel — bestie, this is your all-access pass to the Citadel.org protocol, like the whole thing, cover to cover. It's a Perl module (3pm, she's a manual-page girlie 💅).

✨ VERSION ✨

This is Version 0.25, no cap.

🦋 SYNOPSIS 🦋

okay so here's the vibe, in code:

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;

look at her go 😭✨

🌸 DESCRIPTION 🌸

So Citadel is, quoting the marketing girlies, a "turnkey open-source solution for email and collaboration" — and honestly that's as far as marketing can go :-). The main character of the whole thing is the citadel server. To talk to it you've got options: a web interface, or — if you're the automation type (and you are, you're here) — a protocol:

L<http://www.citadel.org/doku.php?id=documentation:appproto:start>

This package does a lil bit of abstraction (more could honestly be done, ngl) and handles some of the protocol handling for you. The whole idea is that whatever app is using this package gets to deal with Citadel's objects: rooms, floors, users. Cute, right? 🎀

👑 CONSTANTS 👑

🔧 Configuration

  • CITADEL_PORT — the constant $CITADEL_PORT equals 504, which is the IANA standard Citadel port. iconic number fr.

📟 Result Codes

  • LISTING_FOLLOWS — the result code $LISTING_FOLLOWS equals 100, and the Citadel server uses it to say: heads up, after this response I'm gonna dump a listing of some sort. 💌
  • CIT_OK — the result code $CIT_OK equals 200, and it means the thing you asked for worked. slay.
  • MORE_DATA — the result code $MORE_DATA equals 300, and it means the operation succeeded but you gotta send another command to actually finish it. cliffhanger energy.
  • SEND_LISTING — the result code $SEND_LISTING equals 400, and it means the operation is progressing and the server is now expecting zero or more lines of text from you.
  • ERROR — the result code $ERROR equals 500, and it means the operation failed 😭. The second and third digits of the error code and/or the error message following it will tell you why.
  • BINARY_FOLLOWS — the result code $BINARY_FOLLOWS equals 600, and it means: after this line, read "n" bytes. (<Cn> follows after a blank.)
  • SEND_BINARY — the result code $SEND_BINARY equals 700, and it means you can now send "n" bytes of binary data. ("n" follows after a blank.
  • START_CHAT_MODE — the result code $START_CHAT_MODE equals 800, and it means the system is in chat mode now. Every single line you send gets broadcasted. main character energy, everyone's watching 👀
  • ASYNC_MSG — the result code $ASYC_MSG equals 900, and it means there's a page waiting that needs to be fetched.

🚪 Room Access

  • PUBLIC — the room access code $PUBLIC equals 0, and it means the room is to have public access. come on in 🫶
  • PRIVATE — the room access code $PRIVATE equals 1, and it means the room is to have private access.
  • PRIVATE_PASSWORD — the room access code $PRIVATE_PASSWORD equals 2, and it means the room is to have private access using a password.
  • PRIVATE_INVITATION — the room access code $PRIVATE_INVITATION equals 3, and it means the room is to have private access by invitation. you're on the list or you're not 💅
  • PERSONAL — the room access code $PERSONAL equals 4, and it means the room is to be a private mailbox only for a particular user.
  • DELETED_USER — the room access code $DELETED_USER equals 0.
  • NEW_USER — the User related constant $NEW_USER equals 1.
  • PROBLEM_USER — the User related constant $PROBLEM_USER equals 2.
  • LOCAL_USER — the User related constant $LOCAL_USER equals 3.
  • NETWORK_USER — the User related constant $NETWORK_USER equals 4.
  • PREFERRED_USER — the User related constant $PREFERRED_USER equals 5.
  • AIDE_USER — the User related constant $AIDE user equals 6.

🌈 INTERFACE 🌈

🏗️ Constructor

"$c = new Net::Citadel (host =" $ctdl_host)>

The constructor creates a handle to the citadel server — and yes, it literally makes the TCP connection while it's at it. It takes these 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. no server, no vibes.

🛠️ Methods

🔐 Authentication

  • login — $c->login ($user, $pwd) Logs in this user, or will croak if that fails. it's giving gatekeeping.
  • logout — $c->logout Well, logs out the current user. bye bestie 👋

🏢 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 it 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 a 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. she's a work in progress, be patient 🫶

🧑 Users

  • create_user — $c->create_user ($username, $password) Tries to create a user with name and password. Fails if this user already exists (or for some other reason). no dupes allowed 💅
  • 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 it sets their level to "DELETED_USER"). it's not a delete delete, it's a vibe delete.

🎀 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. like yelling into a cave but productive.
  • 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 is 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

manifesting it ✨

👀 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 (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.

and that's the whole page, bestie 🎀 this manual page dropped on 2018-06-28 and ships with perl v5.26.2 — go forth and talk to your Citadel server, you've got this 💅✨

📦 where this page comes from