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 (at) 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 sufficient 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 * See also \subpage simple 104 */ 105 106 /** \example pacat-simple.c 107 * A simple playback tool using the simple API */ 108 109 /** \example parec-simple.c 110 * A simple recording tool using the simple API */ 111 112 PA_C_DECL_BEGIN 113 114 /** \struct pa_simple 115 * An opaque simple connection object */ 116 typedef struct pa_simple pa_simple; 117 118 /** Create a new connection to the server */ 119 pa_simple* pa_simple_new( 120 const char *server, /**< Server name, or NULL for default */ 121 const char *name, /**< A descriptive name for this client (application name, ...) */ 122 pa_stream_direction_t dir, /**< Open this stream for recording or playback? */ 123 const char *dev, /**< Sink (resp. source) name, or NULL for default */ 124 const char *stream_name, /**< A descriptive name for this client (application name, song title, ...) */ 125 const pa_sample_spec *ss, /**< The sample type to use */ 126 const pa_channel_map *map, /**< The channel map to use, or NULL for default */ 127 const pa_buffer_attr *attr, /**< Buffering attributes, or NULL for default */ 128 int *error /**< A pointer where the error code is stored when the routine returns NULL. It is OK to pass NULL here. */ 129 ); 130 131 /** Close and free the connection to the server. The connection objects becomes invalid when this is called. */ 132 void pa_simple_free(pa_simple *s); 133 134 /** Write some data to the server */ 135 int pa_simple_write(pa_simple *s, const void*data, size_t bytes, int *error); 136 137 /** Wait until all data already written is played by the daemon */ 138 int pa_simple_drain(pa_simple *s, int *error); 139 140 /** Read some data from the server */ 141 int pa_simple_read(pa_simple *s, void*data, size_t bytes, int *error); 142 143 /** Return the playback latency. */ 144 pa_usec_t pa_simple_get_latency(pa_simple *s, int *error); 145 146 /** Flush the playback buffer. This discards any audio in the buffer. */ 147 int pa_simple_flush(pa_simple *s, int *error); 148 149 PA_C_DECL_END 150 151 #endif 152
