code.delx.au - pulseaudio/blob - 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 /* The following functions may only be called from the main thread. */
 114
 115 /* Registers the given interface to the given object path. It doesn't matter
 116  * whether or not the object has already been registered; if it is, then its
 117  * interface set is extended.
 118  *
 119  * Introspection requests are handled automatically.
 120  *
 121  * Userdata is passed to all the callbacks.
 122  *
 123  * Fails and returns a negative number if the object already has the interface
 124  * registered. */
 125 int pa_dbus_protocol_add_interface(pa_dbus_protocol *p, const char *path, const pa_dbus_interface_info *info, void *userdata);
 126
 127 /* Returns a negative number if the given object doesn't have the given
 128  * interface registered. */
 129 int pa_dbus_protocol_remove_interface(pa_dbus_protocol *p, const char* path, const char* interface);
 130
 131 /* Fails and returns a negative number if the connection is already
 132  * registered. */
 133 int pa_dbus_protocol_register_connection(pa_dbus_protocol *p, DBusConnection *conn, pa_client *client);
 134
 135 /* Returns a negative number if the connection isn't registered. */
 136 int pa_dbus_protocol_unregister_connection(pa_dbus_protocol *p, DBusConnection *conn);
 137
 138 /* Returns NULL if the connection isn't registered. */
 139 pa_client *pa_dbus_protocol_get_client(pa_dbus_protocol *p, DBusConnection *conn);
 140
 141 /* Enables signal receiving for the given connection. The connection must have
 142  * been registered earlier. The signal string must contain both the signal
 143  * interface and the signal name, concatenated using a period as the separator.
 144  *
 145  * If the signal argument is NULL, all signals will be sent to the connection,
 146  * otherwise calling this function only adds the given signal to the list of
 147  * signals that will be delivered to the connection.
 148  *
 149  * The objects argument is a list of object paths. If the list is not empty,
 150  * only signals from the given objects are delivered. If this function is
 151  * called multiple time for the same connection and signal, the latest call
 152  * always replaces the previous object list. */
 153 void pa_dbus_protocol_add_signal_listener(
 154         pa_dbus_protocol *p,
 155         DBusConnection *conn,
 156         const char *signal,
 157         char **objects,
 158         unsigned n_objects);
 159
 160 /* Disables the delivery of the signal for the given connection. The connection
 161  * must have been registered. If signal is NULL, all signals are disabled. If
 162  * signal is non-NULL and _add_signal_listener() was previously called with
 163  * NULL signal (causing all signals to be enabled), this function doesn't do
 164  * anything. Also, if the signal wasn't enabled before, this function doesn't
 165  * do anything in that case either. */
 166 void pa_dbus_protocol_remove_signal_listener(pa_dbus_protocol *p, DBusConnection *conn, const char *signal);
 167
 168 /* Sends the given signal to all interested clients. By default no signals are
 169  * sent - clients have to explicitly to request signals by calling
 170  * .Core1.ListenForSignal. That method's handler then calls
 171  * pa_dbus_protocol_add_signal_listener(). */
 172 void pa_dbus_protocol_send_signal(pa_dbus_protocol *p, DBusMessage *signal);
 173
 174 /* Returns an array of extension identifier strings. The strings pointers point
 175  * to the internal copies, so don't free the strings. The caller must free the
 176  * array, however. Also, do not save the returned pointer or any of the string
 177  * pointers, because the contained strings may be freed at any time. If you
 178  * need to save the array, copy it. */
 179 const char **pa_dbus_protocol_get_extensions(pa_dbus_protocol *p, unsigned *n);
 180
 181 /* Modules that want to provide a D-Bus interface for clients should register
 182  * an identifier that the clients can use to check whether the additional
 183  * functionality is available.
 184  *
 185  * This function registers the extension with the given name. It is recommended
 186  * that the name follows the D-Bus interface naming convention, so that the
 187  * names remain unique in case there will be at some point in the future
 188  * extensions that aren't included with the main PulseAudio source tree. For
 189  * in-tree extensions the convention is to use the org.PulseAudio.Ext
 190  * namespace.
 191  *
 192  * It is suggested that the name contains a version number, and whenever the
 193  * extension interface is modified in non-backwards compatible way, the version
 194  * number is incremented.
 195  *
 196  * Fails and returns a negative number if the extension is already registered.
 197  */
 198 int pa_dbus_protocol_register_extension(pa_dbus_protocol *p, const char *name);
 199
 200 /* Returns a negative number if the extension isn't registered. */
 201 int pa_dbus_protocol_unregister_extension(pa_dbus_protocol *p, const char *name);
 202
 203 /* All hooks have the pa_dbus_protocol object as hook data. */
 204 typedef enum pa_dbus_protocol_hook {
 205     PA_DBUS_PROTOCOL_HOOK_EXTENSION_REGISTERED, /* Extension name as call data. */
 206     PA_DBUS_PROTOCOL_HOOK_EXTENSION_UNREGISTERED, /* Extension name as call data. */
 207     PA_DBUS_PROTOCOL_HOOK_MAX
 208 } pa_dbus_protocol_hook_t;
 209
 210 pa_hook_slot *pa_dbus_protocol_hook_connect(
 211         pa_dbus_protocol *p,
 212         pa_dbus_protocol_hook_t hook,
 213         pa_hook_priority_t prio,
 214         pa_hook_cb_t cb,
 215         void *data);
 216
 217 #endif