src/pulsecore/protocol-dbus.h

   1 #ifndef fooprotocoldbushfoo
   2 #define fooprotocoldbushfoo
   3
   4 /***
   5   This file is part of PulseAudio.
   6
   7   Copyright 2009 Tanu Kaskinen
   8
   9   PulseAudio is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU Lesser General Public License as published
  11   by the Free Software Foundation; either version 2.1 of the License,
  12   or (at your option) any later version.
  13
  14   PulseAudio 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 Lesser General Public License
  20   along with PulseAudio; 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 <dbus/dbus.h>
  26
  27 #include <pulsecore/core.h>
  28 #include <pulsecore/macro.h>
  29
  30 #define PA_DBUS_DEFAULT_PORT 24883
  31 #define PA_DBUS_SOCKET_NAME "dbus-socket"
  32
  33 #define PA_DBUS_SYSTEM_SOCKET_PATH PA_SYSTEM_RUNTIME_PATH PA_PATH_SEP PA_DBUS_SOCKET_NAME
  34
  35 #define PA_DBUS_CORE_INTERFACE "org.PulseAudio.Core1"
  36 #define PA_DBUS_CORE_OBJECT_PATH "/org/pulseaudio/core1"
  37
  38 #define PA_DBUS_ERROR_NO_SUCH_INTERFACE PA_DBUS_CORE_INTERFACE ".NoSuchInterfaceError"
  39 #define PA_DBUS_ERROR_NO_SUCH_PROPERTY PA_DBUS_CORE_INTERFACE ".NoSuchPropertyError"
  40 #define PA_DBUS_ERROR_NOT_FOUND PA_DBUS_CORE_INTERFACE ".NotFoundError"
  41
  42 /* Returns the default address of the server type in the escaped form. For
  43  * PA_SERVER_TYPE_NONE an empty string is returned. The caller frees the
  44  * string. */
  45 char *pa_get_dbus_address_from_server_type(pa_server_type_t server_type);
  46
  47 typedef struct pa_dbus_protocol pa_dbus_protocol;
  48
  49 /* This function either creates a new pa_dbus_protocol object, or if one
  50  * already exists, increases the reference count. */
  51 pa_dbus_protocol* pa_dbus_protocol_get(pa_core *c);
  52
  53 pa_dbus_protocol* pa_dbus_protocol_ref(pa_dbus_protocol *p);
  54 void pa_dbus_protocol_unref(pa_dbus_protocol *p);
  55
  56 /* Called when a received message needs handling. Completely ignoring the
  57  * message isn't a good idea; if you can't handle the message, reply with an
  58  * error.
  59  *
  60  * The message signature is already checked against the introspection data, so
  61  * you don't have to do that yourself.
  62  *
  63  * All messages are method calls. */
  64 typedef void (*pa_dbus_receive_cb_t)(DBusConnection *conn, DBusMessage *msg, void *userdata);
  65
  66 /* A specialized version of pa_dbus_receive_cb_t: the additional iterator
  67  * argument points to the element inside the new value variant.
  68  *
  69  * The new value signature is checked against the introspection data, so you
  70  * don't have to do that yourself. */
  71 typedef void (*pa_dbus_set_property_cb_t)(DBusConnection *conn, DBusMessage *msg, DBusMessageIter *iter, void *userdata);
  72
  73 typedef struct pa_dbus_arg_info {
  74     const char *name;
  75     const char *type;
  76     const char *direction; /* NULL for signal arguments. */
  77 } pa_dbus_arg_info;
  78
  79 typedef struct pa_dbus_signal_info {
  80     const char *name;
  81     const pa_dbus_arg_info *arguments; /* NULL, if the signal has no args. */
  82     unsigned n_arguments;
  83 } pa_dbus_signal_info;
  84
  85 typedef struct pa_dbus_method_handler {
  86     const char *method_name;
  87     const pa_dbus_arg_info *arguments; /* NULL, if the method has no args. */
  88     unsigned n_arguments;
  89     pa_dbus_receive_cb_t receive_cb;
  90 } pa_dbus_method_handler;
  91
  92 typedef struct pa_dbus_property_handler {
  93     const char *property_name;
  94     const char *type;
  95
  96     /* The access mode for the property is determined by checking whether
  97      * get_cb or set_cb is NULL. */
  98     pa_dbus_receive_cb_t get_cb;
  99     pa_dbus_set_property_cb_t set_cb;
 100 } pa_dbus_property_handler;
 101
 102 typedef struct pa_dbus_interface_info {
 103     const char* name;
 104     const pa_dbus_method_handler *method_handlers; /* NULL, if the interface has no methods. */
 105     unsigned n_method_handlers;
 106     const pa_dbus_property_handler *property_handlers; /* NULL, if the interface has no properties. */
 107     unsigned n_property_handlers;
 108     const pa_dbus_receive_cb_t get_all_properties_cb; /* May be NULL, in which case GetAll returns an error. */
 109     const pa_dbus_signal_info *signals; /* NULL, if the interface has no signals. */
 110     unsigned n_signals;
 111 } pa_dbus_interface_info;
 112
 113
 114 /* The following functions may only be called from the main thread. */
 115
 116 /* Registers the given interface to the given object path. It doesn't matter
 117  * whether or not the object has already been registered; if it is, then its
 118  * interface set is extended.
 119  *
 120  * Introspection requests are handled automatically.
 121  *
 122  * Userdata is passed to all the callbacks.
 123  *
 124  * Fails and returns a negative number if the object already has the interface
 125  * registered. */
 126 int pa_dbus_protocol_add_interface(pa_dbus_protocol *p, const char *path, const pa_dbus_interface_info *info, void *userdata);
 127
 128 /* Returns a negative number if the given object doesn't have the given
 129  * interface registered. */
 130 int pa_dbus_protocol_remove_interface(pa_dbus_protocol *p, const char* path, const char* interface);
 131
 132 /* Fails and returns a negative number if the connection is already
 133  * registered. */
 134 int pa_dbus_protocol_register_connection(pa_dbus_protocol *p, DBusConnection *conn, pa_client *client);
 135
 136 /* Returns a negative number if the connection isn't registered. */
 137 int pa_dbus_protocol_unregister_connection(pa_dbus_protocol *p, DBusConnection *conn);
 138
 139 /* Returns NULL if the connection isn't registered. */
 140 pa_client *pa_dbus_protocol_get_client(pa_dbus_protocol *p, DBusConnection *conn);
 141
 142 /* Enables signal receiving for the given connection. The connection must have
 143  * been registered earlier. The signal string must contain both the signal
 144  * interface and the signal name, concatenated using a period as the separator.
 145  *
 146  * If the signal argument is NULL, all signals will be sent to the connection,
 147  * otherwise calling this function only adds the given signal to the list of
 148  * signals that will be delivered to the connection.
 149  *
 150  * The objects argument is a list of object paths. If the list is not empty,
 151  * only signals from the given objects are delivered. If this function is
 152  * called multiple time for the same connection and signal, the latest call
 153  * always replaces the previous object list. */
 154 void pa_dbus_protocol_add_signal_listener(
 155         pa_dbus_protocol *p,
 156         DBusConnection *conn,
 157         const char *signal,
 158         char **objects,
 159         unsigned n_objects);
 160
 161 /* Disables the delivery of the signal for the given connection. The connection
 162  * must have been registered. If signal is NULL, all signals are disabled. If
 163  * signal is non-NULL and _add_signal_listener() was previously called with
 164  * NULL signal (causing all signals to be enabled), this function doesn't do
 165  * anything. Also, if the signal wasn't enabled before, this function doesn't
 166  * do anything in that case either. */
 167 void pa_dbus_protocol_remove_signal_listener(pa_dbus_protocol *p, DBusConnection *conn, const char *signal);
 168
 169 /* Sends the given signal to all interested clients. By default no signals are
 170  * sent - clients have to explicitly to request signals by calling
 171  * .Core1.ListenForSignal. That method's handler then calls
 172  * pa_dbus_protocol_add_signal_listener(). */
 173 void pa_dbus_protocol_send_signal(pa_dbus_protocol *p, DBusMessage *signal);
 174
 175 /* Returns an array of extension identifier strings. The strings pointers point
 176  * to the internal copies, so don't free the strings. The caller must free the
 177  * array, however. Also, do not save the returned pointer or any of the string
 178  * pointers, because the contained strings may be freed at any time. If you
 179  * need to save the array, copy it. */
 180 const char **pa_dbus_protocol_get_extensions(pa_dbus_protocol *p, unsigned *n);
 181
 182 /* Modules that want to provide a D-Bus interface for clients should register
 183  * an identifier that the clients can use to check whether the additional
 184  * functionality is available.
 185  *
 186  * This function registers the extension with the given name. It is recommended
 187  * that the name follows the D-Bus interface naming convention, so that the
 188  * names remain unique in case there will be at some point in the future
 189  * extensions that aren't included with the main PulseAudio source tree. For
 190  * in-tree extensions the convention is to use the org.PulseAudio.Ext
 191  * namespace.
 192  *
 193  * It is suggested that the name contains a version number, and whenever the
 194  * extension interface is modified in non-backwards compatible way, the version
 195  * number is incremented.
 196  *
 197  * Fails and returns a negative number if the extension is already registered.
 198  */
 199 int pa_dbus_protocol_register_extension(pa_dbus_protocol *p, const char *name);
 200
 201 /* Returns a negative number if the extension isn't registered. */
 202 int pa_dbus_protocol_unregister_extension(pa_dbus_protocol *p, const char *name);
 203
 204 /* All hooks have the pa_dbus_protocol object as hook data. */
 205 typedef enum pa_dbus_protocol_hook {
 206     PA_DBUS_PROTOCOL_HOOK_EXTENSION_REGISTERED, /* Extension name as call data. */
 207     PA_DBUS_PROTOCOL_HOOK_EXTENSION_UNREGISTERED, /* Extension name as call data. */
 208     PA_DBUS_PROTOCOL_HOOK_MAX
 209 } pa_dbus_protocol_hook_t;
 210
 211 pa_hook_slot *pa_dbus_protocol_hook_connect(
 212         pa_dbus_protocol *p,
 213         pa_dbus_protocol_hook_t hook,
 214         pa_hook_priority_t prio,
 215         pa_hook_cb_t cb,
 216         void *data);
 217
 218 #endif