- Citadel/UX Server Extension API Documentation
+ Citadel 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.
+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
----------------------
- The fundamental user data is stored in "struct usersupp" which is defined
+ The fundamental user data is stored in "struct ctdluser" which is defined
in citadel.h. The following functions are available:
- int getuser(struct usersupp *usbuf, char name[])
+ int getuser(struct ctdluser *usbuf, char name[])
- Given the name of a requested user and a buffer to store the usersupp
+ Given the name of a requested user and a buffer to store the user
record in, getuser() will search the userlog for the named user and load its
data into the buffer. getuser() returns 0 upon success or a nonzero error
code if the requested operation could not be performed.
- void putuser(struct usersupp *usbuf, char *name)
+ void putuser(struct ctdluser *usbuf, char *name)
After reading in a user record with getuser() and perhaps modifying the data
in some way, a program may use putuser() to write it back to disk.
- int lgetuser(struct usersupp *usbuf, char *name)
- void lputuser(struct usersupp *usbuf, char *name)
+ int lgetuser(struct ctdluser *usbuf, char *name)
+ void lputuser(struct ctdluser *usbuf, char *name)
If critical-section operation is required, this pair of calls may be used.
They function the same as getuser() and putuser(), except that lgetuser()
entire server.
- void ForEachUser(void (*CallBack)(struct usersupp *EachUser))
+ void ForEachUser(void (*CallBack)(struct ctdluser *EachUser))
This allows a user-supplied function to be called once for each user on
the system. The user-supplied function will be called with a pointer to a
-usersupp structure as its only argument.
+user structure as its only argument.
- int getuserbynumber(struct usersupp *usbuf, long int number)
+ int getuserbynumber(struct ctdluser *usbuf, long int number)
getuserbynumber() functions similarly to getuser(), except that it is
supplied with a user number rather than a name. Calling this function
void CtdlRegisterProtoHook(void (*handler)(char *), char *cmd, char *desc)
+ void CtdlUnregisterProtoHook(void (*handler)(char *), char *cmd)
- 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.
+ CtdlRegisterProtoHook() 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.
+
+ CtdlUnregisterProtoHook() removes a server command from the system. It
+must be called with the same handler and cmd which were previously registered.
void CtdlRegisterCleanupHook(void *fcn_ptr)
+ void CtdlUnregisterCleanupHook(void *fcn_ptr)
- Registers a new function to be called whenever the server is shutting down.
-Cleanup functions accept no parameters.
+ CtdlRegisterCleanupHook() registers a new function to be called whenever the
+server is shutting down. Cleanup functions accept no parameters.
+
+ CtdlUnregsiterCleanupHook() removes a cleanup function from the system. It
+must be called with the same fcn_ptr which was previously registered.
void CtdlRegisterSessionHook(void *fcn_ptr, int EventType)
+void CtdlUnregisterSessionHook(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:
+ CtdlRegisterSessionHook() 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_NEWROOM 3 /* Changing rooms */
#define EVT_LOGOUT 4 /* A user is logging out */
#define EVT_SETPASS 5 /* Setting or changing password */
+#define EVT_CMD 6 /* Called after each server command */
+#define EVT_RWHO 7 /* An RWHO command is being executed */
+#define EVT_ASYNC 8 /* Doing asynchronous message */
+
+#define EVT_TIMER 50 /* Timer events are called once per minute */
+#define EVT_HOUSE 51 /* Housekeeping event */
+ CtdlUnregisterSessionHook() removes a session hook. It must be called with
+the same fcn_ptr and EventTYpe which were previously registered.
+
void CtdlRegisterUserHook(void *fcn_ptr, int EventType)
+void CtdlUnregisterUserHook(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:
+ CtdlRegisterUserHook() 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 */
+ CtdlUnregisterUserHook() removes a user hook from the system. It must be
+called with the same fcn_ptr and EventType which were previously registered.
+
+
+ void CtdlRegisterLogHook(void (*fcn_ptr) (char *), int loglevel)
+ void CtdlUnregisterLogHook(void (*fcn_ptr) (char *), int loglevel)
+
+ CtdlRegisterLogHook() adds a new logging function to the system. The
+handler function should accept a single string as a parameter. Logging
+functions can be used to implement additional logging facilities in
+addition to the Citadel trace file, which is output on stderr, or
+redirected to a file with the -t command line option. The handler
+function will be called if the loglevel is greater than or equal to
+loglevel.
+
+ Security considerations: Logs may contain plain text passwords and
+other sensitive information. It is your responsibility to ensure that
+your logs have appropriate access protection. The Citadel trace file
+is readable only by the superuser when the -t option is used.
+
+ CtdlUnregisterLogHook() removes a logging function from the system. It
+must be called with the same fcn_ptr and loglevel which were previously
+registered.
+
+
+ void CtdlRegisterMessageHook(int (*handler) (struct CtdlMessage *),
+ int EventType)
+ void CtdlUnregisterMessageHook(int (*handler) (struct CtdlMessage *),
+ int EventType)
+
+
+ CtdlRegisterMessageHook() registers a function with the message
+handling subsystem. This function will be called with one parameter,
+a pointer to a CtdlMessage structure, when the message triggers an event
+of type EventType. The registered function should return non zero if it
+has handled the event to prevent other hook functions from also processing
+the event.
+
+ CtdlUnregisterMessageHook() removes a function from the list of registered
+message handlers. To successfully remove a function registered with
+CtdlRegisterMessageHook() CtdlUnregisterMessageHook() must be called with
+the same parameters.
+
+ Possible values for EventType are:
+ EVT_BEFOREREAD Called after a message is loaded from disk but before
+it is presented for reading.
+ EVT_BEFORESAVE Called before the message is saved to disk. returning
+non zero for this event will prevent the message being saved to disk in the
+normal manner.
+ EVT_AFTERSAVE Called after the message is saved to disk but before
+any IGnet spooling is carried out.
+ EVT_SMTPSCAN Called during the SMTP reception of a message after the
+message is received and before the response is sent to the sender. This is
+intended for spam filters and virus checkers. A positive return code will
+cause the message to be rejected by the SMTP server.
+
+
+ void CtdlRegisterRoomHook(int (*fcn_ptr) (char *))
+ void CtdlUnregisterRoomHook(int (*fcn_ptr) (char *))
+
+ Register or remove a function with the room processing system.
+Registered functions are called in the order they are registered when a message
+is added to a room. This allows modules such as Sieve to process new messages
+appearing in a room.
+
+
+ void CtdlRegisterXmsgHook(int (*fcn_ptr) (char *, char *, char *), int order)
+ void CtdlUnregisterXmsgHook(int (*fcn_ptr) (char *, char *, char *), int order)
+
+ Please write documentation for me!
+
+
+ void CtdlRegisterServiceHook(int tcp_port, char *sockpath,
+ void (*h_greeting_function) (void),
+ void (*h_command_function) (void))
+ void CtdlUnregisterServiceHook(int tcp_port, char *sockpath,
+ void (*h_greeting_function) (void),
+ void (*h_command_function) (void))
+
+ Please write documentation for me!
+
-
FUNCTIONS WHICH MANIPULATE USER/ROOM RELATIONSHIPS
void CtdlGetRelationship(struct visit *vbuf,
- struct usersupp *rel_user,
- struct quickroom *rel_room);
+ struct ctdluser *rel_user,
+ struct ctdlroom *rel_room);
void CtdlSetRelationship(struct visit *newvisit,
- struct usersupp *rel_user,
- struct quickroom *rel_room);
+ struct ctdluser *rel_user,
+ struct ctdlroom *rel_room);
These functions get/set a "struct visit" structure which may contain
information about the relationship between a user and a room. Specifically:
- int CtdlRoomAccess(struct quickroom *roombuf, struct usersupp *userbuf)
+ int CtdlRoomAccess(struct ctdlroom *roombuf, struct ctdluser *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
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
+data structure item room.QRflags). If the room cannot be created (for
example, a room with the name already exists), it returns 0.
projects / citadel.git / blobdiff