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_PROPERTY PA_DBUS_CORE_INTERFACE ".NoSuchPropertyError"
  39 #define PA_DBUS_ERROR_NOT_FOUND PA_DBUS_CORE_INTERFACE ".NotFoundError"
  40
  41 /* Returns the default address of the server type in the escaped form. For
  42  * PA_SERVER_TYPE_NONE an empty string is returned. The caller frees the
  43  * string. */
  44 char *pa_get_dbus_address_from_server_type(pa_server_type_t server_type);
  45
  46 typedef struct pa_dbus_protocol pa_dbus_protocol;
  47
  48 /* This function either creates a new pa_dbus_protocol object, or if one
  49  * already exists, increases the reference count. */
  50 pa_dbus_protocol* pa_dbus_protocol_get(pa_core *c);
  51
  52 pa_dbus_protocol* pa_dbus_protocol_ref(pa_dbus_protocol *p);
  53 void pa_dbus_protocol_unref(pa_dbus_protocol *p);
  54
  55 /* Called when a received message needs handling. Completely ignoring the
  56  * message isn't a good idea; if you can't handle the message, reply with an
  57  * error.
  58  *
  59  * All messages are method calls. */
  60 typedef void (*pa_dbus_receive_cb_t)(DBusConnection *conn, DBusMessage *msg, void *userdata);
  61
  62 typedef struct pa_dbus_arg_info {
  63     const char *name;
  64     const char *type;
  65     const char *direction; /* NULL for signal arguments. */
  66 } pa_dbus_arg_info;
  67
  68 typedef struct pa_dbus_signal_info {
  69     const char *name;
  70     const pa_dbus_arg_info *arguments; /* NULL, if the signal has no args. */
  71     unsigned n_arguments;
  72 } pa_dbus_signal_info;
  73
  74 typedef struct pa_dbus_method_handler {
  75     const char *method_name;
  76     const pa_dbus_arg_info *arguments; /* NULL, if the method has no args. */
  77     unsigned n_arguments;
  78     pa_dbus_receive_cb_t receive_cb;
  79 } pa_dbus_method_handler;
  80
  81 typedef struct pa_dbus_property_handler {
  82     const char *property_name;
  83     const char *type;
  84
  85     /* The access mode for the property is determined by checking whether
  86      * get_cb or set_cb is NULL. */
  87     pa_dbus_receive_cb_t get_cb;
  88     pa_dbus_receive_cb_t set_cb;
  89 } pa_dbus_property_handler;
  90
  91 typedef struct pa_dbus_interface_info {
  92     const char* name;
  93     const pa_dbus_method_handler *method_handlers; /* NULL, if the interface has no methods. */
  94     unsigned n_method_handlers;
  95     const pa_dbus_property_handler *property_handlers; /* NULL, if the interface has no properties. */
  96     unsigned n_property_handlers;
  97     const pa_dbus_receive_cb_t get_all_properties_cb; /* May be NULL, in which case GetAll returns an error. */
  98     const pa_dbus_signal_info *signals; /* NULL, if the interface has no signals. */
  99     unsigned n_signals;
 100 } pa_dbus_interface_info;
 101
 102
 103 /* The following functions may only be called from the main thread. */
 104
 105 /* Registers the given interface to the given object path. It doesn't matter
 106  * whether or not the object has already been registered; if it is, then its
 107  * interface set is extended.
 108  *
 109  * Introspection requests are handled automatically.
 110  *
 111  * Userdata is passed to all the callbacks.
 112  *
 113  * Fails and returns a negative number if the object already has the interface
 114  * registered. */
 115 int pa_dbus_protocol_add_interface(pa_dbus_protocol *p, const char *path, const pa_dbus_interface_info *info, void *userdata);
 116
 117 /* Returns a negative number if the given object doesn't have the given
 118  * interface registered. */
 119 int pa_dbus_protocol_remove_interface(pa_dbus_protocol *p, const char* path, const char* interface);
 120
 121 /* Fails and returns a negative number if the connection is already
 122  * registered. */
 123 int pa_dbus_protocol_register_connection(pa_dbus_protocol *p, DBusConnection *conn, pa_client *client);
 124
 125 /* Returns a negative number if the connection isn't registered. */
 126 int pa_dbus_protocol_unregister_connection(pa_dbus_protocol *p, DBusConnection *conn);
 127
 128 /* Returns NULL if the connection isn't registered. */
 129 pa_client *pa_dbus_protocol_get_client(pa_dbus_protocol *p, DBusConnection *conn);
 130
 131 /* Enables signal receiving for the given connection. The connection must have
 132  * been registered earlier.
 133  *
 134  * If the signal argument is NULL, all signals will be sent to the connection,
 135  * otherwise calling this function only adds the given signal to the list of
 136  * signals that will be delivered to the connection.
 137  *
 138  * The objects argument is a list of object paths. If the list is not empty,
 139  * only signals from the given objects are delivered. If this function is
 140  * called multiple time for the same connection and signal, the latest call
 141  * always replaces the previous object list. */
 142 void pa_dbus_protocol_add_signal_listener(pa_dbus_protocol *p, DBusConnection *conn, const char *signal, char **objects, unsigned n_objects);
 143
 144 /* Disables the delivery of the signal for the given connection. The connection
 145  * must have been registered. If signal is NULL, all signals are disabled. If
 146  * signal is non-NULL and _add_signal_listener() was previously called with
 147  * NULL signal (causing all signals to be enabled), this function doesn't do
 148  * anything. Also, if the signal wasn't enabled before, this function doesn't
 149  * do anything in that case either. */
 150 void pa_dbus_protocol_remove_signal_listener(pa_dbus_protocol *p, DBusConnection *conn, const char *signal);
 151
 152 void pa_dbus_protocol_send_signal(pa_dbus_protocol *p, DBusMessage *signal);
 153
 154 /* Returns an array of extension identifier strings. The strings pointers point
 155  * to the internal copies, so don't free the strings. The caller must free the
 156  * array, however. Also, do not save the returned pointer or any of the string
 157  * pointers, because the contained strings may be freed at any time. If you
 158  * need to save the array, copy it. */
 159 const char **pa_dbus_protocol_get_extensions(pa_dbus_protocol *p, unsigned *n);
 160
 161 /* Modules that want to provide a D-Bus interface for clients should register
 162  * an identifier that the clients can use to check whether the additional
 163  * functionality is available.
 164  *
 165  * This function registers the extension with the given name. It is recommended
 166  * that the name follows the D-Bus interface naming convention, so that the
 167  * names remain unique in case there will be at some point in the future
 168  * extensions that aren't included with the main PulseAudio source tree. For
 169  * in-tree extensions the convention is to use the org.PulseAudio.Ext
 170  * namespace.
 171  *
 172  * It is suggested that the name contains a version number, and whenever the
 173  * extension interface is modified in non-backwards compatible way, the version
 174  * number is incremented.
 175  *
 176  * Fails and returns a negative number if the extension is already registered.
 177  */
 178 int pa_dbus_protocol_register_extension(pa_dbus_protocol *p, const char *name);
 179
 180 /* Returns a negative number if the extension isn't registered. */
 181 int pa_dbus_protocol_unregister_extension(pa_dbus_protocol *p, const char *name);
 182
 183 /* All hooks have the pa_dbus_protocol object as hook data. */
 184 typedef enum pa_dbus_protocol_hook {
 185     PA_DBUS_PROTOCOL_HOOK_EXTENSION_REGISTERED, /* Extension name as call data. */
 186     PA_DBUS_PROTOCOL_HOOK_EXTENSION_UNREGISTERED, /* Extension name as call data. */
 187     PA_DBUS_PROTOCOL_HOOK_MAX
 188 } pa_dbus_protocol_hook_t;
 189
 190 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);
 191
 192 #endif