citadel/techdoc/citadelapi.txt

   1 Here's "take two" on the CitadelAPI extension library.  These days it's not
   2 really a library at all, but rather a list of stuff that's inside the server that
   3 might be useful.  Sort of.  We'll see how it evolves.
   4
   5
   6   USER RELATED FUNCTIONS
   7   ----------------------
   8
   9  The fundamental user data is stored in "struct usersupp" which is defined
  10 in citadel.h.  The following functions are available:
  11
  12
  13  int getuser(struct usersupp *usbuf, char name[])
  14
  15  Given the name of a requested user and a buffer to store the usersupp
  16 record in, getuser() will search the userlog for the named user and load its
  17 data into the buffer.  getuser() returns 0 upon success or a nonzero error
  18 code if the requested operation could not be performed.
  19
  20
  21  void putuser(struct usersupp *usbuf, char *name)
  22
  23  After reading in a user record with getuser() and perhaps modifying the data
  24 in some way, a program may use putuser() to write it back to disk.
  25
  26
  27  int lgetuser(struct usersupp *usbuf, char *name)
  28  void lputuser(struct usersupp *usbuf, char *name)
  29
  30  If critical-section operation is required, this pair of calls may be used.
  31 They function the same as getuser() and putuser(), except that lgetuser()
  32 locks the user file immediately after retrieving the record and lputuser()
  33 unlocks it.  This will guarantee that no other threads manipulate the same
  34 user record at the same time.
  35
  36  NOTE: do NOT attempt to combine the locking lgetuser/lputuser calls with any
  37 other locking calls in this API.  Attempting to obtain concurrent locks on
  38 multiple files may result in a deadlock condition which would freeze the
  39 entire server.
  40
  41
  42  void ForEachUser(void (*CallBack)(struct usersupp *EachUser))
  43
  44  This allows a user-supplied function to be called once for each user on
  45 the system.  The user-supplied function will be called with a pointer to a
  46 usersupp structure as its only argument.
  47
  48
  49  int getuserbynumber(struct usersupp *usbuf, long int number)
  50
  51  getuserbynumber() functions similarly to getuser(), except that it is
  52 supplied with a user number rather than a name.  Calling this function
  53 results in a sequential search of the user file, so use it sparingly if at
  54 all.
  55
  56
  57  int purge_user(char *pname)
  58
  59  This function deletes the named user off the system and erases all related
  60 objects: bio, photo, etc.  It returns 0 upon success or a nonzero error code
  61 if the requested operation could not be performed.
  62
  63
  64
  65  HOW TO REGISTER FUNCTION HOOKS
  66  ------------------------------
  67
  68  The truly powerful part of the Citadel API is the ability for extensions to
  69 register "hooks" -- user-supplied functions will be called while the server
  70 is performing various tasks.  Here are the API calls to register hooks:
  71
  72
  73  void CtdlRegisterProtoHook(void (*handler)(char *), char *cmd, char *desc)
  74
  75  Adds a new server command to the system.  The handler function should accept
  76 a single string parameter, which will be set to a string containing any
  77 parameters the client software sent along with the server command.  "cmd"
  78 should be the four-character mnemonic the server command is known by, and
  79 "desc" is a description of the new command.
  80
  81
  82  void CtdlRegisterCleanupHook(void *fcn_ptr)
  83
  84  Registers a new function to be called whenever the server is shutting down.
  85 Cleanup functions accept no parameters.
  86
  87
  88 void CtdlRegisterSessionHook(void *fcn_ptr, int EventType)
  89
  90  Registers a session hook.  Session hooks accept no parameters.  There are
  91 multiple types of session hooks; the server extension registers which one it
  92 is interested in by setting the value of EventType.  The available session
  93 hook types are:
  94
  95 #define EVT_STOP        0       /* Session is terminating */
  96 #define EVT_START       1       /* Session is starting */
  97 #define EVT_LOGIN       2       /* A user is logging in */
  98 #define EVT_NEWROOM     3       /* Changing rooms */
  99 #define EVT_LOGOUT      4       /* A user is logging out */
 100 #define EVT_SETPASS     5       /* Setting or changing password */
 101
 102
 103 void CtdlRegisterUserHook(void *fcn_ptr, int EventType)
 104
 105  Registers a user hook.  User hooks accept two parameters: a string pointer
 106 containing the user name, and a long which *may* contain a user number (only
 107 applicable for certain types of hooks).  The available user hook types are:
 108
 109 #define EVT_PURGEUSER   100     /* Deleting a user */
 110 #define EVT_OUTPUTMSG   101     /* Outputting a message */
 111
 112
 113
 114   FUNCTIONS WHICH MANIPULATE USER/ROOM RELATIONSHIPS
 115
 116  void CtdlGetRelationship(struct visit *vbuf,
 117                         struct usersupp *rel_user,
 118                         struct quickroom *rel_room);
 119  void CtdlSetRelationship(struct visit *newvisit,
 120                         struct usersupp *rel_user,
 121                         struct quickroom *rel_room);
 122
 123  These functions get/set a "struct visit" structure which may contain
 124 information about the relationship between a user and a room.  Specifically:
 125
 126 struct visit {
 127         char v_roomname[20];
 128         long v_generation;
 129         long v_lastseen;
 130         unsigned int v_flags;
 131         };
 132
 133 #define V_FORGET        1               /* User has zapped this room        */
 134 #define V_LOCKOUT       2               /* User is locked out of this room  */
 135 #define V_ACCESS        4               /* Access is granted to this room   */
 136
 137  Don't change v_roomname or v_generation; they're used to identify the room
 138 being referred to.  A room is unique to the system by its combination of room
 139 name and generation number.  If a new room is created with the same name as
 140 a recently deleted room, it will have a new generation number, and therefore
 141 stale "visit" records will not be applied (and will eventually be purged).
 142
 143  v_lastseen contains the number of the newest message the user has read in
 144 this room.  Any existing messages higher than this number can be considered
 145 as "new messages."
 146
 147  v_flags contains information regarding access to the room.
 148
 149
 150
 151  int CtdlRoomAccess(struct quickroom *roombuf, struct usersupp *userbuf)
 152
 153  This is a convenience function which uses CtdlGetRelationship() to determine
 154 whether a user has access to a room.  It returns a bucket of bits which may
 155 contain:
 156
 157 #define UA_INUSE                1       /* Room exists */
 158 #define UA_KNOWN                2       /* Room is in user's Known list */
 159 #define UA_GOTOALLOWED          4       /* User may <.G>oto this room */
 160 #define UA_HASNEWMSGS           8       /* Room contains new messages */
 161 #define UA_ZAPPED               16      /* User has forgotten this room */