1 #ifndef foosimplehfoo 2 #define foosimplehfoo 3 4 /* $Id: simple.h 1999 2007-10-30 14:17:41Z lennart $ */ 5 6 /*** 7 This file is part of PulseAudio. 8 9 Copyright 2004-2006 Lennart Poettering 10 Copyright 2006 Pierre Ossman <ossman (at) cendio.se> for Cendio AB 11 12 PulseAudio is free software; you can redistribute it and/or modify 13 it under the terms of the GNU Lesser General Public License as published 14 by the Free Software Foundation; either version 2 of the License, 15 or (at your option) any later version. 16 17 PulseAudio is distributed in the hope that it will be useful, but 18 WITHOUT ANY WARRANTY; without even the implied warranty of 19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 20 General Public License for more details. 21 22 You should have received a copy of the GNU Lesser General Public License 23 along with PulseAudio; if not, write to the Free Software 24 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 25 USA. 26 ***/ 27 28 #include <sys/types.h> 29 30 #include <pulse/sample.h> 31 #include <pulse/channelmap.h> 32 #include <pulse/def.h> 33 #include <pulse/cdecl.h> 34 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 handling of complex features like events, channel 42 * mappings and volume control. It is, however, very simple to use and 43 * quite sufficent 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 call pa_simple_read() 78 * and pa_simple_write(). Note that these operations always block. 79 * 80 * \section ctrl_sec Buffer control 81 * 82 * If a playback stream is used then a few other operations are available: 83 * 84 * \li pa_simple_drain() - Will wait for all sent data to finish playing. 85 * \li pa_simple_flush() - Will throw away all data currently in buffers. 86 * \li pa_simple_get_playback_latency() - Will return the total latency of 87 * the playback pipeline. 88 * 89 * \section cleanup_sec Cleanup 90 * 91 * Once playback or capture is complete, the connection should be closed 92 * and resources freed. This is done through: 93 * 94 * \code 95 * pa_simple_free(s); 96 * \endcode 97 */ 98 99 /** \file 100 * A simple but limited synchronous playback and recording 101 * API. This is a synchronous, simplified wrapper around the standard 102 * asynchronous API. */ 103 104 /** \example pacat-simple.c 105 * A simple playback tool using the simple API */ 106 107 /** \example parec-simple.c 108 * A simple recording tool using the simple API */ 109 110 PA_C_DECL_BEGIN 111 112 /** \struct pa_simple 113 * An opaque simple connection object */ 114 typedef struct pa_simple pa_simple; 115 116 /** Create a new connection to the server */ 117 pa_simple* pa_simple_new( 118 const char *server, /**< Server name, or NULL for default */ 119 const char *name, /**< A descriptive name for this client (application name, ...) */ 120 pa_stream_direction_t dir, /**< Open this stream for recording or playback? */ 121 const char *dev, /**< Sink (resp. source) name, or NULL for default */ 122 const char *stream_name, /**< A descriptive name for this client (application name, song title, ...) */ 123 const pa_sample_spec *ss, /**< The sample type to use */ 124 const pa_channel_map *map, /**< The channel map to use, or NULL for default */ 125 const pa_buffer_attr *attr, /**< Buffering attributes, or NULL for default */ 126 int *error /**< A pointer where the error code is stored when the routine returns NULL. It is OK to pass NULL here. */ 127 ); 128 129 /** Close and free the connection to the server. The connection objects becomes invalid when this is called. */ 130 void pa_simple_free(pa_simple *s); 131 132 /** Write some data to the server */ 133 int pa_simple_write(pa_simple *s, const void*data, size_t bytes, int *error); 134 135 /** Wait until all data already written is played by the daemon */ 136 int pa_simple_drain(pa_simple *s, int *error); 137 138 /** Read some data from the server */ 139 int pa_simple_read(pa_simple *s, void*data, size_t bytes, int *error); 140 141 /** Return the playback latency. \since 0.5 */ 142 pa_usec_t pa_simple_get_latency(pa_simple *s, int *error); 143 144 /** Flush the playback buffer. \since 0.5 */ 145 int pa_simple_flush(pa_simple *s, int *error); 146 147 PA_C_DECL_END 148 149 #endif 150
