1 /* PipeWire 2 * 3 * Copyright © 2016 Wim Taymans <wim.taymans@gmail.com> 4 * 5 * Permission is hereby granted, free of charge, to any person obtaining a 6 * copy of this software and associated documentation files (the "Software"), 7 * to deal in the Software without restriction, including without limitation 8 * the rights to use, copy, modify, merge, publish, distribute, sublicense, 9 * and/or sell copies of the Software, and to permit persons to whom the 10 * Software is furnished to do so, subject to the following conditions: 11 * 12 * The above copyright notice and this permission notice (including the next 13 * paragraph) shall be included in all copies or substantial portions of the 14 * Software. 15 * 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 19 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 22 * DEALINGS IN THE SOFTWARE. 23 */ 24 25 #ifndef PIPEWIRE_INTERFACES_V0_H 26 #define PIPEWIRE_INTERFACES_V0_H 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 #include <spa/utils/defs.h> 33 #include <spa/param/param.h> 34 #include <spa/node/node.h> 35 36 #include <pipewire/pipewire.h> 37 38 /** Core */ 39 40 #define PW_VERSION_CORE_V0 0 41 42 #define PW_CORE_V0_METHOD_HELLO 0 43 #define PW_CORE_V0_METHOD_UPDATE_TYPES 1 44 #define PW_CORE_V0_METHOD_SYNC 2 45 #define PW_CORE_V0_METHOD_GET_REGISTRY 3 46 #define PW_CORE_V0_METHOD_CLIENT_UPDATE 4 47 #define PW_CORE_V0_METHOD_PERMISSIONS 5 48 #define PW_CORE_V0_METHOD_CREATE_OBJECT 6 49 #define PW_CORE_V0_METHOD_DESTROY 7 50 #define PW_CORE_V0_METHOD_NUM 8 51 52 /** 53 * Key to update default permissions of globals without specific 54 * permissions. value is "[r][w][x]" */ 55 #define PW_CORE_PERMISSIONS_DEFAULT "permissions.default" 56 57 /** 58 * Key to update specific permissions of a global. If the global 59 * did not have specific permissions, it will first be assigned 60 * the default permissions before it is updated. 61 * Value is "<global-id>:[r][w][x]"*/ 62 #define PW_CORE_PERMISSIONS_GLOBAL "permissions.global" 63 64 /** 65 * Key to update specific permissions of all existing globals. 66 * This is equivalent to using \ref PW_CORE_PERMISSIONS_GLOBAL 67 * on each global id individually that did not have specific 68 * permissions. 69 * Value is "[r][w][x]" */ 70 #define PW_CORE_PERMISSIONS_EXISTING "permissions.existing" 71 72 #define PW_LINK_OUTPUT_NODE_ID "link.output_node.id" 73 #define PW_LINK_OUTPUT_PORT_ID "link.output_port.id" 74 #define PW_LINK_INPUT_NODE_ID "link.input_node.id" 75 #define PW_LINK_INPUT_PORT_ID "link.input_port.id" 76 77 /** 78 * \struct pw_core_v0_methods 79 * \brief Core methods 80 * 81 * The core global object. This is a singleton object used for 82 * creating new objects in the remote PipeWire instance. It is 83 * also used for internal features. 84 */ 85 struct pw_core_v0_methods { 86 #define PW_VERSION_CORE_V0_METHODS 0 87 uint32_t version; 88 /** 89 * Start a conversation with the server. This will send 90 * the core info and server types. 91 * 92 * All the existing resources for the client (except the core 93 * resource) will be destroyed. 94 */ 95 void (*hello) (void *object); 96 /** 97 * Update the type map 98 * 99 * Send a type map update to the PipeWire server. The server uses this 100 * information to keep a mapping between client types and the server types. 101 * \param first_id the id of the first type 102 * \param types the types as a string 103 * \param n_types the number of types 104 */ 105 void (*update_types) (void *object, 106 uint32_t first_id, 107 const char **types, 108 uint32_t n_types); 109 /** 110 * Do server roundtrip 111 * 112 * Ask the server to emit the 'done' event with \a id. 113 * Since methods are handled in-order and events are delivered 114 * in-order, this can be used as a barrier to ensure all previous 115 * methods and the resulting events have been handled. 116 * \param seq the sequence number passed to the done event 117 */ 118 void (*sync) (void *object, uint32_t seq); 119 /** 120 * Get the registry object 121 * 122 * Create a registry object that allows the client to list and bind 123 * the global objects available from the PipeWire server 124 * \param version the client proxy id 125 * \param id the client proxy id 126 */ 127 void (*get_registry) (void *object, uint32_t version, uint32_t new_id); 128 /** 129 * Update the client properties 130 * \param props the new client properties 131 */ 132 void (*client_update) (void *object, const struct spa_dict *props); 133 /** 134 * Manage the permissions of the global objects 135 * 136 * Update the permissions of the global objects using the 137 * dictionary with properties. 138 * 139 * Globals can use the default permissions or can have specific 140 * permissions assigned to them. 141 * 142 * \param id the global id to change 143 * \param props dictionary with permission properties 144 */ 145 void (*permissions) (void *object, const struct spa_dict *props); 146 /** 147 * Create a new object on the PipeWire server from a factory. 148 * Use a \a factory_name of "client-node" to create a 149 * \ref pw_client_node. 150 * 151 * \param factory_name the factory name to use 152 * \param type the interface to bind to 153 * \param version the version of the interface 154 * \param props extra properties 155 * \param new_id the client proxy id 156 */ 157 void (*create_object) (void *object, 158 const char *factory_name, 159 uint32_t type, 160 uint32_t version, 161 const struct spa_dict *props, 162 uint32_t new_id); 163 164 /** 165 * Destroy an object id 166 * 167 * \param id the object id to destroy 168 */ 169 void (*destroy) (void *object, uint32_t id); 170 }; 171 172 #define PW_CORE_V0_EVENT_UPDATE_TYPES 0 173 #define PW_CORE_V0_EVENT_DONE 1 174 #define PW_CORE_V0_EVENT_ERROR 2 175 #define PW_CORE_V0_EVENT_REMOVE_ID 3 176 #define PW_CORE_V0_EVENT_INFO 4 177 #define PW_CORE_V0_EVENT_NUM 5 178 179 /** \struct pw_core_v0_events 180 * \brief Core events 181 * \ingroup pw_core_interface The pw_core interface 182 */ 183 struct pw_core_v0_events { 184 #define PW_VERSION_CORE_V0_EVENTS 0 185 uint32_t version; 186 /** 187 * Update the type map 188 * 189 * Send a type map update to the client. The client uses this 190 * information to keep a mapping between server types and the client types. 191 * \param first_id the id of the first type 192 * \param types the types as a string 193 * \param n_types the number of \a types 194 */ 195 void (*update_types) (void *object, 196 uint32_t first_id, 197 const char **types, 198 uint32_t n_types); 199 /** 200 * Emit a done event 201 * 202 * The done event is emitted as a result of a sync method with the 203 * same sequence number. 204 * \param seq the sequence number passed to the sync method call 205 */ 206 void (*done) (void *object, uint32_t seq); 207 /** 208 * Fatal error event 209 * 210 * The error event is sent out when a fatal (non-recoverable) 211 * error has occurred. The id argument is the object where 212 * the error occurred, most often in response to a request to that 213 * object. The message is a brief description of the error, 214 * for (debugging) convenience. 215 * \param id object where the error occurred 216 * \param res error code 217 * \param error error description 218 */ 219 void (*error) (void *object, uint32_t id, int res, const char *error, ...); 220 /** 221 * Remove an object ID 222 * 223 * This event is used internally by the object ID management 224 * logic. When a client deletes an object, the server will send 225 * this event to acknowledge that it has seen the delete request. 226 * When the client receives this event, it will know that it can 227 * safely reuse the object ID. 228 * \param id deleted object ID 229 */ 230 void (*remove_id) (void *object, uint32_t id); 231 /** 232 * Notify new core info 233 * 234 * \param info new core info 235 */ 236 void (*info) (void *object, struct pw_core_info *info); 237 }; 238 239 #define pw_core_resource_v0_update_types(r,...) pw_resource_notify(r,struct pw_core_v0_events,update_types,__VA_ARGS__) 240 #define pw_core_resource_v0_done(r,...) pw_resource_notify(r,struct pw_core_v0_events,done,__VA_ARGS__) 241 #define pw_core_resource_v0_error(r,...) pw_resource_notify(r,struct pw_core_v0_events,error,__VA_ARGS__) 242 #define pw_core_resource_v0_remove_id(r,...) pw_resource_notify(r,struct pw_core_v0_events,remove_id,__VA_ARGS__) 243 #define pw_core_resource_v0_info(r,...) pw_resource_notify(r,struct pw_core_v0_events,info,__VA_ARGS__) 244 245 246 #define PW_VERSION_REGISTRY_V0 0 247 248 /** \page page_registry Registry 249 * 250 * \section page_registry_overview Overview 251 * 252 * The registry object is a singleton object that keeps track of 253 * global objects on the PipeWire instance. See also \ref page_global. 254 * 255 * Global objects typically represent an actual object in PipeWire 256 * (for example, a module or node) or they are singleton 257 * objects such as the core. 258 * 259 * When a client creates a registry object, the registry object 260 * will emit a global event for each global currently in the 261 * registry. Globals come and go as a result of device hotplugs or 262 * reconfiguration or other events, and the registry will send out 263 * global and global_remove events to keep the client up to date 264 * with the changes. To mark the end of the initial burst of 265 * events, the client can use the pw_core.sync methosd immediately 266 * after calling pw_core.get_registry. 267 * 268 * A client can bind to a global object by using the bind 269 * request. This creates a client-side proxy that lets the object 270 * emit events to the client and lets the client invoke methods on 271 * the object. See \ref page_proxy 272 * 273 * Clients can also change the permissions of the global objects that 274 * it can see. This is interesting when you want to configure a 275 * pipewire session before handing it to another application. You 276 * can, for example, hide certain existing or new objects or limit 277 * the access permissions on an object. 278 */ 279 #define PW_REGISTRY_V0_METHOD_BIND 0 280 #define PW_REGISTRY_V0_METHOD_NUM 1 281 282 /** Registry methods */ 283 struct pw_registry_v0_methods { 284 #define PW_VERSION_REGISTRY_V0_METHODS 0 285 uint32_t version; 286 /** 287 * Bind to a global object 288 * 289 * Bind to the global object with \a id and use the client proxy 290 * with new_id as the proxy. After this call, methods can be 291 * send to the remote global object and events can be received 292 * 293 * \param id the global id to bind to 294 * \param type the interface type to bind to 295 * \param version the interface version to use 296 * \param new_id the client proxy to use 297 */ 298 void (*bind) (void *object, uint32_t id, uint32_t type, uint32_t version, uint32_t new_id); 299 }; 300 301 #define PW_REGISTRY_V0_EVENT_GLOBAL 0 302 #define PW_REGISTRY_V0_EVENT_GLOBAL_REMOVE 1 303 #define PW_REGISTRY_V0_EVENT_NUM 2 304 305 /** Registry events */ 306 struct pw_registry_v0_events { 307 #define PW_VERSION_REGISTRY_V0_EVENTS 0 308 uint32_t version; 309 /** 310 * Notify of a new global object 311 * 312 * The registry emits this event when a new global object is 313 * available. 314 * 315 * \param id the global object id 316 * \param parent_id the parent global id 317 * \param permissions the permissions of the object 318 * \param type the type of the interface 319 * \param version the version of the interface 320 * \param props extra properties of the global 321 */ 322 void (*global) (void *object, uint32_t id, uint32_t parent_id, 323 uint32_t permissions, uint32_t type, uint32_t version, 324 const struct spa_dict *props); 325 /** 326 * Notify of a global object removal 327 * 328 * Emitted when a global object was removed from the registry. 329 * If the client has any bindings to the global, it should destroy 330 * those. 331 * 332 * \param id the id of the global that was removed 333 */ 334 void (*global_remove) (void *object, uint32_t id); 335 }; 336 337 #define pw_registry_resource_v0_global(r,...) pw_resource_notify(r,struct pw_registry_v0_events,global,__VA_ARGS__) 338 #define pw_registry_resource_v0_global_remove(r,...) pw_resource_notify(r,struct pw_registry_v0_events,global_remove,__VA_ARGS__) 339 340 341 #define PW_VERSION_MODULE_V0 0 342 343 #define PW_MODULE_V0_EVENT_INFO 0 344 #define PW_MODULE_V0_EVENT_NUM 1 345 346 /** Module events */ 347 struct pw_module_v0_events { 348 #define PW_VERSION_MODULE_V0_EVENTS 0 349 uint32_t version; 350 /** 351 * Notify module info 352 * 353 * \param info info about the module 354 */ 355 void (*info) (void *object, struct pw_module_info *info); 356 }; 357 358 #define pw_module_resource_v0_info(r,...) pw_resource_notify(r,struct pw_module_v0_events,info,__VA_ARGS__) 359 360 #define PW_VERSION_NODE_V0 0 361 362 #define PW_NODE_V0_EVENT_INFO 0 363 #define PW_NODE_V0_EVENT_PARAM 1 364 #define PW_NODE_V0_EVENT_NUM 2 365 366 /** Node events */ 367 struct pw_node_v0_events { 368 #define PW_VERSION_NODE_V0_EVENTS 0 369 uint32_t version; 370 /** 371 * Notify node info 372 * 373 * \param info info about the node 374 */ 375 void (*info) (void *object, struct pw_node_info *info); 376 /** 377 * Notify a node param 378 * 379 * Event emitted as a result of the enum_params method. 380 * 381 * \param id the param id 382 * \param index the param index 383 * \param next the param index of the next param 384 * \param param the parameter 385 */ 386 void (*param) (void *object, 387 uint32_t id, uint32_t index, uint32_t next, 388 const struct spa_pod *param); 389 }; 390 391 #define pw_node_resource_v0_info(r,...) pw_resource_notify(r,struct pw_node_v0_events,info,__VA_ARGS__) 392 #define pw_node_resource_v0_param(r,...) pw_resource_notify(r,struct pw_node_v0_events,param,__VA_ARGS__) 393 394 #define PW_NODE_V0_METHOD_ENUM_PARAMS 0 395 #define PW_NODE_V0_METHOD_NUM 1 396 397 /** Node methods */ 398 struct pw_node_v0_methods { 399 #define PW_VERSION_NODE_V0_METHODS 0 400 uint32_t version; 401 /** 402 * Enumerate node parameters 403 * 404 * Start enumeration of node parameters. For each param, a 405 * param event will be emitted. 406 * 407 * \param id the parameter id to enum or PW_ID_ANY for all 408 * \param start the start index or 0 for the first param 409 * \param num the maximum number of params to retrieve 410 * \param filter a param filter or NULL 411 */ 412 void (*enum_params) (void *object, uint32_t id, uint32_t start, uint32_t num, 413 const struct spa_pod *filter); 414 }; 415 416 #define PW_VERSION_PORT_V0 0 417 418 #define PW_PORT_V0_EVENT_INFO 0 419 #define PW_PORT_V0_EVENT_PARAM 1 420 #define PW_PORT_V0_EVENT_NUM 2 421 422 /** Port events */ 423 struct pw_port_v0_events { 424 #define PW_VERSION_PORT_V0_EVENTS 0 425 uint32_t version; 426 /** 427 * Notify port info 428 * 429 * \param info info about the port 430 */ 431 void (*info) (void *object, struct pw_port_info *info); 432 /** 433 * Notify a port param 434 * 435 * Event emitted as a result of the enum_params method. 436 * 437 * \param id the param id 438 * \param index the param index 439 * \param next the param index of the next param 440 * \param param the parameter 441 */ 442 void (*param) (void *object, 443 uint32_t id, uint32_t index, uint32_t next, 444 const struct spa_pod *param); 445 }; 446 447 #define pw_port_resource_v0_info(r,...) pw_resource_notify(r,struct pw_port_v0_events,info,__VA_ARGS__) 448 #define pw_port_resource_v0_param(r,...) pw_resource_notify(r,struct pw_port_v0_events,param,__VA_ARGS__) 449 450 #define PW_PORT_V0_METHOD_ENUM_PARAMS 0 451 #define PW_PORT_V0_METHOD_NUM 1 452 453 /** Port methods */ 454 struct pw_port_v0_methods { 455 #define PW_VERSION_PORT_V0_METHODS 0 456 uint32_t version; 457 /** 458 * Enumerate port parameters 459 * 460 * Start enumeration of port parameters. For each param, a 461 * param event will be emitted. 462 * 463 * \param id the parameter id to enumerate 464 * \param start the start index or 0 for the first param 465 * \param num the maximum number of params to retrieve 466 * \param filter a param filter or NULL 467 */ 468 void (*enum_params) (void *object, uint32_t id, uint32_t start, uint32_t num, 469 const struct spa_pod *filter); 470 }; 471 472 #define PW_VERSION_FACTORY_V0 0 473 474 #define PW_FACTORY_V0_EVENT_INFO 0 475 #define PW_FACTORY_V0_EVENT_NUM 1 476 477 /** Factory events */ 478 struct pw_factory_v0_events { 479 #define PW_VERSION_FACTORY_V0_EVENTS 0 480 uint32_t version; 481 /** 482 * Notify factory info 483 * 484 * \param info info about the factory 485 */ 486 void (*info) (void *object, struct pw_factory_info *info); 487 }; 488 489 #define pw_factory_resource_v0_info(r,...) pw_resource_notify(r,struct pw_factory_v0_events,info,__VA_ARGS__) 490 491 #define PW_VERSION_CLIENT_V0 0 492 493 #define PW_CLIENT_V0_EVENT_INFO 0 494 #define PW_CLIENT_V0_EVENT_NUM 1 495 496 /** Client events */ 497 struct pw_client_v0_events { 498 #define PW_VERSION_CLIENT_V0_EVENTS 0 499 uint32_t version; 500 /** 501 * Notify client info 502 * 503 * \param info info about the client 504 */ 505 void (*info) (void *object, struct pw_client_info *info); 506 }; 507 508 #define pw_client_resource_v0_info(r,...) pw_resource_notify(r,struct pw_client_v0_events,info,__VA_ARGS__) 509 510 511 #define PW_VERSION_LINK_V0 0 512 513 #define PW_LINK_V0_EVENT_INFO 0 514 #define PW_LINK_V0_EVENT_NUM 1 515 516 /** Link events */ 517 struct pw_link_v0_events { 518 #define PW_VERSION_LINK_V0_EVENTS 0 519 uint32_t version; 520 /** 521 * Notify link info 522 * 523 * \param info info about the link 524 */ 525 void (*info) (void *object, struct pw_link_info *info); 526 }; 527 528 #define pw_link_resource_v0_info(r,...) pw_resource_notify(r,struct pw_link_v0_events,info,__VA_ARGS__) 529 530 #ifdef __cplusplus 531 } /* extern "C" */ 532 #endif 533 534 #endif /* PIPEWIRE_INTERFACES_V0_H */ 535