Merge branch 'refs/heads/t/si_update'
[paraslash.git] / aft.c
diff --git a/aft.c b/aft.c
index 36f8494..6c07bcc 100644 (file)
--- a/aft.c
+++ b/aft.c
@@ -138,7 +138,7 @@ struct ls_options {
 /**
  * Describes the layout of the mmapped-afs info struct.
  *
- * \sa struct afs_info.
+ * \sa struct \ref afs_info.
  */
 enum afsi_offsets {
        /** Where .last_played is stored. */
@@ -167,7 +167,7 @@ enum afsi_offsets {
  * \param afsi Pointer to the audio file info to be converted.
  * \param obj Result pointer.
  *
- * \sa load_afsi().
+ * \sa \ref load_afsi().
  */
 static void save_afsi(struct afs_info *afsi, struct osl_object *obj)
 {
@@ -192,7 +192,7 @@ static void save_afsi(struct afs_info *afsi, struct osl_object *obj)
  *
  * \return Standard.
  *
- * \sa save_afsi().
+ * \sa \ref save_afsi().
  */
 static int load_afsi(struct afs_info *afsi, struct osl_object *obj)
 {
@@ -365,7 +365,10 @@ static void save_afhi(struct afh_info *afhi, char *buf)
        write_u32(buf + CHUNK_TV_TV_SEC_OFFSET, afhi->chunk_tv.tv_sec);
        write_u32(buf + CHUNK_TV_TV_USEC_OFFSET, afhi->chunk_tv.tv_usec);
        p = buf + AFHI_INFO_STRING_OFFSET;
-       /* The sprintf's below are OK as our caller made sure that buf is large enough */
+       /*
+        * The below sprintf(3) calls are OK because our caller already made
+        * sure that buf is large enough.
+        */
        p += sprintf(p, "%s", afhi->techinfo) + 1;
        p += sprintf(p, "%s", afhi->tags.artist) + 1;
        p += sprintf(p, "%s", afhi->tags.title) + 1;
@@ -374,6 +377,7 @@ static void save_afhi(struct afh_info *afhi, char *buf)
        sprintf(p, "%s", afhi->tags.comment);
 }
 
+/* does not load the chunk table */
 static void load_afhi(const char *buf, struct afh_info *afhi)
 {
        afhi->seconds_total = read_u32(buf + AFHI_SECONDS_TOTAL_OFFSET);
@@ -528,7 +532,7 @@ static int get_afsi_of_path(const char *path, struct afs_info *afsi)
  * \param row Pointer to a row in the audio file table.
  * \param path Result pointer.
  *
- * The result is a pointer to mmapped data. The caller must not attempt
+ * The result is a pointer to memory-mapped data. The caller must not attempt
  * to free it.
  *
  * \return Standard.
@@ -538,10 +542,12 @@ int get_audio_file_path_of_row(const struct osl_row *row, char **path)
        struct osl_object path_obj;
        int ret = osl(osl_get_object(audio_file_table, row, AFTCOL_PATH,
                &path_obj));
+
        if (ret < 0)
-               return ret;
-       *path = path_obj.data;
-       return 1;
+               *path = NULL;
+       else
+               *path = path_obj.data;
+       return ret;
 }
 
 /**
@@ -552,7 +558,7 @@ int get_audio_file_path_of_row(const struct osl_row *row, char **path)
  *
  * \return The return value of the underlying call to osl_get_object().
  *
- * \sa get_hash_of_row().
+ * \sa \ref get_hash_of_row().
  */
 static int get_hash_object_of_aft_row(const struct osl_row *row,
                struct osl_object *obj)
@@ -590,7 +596,9 @@ static int get_hash_of_row(const struct osl_row *row, unsigned char **hash)
  *
  * \return The return value of the underlying call to osl_get_object().
  *
- * \sa get_chunk_table_of_row().
+ * After the call the members of the afhi structure point to mapped memory
+ * which is owned by the osl table, Hence the caller must not attempt to free
+ * this memory by calling \ref clear_afhi().
  */
 int get_afhi_of_row(const struct osl_row *row, struct afh_info *afhi)
 {
@@ -694,7 +702,7 @@ static int get_local_time(uint64_t *seconds, char *buf, size_t size,
        /*
         * If the given time is more than six month away from the current time,
         * we print only the year. The additional space character in the format
-        * string below makes the formated date align nicely with dates that
+        * string below makes the formatted date align nicely with dates that
         * contain the time (those written by the above strftime() statement).
         */
        if (!strftime(buf, size, "%b %e  %Y", tm))
@@ -1106,6 +1114,12 @@ out:
        return ret;
 }
 
+static int ls_hash_compare(const void *a, const void *b)
+{
+       struct ls_data *d1 = *(struct ls_data **)a, *d2 = *(struct ls_data **)b;
+       return memcmp(d1->hash, d2->hash, HASH_SIZE);
+}
+
 static int ls_audio_format_compare(const void *a, const void *b)
 {
        struct ls_data *d1 = *(struct ls_data **)a, *d2 = *(struct ls_data **)b;
@@ -1223,6 +1237,8 @@ static int sort_matching_paths(struct ls_options *options)
                compar = ls_duration_compare; break;
        case LS_SORT_BY_AUDIO_FORMAT:
                compar = ls_audio_format_compare; break;
+       case LS_SORT_BY_HASH:
+               compar = ls_hash_compare; break;
        default:
                return -E_BAD_SORT;
        }
@@ -1371,7 +1387,6 @@ out:
        return ret;
 }
 
-/* TODO: flags -h (sort by hash) */
 static int com_ls(struct command_context *cc, struct lls_parse_result *lpr)
 {
        const struct lls_command *cmd = SERVER_CMD_CMD_PTR(LS);
@@ -1437,6 +1452,8 @@ static int com_ls(struct command_context *cc, struct lls_parse_result *lpr)
                        opts->sorting = LS_SORT_BY_DURATION;
                else if (!strcmp(val, "a") || !strcmp(val, "audio-format"))
                        opts->sorting = LS_SORT_BY_AUDIO_FORMAT;
+               else if (!strcmp(val, "h") || !strcmp(val, "hash"))
+                       opts->sorting = LS_SORT_BY_HASH;
                else {
                        ret = -E_AFT_SYNTAX;
                        goto out;
@@ -1909,11 +1926,7 @@ out:
 }
 EXPORT_SERVER_CMD_HANDLER(add);
 
-/**
- * Flags used by the touch command.
- *
- * \sa com_touch().
- */
+/** Flags used by the touch command. */
 enum touch_flags {
        /** Whether the \p FNM_PATHNAME flag should be passed to fnmatch(). */
        TOUCH_FLAG_FNM_PATHNAME = 1,
@@ -2399,8 +2412,6 @@ static int check_audio_file(struct osl_row *row, void *data)
  * \param aca Only ->pbout is used for diagnostics.
  *
  * \return Standard. Inconsistencies are reported but not regarded as an error.
- *
- * \sa com_check().
  */
 int aft_check_callback(struct afs_callback_arg *aca)
 {
@@ -2469,7 +2480,7 @@ int aft_check_attributes(uint64_t att_mask, struct para_buffer *pb)
  *
  * \param flags Usual flags that are passed to osl_close_table().
  *
- * \sa osl_close_table().
+ * \sa \ref osl_close_table().
  */
 static void aft_close(void)
 {
@@ -2484,7 +2495,7 @@ static void aft_close(void)
  *
  * \return Standard.
  *
- * \sa osl_open_table().
+ * \sa \ref osl_open_table().
  */
 static int aft_open(const char *dir)
 {