X-Git-Url: https://code.delx.au/pulseaudio/blobdiff_plain/22cb23eedb2eae7c79dc8fcf395be08bfc666256..fa499dad06ba6558111cdef64c18f2401e803cff:/polyp/polyplib-context.h

diff --git a/polyp/polyplib-context.h b/polyp/polyplib-context.h
index 6a1cc8bd..565701b2 100644
--- a/polyp/polyplib-context.h
+++ b/polyp/polyplib-context.h
@@ -1,3 +1,4 @@
+
 #ifndef foopolyplibcontexthfoo
 #define foopolyplibcontexthfoo
 
@@ -7,7 +8,7 @@
   This file is part of polypaudio.
  
   polypaudio is free software; you can redistribute it and/or modify
-  it under the terms of the GNU General Public License as published
+  it under the terms of the GNU Lesser General Public License as published
   by the Free Software Foundation; either version 2 of the License,
   or (at your option) any later version.
  
@@ -16,7 +17,7 @@
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
   General Public License for more details.
  
-  You should have received a copy of the GNU General Public License
+  You should have received a copy of the GNU Lesser General Public License
   along with polypaudio; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
   USA.
@@ -29,23 +30,28 @@
 #include "polyplib-operation.h"
 
 /** \file
- * Connection contexts */
+ * Connection contexts for asynchrononous communication with a
+ * server. A pa_context object wraps a connection to a polypaudio
+ * server using its native protocol. A context may be used to issue
+ * commands on the server or to create playback or recording
+ * streams. Multiple playback streams may be piped through a single
+ * connection context. Operations on the contect involving
+ * communication with the server are executed asynchronously: i.e. the
+ * client function do not implicitely wait for completion of the
+ * operation on the server. Instead the caller specifies a call back
+ * function that is called when the operation is completed. Currently
+ * running operations may be canceled using pa_operation_cancel(). */
+
+/** \example pacat.c
+ * A playback and recording tool using the asynchronous API */
+
+/** \example paplay.c
+ * A sound file playback tool using the asynchronous API, based on libsndfile */
 
 PA_C_DECL_BEGIN
 
-/** The state of a connection context */
-enum pa_context_state {
-    PA_CONTEXT_UNCONNECTED,    /**< The context hasn't been connected yet */
-    PA_CONTEXT_CONNECTING,     /**< A connection is being established */
-    PA_CONTEXT_AUTHORIZING,    /**< The client is authorizing itself to the daemon */
-    PA_CONTEXT_SETTING_NAME,   /**< The client is passing its application name to the daemon */
-    PA_CONTEXT_READY,          /**< The connection is established, the context is ready to execute operations */
-    PA_CONTEXT_FAILED,         /**< The connection failed or was disconnected */
-    PA_CONTEXT_TERMINATED      /**< The connect was terminated cleanly */
-};
-
 /** \struct pa_context
- * A connection context to a daemon */
+ * An opaque connection context to a daemon */
 struct pa_context;
 
 /** Instantiate a new connection context with an abstract mainloop API
@@ -73,8 +79,11 @@ enum pa_context_state pa_context_get_state(struct pa_context *c);
 /** Connect the context to the specified server. If server is NULL,
 connect to the default server. This routine may but will not always
 return synchronously on error. Use pa_context_set_state_callback() to
-be notified when the connection is established */
-int pa_context_connect(struct pa_context *c, const char *server);
+be notified when the connection is established. If spawn is non-zero
+and no specific server is specified or accessible a new daemon is
+spawned. If api is non-NULL, the functions specified in the structure
+are used when forking a new child process. */
+int pa_context_connect(struct pa_context *c, const char *server, int spawn, const struct pa_spawn_api *api);
 
 /** Terminate the context connection immediately */
 void pa_context_disconnect(struct pa_context *c);
@@ -87,6 +96,18 @@ struct pa_operation* pa_context_drain(struct pa_context *c, void (*cb) (struct p
  * would never complete. */
 void pa_context_exit_daemon(struct pa_context *c);
 
+/** Set the name of the default sink. \since 0.4 */
+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);
+
+/** Set the name of the default source. \since 0.4 */
+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);
+
+/** Returns 1 when the connection is to a local daemon. Returns negative when no connection has been made yet. \since 0.5 */
+int pa_context_is_local(struct pa_context *c);
+
+/** Set a different application name for context on the server. \since 0.5 */
+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);
+
 PA_C_DECL_END
 
 #endif