-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.
+
+ 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
----------------------
objects: bio, photo, etc. It returns 0 upon success or a nonzero error code
if the requested operation could not be performed.
+
+
+ HOW TO REGISTER FUNCTION HOOKS
+ ------------------------------
+
+ The truly powerful part of the Citadel API is the ability for extensions to
+register "hooks" -- user-supplied functions will be called while the server
+is performing various tasks. Here are the API calls to register hooks:
+
+
+ void CtdlRegisterProtoHook(void (*handler)(char *), char *cmd, char *desc)
+
+ Adds a new server command to the system. The handler function should accept
+a single string parameter, which will be set to a string containing any
+parameters the client software sent along with the server command. "cmd"
+should be the four-character mnemonic the server command is known by, and
+"desc" is a description of the new command.
+
+
+ void CtdlRegisterCleanupHook(void *fcn_ptr)
+
+ Registers a new function to be called whenever the server is shutting down.
+Cleanup functions accept no parameters.
+
+
+void CtdlRegisterSessionHook(void *fcn_ptr, int EventType)
+
+ Registers a session hook. Session hooks accept no parameters. There are
+multiple types of session hooks; the server extension registers which one it
+is interested in by setting the value of EventType. The available session
+hook types are:
+
+#define EVT_STOP 0 /* Session is terminating */
+#define EVT_START 1 /* Session is starting */
+#define EVT_LOGIN 2 /* A user is logging in */
+#define EVT_NEWROOM 3 /* Changing rooms */
+#define EVT_LOGOUT 4 /* A user is logging out */
+#define EVT_SETPASS 5 /* Setting or changing password */
+
+
+void CtdlRegisterUserHook(void *fcn_ptr, int EventType)
+
+ Registers a user hook. User hooks accept two parameters: a string pointer
+containing the user name, and a long which *may* contain a user number (only
+applicable for certain types of hooks). The available user hook types are:
+
+#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 */
projects / citadel.git / blobdiff