- Citadel/UX Server Extension API Documentation
+ Citadel Server Extension API Documentation
---------------------------------------------
This is a VERY INCOMPLETE documentation of the API for extending the
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
#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 CtdlUnregisterMessageHook(int (*handler) (struct CtdlMessage *),
int EventType)
- Please write documentation for me!
+
+ 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)
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.