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 /** \pa_context
  53  * An opaque connection context to a daemon */
  54 typedef struct pa_context pa_context;
  55
  56 /** Instantiate a new connection context with an abstract mainloop API
  57  * and an application name */
  58 pa_context *pa_context_new(pa_mainloop_api *mainloop, const char *name);
  59
  60 /** Decrease the reference counter of the context by one */
  61 void pa_context_unref(pa_context *c);
  62
  63 /** Increase the reference counter of the context by one */
  64 pa_context* pa_context_ref(pa_context *c);
  65
  66 typedef void (*pa_context_state_callback)(pa_context *c, void *userdata);
  67
  68 /** Set a callback function that is called whenever the context status changes */
  69 void pa_context_set_state_callback(pa_context *c, pa_context_state_callback callback, void *userdata);
  70
  71 /** Return the error number of the last failed operation */
  72 int pa_context_errno(pa_context *c);
  73
  74 /** Return non-zero if some data is pending to be written to the connection */
  75 int pa_context_is_pending(pa_context *c);
  76
  77 /** Return the current context status */
  78 pa_context_state_t pa_context_get_state(pa_context *c);
  79
  80 /** Connect the context to the specified server. If server is NULL,
  81 connect to the default server. This routine may but will not always
  82 return synchronously on error. Use pa_context_set_state_callback() to
  83 be notified when the connection is established. If spawn is non-zero
  84 and no specific server is specified or accessible a new daemon is
  85 spawned. If api is non-NULL, the functions specified in the structure
  86 are used when forking a new child process. */
  87 int pa_context_connect(pa_context *c, const char *server, int spawn, const pa_spawn_api *api);
  88
  89 /** Terminate the context connection immediately */
  90 void pa_context_disconnect(pa_context *c);
  91
  92 /** Drain the context. If there is nothing to drain, the function returns NULL */
  93 pa_operation* pa_context_drain(pa_context *c, void (*cb) (pa_context*c, void *userdata), void *userdata);
  94
  95 /** Tell the daemon to exit. No operation object is returned as the
  96  * connection is terminated when the daemon quits, thus this operation
  97  * would never complete. */
  98 void pa_context_exit_daemon(pa_context *c);
  99
 100 /** Set the name of the default sink. \since 0.4 */
 101 pa_operation* pa_context_set_default_sink(pa_context *c, const char *name, void(*cb)(pa_context*c, int success, void *userdata), void *userdata);
 102
 103 /** Set the name of the default source. \since 0.4 */
 104 pa_operation* pa_context_set_default_source(pa_context *c, const char *name, void(*cb)(pa_context*c, int success,  void *userdata), void *userdata);
 105
 106 /** Returns 1 when the connection is to a local daemon. Returns negative when no connection has been made yet. \since 0.5 */
 107 int pa_context_is_local(pa_context *c);
 108
 109 /** Set a different application name for context on the server. \since 0.5 */
 110 pa_operation* pa_context_set_name(pa_context *c, const char *name, void(*cb)(pa_context*c, int success,  void *userdata), void *userdata);
 111
 112 /** Return the server name this context is connected to. \since 0.7 */
 113 const char* pa_context_get_server(pa_context *c);
 114
 115 PA_C_DECL_END
 116
 117 #endif