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  USER ACCOUNT RELATED FUNCTIONS
  66  ------------------------------
  67
  68  These are functions which access or manipulate user records.  Each function
  69 requires a user name, but a zero-length string may be substituted to request
  70 the currently-logged-in user.  If a lookup fails, ERROR+NOT_LOGGED_IN or
  71 ERROR+NO_SUCH_USER may be set.
  72
  73
  74  int CtdlGetUserAccessLevel(char *UserName)
  75
  76  This function returns a user's access level, or -1 in the event of an error.
  77 The defined access levels are 1 through 6 and may be referenced in "axdefs.h"
  78
  79
  80  long CtdlGetUserNumber(char *UserName)
  81
  82  This function returns a user's user number, or -1 in the event of an error.
  83 User numbers are always unique to the entire system and never reused, even if
  84 the user account is deleted.
  85
  86  time_t CtdlGetUserLastCall(char *UserName)
  87
  88  This function returns the date and time (in standard Unix timestamp format)
  89 when the user last logged on to the server.