Update doxygen documentation.
authorAndre Noll <maan@systemlinux.org>
Tue, 25 Mar 2008 00:19:21 +0000 (01:19 +0100)
committerAndre Noll <maan@systemlinux.org>
Tue, 25 Mar 2008 00:19:21 +0000 (01:19 +0100)
afs.c
afs.h
aft.c
mood.c
playlist.c
string.h

diff --git a/afs.c b/afs.c
index 2260344..d7c1ecf 100644 (file)
--- a/afs.c
+++ b/afs.c
@@ -145,11 +145,20 @@ struct callback_result {
  *
  * \param f The function to be called.
  * \param query Pointer to arbitrary data for the callback.
- * \param result Callback result will be stored here.
+ * \param result_handler Called for each shm area sent by the callback.
+ * \param private_result_data Passed verbatim to \a result_handler.
  *
- * This function creates a shared memory area, copies the buffer pointed to by
- * \a query to that area and notifies the afs process that \a f should be
- * called ASAP.
+ * This function creates a socket for communication with the afs process and a
+ * shared memory area (sma) to which the buffer pointed to by \a query is
+ * copied.  It then notifies the afs process that the callback function \a f
+ * should be executed by sending the shared memory identifier (shmid) to the
+ * socket.
+
+ * If the callback produces a result, it sends any number of shared memory
+ * identifiers back via the socket. For each such identifier received, \a
+ * result_handler is called. The contents of the sma identified by the received
+ * shmid are passed to that function as an osl object. The private_result_data
+ * pointer is passed as the second argument to \a result_handler.
  *
  * \return Negative, on errors, the return value of the callback function
  * otherwise.
@@ -245,7 +254,8 @@ out:
  * \param argc Argument count.
  * \param argv Standard argument vector.
  * \param f The callback function.
- * \param result The result of the query is stored here.
+ * \param result_handler See \ref send_callback_request.
+ * \param private_result_data See \ref send_callback_request.
  *
  * Some commands have a couple of options that are parsed in child context for
  * syntactic correctness and are stored in a special options structure for that
@@ -287,7 +297,8 @@ int send_option_arg_callback_request(struct osl_object *options,
  * \param argc The same meaning as in send_option_arg_callback_request().
  * \param argv The same meaning as in send_option_arg_callback_request().
  * \param f The same meaning as in send_option_arg_callback_request().
- * \param result The same meaning as in send_option_arg_callback_request().
+ * \param result_handler See \ref send_callback_request.
+ * \param private_result_data See \ref send_callback_request.
  *
  * This is similar to send_option_arg_callback_request(), but no options buffer
  * is passed to the parent process.
@@ -407,13 +418,15 @@ static int fd2buf(int fd, unsigned max_size, struct osl_object *obj)
  * \param arg_obj Pointer to the arguments to \a f.
  * \param f The callback function.
  * \param max_len Don't read more than that many bytes from stdin.
- * \param result The result of the query is stored here.
+ * \param result_handler See \ref send_callback_request.
+ * \param private_result_data See \ref send_callback_request.
  *
  * This function is used by commands that wish to let para_server store
  * arbitrary data specified by the user (for instance the add_blob family of
  * commands). First, at most \a max_len bytes are read from \a fd, the result
  * is concatenated with the buffer given by \a arg_obj, and the combined buffer
- * is made available to the parent process via shared memory.
+ * is made available to the afs process via the callback method. See \ref
+ * send_callback_request for details.
  *
  * \return Negative on errors, the return value of the underlying call to
  * send_callback_request() otherwise.
@@ -612,9 +625,19 @@ out:
        free(pb.buf);
 }
 
-int send_result(struct osl_object *result, void *private_result_data)
+/**
+ * Result handler for sending data to the para_client process.
+ *
+ * \param result The data to be sent.
+ * \param fd_ptr Pointer to the file descriptor.
+ *
+ * \return The return value of the underlying call to send_bin_buffer().
+ *
+ * \sa \ref callback_result_handler.
+ */
+int send_result(struct osl_object *result, void *fd_ptr)
 {
-       int fd = *(int *)private_result_data;
+       int fd = *(int *)fd_ptr;
        if (!result->size)
                return 1;
        return send_bin_buffer(fd, result->data, result->size);
@@ -805,9 +828,27 @@ static void command_pre_select(struct sched *s, struct task *t)
        t->ret = 1;
 }
 
-int pass_buffer_as_shm(char *buf, size_t size, void *private_data)
+/**
+ * Send data as shared memory to a file descriptor.
+ *
+ * \param buf The buffer holding the data to be sent.
+ * \param size The size of \a buf.
+ * \param fd_ptr A pointer to the file descriptor.
+ *
+ * This function is used as the \a max_size handler in a \ref para_buffer
+ * structure. If used this way, it is called by \ref para_printf() whenever
+ * the buffer passed to para_printf() is about to exceed its maximal size.
+ *
+ * This function creates a shared memory area large enough to hold
+ * the content given by \a buf and \a size and sends the identifier
+ * of this area to the file descriptor given by \a fd_ptr.
+ *
+ * \return Zero if \a buf is \p NULL or \a size is zero. Negative on errors,
+ * and positive on success.
+ */
+int pass_buffer_as_shm(char *buf, size_t size, void *fd_ptr)
 {
-       int ret, shmid, fd = *(int *)private_data;
+       int ret, shmid, fd = *(int *)fd_ptr;
        void *shm;
        struct callback_result *cr;
 
diff --git a/afs.h b/afs.h
index ad9bfc8..d01f0cf 100644 (file)
--- a/afs.h
+++ b/afs.h
@@ -159,7 +159,7 @@ struct pattern_match_data {
        int (*action)(struct osl_table *table, struct osl_row *row, const char *name, void *data);
 };
 
-/* afs */
+
 /**
  * Afs command handlers run as a process which is not related to the afs
  * process, i.e. they can not change the address space of afs directly.
@@ -169,9 +169,17 @@ struct pattern_match_data {
  * \sa send_callback_request().
  */
 typedef void callback_function(int fd, const struct osl_object *);
+
+/**
+ * Callbacks send chunks to data back to the command handler. Pointers to
+ * this type of function are used by \ref send_callback_request and friends
+ * to deal with the data in the command handler process.
+ *
+ * \sa \ref send_callback_request().
+ */
 typedef int callback_result_handler(struct osl_object *result, void *private);
-int send_result(struct osl_object *result, void *private_result_data);
-int pass_buffer_as_shm(char *buf, size_t size, void *private_data);
+int send_result(struct osl_object *result, void *fd_ptr);
+int pass_buffer_as_shm(char *buf, size_t size, void *fd_ptr);
 
 __noreturn void afs_init(uint32_t cookie, int socket_fd);
 void afs_event(enum afs_events event, struct para_buffer *pb,
diff --git a/aft.c b/aft.c
index 0ffacbe..f6cfddf 100644 (file)
--- a/aft.c
+++ b/aft.c
@@ -2378,8 +2378,8 @@ static int check_audio_file(struct osl_row *row, void *data)
 /**
  * Check the audio file table for inconsistencies.
  *
+ * \param fd The afs socket.
  * \param query Unused.
- * \param result Contains message string upon return.
  *
  * This function always succeeds.
  *
diff --git a/mood.c b/mood.c
index 590a68f..40f3cac 100644 (file)
--- a/mood.c
+++ b/mood.c
@@ -561,8 +561,8 @@ out:
 /**
  * Check all moods for syntax errors.
  *
+ * \param fd The afs socket.
  * \param query Unused.
- * \param result: Contains check messages.
  */
 void mood_check_callback(int fd, __a_unused const struct osl_object *query)
 {
index 7a912ba..171ebab 100644 (file)
@@ -120,8 +120,8 @@ static int check_playlist(struct osl_row *row, void *data)
 /**
  * Check the playlist table for inconsistencies.
  *
+ * \param fd The afs socket.
  * \param query Unused.
- * \param result Contains messages about inconsistencies.
  *
  * \return The return value of the underlying call to osl_rbtree_loop().
  */
index c01d619..561ff4e 100644 (file)
--- a/string.h
+++ b/string.h
@@ -18,7 +18,7 @@ struct para_buffer {
        size_t offset;
        /**
         * If an attempt to print into this buffer is made that would need to
-        * grow \buf to a size larger than \a max_size, then this function is
+        * grow \buf to a size larger than \a max_size, then this function is
         * called.
         */
        int (*max_size_handler)(char *buf, size_t size, void *private_data);