code.delx.au - pulseaudio/blob - src/polyp/stream.h

   1 #ifndef foostreamhfoo
   2 #define foostreamhfoo
   3
   4 /* $Id$ */
   5
   6 /***
   7   This file is part of polypaudio.
   8
   9   polypaudio is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU Lesser General Public License as published
  11   by the Free Software Foundation; either version 2 of the License,
  12   or (at your option) any later version.
  13
  14   polypaudio is distributed in the hope that it will be useful, but
  15   WITHOUT ANY WARRANTY; without even the implied warranty of
  16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  17   General Public License for more details.
  18
  19   You should have received a copy of the GNU Lesser General Public License
  20   along with polypaudio; if not, write to the Free Software
  21   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  22   USA.
  23 ***/
  24
  25 #include <sys/types.h>
  26
  27 #include <polyp/sample.h>
  28 #include <polyp/channelmap.h>
  29 #include <polyp/volume.h>
  30 #include <polyp/def.h>
  31 #include <polyp/cdecl.h>
  32 #include <polyp/operation.h>
  33
  34 /** \file
  35  * Audio streams for input, output and sample upload */
  36
  37 PA_C_DECL_BEGIN
  38
  39 /** \struct pa_stream
  40  * An opaque stream for playback or recording */
  41 typedef struct pa_stream pa_stream;
  42
  43 /** Create a new, unconnected stream with the specified name and sample type */
  44 pa_stream* pa_stream_new(pa_context *c, const char *name, const pa_sample_spec *ss, const pa_channel_map *map);
  45
  46 /** Decrease the reference counter by one */
  47 void pa_stream_unref(pa_stream *s);
  48
  49 /** Increase the reference counter by one */
  50 pa_stream *pa_stream_ref(pa_stream *s);
  51
  52 /** Return the current state of the stream */
  53 pa_stream_state_t pa_stream_get_state(pa_stream *p);
  54
  55 /** Return the context this stream is attached to */
  56 pa_context* pa_stream_get_context(pa_stream *p);
  57
  58 /** Return the device (sink input or source output) index this stream is connected to */
  59 uint32_t pa_stream_get_index(pa_stream *s);
  60
  61 /** Connect the stream to a sink */
  62 void pa_stream_connect_playback(
  63     pa_stream *s,
  64     const char *dev,
  65     const pa_buffer_attr *attr,
  66     pa_stream_flags_t flags,
  67     pa_cvolume *volume);
  68
  69 /** Connect the stream to a source */
  70 void pa_stream_connect_record(
  71     pa_stream *s,
  72     const char *dev,
  73     const pa_buffer_attr *attr,
  74     pa_stream_flags_t flags);
  75
  76 /** Disconnect a stream from a source/sink */
  77 void pa_stream_disconnect(pa_stream *s);
  78
  79 /** Write some data to the server (for playback sinks), if free_cb is
  80  * non-NULL this routine is called when all data has been written out
  81  * and an internal reference to the specified data is kept, the data
  82  * is not copied. If NULL, the data is copied into an internal
  83  * buffer. */
  84 void pa_stream_write(pa_stream *p      /**< The stream to use */,
  85                      const void *data         /**< The data to write */,
  86                      size_t length            /**< The length of the data to write */,
  87                      void (*free_cb)(void *p) /**< A cleanup routine for the data or NULL to request an internal copy */,
  88                      size_t delta             /**< Drop this many
  89                                                  bytes in the playback
  90                                                  buffer before writing
  91                                                  this data. Use
  92                                                  (size_t) -1 for
  93                                                  clearing the whole
  94                                                  playback
  95                                                  buffer. Normally you
  96                                                  will specify 0 here,
  97                                                  i.e. append to the
  98                                                  playback buffer. If
  99                                                  the value given here
 100                                                  is greater than the
 101                                                  buffered data length
 102                                                  the buffer is cleared
 103                                                  and the data is
 104                                                  written to the
 105                                                  buffer's start. This
 106                                                  value is ignored on
 107                                                  upload streams. */);
 108
 109 /** Read the next fragment from the buffer (for capture sources).
 110  * data will point to the actual data and length will contain the size
 111  * of the data in bytes (which can be less than a complete framgnet).
 112  * Use pa_stream_drop() to actually remove the data from the buffer.
 113  * \since 0.8 */
 114 void pa_stream_peek(pa_stream *p                 /**< The stream to use */,
 115                      void **data                 /**< Pointer to pointer that will point to data */,
 116                      size_t *length              /**< The length of the data read */);
 117
 118 /** Remove the current fragment. It is invalid to do this without first
 119  * calling pa_stream_peek(). \since 0.8 */
 120 void pa_stream_drop(pa_stream *p);
 121
 122 /** Return the amount of bytes that may be written using pa_stream_write() */
 123 size_t pa_stream_writable_size(pa_stream *p);
 124
 125 /** Return the ammount of bytes that may be read using pa_stream_read() \since 0.8 */
 126 size_t pa_stream_readable_size(pa_stream *p);
 127
 128 /** Drain a playback stream */
 129 pa_operation* pa_stream_drain(pa_stream *s, void (*cb) (pa_stream*s, int success, void *userdata), void *userdata);
 130
 131 /** Get the playback latency of a stream */
 132 pa_operation* pa_stream_get_latency_info(pa_stream *p, void (*cb)(pa_stream *p, const pa_latency_info *i, void *userdata), void *userdata);
 133
 134 /** Set the callback function that is called whenever the state of the stream changes */
 135 void pa_stream_set_state_callback(pa_stream *s, void (*cb)(pa_stream *s, void *userdata), void *userdata);
 136
 137 /** Set the callback function that is called when new data may be
 138  * written to the stream. */
 139 void pa_stream_set_write_callback(pa_stream *p, void (*cb)(pa_stream *p, size_t length, void *userdata), void *userdata);
 140
 141 /** Set the callback function that is called when new data is available from the stream.
 142  * Return the number of bytes read. \since 0.8
 143  */
 144 void pa_stream_set_read_callback(pa_stream *p, void (*cb)(pa_stream *p, size_t length, void *userdata), void *userdata);
 145
 146 /** Pause (or resume) playback of this stream temporarily. Available on both playback and recording streams. \since 0.3 */
 147 pa_operation* pa_stream_cork(pa_stream *s, int b, void (*cb) (pa_stream*s, int success, void *userdata), void *userdata);
 148
 149 /** Flush the playback buffer of this stream. Most of the time you're
 150  * better off using the parameter delta of pa_stream_write() instead of this
 151  * function. Available on both playback and recording streams. \since 0.3 */
 152 pa_operation* pa_stream_flush(pa_stream *s, void (*cb)(pa_stream *s, int success, void *userdata), void *userdata);
 153
 154 /** Reenable prebuffering. Available for playback streams only. \since 0.6 */
 155 pa_operation* pa_stream_prebuf(pa_stream *s, void (*cb)(pa_stream *s, int success, void *userdata), void *userdata);
 156
 157 /** Request immediate start of playback on this stream. This disables
 158  * prebuffering as specified in the pa_buffer_attr structure. Available for playback streams only. \since
 159  * 0.3 */
 160 pa_operation* pa_stream_trigger(pa_stream *s, void (*cb)(pa_stream *s, int success, void *userdata), void *userdata);
 161
 162 /** Rename the stream. \since 0.5 */
 163 pa_operation* pa_stream_set_name(pa_stream *s, const char *name, void(*cb)(pa_stream*c, int success,  void *userdata), void *userdata);
 164
 165 /** Return the total number of bytes written to/read from the
 166  * stream. This counter is not reset on pa_stream_flush(), you may do
 167  * this yourself using pa_stream_reset_counter(). \since 0.6 */
 168 uint64_t pa_stream_get_counter(pa_stream *s);
 169
 170 /** Return the current playback/recording time. This is based on the
 171  * counter accessible with pa_stream_get_counter(). This function
 172  * requires a pa_latency_info structure as argument, which should be
 173  * acquired using pa_stream_get_latency(). \since 0.6 */
 174 pa_usec_t pa_stream_get_time(pa_stream *s, const pa_latency_info *i);
 175
 176 /** Return the total stream latency. Thus function requires a
 177  * pa_latency_info structure as argument, which should be aquired
 178  * using pa_stream_get_latency(). In case the stream is a monitoring
 179  * stream the result can be negative, i.e. the captured samples are
 180  * not yet played. In this case *negative is set to 1. \since 0.6 */
 181 pa_usec_t pa_stream_get_latency(pa_stream *s, const pa_latency_info *i, int *negative);
 182
 183 /** Return the interpolated playback/recording time. Requires the
 184  *  PA_STREAM_INTERPOLATE_LATENCY bit set when creating the stream. In
 185  *  contrast to pa_stream_get_latency() this function doesn't require
 186  *  a whole roundtrip for response. \since 0.6 */
 187 pa_usec_t pa_stream_get_interpolated_time(pa_stream *s);
 188
 189 /** Return the interpolated playback/recording latency. Requires the
 190  * PA_STREAM_INTERPOLATE_LATENCY bit set when creating the
 191  * stream. \since 0.6 */
 192 pa_usec_t pa_stream_get_interpolated_latency(pa_stream *s, int *negative);
 193
 194 /** Return a pointer to the streams sample specification. \since 0.6 */
 195 const pa_sample_spec* pa_stream_get_sample_spec(pa_stream *s);
 196
 197 PA_C_DECL_END
 198
 199 #endif