+
#ifndef foopolyplibcontexthfoo
#define foopolyplibcontexthfoo
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.
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.
#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
/** 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);
* 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