-Here's "take two" on the CitadelAPI extension library. These days it's not
-really a library at all, but rather a list of stuff that's inside the server that
-might be useful. Sort of. We'll see how it evolves.
-
+ Citadel/UX Server Extension API Documentation
+ ---------------------------------------------
+
+ This is a VERY INCOMPLETE documentation of the API for extending the
+Citadel server using dynamically loaded modules. It really isn't an API at
+all, but rather a list of some of the functions available in the server which
+are likely to be of use to module writers.
+ The current trend is to move as much stuff as possible out of the server
+proper and into loadable modules. This makes the code much easier to read and
+understand.
+
+ Expect this document to become more complete over time, as both the API and
+the person documenting it have a chance to mature a bit. :)
+
+
+
USER RELATED FUNCTIONS
----------------------
#define EVT_PURGEUSER 100 /* Deleting a user */
#define EVT_OUTPUTMSG 101 /* Outputting a message */
+
+
+
+ FUNCTIONS WHICH MANIPULATE USER/ROOM RELATIONSHIPS
+
+ void CtdlGetRelationship(struct visit *vbuf,
+ struct usersupp *rel_user,
+ struct quickroom *rel_room);
+ void CtdlSetRelationship(struct visit *newvisit,
+ struct usersupp *rel_user,
+ struct quickroom *rel_room);
+
+ These functions get/set a "struct visit" structure which may contain
+information about the relationship between a user and a room. Specifically:
+
+struct visit {
+ char v_roomname[20];
+ long v_generation;
+ long v_lastseen;
+ unsigned int v_flags;
+ };
+
+#define V_FORGET 1 /* User has zapped this room */
+#define V_LOCKOUT 2 /* User is locked out of this room */
+#define V_ACCESS 4 /* Access is granted to this room */
+
+ Don't change v_roomname or v_generation; they're used to identify the room
+being referred to. A room is unique to the system by its combination of room
+name and generation number. If a new room is created with the same name as
+a recently deleted room, it will have a new generation number, and therefore
+stale "visit" records will not be applied (and will eventually be purged).
+
+ v_lastseen contains the number of the newest message the user has read in
+this room. Any existing messages higher than this number can be considered
+as "new messages."
+
+ v_flags contains information regarding access to the room.
+
+
+
+ int CtdlRoomAccess(struct quickroom *roombuf, struct usersupp *userbuf)
+
+ This is a convenience function which uses CtdlGetRelationship() to determine
+whether a user has access to a room. It returns a bucket of bits which may
+contain:
+
+#define UA_INUSE 1 /* Room exists */
+#define UA_KNOWN 2 /* Room is in user's Known list */
+#define UA_GOTOALLOWED 4 /* User may <.G>oto this room */
+#define UA_HASNEWMSGS 8 /* Room contains new messages */
+#define UA_ZAPPED 16 /* User has forgotten this room */
+
+
+
+
+ ROOM RELATED FUNCTIONS
+ ----------------------
+
+
+unsigned create_room(char *new_room_name,
+ int new_room_type,
+ char *new_room_pass,
+ int new_room_floor,
+ int really_create)
+
+ This function is used to create a new room. new_room_name should be set to
+the desired name for the new room.
+
+ new_room_type should be set to one of the following values:
+ 0 = public room
+ 1 = guess-name room
+ 2 = passworded room
+ 3 = invitation-only room
+ 4 = personal (mailbox) room
+ 5 = personal (mailbox) room, and new_room_name already contains
+ the namespace prefix (use with caution!)
+
+ new_room_pass should be set to the desired password for the room (obviously
+this is only valid for passworded rooms).
+
+ If the room is really to be created, set really_create to 1. Otherwise, the
+caller may merely check to see if it's possible to create the room without
+actually creating it by setting really_create to 0.
+
+ create_room() returns the flags associated with the new room (as in the
+data structure item quickroom.QRflags). If the room cannot be created (for
+example, a room with the name already exists), it returns 0.
+
+
projects / citadel.git / blobdiff