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