code.delx.au - pulseaudio/blob - 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 /** \page simple Simple API
  35  *
  36  * \section overv_sec Overview
  37  *
  38  * The simple API is designed for applications with very basic sound
  39  * playback or capture needs. It can only support a single stream per
  40  * connection and has no handling of complex features like events, channel
  41  * mappings and volume control. It is, however, very simple to use and
  42  * quite sufficent for many programs.
  43  *
  44  * \section conn_sec Connecting
  45  *
  46  * The first step before using the sound system is to connect to the
  47  * server. This is normally done this way:
  48  *
  49  * \code
  50  * pa_simple *s;
  51  * pa_sample_spec ss;
  52  *
  53  * ss.format = PA_SAMPLE_S16NE;
  54  * ss.channels = 2;
  55  * ss.rate = 44100;
  56  *
  57  * s = pa_simple_new(NULL,               // Use the default server.
  58  *                   "Fooapp",           // Our application's name.
  59  *                   PA_STREAM_PLAYBACK,
  60  *                   NULL,               // Use the default device.
  61  *                   "Music",            // Description of our stream.
  62  *                   &ss,                // Our sample format.
  63  *                   NULL,               // Use default channel map
  64  *                   NULL,               // Use default buffering attributes.
  65  *                   NULL,               // Ignore error code.
  66  *                   );
  67  * \endcode
  68  *
  69  * At this point a connected object is returned, or NULL if there was a
  70  * problem connecting.
  71  *
  72  * \section transfer_sec Transferring data
  73  *
  74  * Once the connection is established to the server, data can start flowing.
  75  * Using the connection is very similar to the normal read() and write()
  76  * system calls. The main difference is that they're call pa_simple_read()
  77  * and pa_simple_write(). Note that these operations always block.
  78  *
  79  * \section ctrl_sec Buffer control
  80  *
  81  * If a playback stream is used then a few other operations are available:
  82  *
  83  * \li pa_simple_drain() - Will wait for all sent data to finish playing.
  84  * \li pa_simple_flush() - Will throw away all data currently in buffers.
  85  * \li pa_simple_get_latency() - Will return the total latency of
  86  *                               the playback pipeline.
  87  *
  88  * \section cleanup_sec Cleanup
  89  *
  90  * Once playback or capture is complete, the connection should be closed
  91  * and resources freed. This is done through:
  92  *
  93  * \code
  94  * pa_simple_free(s);
  95  * \endcode
  96  */
  97
  98 /** \file
  99  * A simple but limited synchronous playback and recording
 100  * API. This is a synchronous, simplified wrapper around the standard
 101  * asynchronous API. */
 102
 103 /** \example pacat-simple.c
 104  * A simple playback tool using the simple API */
 105
 106 /** \example parec-simple.c
 107  * A simple recording tool using the simple API */
 108
 109 PA_C_DECL_BEGIN
 110
 111 /** \struct pa_simple
 112  * An opaque simple connection object */
 113 typedef struct pa_simple pa_simple;
 114
 115 /** Create a new connection to the server */
 116 pa_simple* pa_simple_new(
 117     const char *server,                 /**< Server name, or NULL for default */
 118     const char *name,                   /**< A descriptive name for this client (application name, ...) */
 119     pa_stream_direction_t dir,          /**< Open this stream for recording or playback? */
 120     const char *dev,                    /**< Sink (resp. source) name, or NULL for default */
 121     const char *stream_name,            /**< A descriptive name for this client (application name, song title, ...) */
 122     const pa_sample_spec *ss,           /**< The sample type to use */
 123     const pa_channel_map *map,          /**< The channel map to use, or NULL for default */
 124     const pa_buffer_attr *attr,         /**< Buffering attributes, or NULL for default */
 125     int *error                          /**< A pointer where the error code is stored when the routine returns NULL. It is OK to pass NULL here. */
 126     );
 127
 128 /** Close and free the connection to the server. The connection objects becomes invalid when this is called. */
 129 void pa_simple_free(pa_simple *s);
 130
 131 /** Write some data to the server */
 132 int pa_simple_write(pa_simple *s, const void*data, size_t bytes, int *error);
 133
 134 /** Wait until all data already written is played by the daemon */
 135 int pa_simple_drain(pa_simple *s, int *error);
 136
 137 /** Read some data from the server */
 138 int pa_simple_read(pa_simple *s, void*data, size_t bytes, int *error);
 139
 140 /** Return the playback latency. */
 141 pa_usec_t pa_simple_get_latency(pa_simple *s, int *error);
 142
 143 /** Flush the playback buffer. */
 144 int pa_simple_flush(pa_simple *s, int *error);
 145
 146 PA_C_DECL_END
 147
 148 #endif