* Updated some of the docs. Bumped version number to 5.80 in anticipation

[citadel.git] / citadel / techdoc / citadelapi.txt

diff --git a/citadel/techdoc/citadelapi.txt b/citadel/techdoc/citadelapi.txt
index e1f06a6547ee7fa5e337a06308e4aaf7be10f639..259299d4009abd25b4b7c35526539ea977183b02 100644 (file)
--- a/citadel/techdoc/citadelapi.txt
+++ b/citadel/techdoc/citadelapi.txt
@@ -1,8 +1,20 @@
-Here's "take two" on the CitadelAPI extension library.  These days it's not
-really a library at all, but rather a list of stuff that's inside the server that
-might be useful.  Sort of.  We'll see how it evolves.
-
+ Citadel/UX Server Extension API Documentation
+ ---------------------------------------------
+ 
+  This is a VERY INCOMPLETE documentation of the API for extending the
+Citadel server using dynamically loaded modules.  It really isn't an API at
+all, but rather a list of some of the functions available in the server which
+are likely to be of use to module writers.
  
+  The current trend is to move as much stuff as possible out of the server
+proper and into loadable modules.  This makes the code much easier to read and
+understand.
+  
+  Expect this document to become more complete over time, as both the API and
+the person documenting it have a chance to mature a bit.  :)
+  
+  
+   
   USER RELATED FUNCTIONS
   ----------------------
  
@@ -159,3 +171,41 @@ contain:
 #define UA_GOTOALLOWED          4      /* User may <.G>oto this room */
 #define UA_HASNEWMSGS           8      /* Room contains new messages */
 #define UA_ZAPPED              16      /* User has forgotten this room */
+
+
+
+
+   ROOM RELATED FUNCTIONS
+   ----------------------
+ 
+ 
+unsigned create_room(char *new_room_name,
+                     int new_room_type,
+                     char *new_room_pass,
+                     int new_room_floor,
+                    int really_create)
+ 
+ This function is used to create a new room.  new_room_name should be set to
+the desired name for the new room.
+  
+ new_room_type should be set to one of the following values:
+       0 = public room
+       1 = guess-name room
+       2 = passworded room
+       3 = invitation-only room
+       4 = personal (mailbox) room
+       5 = personal (mailbox) room, and new_room_name already contains
+           the namespace prefix (use with caution!)
+ 
+ new_room_pass should be set to the desired password for the room (obviously
+this is only valid for passworded rooms).
+ 
+ If the room is really to be created, set really_create to 1.  Otherwise, the
+caller may merely check to see if it's possible to create the room without
+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
+example, a room with the name already exists), it returns 0.
+ 
+