citadel/techdoc/api.txt

   1  Yeesh.
   2
   3  This is a rough start at the beginnings of what will eventually become
   4 something that resembles a draft of the implementation of an API for writing
   5 Citadel extensions...
   6
   7  In other words, as functions are developed we'll stick writeups in here.
   8
   9
  10
  11  CONVENTIONS
  12  -----------
  13
  14  1. All user-callable functions start with "Ctdl".
  15
  16  2. The functions starting with "CtdlInternal" are only to be used by other
  17 API functions.  They are implemented mainly to consolidate the common code
  18 used by similar API functions, and make their implementation simple and
  19 straightforward.
  20
  21
  22
  23  WRITING A SERVER-SIDE APPLICATION
  24  ---------------------------------
  25
  26  Server-side applications written to the CitadelAPI may be written in any
  27 language, as long as the "citadelapi" library is linked in.  Unlike normal
  28 user-mode programs, you must not declare a main() function, and there will be
  29 no stdin/stdout/stderr available.  Instead, you must declare this:
  30
  31  void CtdlMain() {
  32                  /* your program's main loop goes here */
  33                  }
  34
  35  When a server-side application is started, the main() loop inside the
  36 CitadelAPI is invoked.  This will perform all of the necessary initialization
  37 (attach to the server, authenticate, identify itself, etc.) and then call
  38 your program's CtdlMain() loop.
  39
  40  By the time CtdlMain() receives control, there will be two public symbols
  41 you can access, which point to data structures containing various information
  42 that may be useful to the program:
  43
  44  extern struct CtdlServerHandle CtdlAppHandle;
  45  extern struct CtdlServInfo CtdlAppServInfo;
  46
  47  CtdlAppHandle contains various information about how and why this program is
  48 connected to the server.  CtdlAppSrvInfo contains various static information
  49 about the server the program is connected to.  Both CtdlServerHandle and
  50 CtdlServInfo are defined in the standard header files.
  51
  52
  53
  54  ERROR HANDLING
  55  --------------
  56
  57  int CtdlGetLastError()
  58
  59  Returns the error code of a failed API call.  The error codes used by the
  60 API are the same as those used by the Citadel session layer protocol, in order
  61 to facilitate a consistent development experience.
  62
  63
  64
  65  INTERPROCESS COMMUNICATION FUNCTIONS
  66  ------------------------------------
  67
  68  int CtdlSendExpressMessage(char *ToUser, char *MsgText)
  69
  70  This function sends an express message (page) to the named user.
  71
  72
  73
  74  USER ACCOUNT FUNCTIONS
  75  ----------------------
  76  The user account functions require administrative or privileged access.  They
  77 return -1 in the event of an error.
  78
  79
  80
  81  int CtdlGetUserPassword(char *buf, char *WhichUser)
  82  int CtdlSetUserPassword(char *buf, char *WhichUser)
  83
  84  Get or set the password for a user account.
  85
  86
  87  unsigned int CtdlGetUserFlags(char *WhichUser)
  88  int CtdlSetUserFlags(unsigned int NewFlags, char *WhichUser)
  89
  90  Get or set the various bits associated with a user account.  Be careful with
  91 these flags; it is possible to corrupt a user account by handling them the
  92 wrong way.  It is best to call CtdlGetUserFlags() to acquire the current set
  93 of flags, then twiddle the bits you're interested in, then call
  94 CtdlSetUserFlags() to write them back.
  95
  96
  97  int CtdlGetUserTimesCalled(char *WhichUser)
  98  int CtdlSetUserTimesCalled(unsigned int NewValue, char *WhichUser)
  99
 100  Get or set the "number of times called" value for a user.
 101
 102
 103  int CtdlGetUserMessagesPosted(char *WhichUser)
 104  int CtdlSetUserMessagesPosted(unsigned int NewValue, char *WhichUser)
 105
 106  Get or set the "number of messages posted" value for a user.
 107
 108
 109  int CtdlGetUserAccessLevel(char *WhichUser)
 110  int CtdlSetUserAccessLevel(unsigned int NewValue, char *WhichUser)
 111
 112  Get or set a user's access level.
 113
 114
 115  long CtdlGetUserNumber(char *WhichUser)
 116  int CtdlSetUserNumber(long NewValue, char *WhichUser)
 117
 118  Get or set the user number,  In general there is never any reason to change
 119 a user's number.  If for some reason you need to do this, be sure not to use
 120 a user number which already exists, or which has not yet been assigned.
 121
 122
 123  time_t CtdlGetUserLastCall(char *WhichUser)
 124  int CtdlSetUserLastCall(time_t NewValue, char *WhichUser)
 125
 126  Get or set the timestamp of a user's last call.
 127
 128
 129  int CtdlForEachUser(int (*CallBack)(char *EachUser))
 130
 131  This allows a user-supplied function to be called once for each user account
 132 on the system; the single argument passed to the function will be the name of
 133 the user being processed.
 134
 135
 136
 137
 138   ROOM FUNCTIONS
 139   --------------
 140
 141   extern struct CtdlRoomInfo CtdlCurrentRoom;
 142
 143   This structure contains information about the current room.
 144
 145
 146
 147  int CtdlGotoRoom(char *RoomName)
 148
 149  Goto any room to which the extension has access.  An extension with
 150 administrative or privileged access may enter any room on the system.  An
 151 extension running in the context of an ordinary user may enter any room to
 152 which the user has access.
 153
 154
 155  int CtdlForEachRoom(int (*CallBack)(char *EachRoom))
 156
 157  This allows a user-supplied function to be called once for each active room
 158 on the system; the single argument passed to the function will be the name of
 159 the room being processed.