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.