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