PipeWire: pipewire/core.h Source File

PipeWire 1.6.8

Loading...
Searching...
No Matches
core.h
Go to the documentation of this file.
1/* PipeWire */
2/* SPDX-FileCopyrightText: Copyright © 2018 Wim Taymans */
3/* SPDX-License-Identifier: MIT */
4
5#ifndef PIPEWIRE_CORE_H
6#define PIPEWIRE_CORE_H
7
8#include <stdarg.h>
9#include <errno.h>
10
11#include <spa/utils/hook.h>
12
13#include <pipewire/type.h>
14
15#ifdef __cplusplus
16extern "C" {
17#endif
18
31
36#define PW_TYPE_INTERFACE_Core PW_TYPE_INFO_INTERFACE_BASE "Core"
37#define PW_TYPE_INTERFACE_Registry PW_TYPE_INFO_INTERFACE_BASE "Registry"
38
39#define PW_CORE_PERM_MASK PW_PERM_R|PW_PERM_X|PW_PERM_M
40
41#define PW_VERSION_CORE 4
42 struct pw_core;
43#define PW_VERSION_REGISTRY 3
44 struct pw_registry;
45
46#ifndef PW_API_CORE_IMPL
47#define PW_API_CORE_IMPL static inline
48#endif
49#ifndef PW_API_REGISTRY_IMPL
50#define PW_API_REGISTRY_IMPL static inline
51#endif
52
54#define PW_DEFAULT_REMOTE "pipewire-0"
55
57#define PW_ID_CORE 0
58
59/* invalid ID that matches any object when used for permissions */
60#define PW_ID_ANY (uint32_t)(0xffffffff)
61
64 struct pw_core_info {
65 uint32_t id;
66 uint32_t cookie;
67 const char *user_name;
68 const char *host_name;
69 const char *version;
70 const char *name;
71#define PW_CORE_CHANGE_MASK_PROPS (1 << 0)
72#define PW_CORE_CHANGE_MASK_ALL ((1 << 1)-1)
73 uint64_t change_mask;
74 struct spa_dict *props;
75};
76
77#include <pipewire/context.h>
78#include <pipewire/properties.h>
79#include <pipewire/proxy.h>
80
81/** Update an existing \ref pw_core_info with \a update with reset. When info is NULL,
82 * a new one will be allocated. Returns NULL on failure. */
83 struct pw_core_info *
84 pw_core_info_update(struct pw_core_info *info,
85 const struct pw_core_info *update);
88struct pw_core_info *
89 pw_core_info_merge(struct pw_core_info *info,
90 const struct pw_core_info *update, bool reset);
92 void pw_core_info_free(struct pw_core_info *info);
93
95
96#define PW_CORE_EVENT_INFO 0
97#define PW_CORE_EVENT_DONE 1
98#define PW_CORE_EVENT_PING 2
99#define PW_CORE_EVENT_ERROR 3
100#define PW_CORE_EVENT_REMOVE_ID 4
101#define PW_CORE_EVENT_BOUND_ID 5
102#define PW_CORE_EVENT_ADD_MEM 6
103#define PW_CORE_EVENT_REMOVE_MEM 7
104#define PW_CORE_EVENT_BOUND_PROPS 8
105#define PW_CORE_EVENT_NUM 9
106
110struct pw_core_events {
111#define PW_VERSION_CORE_EVENTS 1
112 uint32_t version;
113
122 void (*info) (void *data, const struct pw_core_info *info);
131 void (*done) (void *data, uint32_t id, int seq);
132
138 void (*ping) (void *data, uint32_t id, int seq);
139
157 void (*error) (void *data, uint32_t id, int seq, int res, const char *message);
169 void (*remove_id) (void *data, uint32_t id);
170
184 void (*bound_id) (void *data, uint32_t id, uint32_t global_id);
185
200 void (*add_mem) (void *data, uint32_t id, uint32_t type, int fd, uint32_t flags);
201
207 void (*remove_mem) (void *data, uint32_t id);
208
224 void (*bound_props) (void *data, uint32_t id, uint32_t global_id, const struct spa_dict *props);
225};
226
227#define PW_CORE_METHOD_ADD_LISTENER 0
228#define PW_CORE_METHOD_HELLO 1
229#define PW_CORE_METHOD_SYNC 2
230#define PW_CORE_METHOD_PONG 3
231#define PW_CORE_METHOD_ERROR 4
232#define PW_CORE_METHOD_GET_REGISTRY 5
233#define PW_CORE_METHOD_CREATE_OBJECT 6
234#define PW_CORE_METHOD_DESTROY 7
235#define PW_CORE_METHOD_NUM 8
236
245struct pw_core_methods {
246#define PW_VERSION_CORE_METHODS 0
247 uint32_t version;
248
249 int (*add_listener) (void *object,
250 struct spa_hook *listener,
251 const struct pw_core_events *events,
252 void *data);
256
260 int (*hello) (void *object, uint32_t version);
274 int (*sync) (void *object, uint32_t id, int seq);
284 int (*pong) (void *object, uint32_t id, int seq);
303 int (*error) (void *object, uint32_t id, int seq, int res, const char *message);
314 struct pw_registry * (*get_registry) (void *object, uint32_t version,
315 size_t user_data_size);
316
328 void * (*create_object) (void *object,
329 const char *factory_name,
330 const char *type,
331 uint32_t version,
332 const struct spa_dict *props,
333 size_t user_data_size);
343 int (*destroy) (void *object, void *proxy);
344};
345
346
349 PW_API_CORE_IMPL int pw_core_add_listener(struct pw_core *object,
350 struct spa_hook *listener,
351 const struct pw_core_events *events,
352 void *data)
353{
354 return spa_api_method_r(int, -ENOTSUP,
355 pw_core, (struct spa_interface*)object, add_listener, 0,
356 listener, events, data);
357}
360 PW_API_CORE_IMPL int pw_core_hello(struct pw_core *object, uint32_t version)
361{
362 return spa_api_method_r(int, -ENOTSUP,
363 pw_core, (struct spa_interface*)object, hello, 0,
364 version);
365}
368 PW_API_CORE_IMPL int pw_core_sync(struct pw_core *object, uint32_t id, int seq)
369{
370 return spa_api_method_r(int, -ENOTSUP,
371 pw_core, (struct spa_interface*)object, sync, 0,
372 id, seq);
373}
376 PW_API_CORE_IMPL int pw_core_pong(struct pw_core *object, uint32_t id, int seq)
377{
378 return spa_api_method_r(int, -ENOTSUP,
379 pw_core, (struct spa_interface*)object, pong, 0,
380 id, seq);
381}
384 PW_API_CORE_IMPL int pw_core_error(struct pw_core *object, uint32_t id, int seq, int res, const char *message)
385{
386 return spa_api_method_r(int, -ENOTSUP,
387 pw_core, (struct spa_interface*)object, error, 0,
388 id, seq, res, message);
389}
390 PW_API_CORE_IMPL
391 SPA_PRINTF_FUNC(5, 0) int
392pw_core_errorv(struct pw_core *core, uint32_t id, int seq,
393 int res, const char *message, va_list args)
394{
395 char buffer[1024];
396 vsnprintf(buffer, sizeof(buffer), message, args);
397 buffer[1023] = '\0';
398 return pw_core_error(core, id, seq, res, buffer);
399}
400
401 PW_API_CORE_IMPL
402 SPA_PRINTF_FUNC(5, 6) int
403pw_core_errorf(struct pw_core *core, uint32_t id, int seq,
404 int res, const char *message, ...)
405{
406 va_list args;
407 int r;
408 va_start(args, message);
409 r = pw_core_errorv(core, id, seq, res, message, args);
410 va_end(args);
411 return r;
412}
413
414
416 PW_API_CORE_IMPL struct pw_registry *
417 pw_core_get_registry(struct pw_core *core, uint32_t version, size_t user_data_size)
418{
419 return spa_api_method_r(struct pw_registry*, NULL,
420 pw_core, (struct spa_interface*)core, get_registry, 0,
421 version, user_data_size);
422}
424 * \sa pw_core_methods.create_object */
425 PW_API_CORE_IMPL void *
426 pw_core_create_object(struct pw_core *core,
427 const char *factory_name,
428 const char *type,
429 uint32_t version,
430 const struct spa_dict *props,
431 size_t user_data_size)
432{
433 return spa_api_method_r(void*, NULL,
434 pw_core, (struct spa_interface*)core, create_object, 0,
435 factory_name, type, version, props, user_data_size);
436}
439 PW_API_CORE_IMPL void
440 pw_core_destroy(struct pw_core *core, void *proxy)
441{
442 spa_api_method_v(pw_core, (struct spa_interface*)core, destroy, 0,
443 proxy);
444}
445
449
457 * objects such as the core.
458 *
459 * When a client creates a registry object, the registry object
460 * will emit a global event for each global currently in the
461 * registry. Globals come and go as a result of device hotplugs or
462 * reconfiguration or other events, and the registry will send out
463 * global and global_remove events to keep the client up to date
464 * with the changes. To mark the end of the initial burst of
465 * events, the client can use the pw_core.sync methosd immediately
466 * after calling pw_core.get_registry.
467 *
468 * A client can bind to a global object by using the bind
469 * request. This creates a client-side proxy that lets the object
470 * emit events to the client and lets the client invoke methods on
471 * the object. See \ref page_proxy
472 *
473 * Clients can also change the permissions of the global objects that
474 * it can see. This is interesting when you want to configure a
475 * pipewire session before handing it to another application. You
476 * can, for example, hide certain existing or new objects or limit
477 * the access permissions on an object.
478 */
479
480/**
481 * \addtogroup pw_registry
482 * \{
483 */
484
485#define PW_REGISTRY_EVENT_GLOBAL 0
486#define PW_REGISTRY_EVENT_GLOBAL_REMOVE 1
487#define PW_REGISTRY_EVENT_NUM 2
488
490struct pw_registry_events {
491#define PW_VERSION_REGISTRY_EVENTS 0
492 uint32_t version;
505 void (*global) (void *data, uint32_t id,
506 uint32_t permissions, const char *type, uint32_t version,
507 const struct spa_dict *props);
517 void (*global_remove) (void *data, uint32_t id);
518};
519
520#define PW_REGISTRY_METHOD_ADD_LISTENER 0
521#define PW_REGISTRY_METHOD_BIND 1
522#define PW_REGISTRY_METHOD_DESTROY 2
523#define PW_REGISTRY_METHOD_NUM 3
524
526 struct pw_registry_methods {
527#define PW_VERSION_REGISTRY_METHODS 0
528 uint32_t version;
529
530 int (*add_listener) (void *object,
531 struct spa_hook *listener,
532 const struct pw_registry_events *events,
533 void *data);
546 void * (*bind) (void *object, uint32_t id, const char *type, uint32_t version,
547 size_t use_data_size);
548
557 int (*destroy) (void *object, uint32_t id);
558};
559
560
563
564 PW_API_REGISTRY_IMPL int pw_registry_add_listener(struct pw_registry *registry,
565 struct spa_hook *listener,
566 const struct pw_registry_events *events,
567 void *data)
568{
569 return spa_api_method_r(int, -ENOTSUP,
570 pw_registry, (struct spa_interface*)registry, add_listener, 0,
571 listener, events, data);
572}
574 * \sa pw_registry_methods.bind */
575 PW_API_REGISTRY_IMPL void *
576 pw_registry_bind(struct pw_registry *registry,
577 uint32_t id, const char *type, uint32_t version,
578 size_t user_data_size)
579{
580 return spa_api_method_r(void*, NULL,
581 pw_registry, (struct spa_interface*)registry, bind, 0,
582 id, type, version, user_data_size);
583}
586 PW_API_REGISTRY_IMPL int
587 pw_registry_destroy(struct pw_registry *registry, uint32_t id)
588{
589 return spa_api_method_r(int, -ENOTSUP,
590 pw_registry, (struct spa_interface*)registry, destroy, 0, id);
591}
592
596
601
608
612struct pw_core *
613 pw_context_connect(struct pw_context *context,
614 struct pw_properties *properties,
615 size_t user_data_size);
616
622
625 *
626 * \return a \ref pw_core on success or NULL with errno set on error */
627struct pw_core *
628 pw_context_connect_fd(struct pw_context *context,
629 int fd,
630 struct pw_properties *properties,
631 size_t user_data_size);
632
633
636 * \param properties optional properties, ownership of the properties is
637 * taken.
638 * \param user_data_size extra user data size
639 *
640 * \return a \ref pw_core on success or NULL with errno set on error */
641struct pw_core *
642 pw_context_connect_self(struct pw_context *context,
643 struct pw_properties *properties,
644 size_t user_data_size);
645
648int pw_core_steal_fd(struct pw_core *core);
649
652int pw_core_set_paused(struct pw_core *core, bool paused);
653
655int pw_core_disconnect(struct pw_core *core);
656
659void *pw_core_get_user_data(struct pw_core *core);
660
663struct pw_client * pw_core_get_client(struct pw_core *core);
664
666struct pw_context * pw_core_get_context(struct pw_core *core);
667
669const struct pw_properties *pw_core_get_properties(struct pw_core *core);
670
674int pw_core_update_properties(struct pw_core *core, const struct spa_dict *dict);
675
677struct pw_mempool * pw_core_get_mempool(struct pw_core *core);
678
680struct pw_proxy *pw_core_find_proxy(struct pw_core *core, uint32_t id);
681
683struct pw_proxy *pw_core_export(struct pw_core *core,
684 const char *type,
685 const struct spa_dict *props,
686 void *object,
687 size_t user_data_size );
688
692
693#ifdef __cplusplus
694}
695#endif
696
697#endif /* PIPEWIRE_CORE_H */
pw_core_get_context
struct pw_context * pw_core_get_context(struct pw_core *core)
Get the context object used to created this core.
Definition core.c:142
args
uint32_t int int const char va_list args
Definition core.h:434
pw_core_find_proxy
struct pw_proxy * pw_core_find_proxy(struct pw_core *core, uint32_t id)
Get the proxy with the given id.
Definition core.c:279
pw_core_pong
PW_API_CORE_IMPL int pw_core_pong(struct pw_core *object, uint32_t id, int seq)
Reply to a server ping event.
Definition core.h:416
va_end
va_end(args)
pw_context_connect
struct pw_core * pw_context_connect(struct pw_context *context, struct pw_properties *properties, size_t user_data_size)
Connect to a PipeWire instance.
Definition core.c:410
pw_core_get_mempool
struct pw_mempool * pw_core_get_mempool(struct pw_core *core)
Get the core mempool object.
Definition core.c:491
pw_core_get_properties
const struct pw_properties * pw_core_get_properties(struct pw_core *core)
Get properties from the core.
Definition core.c:148
pw_core_add_listener
PW_API_CORE_IMPL int pw_core_add_listener(struct pw_core *object, struct spa_hook *listener, const struct pw_core_events *events, void *data)
Definition core.h:389
seq
uint32_t int seq
Definition core.h:432
pw_core_destroy
PW_API_CORE_IMPL void pw_core_destroy(struct pw_core *core, void *proxy)
Destroy an resource.
Definition core.h:480
pw_context_connect_self
struct pw_core * pw_context_connect_self(struct pw_context *context, struct pw_properties *properties, size_t user_data_size)
Connect to a given PipeWire instance.
Definition core.c:462
pw_core_get_client
struct pw_client * pw_core_get_client(struct pw_core *core)
Get the client proxy of the connected core.
Definition core.c:273
vsnprintf
vsnprintf(buffer, sizeof(buffer), message, args)
PW_API_REGISTRY_IMPL
#define PW_API_REGISTRY_IMPL
Definition core.h:64
pw_core_create_object
PW_API_CORE_IMPL void * pw_core_create_object(struct pw_core *core, const char *factory_name, const char *type, uint32_t version, const struct spa_dict *props, size_t user_data_size)
Create a new object on the PipeWire server from a factory.
Definition core.h:466
pw_core_get_registry
PW_API_CORE_IMPL struct pw_registry * pw_core_get_registry(struct pw_core *core, uint32_t version, size_t user_data_size)
Get the registry object.
Definition core.h:457
pw_core_get_user_data
void * pw_core_get_user_data(struct pw_core *core)
Get the user_data.
Definition core.c:172
pw_core_update_properties
int pw_core_update_properties(struct pw_core *core, const struct spa_dict *dict)
Update the core properties.
Definition core.c:154
pw_core_export
struct pw_proxy * pw_core_export(struct pw_core *core, const char *type, const struct spa_dict *props, void *object, size_t user_data_size)
Export an object into the PipeWire instance associated with core.
Definition core.c:285
pw_core_disconnect
int pw_core_disconnect(struct pw_core *core)
disconnect and destroy a core
Definition core.c:506
pw_core_steal_fd
int pw_core_steal_fd(struct pw_core *core)
Steal the fd of the core connection or < 0 on error.
Definition core.c:476
PW_API_CORE_IMPL
#define PW_API_CORE_IMPL
Definition core.h:60
id
uint32_t id
Definition core.h:432
message
uint32_t int int const char * message
Definition core.h:433
r
uint32_t int int const char int r
Definition core.h:447
res
uint32_t int int res
Definition core.h:433
pw_core_set_paused
int pw_core_set_paused(struct pw_core *core, bool paused)
Pause or resume the core.
Definition core.c:484
pw_core_info_free
void pw_core_info_free(struct pw_core_info *info)
Free a pw_core_info.
Definition introspect.c:147
pw_core_sync
PW_API_CORE_IMPL int pw_core_sync(struct pw_core *object, uint32_t id, int seq)
Do server roundtrip.
Definition core.h:408
va_start
va_start(args, message)
pw_context_connect_fd
struct pw_core * pw_context_connect_fd(struct pw_context *context, int fd, struct pw_properties *properties, size_t user_data_size)
Connect to a PipeWire instance on the given socket.
Definition core.c:437
pw_core_info_merge
struct pw_core_info * pw_core_info_merge(struct pw_core_info *info, const struct pw_core_info *update, bool reset)
Update an existing pw_core_info with update.
Definition introspect.c:109
pw_core_info_update
struct pw_core_info * pw_core_info_update(struct pw_core_info *info, const struct pw_core_info *update)
Update an existing pw_core_info with update with reset.
Definition introspect.c:140
pw_core_error
PW_API_CORE_IMPL int pw_core_error(struct pw_core *object, uint32_t id, int seq, int res, const char *message)
Fatal error event.
Definition core.h:424
pw_core_hello
PW_API_CORE_IMPL int pw_core_hello(struct pw_core *object, uint32_t version)
Start a conversation with the server.
Definition core.h:400
pw_registry_add_listener
PW_API_REGISTRY_IMPL int pw_registry_add_listener(struct pw_registry *registry, struct spa_hook *listener, const struct pw_registry_events *events, void *data)
Registry.
Definition core.h:613
pw_registry_destroy
PW_API_REGISTRY_IMPL int pw_registry_destroy(struct pw_registry *registry, uint32_t id)
Attempt to destroy a global object.
Definition core.h:636
pw_registry_bind
PW_API_REGISTRY_IMPL void * pw_registry_bind(struct pw_registry *registry, uint32_t id, const char *type, uint32_t version, size_t user_data_size)
Bind to a global object.
Definition core.h:625
spa_api_method_r
#define spa_api_method_r(rtype, def, type, o, method, version,...)
Definition hook.h:291
spa_api_method_v
#define spa_api_method_v(type, o, method, version,...)
Definition hook.h:285
SPA_PRINTF_FUNC
#define SPA_PRINTF_FUNC(fmt, arg1)
Definition defs.h:297
hook.h
spa/utils/hook.h
properties.h
pipewire/properties.h
proxy.h
pipewire/proxy.h
context.h
pipewire/context.h
type.h
pipewire/type.h
pw_client
pw_context
pw_core_events
Core events.
Definition core.h:139
pw_core_events::ping
void(* ping)(void *data, uint32_t id, int seq)
Emit a ping event.
Definition core.h:168
pw_core_events::remove_mem
void(* remove_mem)(void *data, uint32_t id)
Remove memory for a client.
Definition core.h:237
pw_core_events::error
void(* error)(void *data, uint32_t id, int seq, int res, const char *message)
Fatal error event.
Definition core.h:187
pw_core_events::add_mem
void(* add_mem)(void *data, uint32_t id, uint32_t type, int fd, uint32_t flags)
Add memory for a client.
Definition core.h:230
pw_core_events::bound_props
void(* bound_props)(void *data, uint32_t id, uint32_t global_id, const struct spa_dict *props)
Notify an object binding.
Definition core.h:254
pw_core_events::remove_id
void(* remove_id)(void *data, uint32_t id)
Remove an object ID.
Definition core.h:199
pw_core_events::version
uint32_t version
Definition core.h:142
pw_core_events::bound_id
void(* bound_id)(void *data, uint32_t id, uint32_t global_id)
Notify an object binding.
Definition core.h:214
pw_core_events::done
void(* done)(void *data, uint32_t id, int seq)
Emit a done event.
Definition core.h:161
pw_core_info
The core information.
Definition core.h:81
pw_core_info::change_mask
uint64_t change_mask
bitfield of changed fields since last call
Definition core.h:92
pw_core_info::version
const char * version
version of the core
Definition core.h:86
pw_core_info::cookie
uint32_t cookie
a random cookie for identifying this instance of PipeWire
Definition core.h:83
pw_core_info::user_name
const char * user_name
name of the user that started the core
Definition core.h:84
pw_core_info::host_name
const char * host_name
name of the machine the core is running on
Definition core.h:85
pw_core_methods
Core methods.
Definition core.h:284
pw_core_methods::add_listener
int(* add_listener)(void *object, struct spa_hook *listener, const struct pw_core_events *events, void *data)
Definition core.h:289
pw_core_methods::pong
int(* pong)(void *object, uint32_t id, int seq)
Reply to a server ping event.
Definition core.h:324
pw_core_methods::destroy
int(* destroy)(void *object, void *proxy)
Destroy an resource.
Definition core.h:383
pw_core_methods::hello
int(* hello)(void *object, uint32_t version)
Start a conversation with the server.
Definition core.h:300
pw_core_methods::error
int(* error)(void *object, uint32_t id, int seq, int res, const char *message)
Fatal error event.
Definition core.h:343
pw_core_methods::sync
int(* sync)(void *object, uint32_t id, int seq)
Do server roundtrip.
Definition core.h:314
pw_core_methods::version
uint32_t version
Definition core.h:287
pw_core
pw_mempool
A memory pool is a collection of pw_memblocks.
Definition mem.h:66
pw_properties
Definition properties.h:39
pw_properties::dict
struct spa_dict dict
dictionary of key/values
Definition properties.h:40
pw_proxy
pw_registry_events
Registry events.
Definition core.h:533
pw_registry_events::global_remove
void(* global_remove)(void *data, uint32_t id)
Notify of a global object removal.
Definition core.h:561
pw_registry_events::global
void(* global)(void *data, uint32_t id, uint32_t permissions, const char *type, uint32_t version, const struct spa_dict *props)
Notify of a new global object.
Definition core.h:549
pw_registry_events::version
uint32_t version
Definition core.h:536
pw_registry_methods
Registry methods.
Definition core.h:574
pw_registry_methods::bind
void *(* bind)(void *object, uint32_t id, const char *type, uint32_t version, size_t use_data_size)
Bind to a global object.
Definition core.h:595
pw_registry_methods::version
uint32_t version
Definition core.h:577
pw_registry_methods::add_listener
int(* add_listener)(void *object, struct spa_hook *listener, const struct pw_registry_events *events, void *data)
Definition core.h:579
pw_registry_methods::destroy
int(* destroy)(void *object, uint32_t id)
Attempt to destroy a global object.
Definition core.h:606
pw_registry
spa_dict
Definition dict.h:51
spa_hook
A hook, contains the structure with functions and the data passed to the functions.
Definition hook.h:427
spa_interface
Definition hook.h:148