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