revise brc interface and its document.

git-svn-id: http://opensvn.csie.org/pttbbs/trunk/pttbbs@3542 63ad8ddf-47c3-0310-b6dd-a9e9d9715204

1 files changed, 34 insertions, 62 deletions

diff --git a/docs/brc.txt b/docs/brc.txt
index 0a62f13c..315a1fbc 100644
--- a/docs/brc.txt
+++ b/docs/brc.txt
@@ -1,5 +1,6 @@
  
         BRC documentation by scw      08/05/2003
+					06/12/2007 revised by kcwu
  
 源起：
      這篇文章主要是介紹 brc_* 的函式，這組函式是 pttbbs 用來紀錄文章已讀/未讀
@@ -17,20 +18,19 @@ BRC 是什麼？如何運作？
  它的特點是用的空間極少。可以在 24k 以內的空間記下一個人在全站的文章已讀/
  未讀。當然，這樣的方法不可能真正完美，但是對於使用上已經足夠了。為什麼說是不
  完美呢？這跟紀錄的儲存方式有關。
-     紀錄檔在 home/[first charactor of id]/[id]/.boardrc。檔案格式如下：
+     紀錄檔在 home/[first charactor of id]/[id]/.brc2。檔案格式如下：
  
  FILE     := RECORDS ;
  RECORDS  := RECORDS RECORD | ;
- RECORD   := BOARD_NAME BRC_DATA ;
+ RECORD   := BRC_BID BRC_DATA ;
  BRC_DATA := BRC_NUM BRC_LIST ;
  BRC_LIST := NUM NUM ... NUM ;  (共 BRC_NUM 個 NUM)
- BOARD_NAME 是 15 bytes 的板名 (#define BRC_STRLEN 15)
- BRC_NUM    是對這個板的儲存量，1 byte 以 binary 方式儲存，其值 <= MAX_NUM (80)
- BRC_LIST   是對這個板的紀錄，剛好有 BRC_NUM 個 4 bytes integers。
+ BRC_BID 是 board bid, sizeof(brcbid_t)=2 bytes.
+ BRC_NUM    是對這個板的儲存量，sizeof(brcnbrd_t)=2 bytes 以 binary 方式儲存，其值 <= MAX_NUM (80)
+ BRC_LIST   是對這個板的紀錄，剛好有 BRC_NUM 個 sizeof(time4_t)=4 bytes integers。
  另外在 24576 bytes (#define BRC_MAXSIZE 24576) 之外的資料不會被用到。
  
-     在下面會看到，BOARD_NAME 不用另外儲存（已經放在user的全域資料裡了），其他
- 兩項, BRC_NUM 跟 BRC_LIST 都會放在相應的全域變數中, brc_num & brc_list 。
+     在下面會看到，BRC_BID 跟 BRC_NUM 跟 BRC_LIST 都會放在相應的變數中, brc_currbid & brc_num & brc_list 。
      判定一個檔案是否已經讀過的方法是在 brc_list 中搜尋檔案建立的時間，也就是
  檔名 M.xxxxxxxxxx.A.yyy 中 xxxxxxxxx 的那個數字。如果這個數字有在 brc_list 中
  出現就是已讀，要不如果 brc_list 中所有的數字都比這個檔案的建立時間大（也就是
@@ -40,7 +40,7 @@ BRC 是什麼？如何運作？
      這樣可以看出為什麼這個方法不是真正完美但是已經足夠。不完美的原因有三個：
  首先， brc_num <= 80 也就是 brc_list 最多存八十個數，這表示除了很久以前的文章
  外，只會有八十篇是已讀的。第二就是所有一年前的文章都會被判為已讀。最後，如果一
- 個人看的板太多，讓 .boardrc 大小超過 BRC_MAXSIZE 有些板的紀錄就會不見（ 24576
+ 個人看的板太多，讓 .brc2 大小超過 BRC_MAXSIZE 有些板的紀錄就會不見（ 24576
  bytes 最少可以存 73 個板的資料，這還是用全部板 brc_num 都是 80 計算的）。但這
  三個小缺點影響應該不大吧？
  
@@ -48,53 +48,38 @@ BRC 實作
  
  interface: (in proto.h)
  
-  int brc_unread(char *fname, int bnum, int *blist);
+  int brc_initialize();
+  void brc_finalize();
+
+  int brc_unread(int bid, char *fname, int bnum, int *blist);
       判斷一篇文章是否已讀。
       傳入值：文章檔名 (fname) 以及 brc_num (bnum) 和 brc_list (blist)。
       傳回值：如果由 bnum 和 blist 判斷本篇文章未讀傳回 1。
               否則傳回 0。
       額外效果：無。
   
-  int brc_initial(char *boardname);
+  int brc_initial_board(char *boardname);
       初始化在一個板的已讀未讀狀態。
       傳入值：要初始化的板名。
       傳回值：若找到之前的紀錄傳回新的 brc_num，否則傳回 0。
       額外效果：如果傳入的看板就是目前看板會直接傳回 brc_num, 不做別的事。否則
-      本函式會先將目前的 brc data 寫入 .boardrc 中，更改 currboard ，取得
+      本函式會先將目前的 brc data 寫回 brc_buf 中，更改 currboard ，取得
       currbid 和 currbrdattr 後再讀取並更新 brc_num 及 brc_list。如果在使用者
-      的 .boardrc 中沒有關於這個板的紀錄，會設定 brc_num = 1，brc_list[0] = 1
+      的 brc_buf 中沒有關於這個板的紀錄，會設定 brc_num = 1，brc_list[0] = 1
       並傳回 0。
   
   void brc_update();
-      將目前的 brc data 寫入 .boardrc 中。
+      將目前的 brc data 寫入 brc_buf 中。
       額外效果：如果 brc data 未被更改或使用者權限不足則不會有動作。
   
   void brc_addlist(char *fname);
-      將文章標示為已讀。
+      將文章標示為已讀。使用前需先 brc_initial_board()
       傳入值：要標示為已讀的文章檔名。
   
- global variables: (in var.c)
-  
-  int    brc_num;
-      brc_list 中的有效數字個數。
-
-  int    brc_list[BRC_MAXNUM];
-      已讀文章的存檔時間。
-  
-  (in var.h)
-  extern int             brc_num;
-  extern int             brc_list[BRC_MAXNUM];
-  
- constant definition: (in board.c)
-  
-  #define BRC_STRLEN 15           /* Length of board name */
-      板名最大長度。
+ constant definition:
   
   #define BRC_MAXSIZE     24576
-      .boardrc 的有效大小。
-  
-  #define BRC_ITEMSIZE    (BRC_STRLEN + 1 + BRC_MAXNUM * sizeof( int ))
-      每個 record 的最大大小。
+      .brc2 的有效大小。
   
   #define BRC_MAXNUM      80
       brc_num 的最大值。
@@ -105,47 +90,34 @@ BRC 實作
       brc_list 中值的下限，時間在此之前的一律當作已讀。會在 init_brdbuf 中被設
       定為 login_start_time - 365 * 86400。
   
-  static int    brc_changed = 0;
-      從上次讀取 .boardrc 到當時為止，brc_num 與 brc_list 是否改變過（為減少寫
-      檔的次數）。
-  
   static char   brc_buf[BRC_MAXSIZE];
-      呼叫 read_brc_buf 後 .boardrc 的前 BRC_MAXSIZE bytes 會被置入這個 buffer
-      中。
+      呼叫 read_brc_buf 後 .brc2 的前 BRC_MAXSIZE bytes 會被置入這個 buffer 中。
 
   static int    brc_size;
       呼叫 read_brc_buf 後 brc_buf 中的有效字元數。
 
-  static char   brc_name[BRC_STRLEN];
-      目前 brc data 的板名。 （不知道可否用 currboard 代替？ by scw）
+  static int    brc_changed = 0;
+      從上次讀取 .brc2 到當時為止，brc_num 與 brc_list 是否改變過。
 
-  static char * fn_boardrc = ".boardrc";
-      brc 設定檔名。
+  static int    brc_currbid;
 
-  char        * brc_buf_addr=brc_buf;
-      unused variable
-  
- private funcions: (in board.c)
+  static int    brc_num;
+      brc_list 中的有效數字個數。
+
+  static int    brc_list[BRC_MAXNUM];
+      已讀文章的存檔時間。
   
+
   static void read_brc_buf();
-      從 .boardrc 中讀取最多 BRC_MAXSIZE bytes 並存入 brc_buf 中，將存入的字元
+      從 .brc2 中讀取最多 BRC_MAXSIZE bytes 並存入 brc_buf 中，將存入的字元
       數存在 brc_size 中。
 
-  static char * brc_getrecord(char *ptr, char *name, int *pnum, int *list);
-      從 buffer 中讀取一項紀錄。 （通常在 read_brc_bufi() 之後使用）
-      傳入值：ptr 為要讀取的 buffer， name, pnum, 和 list 分別寫入讀到的資料。
-      傳回值：指向讀出的 record 下一個字元的指標。
-      額外效果：name 會被存入最多 BRC_MAXLEN 個字元，為讀到的 record 的板名。
-      pnum 會被存入讀到的 brc_num，list 會被寫入 *pnum 的整數，為 brc_list
-      的資料。
-
-  static char * brc_putrecord(char *ptr, char *name, int num, int *list);
+  static char * brc_putrecord(char *ptr, char *endp, brcbid_t bid, brcnbrd_t num, const time4_t *list);
       與 brc_getrecord() 的作用正好相反，將資料寫入 puffer 中。
-      傳入值：ptr 只向要寫入的 buffer，name, num, list 分別是要寫入的資料。
+      傳入值：ptr 指向要寫入的 buffer，bid, num, list 分別是要寫入的資料。
       傳回值：指向寫入的 record 下一個字元的指標。
-      額外效果：若資料是合法的 (num > 0 && list[0] > brc_expire_time) ptr 會被
-      寫入 BRC_ITEMSIZE bytes 的資料。在 list 中比 brc_expire_time 的數字不會
-      被寫入（所以寫入的 brc_num 可能比 num 小）。
+      額外效果：若資料是合法的 (num > 0 && list[0] > brc_expire_time) 且空間足夠,
+      資料會被寫入 ptr, endp 之間。
 
   static int brc_unread_time(time_t ftime, int bnum, int *blist);
       跟 brc_unread() 類似，只是傳入的是檔案建立的時間。