#define PA_DBUS_SYSTEM_SOCKET_PATH PA_SYSTEM_RUNTIME_PATH PA_PATH_SEP PA_DBUS_SOCKET_NAME
-#define PA_DBUS_ERROR_NO_SUCH_PROPERTY "org.PulseAudio.Core1.NoSuchPropertyError"
-#define PA_DBUS_ERROR_NOT_FOUND "org.PulseAudio.Core1.NotFoundError"
+#define PA_DBUS_CORE_INTERFACE "org.PulseAudio.Core1"
+#define PA_DBUS_CORE_OBJECT_PATH "/org/pulseaudio/core1"
+
+#define PA_DBUS_ERROR_NO_SUCH_INTERFACE PA_DBUS_CORE_INTERFACE ".NoSuchInterfaceError"
+#define PA_DBUS_ERROR_NO_SUCH_PROPERTY PA_DBUS_CORE_INTERFACE ".NoSuchPropertyError"
+#define PA_DBUS_ERROR_NOT_FOUND PA_DBUS_CORE_INTERFACE ".NotFoundError"
/* Returns the default address of the server type in the escaped form. For
* PA_SERVER_TYPE_NONE an empty string is returned. The caller frees the
* message isn't a good idea; if you can't handle the message, reply with an
* error.
*
+ * The message signature is already checked against the introspection data, so
+ * you don't have to do that yourself.
+ *
* All messages are method calls. */
typedef void (*pa_dbus_receive_cb_t)(DBusConnection *conn, DBusMessage *msg, void *userdata);
+/* A specialized version of pa_dbus_receive_cb_t: the additional iterator
+ * argument points to the element inside the new value variant.
+ *
+ * The new value signature is checked against the introspection data, so you
+ * don't have to do that yourself. */
+typedef void (*pa_dbus_set_property_cb_t)(DBusConnection *conn, DBusMessage *msg, DBusMessageIter *iter, void *userdata);
+
typedef struct pa_dbus_arg_info {
const char *name;
const char *type;
/* The access mode for the property is determined by checking whether
* get_cb or set_cb is NULL. */
pa_dbus_receive_cb_t get_cb;
- pa_dbus_receive_cb_t set_cb;
+ pa_dbus_set_property_cb_t set_cb;
} pa_dbus_property_handler;
typedef struct pa_dbus_interface_info {
unsigned n_signals;
} pa_dbus_interface_info;
-
/* The following functions may only be called from the main thread. */
/* Registers the given interface to the given object path. It doesn't matter
* registered. */
int pa_dbus_protocol_register_connection(pa_dbus_protocol *p, DBusConnection *conn, pa_client *client);
-/* Returns a negative number if the connection wasn't registered. */
+/* Returns a negative number if the connection isn't registered. */
int pa_dbus_protocol_unregister_connection(pa_dbus_protocol *p, DBusConnection *conn);
+/* Returns NULL if the connection isn't registered. */
+pa_client *pa_dbus_protocol_get_client(pa_dbus_protocol *p, DBusConnection *conn);
+
/* Enables signal receiving for the given connection. The connection must have
- * been registered earlier.
+ * been registered earlier. The signal string must contain both the signal
+ * interface and the signal name, concatenated using a period as the separator.
*
* If the signal argument is NULL, all signals will be sent to the connection,
* otherwise calling this function only adds the given signal to the list of
* only signals from the given objects are delivered. If this function is
* called multiple time for the same connection and signal, the latest call
* always replaces the previous object list. */
-void pa_dbus_protocol_add_signal_listener(pa_dbus_protocol *p, DBusConnection *conn, const char *signal, char **objects, unsigned n_objects);
+void pa_dbus_protocol_add_signal_listener(
+ pa_dbus_protocol *p,
+ DBusConnection *conn,
+ const char *signal,
+ char **objects,
+ unsigned n_objects);
/* Disables the delivery of the signal for the given connection. The connection
* must have been registered. If signal is NULL, all signals are disabled. If
* do anything in that case either. */
void pa_dbus_protocol_remove_signal_listener(pa_dbus_protocol *p, DBusConnection *conn, const char *signal);
+/* Sends the given signal to all interested clients. By default no signals are
+ * sent - clients have to explicitly to request signals by calling
+ * .Core1.ListenForSignal. That method's handler then calls
+ * pa_dbus_protocol_add_signal_listener(). */
void pa_dbus_protocol_send_signal(pa_dbus_protocol *p, DBusMessage *signal);
-/* Returns NULL if the connection isn't registered. */
-pa_client *pa_dbus_protocol_get_client(pa_dbus_protocol *p, DBusConnection *conn);
-
/* Returns an array of extension identifier strings. The strings pointers point
* to the internal copies, so don't free the strings. The caller must free the
* array, however. Also, do not save the returned pointer or any of the string
* need to save the array, copy it. */
const char **pa_dbus_protocol_get_extensions(pa_dbus_protocol *p, unsigned *n);
+/* Modules that want to provide a D-Bus interface for clients should register
+ * an identifier that the clients can use to check whether the additional
+ * functionality is available.
+ *
+ * This function registers the extension with the given name. It is recommended
+ * that the name follows the D-Bus interface naming convention, so that the
+ * names remain unique in case there will be at some point in the future
+ * extensions that aren't included with the main PulseAudio source tree. For
+ * in-tree extensions the convention is to use the org.PulseAudio.Ext
+ * namespace.
+ *
+ * It is suggested that the name contains a version number, and whenever the
+ * extension interface is modified in non-backwards compatible way, the version
+ * number is incremented.
+ *
+ * Fails and returns a negative number if the extension is already registered.
+ */
+int pa_dbus_protocol_register_extension(pa_dbus_protocol *p, const char *name);
+
+/* Returns a negative number if the extension isn't registered. */
+int pa_dbus_protocol_unregister_extension(pa_dbus_protocol *p, const char *name);
+
+/* All hooks have the pa_dbus_protocol object as hook data. */
+typedef enum pa_dbus_protocol_hook {
+ PA_DBUS_PROTOCOL_HOOK_EXTENSION_REGISTERED, /* Extension name as call data. */
+ PA_DBUS_PROTOCOL_HOOK_EXTENSION_UNREGISTERED, /* Extension name as call data. */
+ PA_DBUS_PROTOCOL_HOOK_MAX
+} pa_dbus_protocol_hook_t;
+
+pa_hook_slot *pa_dbus_protocol_hook_connect(
+ pa_dbus_protocol *p,
+ pa_dbus_protocol_hook_t hook,
+ pa_hook_priority_t prio,
+ pa_hook_cb_t cb,
+ void *data);
+
#endif