[Pmplib-commits] SF.net SVN: pmplib: [212] trunk/pmplib/lib/pmp_iriverplus3

[<ny...@us...>]

Revision: 212
          http://svn.sourceforge.net/pmplib/?rev=212&view=rev
Author:   nyaochi
Date:     2006-12-27 19:20:31 -0800 (Wed, 27 Dec 2006)

Log Message:
-----------
Add more comments.

Modified Paths:
--------------
    trunk/pmplib/lib/pmp_iriverplus3/dic.c
    trunk/pmplib/lib/pmp_iriverplus3/idx.c
    trunk/pmplib/lib/pmp_iriverplus3/ip3db.c

Modified: trunk/pmplib/lib/pmp_iriverplus3/dic.c
===================================================================
--- trunk/pmplib/lib/pmp_iriverplus3/dic.c	2006-12-27 19:22:33 UTC (rev 211)
+++ trunk/pmplib/lib/pmp_iriverplus3/dic.c	2006-12-28 03:20:31 UTC (rev 212)
@@ -23,7 +23,7 @@
 
 /*
 Some important findings from db.dic:
-- This file seems to define field names/types in a database.
+- This file defines field names/types in a database.
 - This file stores offset addresses of root nodes in db.idx.
 */
 

Modified: trunk/pmplib/lib/pmp_iriverplus3/idx.c
===================================================================
--- trunk/pmplib/lib/pmp_iriverplus3/idx.c	2006-12-27 19:22:33 UTC (rev 211)
+++ trunk/pmplib/lib/pmp_iriverplus3/idx.c	2006-12-28 03:20:31 UTC (rev 212)
@@ -23,12 +23,19 @@
 
 /*
 Brief summary of db.idx structure:
-- This file seems to have 12-bytes header
+- This file has 12-bytes header
 - Indices consist of multiple binary search trees
-- The offset addresses to the root nodes are specified in db.dic
+- The offset addresses to the root nodes are described in db.dic
 
 Implementation note:
-- The AVL trees are 
+- The byte order of values (such as offset address, key values, etc)
+  in AVL trees depends on the CPU architecture on which this code runs.
+  Since values in db.idx are written in big-endian, the functions
+  from_be_avltree() and to_be_avltree() convert the byte order from/to
+  big endian to the native byte-order on memory.
+- The balance field of an AVL node stores values -1, 0, or 1 although
+  the field stores the height of a node in db.idx. This conversion
+  will take place in the function to_be_avltree().
 */
 
 #ifdef	HAVE_CONFIG_H

Modified: trunk/pmplib/lib/pmp_iriverplus3/ip3db.c
===================================================================
--- trunk/pmplib/lib/pmp_iriverplus3/ip3db.c	2006-12-27 19:22:33 UTC (rev 211)
+++ trunk/pmplib/lib/pmp_iriverplus3/ip3db.c	2006-12-28 03:20:31 UTC (rev 212)
@@ -121,7 +121,10 @@
 {
 	FILE *fp = 0;
 
-	/* Read db.dic */
+	/*
+	 * Read db.dic first since this file describes the structure of a database
+	 * (e.g., field type and the offset values to the root nodes in db.idx).
+	 */
 	fp = ucs2fopen(dicfn, "rb");
 	if (!fp) {
 		ip3db_finish(db);
@@ -155,7 +158,11 @@
 {
 	FILE *fp = 0;
 
-	/* Write db.dat. This will allocate offset values of the records. */
+	/*
+	 * Write db.dat. The function dat_write() also stores offset addresses
+	 * (db->dat->objects.entries[i].offset and db->dat->music.entries[i].offset)
+	 * where records are stored in the file.
+	 */
 	fp = ucs2fopen(datfn, "wb");
 	if (!fp) {
 		return 1;
@@ -163,9 +170,18 @@
 	dat_write(db->dat, db->dic, fp);
 	fclose(fp);
 
-	/* Construct db.idx and update db.dic. */
+	/*
+	 * Construct binary search trees from records in db->dat. The root offset
+	 * of each search tree will be stored in db->dic.
+	 */
 	idx_construct(db->idx, db->dic, db->dat);
 
+	/*
+	 * Write db.idx. The function idx_write() converts values in the search trees
+	 * from native byte-order to big endian. The byte-order conversion will take
+	 * place in memory. Therefore, do not use db->idx after calling idx_write()
+	 * function.
+	 */
 	fp = ucs2fopen(idxfn, "wb");
 	if (!fp) {
 		return 1;
@@ -173,6 +189,7 @@
 	idx_write(db->idx, db->dic, fp);
 	fclose(fp);
 
+	/* Write db.dic. */
 	fp = ucs2fopen(dicfn, "wb");
 	if (!fp) {
 		return 1;
@@ -198,7 +215,7 @@
 
 result_t ip3db_set(ip3db_t* db, const ip3db_music_record_t* records, int num_records)
 {
-	/* Set music records to dat_t. */
+	/* Construct records in db->dat from the records. */
 	dat_set(db->dat, db->dic, records, num_records);
 	return 0;
 }


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.