Changeset ad1aedc in mainline

Timestamp:

2012-08-20T09:48:02Z (12 years ago)

Author:

Jan Vesely <jano.vesely@…>

Branches:

lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export

Children:

20840922

Parents:

86fe9d1

Message:

libdrv: Document client side audio pcm API.

File:

• uspace/lib/drv/generic/remote_audio_pcm.c (modified) (13 diffs)

uspace/lib/drv/generic/remote_audio_pcm.c

@@ -59 +59 @@
  * CLIENT SIDE
  */
+
+/**
+ * Open audio session with device identified by location service string.
+ *
+ * @param name Location service string.
+ * @return Pointer to a new audio device session, NULL on failure.
+ */
 audio_pcm_sess_t *audio_pcm_open(const char *name)
 {
@@ -69 +76 @@
 }
 
+/**
+ * Open audio session with device identified by location service id
+ *
+ * @param name Location service id.
+ * @return Pointer to a new audio device session, NULL on failure.
+ */
 audio_pcm_sess_t *audio_pcm_open_service(service_id_t id)
 {
@@ -74 +87 @@
 }
 
+/**
+ * Close open audio device session.
+ *
+ * @param name Open audio device session.
+ *
+ * @note Calling this function on already closed or invalid session results
+ * in undefined behavior.
+ */
 void audio_pcm_close(audio_pcm_sess_t *sess)
 {
@@ -80 +101 @@
 }
 
+/**
+ * Get a short description string.
+ *
+ * @param sess Audio device session.
+ * @param name Place to store newly allocated string.
+ *
+ * @return Error code.
+ *
+ * @note Caller is responsible for freeing newly allocated memory.
+ */
 int audio_pcm_get_info_str(audio_pcm_sess_t *sess, const char **name)
 {
@@ -109 +140 @@
 }
 
+
+/**
+ * Query value of specified capability.
+ *
+ * @param sess Audio device session.
+ * @param cap  Audio device capability.
+ * @param val  Place to store queried value.
+ *
+ * @return Error code.
+ */
 int audio_pcm_query_cap(audio_pcm_sess_t *sess, audio_cap_t cap, unsigned *val)
 {
@@ -124 +165 @@
 }
 
+/**
+ * Query current position in device buffer.
+ *
+ * @param sess Audio device session.
+ * @param pos Place to store the result.
+ *
+ * @return Error code.
+ *
+ * Works for both playback and capture.
+ */
 int audio_pcm_get_buffer_pos(audio_pcm_sess_t *sess, size_t *pos)
 {
@@ -139 +190 @@
 }
 
+/**
+ * Test format parameters for device support.
+ *
+ * @param sess Audio device session.
+ * @param channels Number of channels
+ * @param rate Sampling rate.
+ * @format Sample format.
+ *
+ * @return Error code.
+ *
+ * Works for both playback and capture. This function modifies provided
+ * parameters to the nearest values supported by the device.
+ */
 int audio_pcm_test_format(audio_pcm_sess_t *sess, unsigned *channels,
     unsigned *rate, pcm_sample_format_t *format)
@@ -168 +232 @@
 }
 
+/**
+ * Get device accessible playback/capture buffer.
+ *
+ * @param sess Audio device session.
+ * @param buffer Place to store pointer to the buffer.
+ * @param size Place to store buffer size (bytes).
+ * @param event_rec Event callback function.
+ * @param arg Event callback custom parameter.
+ *
+ * @return Error code.
+ */
 int audio_pcm_get_buffer(audio_pcm_sess_t *sess, void **buffer, size_t *size,
     async_client_conn_t event_rec, void* arg)
@@ -200 +275 @@
 }
 
+/**
+ * Release device accessible playback/capture buffer.
+ *
+ * @param sess Audio device session.
+ *
+ * @return Error code.
+ */
 int audio_pcm_release_buffer(audio_pcm_sess_t *sess)
 {
@@ -210 +292 @@
 }
 
+/**
+ * Start playback on buffer from position 0.
+ *
+ * @param sess Audio device session.
+ * @param frames Size of fragment (in frames).
+ * @param channels Number of channels.
+ * @param sample_rate Sampling rate (for one channel).
+ * @param format Sample format.
+ *
+ * @return Error code.
+ *
+ * Event will be generated after every fragment. Set fragment size to
+ * 0 to turn off event generation.
+ */
 int audio_pcm_start_playback(audio_pcm_sess_t *sess, unsigned frames,
     unsigned channels, unsigned sample_rate, pcm_sample_format_t format)
@@ -226 +322 @@
 }
 
+/**
+ * Stop current playback.
+ *
+ * @param sess Audio device session.
+ *
+ * @return Error code.
+ */
 int audio_pcm_stop_playback(audio_pcm_sess_t *sess)
 {
@@ -236 +339 @@
 }
 
+/**
+ * Start capture on buffer from position 0.
+ *
+ * @param sess Audio device session.
+ * @param frames Size of fragment (in frames).
+ * @param channels Number of channels.
+ * @param sample_rate Sampling rate (for one channel).
+ * @param format Sample format.
+ *
+ * @return Error code.
+ *
+ * Event will be generated after every fragment. Set fragment size to
+ * 0 to turn off event generation.
+ */
 int audio_pcm_start_capture(audio_pcm_sess_t *sess, unsigned frames,
     unsigned channels, unsigned sample_rate, pcm_sample_format_t format)
@@ -251 +368 @@
 }
 
+/**
+ * Stop current playback.
+ *
+ * @param sess Audio device session.
+ *
+ * @return Error code.
+ */
 int audio_pcm_stop_capture(audio_pcm_sess_t *sess)
 {