src/pulse/simple.h

   1 #ifndef foosimplehfoo
   2 #define foosimplehfoo
   3
   4 /***
   5   This file is part of PulseAudio.
   6
   7   Copyright 2004-2006 Lennart Poettering
   8   Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB
   9
  10   PulseAudio is free software; you can redistribute it and/or modify
  11   it under the terms of the GNU Lesser General Public License as published
  12   by the Free Software Foundation; either version 2.1 of the License,
  13   or (at your option) any later version.
  14
  15   PulseAudio is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with PulseAudio; if not, write to the Free Software
  22   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  23   USA.
  24 ***/
  25
  26 #include <sys/types.h>
  27
  28 #include <pulse/sample.h>
  29 #include <pulse/channelmap.h>
  30 #include <pulse/def.h>
  31 #include <pulse/cdecl.h>
  32 #include <pulse/version.h>
  33
  34 #include <pulse/proplist.h>
  35 /** \page simple Simple API
  36  *
  37  * \section overv_sec Overview
  38  *
  39  * The simple API is designed for applications with very basic sound
  40  * playback or capture needs. It can only support a single stream per
  41  * connection and has no support for handling of complex features like
  42  * events, channel mappings and volume control. It is, however, very simple
  43  * to use and quite sufficient for many programs.
  44  *
  45  * \section conn_sec Connecting
  46  *
  47  * The first step before using the sound system is to connect to the
  48  * server. This is normally done this way:
  49  *
  50  * \code
  51  * pa_simple *s;
  52  * pa_sample_spec ss;
  53  *
  54  * ss.format = PA_SAMPLE_S16NE;
  55  * ss.channels = 2;
  56  * ss.rate = 44100;
  57  *
  58  * s = pa_simple_new(NULL,               // Use the default server.
  59  *                   "Fooapp",           // Our application's name.
  60  *                   PA_STREAM_PLAYBACK,
  61  *                   NULL,               // Use the default device.
  62  *                   "Music",            // Description of our stream.
  63  *                   &ss,                // Our sample format.
  64  *                   NULL,               // Use default channel map
  65  *                   NULL,               // Use default buffering attributes.
  66  *                   NULL,               // Ignore error code.
  67  *                   );
  68  * \endcode
  69  *
  70  * At this point a connected object is returned, or NULL if there was a
  71  * problem connecting.
  72  *
  73  * \section transfer_sec Transferring data
  74  *
  75  * Once the connection is established to the server, data can start flowing.
  76  * Using the connection is very similar to the normal read() and write()
  77  * system calls. The main difference is that they're called pa_simple_read()
  78  * and pa_simple_write(). Note that these operations always block.
  79  *
  80  * \section ctrl_sec Buffer control
  81  *
  82  * \li pa_simple_get_latency() - Will return the total latency of
  83  *                               the playback or record pipeline, respectively.
  84  * \li pa_simple_flush() - Will throw away all data currently in buffers.
  85  *
  86  * If a playback stream is used then the following operation is available:
  87  *
  88  * \li pa_simple_drain() - Will wait for all sent data to finish playing.
  89  *
  90  * \section cleanup_sec Cleanup
  91  *
  92  * Once playback or capture is complete, the connection should be closed
  93  * and resources freed. This is done through:
  94  *
  95  * \code
  96  * pa_simple_free(s);
  97  * \endcode
  98  */
  99
 100 /** \file
 101  * A simple but limited synchronous playback and recording
 102  * API. This is a synchronous, simplified wrapper around the standard
 103  * asynchronous API.
 104  *
 105  * See also \subpage simple
 106  */
 107
 108 /** \example pacat-simple.c
 109  * A simple playback tool using the simple API */
 110
 111 /** \example parec-simple.c
 112  * A simple recording tool using the simple API */
 113
 114 PA_C_DECL_BEGIN
 115
 116 /** \struct pa_simple
 117  * An opaque simple connection object */
 118 typedef struct pa_simple pa_simple;
 119
 120 /** Create a new connection to the server. */
 121 pa_simple* pa_simple_new(
 122     const char *server,                 /**< Server name, or NULL for default */
 123     const char *name,                   /**< A descriptive name for this client (application name, ...) */
 124     pa_stream_direction_t dir,          /**< Open this stream for recording or playback? */
 125     const char *dev,                    /**< Sink (resp. source) name, or NULL for default */
 126     const char *stream_name,            /**< A descriptive name for this stream (application name, song title, ...) */
 127     const pa_sample_spec *ss,           /**< The sample type to use */
 128     const pa_channel_map *map,          /**< The channel map to use, or NULL for default */
 129     const pa_buffer_attr *attr,         /**< Buffering attributes, or NULL for default */
 130     int *error                          /**< A pointer where the error code is stored when the routine returns NULL. It is OK to pass NULL here. */
 131     );
 132
 133 /** Create a new connection to the server with proplist */
 134 pa_simple* pa_simple_new_proplist(
 135     const char *server,                 /**< Server name, or NULL for default */
 136     const char *name,                   /**< A descriptive name for this client (application name, ...) */
 137     pa_stream_direction_t dir,          /**< Open this stream for recording or playback? */
 138     const char *dev,                    /**< Sink (resp. source) name, or NULL for default */
 139     const char *stream_name,            /**< A descriptive name for this client (application name, song title, ...) */
 140     const pa_sample_spec *ss,           /**< The sample type to use */
 141     const pa_channel_map *map,          /**< The channel map to use, or NULL for default */
 142     const pa_buffer_attr *attr,         /**< Buffering attributes, or NULL for default */
 143     pa_proplist *proplist,              /**< Properties, or NULL for default */
 144     int *error                          /**< A pointer where the error code is stored when the routine returns NULL. It is OK to pass NULL here. */
 145     );
 146 /** Close and free the connection to the server. The connection object becomes invalid when this is called. */
 147 void pa_simple_free(pa_simple *s);
 148
 149 /** Write some data to the server. */
 150 int pa_simple_write(pa_simple *s, const void *data, size_t bytes, int *error);
 151
 152 /** Wait until all data already written is played by the daemon. */
 153 int pa_simple_drain(pa_simple *s, int *error);
 154
 155 /** Read some data from the server. This function blocks until \a bytes amount
 156  * of data has been received from the server, or until an error occurs.
 157  * Returns a negative value on failure. */
 158 int pa_simple_read(
 159     pa_simple *s, /**< The connection object. */
 160     void *data,   /**< A pointer to a buffer. */
 161     size_t bytes, /**< The number of bytes to read. */
 162     int *error
 163     /**< A pointer where the error code is stored when the function returns
 164      * a negative value. It is OK to pass NULL here. */
 165     );
 166
 167 /** Return the playback or record latency. */
 168 pa_usec_t pa_simple_get_latency(pa_simple *s, int *error);
 169
 170 /** Flush the playback or record buffer. This discards any audio in the buffer. */
 171 int pa_simple_flush(pa_simple *s, int *error);
 172
 173 /** Get stream index */
 174 int pa_simple_get_stream_index(pa_simple *p, unsigned int *idx, int *rerror);
 175
 176 PA_C_DECL_END
 177
 178 #endif