Rename length status item to seconds_total and print it only once.
[paraslash.git] / aft.c
diff --git a/aft.c b/aft.c
index ed9d2584c4953b5322fabdf25adb01cfd379cba0..483ab2526e1c1c4259b871644cbab704e524b73d 100644 (file)
--- a/aft.c
+++ b/aft.c
@@ -96,30 +96,27 @@ struct ls_widths {
        unsigned short num_played_width;
 };
 
-/** Data passed to the different compare functions (called by qsort()). */
-struct ls_data {
-       /** Usual audio format handler information. */
-       struct audio_format_info afhi;
-       /** Audio file selector information. */
-       struct afs_info afsi;
-       /** The full path of the audio file. */
-       char *path;
-       /** The score value (if -a was given). */
-       long score;
-       /** The sha1 hash of audio file. */
-       HASH_TYPE *hash;
-};
-
+/** Data passed from the ls command handler to its callback function. */
 struct ls_options {
+       /** The given command line flags. */
        unsigned flags;
+       /** The sorting method given at the command line. */
        enum ls_sorting_method sorting;
+       /** The given listing mode (short, long, verbose, mbox). */
        enum ls_listing_mode mode;
+       /** The arguments passed to the ls command. */
        char **patterns;
+       /** Number of non-option arguments. */
        int num_patterns;
+       /** Used for long listing mode to align the output fields. */
        struct ls_widths widths;
+       /** Size of the \a data array. */
        uint32_t array_size;
+       /** Number of used entries in the data array. */
        uint32_t num_matching_paths;
+       /** Array of matching entries. */
        struct ls_data *data;
+       /** Used to sort the array. */
        struct ls_data **data_ptr;
 };
 
@@ -312,22 +309,28 @@ enum afhi_offsets {
        AFHI_BITRATE_OFFSET = 4,
        /** Position of the frequency. */
        AFHI_FREQUENCY_OFFSET = 8,
+       /** Location of the audio file header. */
+       AFHI_HEADER_OFFSET_OFFSET = 12,
+       /* Length of the audio file header. Zero means: No header. */
+       AFHI_HEADER_LEN_OFFSET = 16,
        /** Number of channels is stored here. */
-       AFHI_CHANNELS_OFFSET = 12,
+       AFHI_CHANNELS_OFFSET = 20,
+       /** EOF timeout in ms. */
+       AFHI_EOF_OFFSET = 21,
        /** The tag info position. */
-       AFHI_INFO_STRING_OFFSET = 13,
+       AFHI_INFO_STRING_OFFSET = 23,
        /** Minimal on-disk size of a valid afhi struct. */
-       MIN_AFHI_SIZE = 14
+       MIN_AFHI_SIZE = 24
 };
 
-static unsigned sizeof_afhi_buf(const struct audio_format_info *afhi)
+static unsigned sizeof_afhi_buf(const struct afh_info *afhi)
 {
        if (!afhi)
                return 0;
        return strlen(afhi->info_string) + MIN_AFHI_SIZE;
 }
 
-static void save_afhi(struct audio_format_info *afhi, char *buf)
+static void save_afhi(struct afh_info *afhi, char *buf)
 {
        if (!afhi)
                return;
@@ -335,23 +338,29 @@ static void save_afhi(struct audio_format_info *afhi, char *buf)
                afhi->seconds_total);
        write_u32(buf + AFHI_BITRATE_OFFSET, afhi->bitrate);
        write_u32(buf + AFHI_FREQUENCY_OFFSET, afhi->frequency);
+       write_u32(buf + AFHI_HEADER_OFFSET_OFFSET, afhi->header_offset);
+       write_u32(buf + AFHI_HEADER_LEN_OFFSET, afhi->header_len);
        write_u8(buf + AFHI_CHANNELS_OFFSET, afhi->channels);
+       write_u16(buf + AFHI_EOF_OFFSET, tv2ms(&afhi->eof_tv));
        strcpy(buf + AFHI_INFO_STRING_OFFSET, afhi->info_string); /* OK */
        PARA_DEBUG_LOG("last byte written: %p\n", buf + AFHI_INFO_STRING_OFFSET + strlen(afhi->info_string));
 }
 
-static void load_afhi(const char *buf, struct audio_format_info *afhi)
+static void load_afhi(const char *buf, struct afh_info *afhi)
 {
        afhi->seconds_total = read_u32(buf + AFHI_SECONDS_TOTAL_OFFSET);
        afhi->bitrate = read_u32(buf + AFHI_BITRATE_OFFSET);
        afhi->frequency = read_u32(buf + AFHI_FREQUENCY_OFFSET);
        afhi->channels = read_u8(buf + AFHI_CHANNELS_OFFSET);
+       afhi->header_offset = read_u32(buf + AFHI_HEADER_OFFSET_OFFSET);
+       afhi->header_len = read_u32(buf + AFHI_HEADER_LEN_OFFSET);
+       ms2tv(read_u16(buf + AFHI_EOF_OFFSET), &afhi->eof_tv);
        strcpy(afhi->info_string, buf + AFHI_INFO_STRING_OFFSET);
 }
 
 //#define SIZEOF_CHUNK_TABLE(afhi) (((afhi)->chunks_total + 1) * sizeof(uint32_t))
 
-static unsigned sizeof_chunk_info_buf(struct audio_format_info *afhi)
+static unsigned sizeof_chunk_info_buf(struct afh_info *afhi)
 {
        if (!afhi)
                return 0;
@@ -375,16 +384,16 @@ enum chunk_info_offsets{
        CHUNK_TABLE_OFFSET = 20,
 };
 
-static void save_chunk_table(struct audio_format_info *afhi, char *buf)
+static void save_chunk_table(struct afh_info *afhi, char *buf)
 {
        int i;
 
-       PARA_NOTICE_LOG("%lu chunks\n", afhi->chunks_total);
+       PARA_DEBUG_LOG("%lu chunks\n", afhi->chunks_total);
        for (i = 0; i <= afhi->chunks_total; i++)
                write_u32(buf + 4 * i, afhi->chunk_table[i]);
 }
 
-static void load_chunk_table(struct audio_format_info *afhi, char *buf)
+static void load_chunk_table(struct afh_info *afhi, char *buf)
 {
        int i;
        for (i = 0; i <= afhi->chunks_total; i++)
@@ -392,7 +401,7 @@ static void load_chunk_table(struct audio_format_info *afhi, char *buf)
 }
 
 /* TODO: audio format handlers could just produce this */
-static void save_chunk_info(struct audio_format_info *afhi, char *buf)
+static void save_chunk_info(struct afh_info *afhi, char *buf)
 {
        if (!afhi)
                return;
@@ -404,7 +413,7 @@ static void save_chunk_info(struct audio_format_info *afhi, char *buf)
        save_chunk_table(afhi, buf + CHUNK_TABLE_OFFSET);
 }
 
-static int load_chunk_info(struct osl_object *obj, struct audio_format_info *afhi)
+static int load_chunk_info(struct osl_object *obj, struct afh_info *afhi)
 {
        char *buf = obj->data;
 
@@ -524,7 +533,10 @@ 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.
  *
- * \return Positive on success, negative on errors.
+ * The result is a pointer to mmapped data. The caller must not attempt
+ * to free it.
+ *
+ * \return Standard.
  */
 int get_audio_file_path_of_row(const struct osl_row *row, char **path)
 {
@@ -584,7 +596,7 @@ static int get_hash_of_row(const struct osl_row *row, HASH_TYPE **hash)
  *
  * \sa get_chunk_table_of_row().
  */
-int get_afhi_of_row(const struct osl_row *row, struct audio_format_info *afhi)
+int get_afhi_of_row(const struct osl_row *row, struct afh_info *afhi)
 {
        struct osl_object obj;
        int ret = osl_get_object(audio_file_table, row, AFTCOL_AFHI,
@@ -595,38 +607,13 @@ int get_afhi_of_row(const struct osl_row *row, struct audio_format_info *afhi)
        return 1;
 }
 
-#if 0
-/**
- * Get the chunk table of an audio file, given a row of the audio file table.
- *
- * \param row Pointer to a row of the audio file table.
- * \param afhi Result pointer.
- *
- * \return The return value of the underlying call to osl_open_disk_object().
- *
- * \sa get_afhi_of_row().
- */
-static int get_chunk_table_of_row(const struct osl_row *row, struct audio_format_info *afhi)
-{
-       struct osl_object obj;
-       int ret = osl_open_disk_object(audio_file_table, row, AFTCOL_CHUNKS,
-               &obj);
-       if (ret < 0)
-               return ret;
-       ret = load_chunk_info(&obj, afhi);
-       osl_close_disk_object(&obj);
-       return ret;
-}
-#endif
-
 /* returns shmid on success */
 static int save_afd(struct audio_file_data *afd)
 {
-       size_t path_size = strlen(afd->path) + 1;
-       size_t size = sizeof(*afd) + path_size
+       size_t size = sizeof(*afd)
                + 4 * (afd->afhi.chunks_total + 1);
 
-       PARA_NOTICE_LOG("size: %zu\n", size);
+       PARA_DEBUG_LOG("size: %zu\n", size);
        int shmid, ret = shm_new(size);
        void *shm_afd;
        char *buf;
@@ -640,8 +627,6 @@ static int save_afd(struct audio_file_data *afd)
        *(struct audio_file_data *)shm_afd = *afd;
        buf = shm_afd;
        buf += sizeof(*afd);
-       strcpy(buf, afd->path);
-       buf += path_size;
        save_chunk_table(&afd->afhi, buf);
        shm_detach(shm_afd);
        return shmid;
@@ -662,8 +647,6 @@ int load_afd(int shmid, struct audio_file_data *afd)
        *afd = *(struct audio_file_data *)shm_afd;
        buf = shm_afd;
        buf += sizeof(*afd);
-       afd->path = para_strdup(buf);
-       buf += strlen(buf) + 1;
        afd->afhi.chunk_table = para_malloc((afd->afhi.chunks_total + 1) * 4);
        load_chunk_table(&afd->afhi, buf);
        shm_detach(shm_afd);
@@ -690,12 +673,15 @@ int open_and_update_audio_file(struct osl_row *aft_row, struct audio_file_data *
        int ret = get_hash_of_row(aft_row, &aft_hash);
        struct afsi_change_event_data aced;
        struct osl_object map, chunk_table_obj;
+       char *path;
 
        if (ret < 0)
                return ret;
-       ret = get_audio_file_path_of_row(aft_row, &afd->path);
+       ret = get_audio_file_path_of_row(aft_row, &path);
        if (ret < 0)
                return ret;
+       strncpy(afd->path, path, sizeof(afd->path) - 1);
+       afd->path[sizeof(afd->path) - 1] = '\0';
        ret = get_afsi_object_of_row(aft_row, &afsi_obj);
        if (ret < 0)
                return ret;
@@ -709,7 +695,7 @@ int open_and_update_audio_file(struct osl_row *aft_row, struct audio_file_data *
                AFTCOL_CHUNKS, &chunk_table_obj);
        if (ret < 0)
                return ret;
-       ret = mmap_full_file(afd->path, O_RDONLY, &map.data,
+       ret = mmap_full_file(path, O_RDONLY, &map.data,
                &map.size, &afd->fd);
        if (ret < 0)
                goto err;
@@ -728,7 +714,22 @@ int open_and_update_audio_file(struct osl_row *aft_row, struct audio_file_data *
        ret = load_chunk_info(&chunk_table_obj, &afd->afhi);
        if (ret < 0)
                goto err;
-
+       {
+               struct ls_data d = {
+                       .afhi = afd->afhi,
+                       .afsi = afd->afsi,
+                       .path = path,
+                       .score = afd->score,
+                       .hash = file_hash
+               };
+               struct para_buffer pb = {.buf = NULL};
+               ret = make_status_items(&d, &pb);
+               if (ret < 0)
+                       goto err;
+               strncpy(afd->afs_status_info, pb.buf, AFS_STATUS_INFO_SIZE);
+               afd->afs_status_info[AFS_STATUS_INFO_SIZE - 1] = '\0';
+               free(pb.buf);
+       }
        aced.aft_row = aft_row;
        aced.old_afsi = &afd->afsi;
        afs_event(AFSI_CHANGE, NULL, &aced);
@@ -786,46 +787,51 @@ static short unsigned get_duration_width(int seconds)
        return width + 6;
 }
 
-static void get_duration_buf(int seconds, char *buf, short unsigned max_width)
+static void get_duration_buf(int seconds, char *buf, struct ls_options *opts)
 {
        unsigned hours = seconds / 3600, mins = (seconds % 3600) / 60;
+       short unsigned max_width;
 
-       if (!hours) /* m:ss or mm:ss */
+       if (!hours) { /* m:ss or mm:ss */
+               max_width = opts->mode == LS_MODE_LONG?
+                       opts->widths.duration_width : 4;
                sprintf(buf, "%*u:%02u", max_width - 3, mins, seconds % 60);
-       else /* more than one hour => h:mm:ss, hh:mm:ss, hhh:mm:ss, ... */
+       } else { /* more than one hour => h:mm:ss, hh:mm:ss, hhh:mm:ss, ... */
+               max_width = opts->mode == LS_MODE_LONG?
+                       opts->widths.duration_width : 7;
                sprintf(buf, "%*u:%02u:%02u", max_width - 6, hours, mins,
                        seconds % 60);
+       }
 }
 
-static char *make_attribute_line(const char *att_bitmap, struct afs_info *afsi)
+static char *make_attribute_lines(const char *att_bitmap, struct afs_info *afsi)
 {
-       char *att_text, *att_line;
+       char *att_text, *att_lines;
 
        get_attribute_text(&afsi->attributes, " ", &att_text);
        if (!att_text)
                return para_strdup(att_bitmap);
-       att_line = make_message("%s (%s)", att_bitmap, att_text);
+       att_lines = make_message("%s\nattributes_txt: %s",
+               att_bitmap, att_text);
        free(att_text);
-       return att_line;
+       return att_lines;
 }
 
-static char *make_lyrics_line(struct afs_info *afsi)
+static char *make_lyrics_lines(struct afs_info *afsi)
 {
        char *lyrics_name;
 
        lyr_get_name_by_id(afsi->lyrics_id, &lyrics_name);
-       if (!lyrics_name)
-               return make_message("%u", afsi->lyrics_id);
-       return make_message("%u (%s)", afsi->lyrics_id, lyrics_name);
+       return make_message("lyrics_id: %u\nlyrics_name: %s\n",
+               afsi->lyrics_id, lyrics_name? lyrics_name : "(none)");
 }
 
-static char *make_image_line(struct afs_info *afsi)
+static char *make_image_lines(struct afs_info *afsi)
 {
        char *image_name;
        img_get_name_by_id(afsi->image_id, &image_name);
-       if (!image_name)
-               return make_message("%u", afsi->image_id);
-       return make_message("%u (%s)", afsi->image_id, image_name);
+       return make_message("image_id: %u\nimage_name: %s\n",
+               afsi->image_id, image_name? image_name : "(none)");
 }
 
 static int print_list_item(struct ls_data *d, struct ls_options *opts,
@@ -837,11 +843,11 @@ static int print_list_item(struct ls_data *d, struct ls_options *opts,
        char duration_buf[30]; /* nobody has an audio file long enough to overflow this */
        char score_buf[30] = "";
        struct afs_info *afsi = &d->afsi;
-       struct audio_format_info *afhi = &d->afhi;
+       struct afh_info *afhi = &d->afhi;
        struct ls_widths *w = &opts->widths;
        int have_score = opts->flags & LS_FLAG_ADMISSIBLE_ONLY;
        char asc_hash[2 * HASH_SIZE + 1];
-       char *att_line, *lyrics_line, *image_line;
+       char *att_lines, *lyrics_lines, *image_lines;
 
        if (opts->mode == LS_MODE_SHORT) {
                para_printf(b, "%s\n", d->path);
@@ -852,7 +858,7 @@ static int print_list_item(struct ls_data *d, struct ls_options *opts,
                sizeof(last_played_time), current_time, opts->mode);
        if (ret < 0)
                return ret;
-       get_duration_buf(afhi->seconds_total, duration_buf, w->duration_width);
+       get_duration_buf(afhi->seconds_total, duration_buf, opts);
        if (have_score) {
                if (opts->mode == LS_MODE_LONG)
                        sprintf(score_buf, "%*li ", w->score_width, d->score);
@@ -890,23 +896,23 @@ static int print_list_item(struct ls_data *d, struct ls_options *opts,
                return 1;
        }
        hash_to_asc(d->hash, asc_hash);
-       att_line = make_attribute_line(att_buf, afsi);
-       lyrics_line = make_lyrics_line(afsi);
-       image_line = make_image_line(afsi);
+       att_lines = make_attribute_lines(att_buf, afsi);
+       lyrics_lines = make_lyrics_lines(afsi);
+       image_lines = make_image_lines(afsi);
        if (opts->mode == LS_MODE_VERBOSE) {
-
                para_printf(b,
                        "%s: %s\n" /* path */
                        "%s%s%s" /* score */
                        "attributes: %s\n"
                        "hash: %s\n"
-                       "image_id: %s\n"
-                       "lyrics_id: %s\n"
+                       "%s" /* image id, image name */
+                       "%s" /* lyrics */
                        "bitrate: %dkbit/s\n"
                        "format: %s\n"
                        "frequency: %dHz\n"
                        "channels: %d\n"
                        "duration: %s\n"
+                       "seconds_total: %lu\n"
                        "num_played: %d\n"
                        "last_played: %s\n"
                        "tag info: %s\n",
@@ -914,15 +920,16 @@ static int print_list_item(struct ls_data *d, struct ls_options *opts,
                                "path" : "file", d->path,
                        have_score? "score: " : "", score_buf,
                                have_score? "\n" : "",
-                       att_line,
+                       att_lines,
                        asc_hash,
-                       image_line,
-                       lyrics_line,
+                       image_lines,
+                       lyrics_lines,
                        afhi->bitrate,
                        audio_format_name(afsi->audio_format_id),
                        afhi->frequency,
                        afhi->channels,
                        duration_buf,
+                       afhi->seconds_total,
                        afsi->num_played,
                        last_played_time,
                        afhi->info_string
@@ -935,9 +942,9 @@ static int print_list_item(struct ls_data *d, struct ls_options *opts,
                        "Received: from\nTo: bar\nFrom: a\n"
                        "Subject: %s\n\n" /* path */
                        "%s%s%s" /* score */
-                       "attributes: %s\n"
+                       "%s\n" /* attributes */
                        "hash: %s\n"
-                       "image_id: %s\n"
+                       "%s\n" /* image id, image name */
                        "lyrics_id: %s\n"
                        "bitrate: %dkbit/s\n"
                        "format: %s\n"
@@ -951,10 +958,10 @@ static int print_list_item(struct ls_data *d, struct ls_options *opts,
                        d->path,
                        have_score? "score: " : "", score_buf,
                                have_score? "\n" : "",
-                       att_line,
+                       att_lines,
                        asc_hash,
-                       image_line,
-                       lyrics_line,
+                       image_lines,
+                       lyrics_lines,
                        afhi->bitrate,
                        audio_format_name(afsi->audio_format_id),
                        afhi->frequency,
@@ -968,12 +975,25 @@ static int print_list_item(struct ls_data *d, struct ls_options *opts,
                if (lyrics_def.data)
                        osl_close_disk_object(lyrics_def.data);
        }
-       free(att_line);
-       free(lyrics_line);
-       free(image_line);
+       free(att_lines);
+       free(lyrics_lines);
+       free(image_lines);
        return 1;
 }
 
+int make_status_items(struct ls_data *d, struct para_buffer *pb)
+{
+       struct ls_options opts = {
+               .flags = LS_FLAG_FULL_PATH | LS_FLAG_ADMISSIBLE_ONLY,
+               .mode = LS_MODE_VERBOSE,
+       };
+       time_t current_time;
+
+       time(&current_time);
+       return print_list_item(d, &opts, pb, current_time);
+}
+
+
 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;
@@ -1226,12 +1246,8 @@ out:
 }
 
 /*
- * TODO: flags -h (sort by hash) -lm (list in mbox format)
- *
- * long list: list hash, attributes as (xx--x-x-), file size, lastplayed
- * full list: list everything, including afsi, afhi, atts as clear text
- *
- * */
+ * TODO: flags -h (sort by hash)
+ */
 int com_ls(int fd, int argc, char * const * const argv)
 {
        int i, ret;
@@ -1378,7 +1394,7 @@ enum aft_row_offsets {
 /* never save the afsi, as the server knows it too. Note that afhi might be NULL.
  * In this case, afhi won't be stored in the buffer  */
 static void save_audio_file_info(HASH_TYPE *hash, const char *path,
-               struct audio_format_info *afhi, uint32_t flags,
+               struct afh_info *afhi, uint32_t flags,
                uint8_t audio_format_num, struct osl_object *obj)
 {
        size_t path_len = strlen(path) + 1;
@@ -1587,8 +1603,11 @@ out:
        return 1;
 }
 
+/** Used by com_add(). */
 struct private_add_data {
+       /** The socket file descriptor. */
        int fd;
+       /** The given add flags. */
        uint32_t flags;
 };
 
@@ -1626,7 +1645,7 @@ static int add_one_audio_file(const char *path, const void *private_data)
        int ret, ret2;
        uint8_t format_num = -1;
        const struct private_add_data *pad = private_data;
-       struct audio_format_info afhi, *afhi_ptr = NULL;
+       struct afh_info afhi, *afhi_ptr = NULL;
        struct osl_row *pb = NULL, *hs = NULL; /* path brother/hash sister */
        struct osl_object map, obj = {.data = NULL}, query, result = {.data = NULL};
        HASH_TYPE hash[HASH_SIZE];
@@ -1695,7 +1714,7 @@ static int add_one_audio_file(const char *path, const void *private_data)
        save_audio_file_info(hash, path, afhi_ptr, pad->flags, format_num, &obj);
        /* Ask afs to consider this entry for adding. */
        ret = send_callback_request(com_add_callback, &obj, &result);
-       if (ret >= 0 && result.data && result.size) {
+       if (ret > 0) {
                ret2 = send_va_buffer(pad->fd, "%s", (char *)result.data);
                free(result.data);
                if (ret >= 0 && ret2 < 0)
@@ -1795,16 +1814,25 @@ enum touch_flags {
        TOUCH_FLAG_VERBOSE = 2
 };
 
+/** Options used by com_touch(). */
 struct com_touch_options {
+       /** New num_played value. */
        int32_t num_played;
+       /** New last played count. */
        int64_t last_played;
+       /** new lyrics id. */
        int32_t lyrics_id;
+       /** new image id. */
        int32_t image_id;
+       /** command line flags (see \ref touch_flags). */
        unsigned flags;
 };
 
+/** Data passed to the action handler of com_touch(). */
 struct touch_action_data {
+       /** Command line options (see \ref com_touch_options). */
        struct com_touch_options *cto;
+       /** Message buffer. */
        struct para_buffer pb;
 };
 
@@ -1944,27 +1972,35 @@ int com_touch(int fd, int argc, char * const * const argv)
        if (ret > 0) {
                send_buffer(fd, (char *)result.data);
                free(result.data);
-       } else
+       } else if (ret < 0)
                send_va_buffer(fd, "%s\n", PARA_STRERROR(-ret));
        return ret;
 }
 
+/** Flags for com_rm(). */
 enum rm_flags {
+       /** -v */
        RM_FLAG_VERBOSE = 1,
+       /** -f */
        RM_FLAG_FORCE = 2,
+       /** -p */
        RM_FLAG_FNM_PATHNAME = 4
 };
 
-struct com_rm_data {
+/** Data passed to the action handler of com_rm(). */
+struct com_rm_action_data {
+       /** Command line flags ((see \ref rm_flags). */
        uint32_t flags;
+       /** Message buffer. */
        struct para_buffer pb;
+       /** Number of audio files removed. */
        unsigned num_removed;
 };
 
 static int remove_audio_file(__a_unused struct osl_table *table,
                struct osl_row *row, const char *name, void *data)
 {
-       struct com_rm_data *crd = data;
+       struct com_rm_action_data *crd = data;
        int ret;
 
        if (crd->flags & RM_FLAG_VERBOSE)
@@ -1981,7 +2017,7 @@ static int remove_audio_file(__a_unused struct osl_table *table,
 static int com_rm_callback(const struct osl_object *query,
                __a_unused struct osl_object *result)
 {
-       struct com_rm_data crd = {.flags = *(uint32_t *)query->data};
+       struct com_rm_action_data crd = {.flags = *(uint32_t *)query->data};
        int ret;
        struct pattern_match_data pmd = {
                .table = audio_file_table,
@@ -2073,10 +2109,15 @@ enum cpsi_flags {
        CPSI_FLAG_VERBOSE = 32,
 };
 
+/** Data passed to the action handler of com_cpsi(). */
 struct cpsi_action_data {
+       /** command line flags (see \ref cpsi_flags). */
        unsigned flags;
+       /** Number of audio files changed. */
        unsigned num_copied;
+       /** Message buffer. */
        struct para_buffer pb;
+       /** Values are copied from here. */
        struct afs_info source_afsi;
 };
 
@@ -2270,7 +2311,7 @@ int aft_check_callback(__a_unused const struct osl_object *query, struct osl_obj
 /**
  * Close the audio file table.
  *
- * \param flags Ususal flags that are passed to osl_close_table().
+ * \param flags Usual flags that are passed to osl_close_table().
  *
  * \sa osl_close_table().
  */