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

   1
   2 #ifndef foopolyplibcontexthfoo
   3 #define foopolyplibcontexthfoo
   4
   5 /* $Id$ */
   6
   7 /***
   8   This file is part of polypaudio.
   9
  10   polypaudio is free software; you can redistribute it and/or modify
  11   it under the terms of the GNU General Public License as published
  12   by the Free Software Foundation; either version 2 of the License,
  13   or (at your option) any later version.
  14
  15   polypaudio is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   General Public License for more details.
  19
  20   You should have received a copy of the GNU General Public License
  21   along with polypaudio; if not, write to the Free Software
  22   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  23   USA.
  24 ***/
  25
  26 #include "sample.h"
  27 #include "polyplib-def.h"
  28 #include "mainloop-api.h"
  29 #include "cdecl.h"
  30 #include "polyplib-operation.h"
  31
  32 /** \file
  33  * Connection contexts for asynchrononous communication with a
  34  * server. A pa_context object wraps a connection to a polypaudio
  35  * server using its native protocol. A context may be used to issue
  36  * commands on the server or to create playback or recording
  37  * streams. Multiple playback streams may be piped through a single
  38  * connection context. Operations on the contect involving
  39  * communication with the server are executed asynchronously: i.e. the
  40  * client function do not implicitely wait for completion of the
  41  * operation on the server. Instead the caller specifies a call back
  42  * function that is called when the operation is completed. Currently
  43  * running operations may be canceled using pa_operation_cancel(). */
  44
  45 /** \example pacat.c
  46  * A playback and recording tool using the asynchronous API */
  47
  48 /** \example paplay.c
  49  * A sound file playback tool using the asynchronous API, based on libsndfile */
  50
  51 PA_C_DECL_BEGIN
  52
  53 /** \struct pa_context
  54  * An opaque connection context to a daemon */
  55 struct pa_context;
  56
  57 /** Instantiate a new connection context with an abstract mainloop API
  58  * and an application name */
  59 struct pa_context *pa_context_new(struct pa_mainloop_api *mainloop, const char *name);
  60
  61 /** Decrease the reference counter of the context by one */
  62 void pa_context_unref(struct pa_context *c);
  63
  64 /** Increase the reference counter of the context by one */
  65 struct pa_context* pa_context_ref(struct pa_context *c);
  66
  67 /** Set a callback function that is called whenever the context status changes */
  68 void pa_context_set_state_callback(struct pa_context *c, void (*cb)(struct pa_context *c, void *userdata), void *userdata);
  69
  70 /** Return the error number of the last failed operation */
  71 int pa_context_errno(struct pa_context *c);
  72
  73 /** Return non-zero if some data is pending to be written to the connection */
  74 int pa_context_is_pending(struct pa_context *c);
  75
  76 /** Return the current context status */
  77 enum pa_context_state pa_context_get_state(struct pa_context *c);
  78
  79 /** Connect the context to the specified server. If server is NULL,
  80 connect to the default server. This routine may but will not always
  81 return synchronously on error. Use pa_context_set_state_callback() to
  82 be notified when the connection is established. If spawn is non-zero
  83 and no specific server is specified or accessible a new daemon is
  84 spawned. If api is non-NULL, the functions specified in the structure
  85 are used when forking a new child process. */
  86 int pa_context_connect(struct pa_context *c, const char *server, int spawn, const struct pa_spawn_api *api);
  87
  88 /** Terminate the context connection immediately */
  89 void pa_context_disconnect(struct pa_context *c);
  90
  91 /** Drain the context. If there is nothing to drain, the function returns NULL */
  92 struct pa_operation* pa_context_drain(struct pa_context *c, void (*cb) (struct pa_context*c, void *userdata), void *userdata);
  93
  94 /** Tell the daemon to exit. No operation object is returned as the
  95  * connection is terminated when the daemon quits, thus this operation
  96  * would never complete. */
  97 void pa_context_exit_daemon(struct pa_context *c);
  98
  99 /** Set the name of the default sink. \since 0.4 */
 100 struct pa_operation* pa_context_set_default_sink(struct pa_context *c, const char *name, void(*cb)(struct pa_context*c, int success, void *userdata), void *userdata);
 101
 102 /** Set the name of the default source. \since 0.4 */
 103 struct pa_operation* pa_context_set_default_source(struct pa_context *c, const char *name, void(*cb)(struct pa_context*c, int success,  void *userdata), void *userdata);
 104
 105 /** Returns 1 when the connection is to a local daemon. Returns negative when no connection has been made yet. \since 0.5 */
 106 int pa_context_is_local(struct pa_context *c);
 107
 108 /** Set a different application name for context on the server. \since 0.5 */
 109 struct pa_operation* pa_context_set_name(struct pa_context *c, const char *name, void(*cb)(struct pa_context*c, int success,  void *userdata), void *userdata);
 110
 111 PA_C_DECL_END
 112
 113 #endif