1 /* PipeWire 2 * 3 * Copyright © 2018 Wim Taymans 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_GLOBAL_H 26 #define PIPEWIRE_GLOBAL_H 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 /** \page page_global Global 33 * 34 * Global objects represent resources that are available on the PipeWire 35 * context and are accessible to remote clients. 36 * Globals come and go when devices or other resources become available for 37 * clients. 38 * 39 * Remote clients receives a list of globals when it binds to the registry 40 * object. See \ref page_registry. 41 * 42 * A client can bind to a global to send methods or receive events from 43 * the global. 44 */ 45 /** \class pw_global 46 * 47 * \brief A global object visible to remote clients 48 * 49 * A global object is visible to remote clients and represents a resource 50 * that can be used or inspected. 51 * 52 * See \ref page_remote_api 53 */ 54 struct pw_global; 55 56 #include <pipewire/impl.h> 57 58 typedef int (*pw_global_bind_func_t) (void *object, 59 struct pw_impl_client *client, /**< client that binds */ 60 uint32_t permissions, /**< permissions for the bind */ 61 uint32_t version, /**< client interface version */ 62 uint32_t id /**< client proxy id */); 63 64 /** Global events, use \ref pw_global_add_listener */ 65 struct pw_global_events { 66 #define PW_VERSION_GLOBAL_EVENTS 0 67 uint32_t version; 68 69 /** The global is destroyed */ 70 void (*destroy) (void *data); 71 /** The global is freed */ 72 void (*free) (void *data); 73 /** The permissions changed for a client */ 74 void (*permissions_changed) (void *data, 75 struct pw_impl_client *client, 76 uint32_t old_permissions, 77 uint32_t new_permissions); 78 }; 79 80 /** Create a new global object */ 81 struct pw_global * 82 pw_global_new(struct pw_context *context, /**< the context */ 83 const char *type, /**< the interface type of the global */ 84 uint32_t version, /**< the interface version of the global */ 85 struct pw_properties *properties, /**< extra properties */ 86 pw_global_bind_func_t func, /**< function to bind */ 87 void *object /**< global object */); 88 89 /** Register a global object to the context registry */ 90 int pw_global_register(struct pw_global *global); 91 92 /** Add an event listener on the global */ 93 void pw_global_add_listener(struct pw_global *global, 94 struct spa_hook *listener, 95 const struct pw_global_events *events, 96 void *data); 97 98 /** Get the permissions of the global for a given client */ 99 uint32_t pw_global_get_permissions(struct pw_global *global, struct pw_impl_client *client); 100 101 /** Get the context object of this global */ 102 struct pw_context *pw_global_get_context(struct pw_global *global); 103 104 /** Get the global type */ 105 const char *pw_global_get_type(struct pw_global *global); 106 107 /** Check a global type */ 108 bool pw_global_is_type(struct pw_global *global, const char *type); 109 110 /** Get the global version */ 111 uint32_t pw_global_get_version(struct pw_global *global); 112 113 /** Get the global properties */ 114 const struct pw_properties *pw_global_get_properties(struct pw_global *global); 115 116 /** Update the global properties, must be done when unregistered */ 117 int pw_global_update_keys(struct pw_global *global, 118 const struct spa_dict *dict, const char *keys[]); 119 120 /** Get the object associated with the global. This depends on the type of the 121 * global */ 122 void *pw_global_get_object(struct pw_global *global); 123 124 /** Get the unique id of the global */ 125 uint32_t pw_global_get_id(struct pw_global *global); 126 127 /** Add a resource to a global */ 128 int pw_global_add_resource(struct pw_global *global, struct pw_resource *resource); 129 130 /** Iterate all resources added to the global The callback should return 131 * 0 to fetch the next item, any other value stops the iteration and returns 132 * the value. When all callbacks return 0, this function returns 0 when all 133 * items are iterated. */ 134 int pw_global_for_each_resource(struct pw_global *global, 135 int (*callback) (void *data, struct pw_resource *resource), 136 void *data); 137 138 /** Let a client bind to a global */ 139 int pw_global_bind(struct pw_global *global, 140 struct pw_impl_client *client, 141 uint32_t permissions, 142 uint32_t version, 143 uint32_t id); 144 145 int pw_global_update_permissions(struct pw_global *global, struct pw_impl_client *client, 146 uint32_t old_permissions, uint32_t new_permissions); 147 148 /** Destroy a global */ 149 void pw_global_destroy(struct pw_global *global); 150 151 #ifdef __cplusplus 152 } 153 #endif 154 155 #endif /* PIPEWIRE_GLOBAL_H */ 156