Some documentation fixes.
[paraslash.git] / attribute.c
index 925795be2902e8aad7f45b1a3f67673397248186..9a7cb45ae88a411f31fa58a3128687fc4e11ea9f 100644 (file)
@@ -1,3 +1,8 @@
+/*
+ * Copyright (C) 1997-2007 Andre Noll <maan@systemlinux.org>
+ *
+ * Licensed under the GPL v2. For licencing details see COPYING.
+ */
 #include "para.h"
 #include "error.h"
 #include "afh.h"
@@ -8,6 +13,16 @@
 static void *attribute_table;
 static int greatest_att_bitnum;
 
+/** The columns of the attribute table. */
+enum attribute_table_columns {
+       /** The bit number (0-63). */
+       ATTCOL_BITNUM,
+       /** The name of the attribute. */
+       ATTCOL_NAME,
+       /** Number of columns in this table. */
+       NUM_ATT_COLUMNS
+};
+
 static int char_compare(const struct osl_object *obj1, const struct osl_object *obj2)
 {
        const unsigned char *c1 = (const unsigned char*)obj1->data;
@@ -19,8 +34,6 @@ static int char_compare(const struct osl_object *obj1, const struct osl_object *
        return 0;
 }
 
-enum attribute_table_columns {ATTCOL_BITNUM, ATTCOL_NAME, NUM_ATT_COLUMNS};
-
 static struct osl_column_description att_cols[] = {
        [ATTCOL_BITNUM] = {
                .storage_type = OSL_MAPPED_STORAGE,
@@ -37,8 +50,7 @@ static struct osl_column_description att_cols[] = {
        }
 };
 
-static const struct osl_table_description attribute_table_desc = {
-       .dir = DATABASE_DIR,
+static struct osl_table_description attribute_table_desc = {
        .name = "attributes",
        .num_columns = NUM_ATT_COLUMNS,
        .flags = 0,
@@ -61,6 +73,14 @@ static void find_greatest_att_bitnum(void)
        greatest_att_bitnum = -E_NO_ATTRIBUTES;
 }
 
+/**
+ * Retrieve the identifier (number) of an attribute.
+ *
+ * \param att_name The name of the attribute.
+ * \param bitnum Result pointer.
+ *
+ * \return Positive on success, negative on errors.
+ */
 int get_attribute_bitnum_by_name(const char *att_name, unsigned char *bitnum)
 {
        struct osl_object obj = {.data = (char *)att_name,
@@ -77,40 +97,63 @@ int get_attribute_bitnum_by_name(const char *att_name, unsigned char *bitnum)
        return 1;
 }
 
-#define LAA_FLAG_ALPHA 1
-#define LAA_FLAG_LONG 2
+/** Whether "-a" was given for the lsatt command. */
+#define LSATT_FLAG_ALPHA 1
+/** Whether "-l" was given for the lsatt command. */
+#define LSATT_FLAG_LONG 2
 
-struct private_laa_data {
-       int fd;
+/** Data passed via osl_rbtree_loop(). */
+struct private_lsatt_data {
+       /** The given flags for the lsatt command. */
        unsigned flags;
+       /** The result buffer. */
+       struct para_buffer b;
 };
 
-static int log_attribute(struct osl_row *row, void *private_data)
+static int print_attribute(struct osl_row *row, void *private_data)
 {
-       struct private_laa_data *pld = private_data;
+       struct private_lsatt_data *pld = private_data;
        int ret;
        struct osl_object name_obj, bitnum_obj;
 
        ret = osl_get_object(attribute_table, row, ATTCOL_NAME, &name_obj);
        if (ret < 0)
                return ret;
-       if (!(pld->flags & LAA_FLAG_LONG)) {
-               send_buffer(pld->fd, (char *)name_obj.data);
+       if (!(pld->flags & LSATT_FLAG_LONG)) {
+               para_printf(&pld->b, "%s\n", (char *)name_obj.data);
                return 1;
        }
        ret = osl_get_object(attribute_table, row, ATTCOL_BITNUM, &bitnum_obj);
        if (ret < 0)
                return ret;
-       send_va_buffer(pld->fd, "%u\t%s\n", *(unsigned char*)bitnum_obj.data,
+       para_printf(&pld->b, "%u\t%s\n", *(unsigned char*)bitnum_obj.data,
                (char *)name_obj.data);
        return 1;
 }
 
-/* FIXME: Need callback */
+static int com_lsatt_callback(const struct osl_object *query,
+               struct osl_object *result)
+{
+       struct private_lsatt_data pld = {.flags = *(uint32_t *) query->data};
+       int ret;
+
+       if (pld.flags & LSATT_FLAG_ALPHA)
+               ret = osl_rbtree_loop(attribute_table, ATTCOL_NAME,
+                       &pld, print_attribute);
+       else
+               ret = osl_rbtree_loop(attribute_table, ATTCOL_BITNUM,
+                       &pld, print_attribute);
+       result->data = pld.b.buf;
+       result->size = pld.b.size;
+       return ret;
+}
+
+
 int com_lsatt(int fd, int argc, char * const * const argv)
 {
-       struct private_laa_data pld = {.fd = fd, .flags = 0};
-       int i;
+       int ret, i;
+       uint32_t flags = 0;
+       struct osl_object query, result;
 
        for (i = 1; i < argc; i++) {
                const char *arg = argv[i];
@@ -121,21 +164,24 @@ int com_lsatt(int fd, int argc, char * const * const argv)
                        break;
                }
                if (!strcmp(arg, "-a")) {
-                       pld.flags |= LAA_FLAG_ALPHA;
+                       flags |= LSATT_FLAG_ALPHA;
                        continue;
                }
                if (!strcmp(arg, "-l")) {
-                       pld.flags |= LAA_FLAG_LONG;
+                       flags |= LSATT_FLAG_LONG;
                        continue;
                }
        }
        if (argc > i)
                return -E_ATTR_SYNTAX;
-       if (pld.flags & LAA_FLAG_ALPHA)
-               return osl_rbtree_loop(attribute_table, ATTCOL_NAME,
-                       &pld, log_attribute);
-       return osl_rbtree_loop(attribute_table, ATTCOL_BITNUM,
-               &pld, log_attribute);
+       query.data = &flags;
+       query.size = sizeof(flags);
+       ret = send_callback_request(com_lsatt_callback, &query, &result);
+       if (ret > 0) {
+               ret = send_buffer(fd, (char *)result.data);
+               free(result.data);
+       }
+       return ret;
 }
 
 static int com_setatt_callback(const struct osl_object *query,
@@ -184,7 +230,7 @@ static int com_setatt_callback(const struct osl_object *query,
                ret = aft_get_row_of_path(p, &aft_row);
                if (ret < 0)
                        return ret;
-               ret = get_afsi_object_of_row(p, &obj);
+               ret = get_afsi_object_of_row(aft_row, &obj);
                if (ret < 0)
                        return ret;
                ret = load_afsi(&old_afsi, &obj);
@@ -194,9 +240,9 @@ static int com_setatt_callback(const struct osl_object *query,
                new_afsi.attributes |= add_mask;
                new_afsi.attributes &= ~del_mask;
                save_afsi(&new_afsi, &obj); /* in-place update */
-               ret = mood_update_audio_file(aft_row, &old_afsi);
-               if (ret < 0)
-                       return ret;
+//             ret = mood_update_audio_file(aft_row, &old_afsi);
+//             if (ret < 0)
+//                     return ret;
        }
        return 1;
 }
@@ -205,7 +251,7 @@ int com_setatt(__a_unused int fd, int argc, char * const * const argv)
 {
        if (argc < 2)
                return -E_ATTR_SYNTAX;
-       return send_standard_callback_request(argc, argv, com_setatt_callback,
+       return send_standard_callback_request(argc - 1, argv + 1, com_setatt_callback,
                NULL);
 }
 
@@ -274,14 +320,14 @@ static int com_addatt_callback(const struct osl_object *query,
        if (ret < 0)
                return ret;
        find_greatest_att_bitnum();
-       return mood_reload();
+       return mood_reload(); /* FIXME: mood_reload() returns an error */
 }
 
 int com_addatt(__a_unused int fd, int argc, char * const * const argv)
 {
        if (argc < 2)
                return -E_ATTR_SYNTAX;
-       return send_standard_callback_request(argc, argv, com_addatt_callback,
+       return send_standard_callback_request(argc - 1, argv + 1, com_addatt_callback,
                NULL);
 }
 
@@ -309,7 +355,7 @@ static int com_rmatt_callback(const struct osl_object *query,
        find_greatest_att_bitnum();
        if (!atts_removed)
                return 1;
-       return mood_reload();
+       return mood_reload(); /* FIXME: Fix mood_reload() */
 }
 
 int com_rmatt(__a_unused int fd, int argc, char * const * const argv)
@@ -320,7 +366,22 @@ int com_rmatt(__a_unused int fd, int argc, char * const * const argv)
                NULL);
 }
 
-void get_attribute_bitmap(uint64_t *atts, char *buf)
+/**
+ * Return a binary representation of the geiven attribute value.
+ *
+ * \param atts Pointer to the attribute value.
+ * \param buf Result.
+ *
+ * This function prints a string of at most 64 characters plus the terminating
+ * \p NULL character into \a buf which must be provided by the caller and at
+ * least 65 bytes long. The "x" character is used for set attributes and "-" is
+ * used for unset attributes.
+ *
+ * In practice, not all 64 attributes are defined. In this case, the function
+ * only prints \a N + 1 charaters where \a N is the greatest id of a defined
+ * attribute.
+ */
+void get_attribute_bitmap(const uint64_t *atts, char *buf)
 {
        int i;
        const uint64_t one = 1;
@@ -329,6 +390,7 @@ void get_attribute_bitmap(uint64_t *atts, char *buf)
                buf[greatest_att_bitnum - i] = (*atts & (one << i))? 'x' : '-';
        buf[i] = '\0';
 }
+
 /**
  * Get a string containing the set attributes in text form.
  *
@@ -375,15 +437,34 @@ err:
        return ret;
 }
 
+/**
+ * Close the attribute table.
+ *
+ * \param flags Ususal flags that are passed to osl_close_table().
+ *
+ * \sa osl_close_table().
+ */
 void attribute_shutdown(enum osl_close_flags flags)
 {
        osl_close_table(attribute_table, flags);
+       attribute_table = NULL;
 }
 
-int attribute_init(struct table_info *ti)
+/**
+ * Open the attribute table.
+ *
+ * \param ti Gets initialized by this function.
+ * \param db The database directory.
+ *
+ * \return Positive on success, negative on errors.
+ *
+ * \sa osl_open_table().
+ */
+int attribute_init(struct table_info *ti, const char *db)
 {
        int ret;
 
+       attribute_table_desc.dir = db;
        ti->desc = &attribute_table_desc;
        ret = osl_open_table(ti->desc, &ti->table);
        greatest_att_bitnum = -1; /* no atts available */