PipeWire  1.3.83
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 #ifdef __cplusplus
9 extern "C" {
10 #endif
11 
12 #include <stdarg.h>
13 #include <errno.h>
14 
15 #include <spa/utils/hook.h>
16 
17 #include <pipewire/type.h>
18 
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 
78 #include <pipewire/properties.h>
79 #include <pipewire/proxy.h>
80 
83 struct pw_core_info *
85  const struct pw_core_info *update);
88 struct pw_core_info *
90  const struct pw_core_info *update, bool reset);
92 void pw_core_info_free(struct pw_core_info *info);
93 
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 
110 struct 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 
245 struct 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);
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 
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 }
391 SPA_PRINTF_FUNC(5, 0) int
392 pw_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 
402 SPA_PRINTF_FUNC(5, 6) int
403 pw_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;
409  r = pw_core_errorv(core, id, seq, res, message, args);
410  va_end(args);
411  return r;
412 }
413 
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 }
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 
485 #define PW_REGISTRY_EVENT_GLOBAL 0
486 #define PW_REGISTRY_EVENT_GLOBAL_REMOVE 1
487 #define PW_REGISTRY_EVENT_NUM 2
488 
490 struct 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 
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 
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 }
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 }
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 
612 struct pw_core *
614  struct pw_properties *properties,
615  size_t user_data_size);
616 
627 struct 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 
641 struct pw_core *
642 pw_context_connect_self(struct pw_context *context,
643  struct pw_properties *properties,
644  size_t user_data_size);
645 
648 int pw_core_steal_fd(struct pw_core *core);
649 
652 int pw_core_set_paused(struct pw_core *core, bool paused);
653 
655 int pw_core_disconnect(struct pw_core *core);
656 
659 void *pw_core_get_user_data(struct pw_core *core);
660 
663 struct pw_client * pw_core_get_client(struct pw_core *core);
664 
666 struct pw_context * pw_core_get_context(struct pw_core *core);
667 
669 const struct pw_properties *pw_core_get_properties(struct pw_core *core);
670 
674 int pw_core_update_properties(struct pw_core *core, const struct spa_dict *dict);
675 
677 struct pw_mempool * pw_core_get_mempool(struct pw_core *core);
678 
680 struct pw_proxy *pw_core_find_proxy(struct pw_core *core, uint32_t id);
681 
683 struct 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 
693 #ifdef __cplusplus
694 }
695 #endif
696 
697 #endif /* PIPEWIRE_CORE_H */
uint32_t int int const char va_list args
Definition: core.h:434
buffer[1023]
Definition: core.h:437
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(args)
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
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
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_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
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:108
uint32_t int seq
Definition: core.h:432
PW_API_CORE_IMPL void pw_core_destroy(struct pw_core *core, void *proxy)
Destroy an resource.
Definition: core.h:480
struct pw_client * pw_core_get_client(struct pw_core *core)
Get the client proxy of the connected core.
Definition: core.c:273
void * pw_core_get_user_data(struct pw_core *core)
Get the user_data.
Definition: core.c:172
struct pw_mempool * pw_core_get_mempool(struct pw_core *core)
Get the core mempool object.
Definition: core.c:491
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:139
vsnprintf(buffer, sizeof(buffer), message, args)
#define PW_API_REGISTRY_IMPL
Definition: core.h:64
int pw_core_update_properties(struct pw_core *core, const struct spa_dict *dict)
Update the core properties.
Definition: core.c:154
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
int pw_core_disconnect(struct pw_core *core)
disconnect and destroy a core
Definition: core.c:506
int pw_core_steal_fd(struct pw_core *core)
Steal the fd of the core connection or < 0 on error.
Definition: core.c:476
#define PW_API_CORE_IMPL
Definition: core.h:60
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
uint32_t id
Definition: core.h:432
uint32_t int int const char * message
Definition: core.h:433
struct pw_context * pw_core_get_context(struct pw_core *core)
Get the context object used to created this core.
Definition: core.c:142
uint32_t int int const char int r
Definition: core.h:445
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
const struct pw_properties * pw_core_get_properties(struct pw_core *core)
Get properties from the core.
Definition: core.c:148
uint32_t int int res
Definition: core.h:433
int pw_core_set_paused(struct pw_core *core, bool paused)
Pause or resume the core.
Definition: core.c:484
void pw_core_info_free(struct pw_core_info *info)
Free a pw_core_info
Definition: introspect.c:146
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(args, message)
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_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_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_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
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_API_REGISTRY_IMPL int pw_registry_destroy(struct pw_registry *registry, uint32_t id)
Attempt to destroy a global object.
Definition: core.h:636
#define spa_api_method_r(rtype, def, type, o, method, version,...)
Definition: hook.h:291
#define spa_api_method_v(type, o, method, version,...)
Definition: hook.h:285
#define SPA_PRINTF_FUNC(fmt, arg1)
Definition: defs.h:295
spa/utils/hook.h
pipewire/properties.h
pipewire/proxy.h
pipewire/context.h
pipewire/type.h
Core events.
Definition: core.h:139
void(* ping)(void *data, uint32_t id, int seq)
Emit a ping event.
Definition: core.h:168
void(* remove_mem)(void *data, uint32_t id)
Remove memory for a client.
Definition: core.h:237
void(* error)(void *data, uint32_t id, int seq, int res, const char *message)
Fatal error event.
Definition: core.h:187
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
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
void(* info)(void *data, const struct pw_core_info *info)
Notify new core info.
Definition: core.h:152
void(* remove_id)(void *data, uint32_t id)
Remove an object ID.
Definition: core.h:199
uint32_t version
Definition: core.h:142
void(* bound_id)(void *data, uint32_t id, uint32_t global_id)
Notify an object binding.
Definition: core.h:214
void(* done)(void *data, uint32_t id, int seq)
Emit a done event.
Definition: core.h:161
The core information.
Definition: core.h:81
uint64_t change_mask
bitfield of changed fields since last call
Definition: core.h:92
const char * version
version of the core
Definition: core.h:86
uint32_t cookie
a random cookie for identifying this instance of PipeWire
Definition: core.h:83
uint32_t id
id of the global
Definition: core.h:82
const char * user_name
name of the user that started the core
Definition: core.h:84
const char * host_name
name of the machine the core is running on
Definition: core.h:85
Core methods.
Definition: core.h:284
int(* add_listener)(void *object, struct spa_hook *listener, const struct pw_core_events *events, void *data)
Definition: core.h:289
int(* pong)(void *object, uint32_t id, int seq)
Reply to a server ping event.
Definition: core.h:324
int(* destroy)(void *object, void *proxy)
Destroy an resource.
Definition: core.h:383
int(* hello)(void *object, uint32_t version)
Start a conversation with the server.
Definition: core.h:300
int(* error)(void *object, uint32_t id, int seq, int res, const char *message)
Fatal error event.
Definition: core.h:343
int(* sync)(void *object, uint32_t id, int seq)
Do server roundtrip.
Definition: core.h:314
uint32_t version
Definition: core.h:287
A memory pool is a collection of pw_memblocks.
Definition: mem.h:63
Definition: properties.h:39
struct spa_dict dict
dictionary of key/values
Definition: properties.h:40
Registry events.
Definition: core.h:533
void(* global_remove)(void *data, uint32_t id)
Notify of a global object removal.
Definition: core.h:561
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
uint32_t version
Definition: core.h:536
Registry methods.
Definition: core.h:574
uint32_t version
Definition: core.h:577
int(* add_listener)(void *object, struct spa_hook *listener, const struct pw_registry_events *events, void *data)
Definition: core.h:579
int(* destroy)(void *object, uint32_t id)
Attempt to destroy a global object.
Definition: core.h:606
Definition: dict.h:51
A hook, contains the structure with functions and the data passed to the functions.
Definition: hook.h:427
Definition: hook.h:148