polyp/polyplib-context.h

   1 #ifndef foopolyplibcontexthfoo
   2 #define foopolyplibcontexthfoo
   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 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 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 "sample.h"
  26 #include "polyplib-def.h"
  27 #include "mainloop-api.h"
  28 #include "cdecl.h"
  29 #include "polyplib-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 PA_C_DECL_BEGIN
  48
  49 /** \struct pa_context
  50  * An opaque connection context to a daemon */
  51 struct pa_context;
  52
  53 /** Instantiate a new connection context with an abstract mainloop API
  54  * and an application name */
  55 struct pa_context *pa_context_new(struct pa_mainloop_api *mainloop, const char *name);
  56
  57 /** Decrease the reference counter of the context by one */
  58 void pa_context_unref(struct pa_context *c);
  59
  60 /** Increase the reference counter of the context by one */
  61 struct pa_context* pa_context_ref(struct pa_context *c);
  62
  63 /** Set a callback function that is called whenever the context status changes */
  64 void pa_context_set_state_callback(struct pa_context *c, void (*cb)(struct pa_context *c, void *userdata), void *userdata);
  65
  66 /** Return the error number of the last failed operation */
  67 int pa_context_errno(struct pa_context *c);
  68
  69 /** Return non-zero if some data is pending to be written to the connection */
  70 int pa_context_is_pending(struct pa_context *c);
  71
  72 /** Return the current context status */
  73 enum pa_context_state pa_context_get_state(struct pa_context *c);
  74
  75 /** Connect the context to the specified server. If server is NULL,
  76 connect to the default server. This routine may but will not always
  77 return synchronously on error. Use pa_context_set_state_callback() to
  78 be notified when the connection is established */
  79 int pa_context_connect(struct pa_context *c, const char *server);
  80
  81 /** Terminate the context connection immediately */
  82 void pa_context_disconnect(struct pa_context *c);
  83
  84 /** Drain the context. If there is nothing to drain, the function returns NULL */
  85 struct pa_operation* pa_context_drain(struct pa_context *c, void (*cb) (struct pa_context*c, void *userdata), void *userdata);
  86
  87 /** Tell the daemon to exit. No operation object is returned as the
  88  * connection is terminated when the daemon quits, thus this operation
  89  * would never complete. */
  90 void pa_context_exit_daemon(struct pa_context *c);
  91
  92 PA_C_DECL_END
  93
  94 #endif