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

   1 #ifndef foopolyplibstreamhfoo
   2 #define foopolyplibstreamhfoo
   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 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 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 "sample.h"
  28 #include "polyplib-def.h"
  29 #include "cdecl.h"
  30 #include "polyplib-operation.h"
  31
  32 /** \file
  33  * Audio streams for input, output and sample upload */
  34
  35 PA_C_DECL_BEGIN
  36
  37 /** \struct pa_stream
  38  * An opaque stream for playback or recording */
  39 struct pa_stream;
  40
  41 /** Create a new, unconnected stream with the specified name and sample type */
  42 struct pa_stream* pa_stream_new(struct pa_context *c, const char *name, const struct pa_sample_spec *ss);
  43
  44 /** Decrease the reference counter by one */
  45 void pa_stream_unref(struct pa_stream *s);
  46
  47 /** Increase the reference counter by one */
  48 struct pa_stream *pa_stream_ref(struct pa_stream *s);
  49
  50 /** Return the current state of the stream */
  51 enum pa_stream_state pa_stream_get_state(struct pa_stream *p);
  52
  53 /** Return the context this stream is attached to */
  54 struct pa_context* pa_stream_get_context(struct pa_stream *p);
  55
  56 /** Return the device (sink input or source output) index this stream is connected to */
  57 uint32_t pa_stream_get_index(struct pa_stream *s);
  58
  59 /** Connect the stream to a sink */
  60 void pa_stream_connect_playback(struct pa_stream *s, const char *dev, const struct pa_buffer_attr *attr, enum pa_stream_flags flags, pa_volume_t volume);
  61
  62 /** Connect the stream to a source */
  63 void pa_stream_connect_record(struct pa_stream *s, const char *dev, const struct pa_buffer_attr *attr, enum pa_stream_flags flags);
  64
  65 /** Disconnect a stream from a source/sink */
  66 void pa_stream_disconnect(struct pa_stream *s);
  67
  68 /** Write some data to the server (for playback sinks), if free_cb is
  69  * non-NULL this routine is called when all data has been written out
  70  * and an internal reference to the specified data is kept, the data
  71  * is not copied. If NULL, the data is copied into an internal
  72  * buffer. */
  73 void pa_stream_write(struct pa_stream *p      /**< The stream to use */,
  74                      const void *data         /**< The data to write */,
  75                      size_t length            /**< The length of the data to write */,
  76                      void (*free_cb)(void *p) /**< A cleanup routine for the data or NULL to request an internal copy */,
  77                      size_t delta             /**< Drop this many
  78                                                  bytes in the playback
  79                                                  buffer before writing
  80                                                  this data. Use
  81                                                  (size_t) -1 for
  82                                                  clearing the whole
  83                                                  playback
  84                                                  buffer. Normally you
  85                                                  will specify 0 here,
  86                                                  i.e. append to the
  87                                                  playback buffer. If
  88                                                  the value given here
  89                                                  is greater than the
  90                                                  buffered data length
  91                                                  the buffer is cleared
  92                                                  and the data is
  93                                                  written to the
  94                                                  buffer's start. This
  95                                                  value is ignored on
  96                                                  upload streams. */);
  97
  98 /** Return the amount of bytes that may be written using pa_stream_write() */
  99 size_t pa_stream_writable_size(struct pa_stream *p);
 100
 101 /** Drain a playback stream */
 102 struct pa_operation* pa_stream_drain(struct pa_stream *s, void (*cb) (struct pa_stream*s, int success, void *userdata), void *userdata);
 103
 104 /** Get the playback latency of a stream */
 105 struct pa_operation* pa_stream_get_latency_info(struct pa_stream *p, void (*cb)(struct pa_stream *p, const struct pa_latency_info *i, void *userdata), void *userdata);
 106
 107 /** Set the callback function that is called whenever the state of the stream changes */
 108 void pa_stream_set_state_callback(struct pa_stream *s, void (*cb)(struct pa_stream *s, void *userdata), void *userdata);
 109
 110 /** Set the callback function that is called when new data may be
 111  * written to the stream. */
 112 void pa_stream_set_write_callback(struct pa_stream *p, void (*cb)(struct pa_stream *p, size_t length, void *userdata), void *userdata);
 113
 114 /** Set the callback function that is called when new data is available from the stream */
 115 void pa_stream_set_read_callback(struct pa_stream *p, void (*cb)(struct pa_stream *p, const void*data, size_t length, void *userdata), void *userdata);
 116
 117 /** Pause (or resume) playback of this stream temporarily. Available on both playback and recording streams. \since 0.3 */
 118 struct pa_operation* pa_stream_cork(struct pa_stream *s, int b, void (*cb) (struct pa_stream*s, int success, void *userdata), void *userdata);
 119
 120 /** Flush the playback buffer of this stream. Most of the time you're
 121  * better off using the parameter delta of pa_stream_write() instead of this
 122  * function. Available on both playback and recording streams. \since 0.3 */
 123 struct pa_operation* pa_stream_flush(struct pa_stream *s, void (*cb)(struct pa_stream *s, int success, void *userdata), void *userdata);
 124
 125 /** Reenable prebuffering. Available for playback streams only. \since 0.6 */
 126 struct pa_operation* pa_stream_prebuf(struct pa_stream *s, void (*cb)(struct pa_stream *s, int success, void *userdata), void *userdata);
 127
 128 /** Request immediate start of playback on this stream. This disables
 129  * prebuffering as specified in the pa_buffer_attr structure. Available for playback streams only. \since
 130  * 0.3 */
 131 struct pa_operation* pa_stream_trigger(struct pa_stream *s, void (*cb)(struct pa_stream *s, int success, void *userdata), void *userdata);
 132
 133 /** Rename the stream. \since 0.5 */
 134 struct pa_operation* pa_stream_set_name(struct pa_stream *s, const char *name, void(*cb)(struct pa_stream*c, int success,  void *userdata), void *userdata);
 135
 136 /** Return the total number of bytes written to/read from the
 137  * stream. This counter is not reset on pa_stream_flush(), you may do
 138  * this yourself using pa_stream_reset_counter(). \since 0.6 */
 139 uint64_t pa_stream_get_counter(struct pa_stream *s);
 140
 141 /** Return the current playback/recording time. This is based on the
 142  * counter accessible with pa_stream_get_counter(). This function
 143  * requires a pa_latency_info structure as argument, which should be
 144  * acquired using pa_stream_get_latency(). \since 0.6 */
 145 pa_usec_t pa_stream_get_time(struct pa_stream *s, const struct pa_latency_info *i);
 146
 147 /** Return the total stream latency. Thus function requires a
 148  * pa_latency_info structure as argument, which should be aquired
 149  * using pa_stream_get_latency(). In case the stream is a monitoring
 150  * stream the result can be negative, i.e. the captured samples are
 151  * not yet played. In this case *negative is set to 1. \since 0.6 */
 152 pa_usec_t pa_stream_get_latency(struct pa_stream *s, const struct pa_latency_info *i, int *negative);
 153
 154 /** Return the interpolated playback/recording time. Requires the
 155  *  PA_STREAM_INTERPOLATE_LATENCY bit set when creating the stream. In
 156  *  contrast to pa_stream_get_latency() this function doesn't require
 157  *  a whole roundtrip for response. \since 0.6 */
 158 pa_usec_t pa_stream_get_interpolated_time(struct pa_stream *s);
 159
 160 /** Return the interpolated playback/recording latency. Requires the
 161  * PA_STREAM_INTERPOLATE_LATENCY bit set when creating the
 162  * stream. \since 0.6 */
 163 pa_usec_t pa_stream_get_interpolated_latency(struct pa_stream *s, int *negative);
 164
 165 /** Return a pointer to the streams sample specification. \since 0.6 */
 166 const struct pa_sample_spec* pa_stream_get_sample_spec(struct pa_stream *s);
 167
 168 PA_C_DECL_END
 169
 170 #endif