source: roaraudio/libroarpulse/stream.c @ 3424:be95fb35f8ec

Last change on this file since 3424:be95fb35f8ec was 3424:be95fb35f8ec, checked in by phi, 14 years ago

prototyoes

File size: 11.0 KB
Line 
1//stream.c:
2
3/*
4 *      Copyright (C) Philipp 'ph3-der-loewe' Schafft - 2010
5 *  The code (may) include prototypes and comments (and maybe
6 *  other code fragements) from libpulse*. They are mostly copyrighted by:
7 *  Lennart Poettering <poettering@users.sourceforge.net> and
8 *  Pierre Ossman <drzeus@drzeus.cx>
9 *
10 *  This file is part of libroarpulse a part of RoarAudio,
11 *  a cross-platform sound system for both, home and professional use.
12 *  See README for details.
13 *
14 *  This file is free software; you can redistribute it and/or modify
15 *  it under the terms of the GNU General Public License version 3
16 *  as published by the Free Software Foundation.
17 *
18 *  RoarAudio is distributed in the hope that it will be useful,
19 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
20 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21 *  GNU General Public License for more details.
22 *
23 *  You should have received a copy of the GNU General Public License
24 *  along with this software; see the file COPYING.  If not, write to
25 *  the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
26 *
27 *  NOTE for everyone want's to change something and send patches:
28 *  read README and HACKING! There a addition information on
29 *  the license of this document you need to read before you send
30 *  any patches.
31 *
32 *  NOTE for uses of non-GPL (LGPL,...) software using libesd, libartsc
33 *  or libpulse*:
34 *  The libs libroaresd, libroararts and libroarpulse link this libroar
35 *  and are therefore GPL. Because of this it may be illigal to use
36 *  them with any software that uses libesd, libartsc or libpulse*.
37 */
38
39#include <libroarpulse/libroarpulse.h>
40
41/** Create a new, unconnected stream with the specified name and sample type */
42pa_stream* pa_stream_new(
43        pa_context *c                     /**< The context to create this stream in */,
44        const char *name                  /**< A name for this stream */,
45        const pa_sample_spec *ss          /**< The desired sample format */,
46        const pa_channel_map *map         /**< The desired channel map, or NULL for default */);
47
48/** Decrease the reference counter by one */
49void pa_stream_unref(pa_stream *s);
50
51/** Increase the reference counter by one */
52pa_stream *pa_stream_ref(pa_stream *s);
53
54/** Return the current state of the stream */
55pa_stream_state_t pa_stream_get_state(pa_stream *p);
56
57/** Return the context this stream is attached to */
58pa_context* pa_stream_get_context(pa_stream *p);
59
60/** Return the device (sink input or source output) index this stream is connected to */
61uint32_t pa_stream_get_index(pa_stream *s);
62
63/** Connect the stream to a sink */
64int pa_stream_connect_playback(
65        pa_stream *s                  /**< The stream to connect to a sink */,
66        const char *dev               /**< Name of the sink to connect to, or NULL for default */ ,
67        const pa_buffer_attr *attr    /**< Buffering attributes, or NULL for default */,
68        pa_stream_flags_t flags       /**< Additional flags, or 0 for default */,
69        pa_cvolume *volume            /**< Initial volume, or NULL for default */,
70        pa_stream *sync_stream        /**< Synchronize this stream with the specified one, or NULL for a standalone stream*/);
71
72/** Connect the stream to a source */
73int pa_stream_connect_record(
74        pa_stream *s                  /**< The stream to connect to a source */ ,
75        const char *dev               /**< Name of the source to connect to, or NULL for default */,
76        const pa_buffer_attr *attr    /**< Buffer attributes, or NULL for default */,
77        pa_stream_flags_t flags       /**< Additional flags, or 0 for default */);
78
79/** Disconnect a stream from a source/sink */
80int pa_stream_disconnect(pa_stream *s);
81
82/** Write some data to the server (for playback sinks), if free_cb is
83 * non-NULL this routine is called when all data has been written out
84 * and an internal reference to the specified data is kept, the data
85 * is not copied. If NULL, the data is copied into an internal
86 * buffer. The client my freely seek around in the output buffer. For
87 * most applications passing 0 and PA_SEEK_RELATIVE as arguments for
88 * offset and seek should be useful.*/
89int pa_stream_write(
90        pa_stream *p             /**< The stream to use */,
91        const void *data         /**< The data to write */,
92        size_t length            /**< The length of the data to write */,
93        pa_free_cb_t free_cb     /**< A cleanup routine for the data or NULL to request an internal copy */,
94        int64_t offset,          /**< Offset for seeking, must be 0 for upload streams */
95        pa_seek_mode_t seek      /**< Seek mode, must be PA_SEEK_RELATIVE for upload streams */);
96
97/** Read the next fragment from the buffer (for recording).
98 * data will point to the actual data and length will contain the size
99 * of the data in bytes (which can be less than a complete framgnet).
100 * Use pa_stream_drop() to actually remove the data from the
101 * buffer. If no data is available will return a NULL pointer  \since 0.8 */
102int pa_stream_peek(
103        pa_stream *p                 /**< The stream to use */,
104        const void **data            /**< Pointer to pointer that will point to data */,
105        size_t *length              /**< The length of the data read */);
106
107/** Remove the current fragment on record streams. It is invalid to do this without first
108 * calling pa_stream_peek(). \since 0.8 */
109int pa_stream_drop(pa_stream *p);
110
111/** Return the nember of bytes that may be written using pa_stream_write() */
112size_t pa_stream_writable_size(pa_stream *p);
113
114/** Return the number of bytes that may be read using pa_stream_read() \since 0.8 */
115size_t pa_stream_readable_size(pa_stream *p);
116
117/** Drain a playback stream. Use this for notification when the buffer is empty */
118pa_operation* pa_stream_drain(pa_stream *s, pa_stream_success_cb_t cb, void *userdata);
119
120/** Request a timing info structure update for a stream. Use
121 * pa_stream_get_timing_info() to get access to the raw timing data,
122 * or pa_stream_get_time() or pa_stream_get_latency() to get cleaned
123 * up values. */
124pa_operation* pa_stream_update_timing_info(pa_stream *p, pa_stream_success_cb_t cb, void *userdata);
125
126/** Set the callback function that is called whenever the state of the stream changes */
127void pa_stream_set_state_callback(pa_stream *s, pa_stream_notify_cb_t cb, void *userdata);
128
129/** Set the callback function that is called when new data may be
130 * written to the stream. */
131void pa_stream_set_write_callback(pa_stream *p, pa_stream_request_cb_t cb, void *userdata);
132
133/** Set the callback function that is called when new data is available from the stream.
134 * Return the number of bytes read. \since 0.8 */
135void pa_stream_set_read_callback(pa_stream *p, pa_stream_request_cb_t cb, void *userdata);
136
137/** Set the callback function that is called when a buffer overflow happens. (Only for playback streams) \since 0.8 */
138void pa_stream_set_overflow_callback(pa_stream *p, pa_stream_notify_cb_t cb, void *userdata);
139
140/** Set the callback function that is called when a buffer underflow happens. (Only for playback streams) \since 0.8 */
141void pa_stream_set_underflow_callback(pa_stream *p, pa_stream_notify_cb_t cb, void *userdata);
142
143/** Set the callback function that is called whenever a latency information update happens. Useful on PA_STREAM_AUTO_TIMING_UPDATE streams only. (Only for playback streams) \since 0.8.2 */
144void pa_stream_set_latency_update_callback(pa_stream *p, pa_stream_notify_cb_t cb, void *userdata);
145
146/** Pause (or resume) playback of this stream temporarily. Available on both playback and recording streams. \since 0.3 */
147pa_operation* pa_stream_cork(pa_stream *s, int b, pa_stream_success_cb_t cb, 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 */
152pa_operation* pa_stream_flush(pa_stream *s, pa_stream_success_cb_t cb, void *userdata);
153/** Reenable prebuffering as specified in the pa_buffer_attr
154 * structure. Available for playback streams only. \since 0.6 */
155pa_operation* pa_stream_prebuf(pa_stream *s, pa_stream_success_cb_t cb, void *userdata);
156
157/** Request immediate start of playback on this stream. This disables
158 * prebuffering as specified in the pa_buffer_attr
159 * structure, temporarily. Available for playback streams only. \since 0.3 */
160pa_operation* pa_stream_trigger(pa_stream *s, pa_stream_success_cb_t cb, void *userdata);
161
162/** Rename the stream. \since 0.5 */
163pa_operation* pa_stream_set_name(pa_stream *s, const char *name, pa_stream_success_cb_t cb, void *userdata);
164
165/** Return the current playback/recording time. This is based on the
166 * data in the timing info structure returned by
167 * pa_stream_get_timing_info(). This function will usually only return
168 * new data if a timing info update has been recieved. Only if timing
169 * interpolation has been requested (PA_STREAM_INTERPOLATE_TIMING)
170 * the data from the last timing update is used for an estimation of
171 * the current playback/recording time based on the local time that
172 * passed since the timing info structure has been acquired. The time
173 * value returned by this function is guaranteed to increase
174 * monotonically. (that means: the returned value is always greater or
175 * equal to the value returned on the last call) This behaviour can
176 * be disabled by using PA_STREAM_NOT_MONOTONOUS. This may be
177 * desirable to deal better with bad estimations of transport
178 * latencies, but may have strange effects if the application is not
179 * able to deal with time going 'backwards'. \since 0.6 */
180int pa_stream_get_time(pa_stream *s, pa_usec_t *r_usec);
181
182/** Return the total stream latency. This function is based on
183 * pa_stream_get_time(). In case the stream is a monitoring stream the
184 * result can be negative, i.e. the captured samples are not yet
185 * played. In this case *negative is set to 1. \since 0.6 */
186int pa_stream_get_latency(pa_stream *s, pa_usec_t *r_usec, int *negative);
187
188/** Return the latest raw timing data structure. The returned pointer
189 * points to an internal read-only instance of the timing
190 * structure. The user should make a copy of this structure if he
191 * wants to modify it. An in-place update to this data structure may
192 * be requested using pa_stream_update_timing_info(). If no
193 * pa_stream_update_timing_info() call was issued before, this
194 * function will fail with PA_ERR_NODATA. Please note that the
195 * write_index member field (and only this field) is updated on each
196 * pa_stream_write() call, not just when a timing update has been
197 * recieved. \since 0.8 */
198const pa_timing_info* pa_stream_get_timing_info(pa_stream *s);
199
200/** Return a pointer to the stream's sample specification. \since 0.6 */
201const pa_sample_spec* pa_stream_get_sample_spec(pa_stream *s);
202
203/** Return a pointer to the stream's channel map. \since 0.8 */
204const pa_channel_map* pa_stream_get_channel_map(pa_stream *s);
205
206/** Return the buffer metrics of the stream. Only valid after the
207 * stream has been connected successfuly and if the server is at least
208 * PulseAudio 0.9. \since 0.9.0 */
209const pa_buffer_attr* pa_stream_get_buffer_attr(pa_stream *s);
210
211//ll
Note: See TracBrowser for help on using the repository browser.