Home | History | Annotate | Download | only in pulse
      1 #ifndef foocontexthfoo
      2 #define foocontexthfoo
      3 
      4 /* $Id: context.h 1426 2007-02-13 15:35:19Z ossman $ */
      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 <pulse/sample.h>
     29 #include <pulse/def.h>
     30 #include <pulse/mainloop-api.h>
     31 #include <pulse/cdecl.h>
     32 #include <pulse/operation.h>
     33 
     34 /** \page async Asynchronous API
     35  *
     36  * \section overv_sec Overview
     37  *
     38  * The asynchronous API is the native interface to the PulseAudio library.
     39  * It allows full access to all available functions. This also means that
     40  * it is rather complex and can take some time to fully master.
     41  *
     42  * \section mainloop_sec Main Loop Abstraction
     43  *
     44  * The API is based around an asynchronous event loop, or main loop,
     45  * abstraction. This abstraction contains three basic elements:
     46  *
     47  * \li Deferred events - Events that will trigger as soon as possible. Note
     48  *                       that some implementations may block all other events
     49  *                       when a deferred event is active.
     50  * \li I/O events - Events that trigger on file descriptor activities.
     51  * \li Times events - Events that trigger after a fixed ammount of time.
     52  *
     53  * The abstraction is represented as a number of function pointers in the
     54  * pa_mainloop_api structure.
     55  *
     56  * To actually be able to use these functions, an implementation needs to
     57  * be coupled to the abstraction. There are three of these shipped with
     58  * PulseAudio, but any other can be used with a minimal ammount of work,
     59  * provided it supports the three basic events listed above.
     60  *
     61  * The implementations shipped with PulseAudio are:
     62  *
     63  * \li \subpage mainloop - A minimal but fast implementation based on poll().
     64  * \li \subpage threaded_mainloop - A special version of the previous
     65  *                                  implementation where all of PulseAudio's
     66  *                                  internal handling runs in a separate
     67  *                                  thread.
     68  * \li \subpage glib-mainloop - A wrapper around GLIB's main loop. Available
     69  *                              for both GLIB 1.2 and GLIB 2.x.
     70  *
     71  * UNIX signals may be hooked to a main loop using the functions from
     72  * \ref mainloop-signal.h. These rely only on the main loop abstraction
     73  * and can therefore be used with any of the implementations.
     74  *
     75  * \section refcnt_sec Reference Counting
     76  *
     77  * Almost all objects in PulseAudio are reference counted. What that means
     78  * is that you rarely malloc() or free() any objects. Instead you increase
     79  * and decrease their reference counts. Whenever an object's reference
     80  * count reaches zero, that object gets destroy and any resources it uses
     81  * get freed.
     82  *
     83  * The benefit of this design is that an application need not worry about
     84  * whether or not it needs to keep an object around in case the library is
     85  * using it internally. If it is, then it has made sure it has its own
     86  * reference to it.
     87  *
     88  * Whenever the library creates an object, it will have an initial
     89  * reference count of one. Most of the time, this single reference will be
     90  * sufficient for the application, so all required reference count
     91  * interaction will be a single call to the objects unref function.
     92  *
     93  * \section context_sec Context
     94  *
     95  * A context is the basic object for a connection to a PulseAudio server.
     96  * It multiplexes commands, data streams and events through a single
     97  * channel.
     98  *
     99  * There is no need for more than one context per application, unless
    100  * connections to multiple servers are needed.
    101  *
    102  * \subsection ops_subsec Operations
    103  *
    104  * All operations on the context are performed asynchronously. I.e. the
    105  * client will not wait for the server to complete the request. To keep
    106  * track of all these in-flight operations, the application is given a
    107  * pa_operation object for each asynchronous operation.
    108  *
    109  * There are only two actions (besides reference counting) that can be
    110  * performed on a pa_operation: querying its state with
    111  * pa_operation_get_state() and aborting it with pa_operation_cancel().
    112  *
    113  * A pa_operation object is reference counted, so an application must
    114  * make sure to unreference it, even if it has no intention of using it.
    115  *
    116  * \subsection conn_subsec Connecting
    117  *
    118  * A context must be connected to a server before any operation can be
    119  * issued. Calling pa_context_connect() will initiate the connection
    120  * procedure. Unlike most asynchronous operations, connecting does not
    121  * result in a pa_operation object. Instead, the application should
    122  * register a callback using pa_context_set_state_callback().
    123  *
    124  * \subsection disc_subsec Disconnecting
    125  *
    126  * When the sound support is no longer needed, the connection needs to be
    127  * closed using pa_context_disconnect(). This is an immediate function that
    128  * works synchronously.
    129  *
    130  * Since the context object has references to other objects it must be
    131  * disconnected after use or there is a high risk of memory leaks. If the
    132  * connection has terminated by itself, then there is no need to explicitly
    133  * disconnect the context using pa_context_disconnect().
    134  *
    135  * \section Functions
    136  *
    137  * The sound server's functionality can be divided into a number of
    138  * subsections:
    139  *
    140  * \li \subpage streams
    141  * \li \subpage scache
    142  * \li \subpage introspect
    143  * \li \subpage subscribe
    144  */
    145 
    146 /** \file
    147  * Connection contexts for asynchrononous communication with a
    148  * server. A pa_context object wraps a connection to a PulseAudio
    149  * server using its native protocol. */
    150 
    151 /** \example pacat.c
    152  * A playback and recording tool using the asynchronous API */
    153 
    154 /** \example paplay.c
    155  * A sound file playback tool using the asynchronous API, based on libsndfile */
    156 
    157 PA_C_DECL_BEGIN
    158 
    159 /** An opaque connection context to a daemon */
    160 typedef struct pa_context pa_context;
    161 
    162 /** Generic notification callback prototype */
    163 typedef void (*pa_context_notify_cb_t)(pa_context *c, void *userdata);
    164 
    165 /** A generic callback for operation completion */
    166 typedef void (*pa_context_success_cb_t) (pa_context *c, int success, void *userdata);
    167 
    168 /** Instantiate a new connection context with an abstract mainloop API
    169  * and an application name */
    170 pa_context *pa_context_new(pa_mainloop_api *mainloop, const char *name);
    171 
    172 /** Decrease the reference counter of the context by one */
    173 void pa_context_unref(pa_context *c);
    174 
    175 /** Increase the reference counter of the context by one */
    176 pa_context* pa_context_ref(pa_context *c);
    177 
    178 /** Set a callback function that is called whenever the context status changes */
    179 void pa_context_set_state_callback(pa_context *c, pa_context_notify_cb_t cb, void *userdata);
    180 
    181 /** Return the error number of the last failed operation */
    182 int pa_context_errno(pa_context *c);
    183 
    184 /** Return non-zero if some data is pending to be written to the connection */
    185 int pa_context_is_pending(pa_context *c);
    186 
    187 /** Return the current context status */
    188 pa_context_state_t pa_context_get_state(pa_context *c);
    189 
    190 /** Connect the context to the specified server. If server is NULL,
    191 connect to the default server. This routine may but will not always
    192 return synchronously on error. Use pa_context_set_state_callback() to
    193 be notified when the connection is established. If flags doesn't have
    194 PA_NOAUTOSPAWN set and no specific server is specified or accessible a
    195 new daemon is spawned. If api is non-NULL, the functions specified in
    196 the structure are used when forking a new child process. */
    197 int pa_context_connect(pa_context *c, const char *server, pa_context_flags_t flags, const pa_spawn_api *api);
    198 
    199 /** Terminate the context connection immediately */
    200 void pa_context_disconnect(pa_context *c);
    201 
    202 /** Drain the context. If there is nothing to drain, the function returns NULL */
    203 pa_operation* pa_context_drain(pa_context *c, pa_context_notify_cb_t cb, void *userdata);
    204 
    205 /** Tell the daemon to exit. The returned operation is unlikely to
    206  * complete succesfully, since the daemon probably died before
    207  * returning a success notification */
    208 pa_operation* pa_context_exit_daemon(pa_context *c, pa_context_success_cb_t cb, void *userdata);
    209 
    210 /** Set the name of the default sink. \since 0.4 */
    211 pa_operation* pa_context_set_default_sink(pa_context *c, const char *name, pa_context_success_cb_t cb, void *userdata);
    212 
    213 /** Set the name of the default source. \since 0.4 */
    214 pa_operation* pa_context_set_default_source(pa_context *c, const char *name, pa_context_success_cb_t cb, void *userdata);
    215 
    216 /** Returns 1 when the connection is to a local daemon. Returns negative when no connection has been made yet. \since 0.5 */
    217 int pa_context_is_local(pa_context *c);
    218 
    219 /** Set a different application name for context on the server. \since 0.5 */
    220 pa_operation* pa_context_set_name(pa_context *c, const char *name, pa_context_success_cb_t cb, void *userdata);
    221 
    222 /** Return the server name this context is connected to. \since 0.7 */
    223 const char* pa_context_get_server(pa_context *c);
    224 
    225 /** Return the protocol version of the library. \since 0.8 */
    226 uint32_t pa_context_get_protocol_version(pa_context *c);
    227 
    228 /** Return the protocol version of the connected server. \since 0.8 */
    229 uint32_t pa_context_get_server_protocol_version(pa_context *c);
    230 
    231 PA_C_DECL_END
    232 
    233 #endif
    234