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

   1 #ifndef foocontexthfoo
   2 #define foocontexthfoo
   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 <polyp/sample.h>
  26 #include <polyp/def.h>
  27 #include <polyp/mainloop-api.h>
  28 #include <polyp/cdecl.h>
  29 #include <polyp/operation.h>
  30
  31 /** \file
  32  * Connection contexts for asynchrononous communication with a
  33  * server. A pa_context object wraps a connection to a polypaudio
  34  * server using its native protocol. A context may be used to issue
  35  * commands on the server or to create playback or recording
  36  * streams. Multiple playback streams may be piped through a single
  37  * connection context. Operations on the contect involving
  38  * communication with the server are executed asynchronously: i.e. the
  39  * client function do not implicitely wait for completion of the
  40  * operation on the server. Instead the caller specifies a call back
  41  * function that is called when the operation is completed. Currently
  42  * running operations may be canceled using pa_operation_cancel(). */
  43
  44 /** \example pacat.c
  45  * A playback and recording tool using the asynchronous API */
  46
  47 /** \example paplay.c
  48  * A sound file playback tool using the asynchronous API, based on libsndfile */
  49
  50 PA_C_DECL_BEGIN
  51
  52 /** An opaque connection context to a daemon */
  53 typedef struct pa_context pa_context;
  54
  55 /** Generic notification callback prototype */
  56 typedef void (*pa_context_notify_cb_t)(pa_context *c, void *userdata);
  57
  58 /** A generic callback for operation completion */
  59 typedef void (*pa_context_success_cb_t) (pa_context *c, int success, void *userdata);
  60
  61 /** Instantiate a new connection context with an abstract mainloop API
  62  * and an application name */
  63 pa_context *pa_context_new(pa_mainloop_api *mainloop, const char *name);
  64
  65 /** Decrease the reference counter of the context by one */
  66 void pa_context_unref(pa_context *c);
  67
  68 /** Increase the reference counter of the context by one */
  69 pa_context* pa_context_ref(pa_context *c);
  70
  71 /** Set a callback function that is called whenever the context status changes */
  72 void pa_context_set_state_callback(pa_context *c, pa_context_notify_cb_t cb, void *userdata);
  73
  74 /** Return the error number of the last failed operation */
  75 int pa_context_errno(pa_context *c);
  76
  77 /** Return non-zero if some data is pending to be written to the connection */
  78 int pa_context_is_pending(pa_context *c);
  79
  80 /** Return the current context status */
  81 pa_context_state_t pa_context_get_state(pa_context *c);
  82
  83 /** Connect the context to the specified server. If server is NULL,
  84 connect to the default server. This routine may but will not always
  85 return synchronously on error. Use pa_context_set_state_callback() to
  86 be notified when the connection is established. If flags doesn't have
  87 PA_NOAUTOSPAWN set and no specific server is specified or accessible a
  88 new daemon is spawned. If api is non-NULL, the functions specified in
  89 the structure are used when forking a new child process. */
  90 int pa_context_connect(pa_context *c, const char *server, pa_context_flags_t flags, const pa_spawn_api *api);
  91
  92 /** Terminate the context connection immediately */
  93 void pa_context_disconnect(pa_context *c);
  94
  95 /** Drain the context. If there is nothing to drain, the function returns NULL */
  96 pa_operation* pa_context_drain(pa_context *c, pa_context_notify_cb_t cb, void *userdata);
  97
  98 /** Tell the daemon to exit. No operation object is returned as the
  99  * connection is terminated when the daemon quits, thus this operation
 100  * would never complete. */
 101 void pa_context_exit_daemon(pa_context *c);
 102
 103 /** Set the name of the default sink. \since 0.4 */
 104 pa_operation* pa_context_set_default_sink(pa_context *c, const char *name, pa_context_success_cb_t cb, void *userdata);
 105
 106 /** Set the name of the default source. \since 0.4 */
 107 pa_operation* pa_context_set_default_source(pa_context *c, const char *name, pa_context_success_cb_t cb, void *userdata);
 108
 109 /** Returns 1 when the connection is to a local daemon. Returns negative when no connection has been made yet. \since 0.5 */
 110 int pa_context_is_local(pa_context *c);
 111
 112 /** Set a different application name for context on the server. \since 0.5 */
 113 pa_operation* pa_context_set_name(pa_context *c, const char *name, pa_context_success_cb_t cb, void *userdata);
 114
 115 /** Return the server name this context is connected to. \since 0.7 */
 116 const char* pa_context_get_server(pa_context *c);
 117
 118 PA_C_DECL_END
 119
 120 #endif