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_IMPL_CLIENT_H 26 #define PIPEWIRE_IMPL_CLIENT_H 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 #include <spa/utils/hook.h> 33 34 /** \class pw_impl_client 35 * 36 * \brief PipeWire client object class. 37 * 38 * The client object represents a client connection with the PipeWire 39 * server. 40 * 41 * Each client has its own list of resources it is bound to along with 42 * a mapping between the client types and server types. 43 */ 44 struct pw_impl_client; 45 46 #include <pipewire/context.h> 47 #include <pipewire/global.h> 48 #include <pipewire/properties.h> 49 #include <pipewire/resource.h> 50 #include <pipewire/permission.h> 51 52 /** \page page_client Client 53 * 54 * \section sec_page_client_overview Overview 55 * 56 * The \ref pw_impl_client object is created by a protocol implementation when 57 * a new client connects. 58 * 59 * The client is used to keep track of all resources belonging to one 60 * connection with the PipeWire server. 61 * 62 * \section sec_page_client_credentials Credentials 63 * 64 * The client object will have its credentials filled in by the protocol. 65 * This information is used to check if a resource or action is available 66 * for this client. See also \ref page_access 67 * 68 * \section sec_page_client_types Types 69 * 70 * The client and server maintain a mapping between the client and server 71 * types. All type ids that are in messages exchanged between the client 72 * and server will automatically be remapped. See also \ref page_types. 73 * 74 * \section sec_page_client_resources Resources 75 * 76 * When a client binds to context global object, a resource is made for this 77 * binding and a unique id is assigned to the resources. The client and 78 * server will use this id as the destination when exchanging messages. 79 * See also \ref page_resource 80 */ 81 82 /** The events that a client can emit */ 83 struct pw_impl_client_events { 84 #define PW_VERSION_IMPL_CLIENT_EVENTS 0 85 uint32_t version; 86 87 /** emitted when the client is destroyed */ 88 void (*destroy) (void *data); 89 90 /** emitted right before the client is freed */ 91 void (*free) (void *data); 92 93 /** the client is initialized */ 94 void (*initialized) (void *data); 95 96 /** emitted when the client info changed */ 97 void (*info_changed) (void *data, const struct pw_client_info *info); 98 99 /** emitted when a new resource is added for client */ 100 void (*resource_added) (void *data, struct pw_resource *resource); 101 102 /** emitted when a resource is removed */ 103 void (*resource_removed) (void *data, struct pw_resource *resource); 104 105 /** emitted when the client becomes busy processing an asynchronous 106 * message. In the busy state no messages should be processed. 107 * Processing should resume when the client becomes not busy */ 108 void (*busy_changed) (void *data, bool busy); 109 }; 110 111 /** Create a new client. This is mainly used by protocols. */ 112 struct pw_impl_client * 113 pw_context_create_client(struct pw_impl_core *core, /**< the core object */ 114 struct pw_protocol *prototol, /**< the client protocol */ 115 struct pw_properties *properties, /**< client properties */ 116 size_t user_data_size /**< extra user data size */); 117 118 /** Destroy a previously created client */ 119 void pw_impl_client_destroy(struct pw_impl_client *client); 120 121 /** Finish configuration and register a client */ 122 int pw_impl_client_register(struct pw_impl_client *client, /**< the client to register */ 123 struct pw_properties *properties/**< extra properties */); 124 125 /** Get the client user data */ 126 void *pw_impl_client_get_user_data(struct pw_impl_client *client); 127 128 /** Get the client information */ 129 const struct pw_client_info *pw_impl_client_get_info(struct pw_impl_client *client); 130 131 /** Update the client properties */ 132 int pw_impl_client_update_properties(struct pw_impl_client *client, const struct spa_dict *dict); 133 134 /** Update the client permissions */ 135 int pw_impl_client_update_permissions(struct pw_impl_client *client, uint32_t n_permissions, 136 const struct pw_permission *permissions); 137 138 /** check if a client has permissions for global_id, Since 0.3.9 */ 139 int pw_impl_client_check_permissions(struct pw_impl_client *client, 140 uint32_t global_id, uint32_t permissions); 141 142 /** Get the client properties */ 143 const struct pw_properties *pw_impl_client_get_properties(struct pw_impl_client *client); 144 145 /** Get the context used to create this client */ 146 struct pw_context *pw_impl_client_get_context(struct pw_impl_client *client); 147 /** Get the protocol used to create this client */ 148 struct pw_protocol *pw_impl_client_get_protocol(struct pw_impl_client *client); 149 150 /** Get the client core resource */ 151 struct pw_resource *pw_impl_client_get_core_resource(struct pw_impl_client *client); 152 153 /** Get a resource with the given id */ 154 struct pw_resource *pw_impl_client_find_resource(struct pw_impl_client *client, uint32_t id); 155 156 /** Get the global associated with this client */ 157 struct pw_global *pw_impl_client_get_global(struct pw_impl_client *client); 158 159 /** listen to events from this client */ 160 void pw_impl_client_add_listener(struct pw_impl_client *client, 161 struct spa_hook *listener, 162 const struct pw_impl_client_events *events, 163 void *data); 164 165 166 /** Mark the client busy. This can be used when an asynchronous operation is 167 * started and no further processing is allowed to happen for the client */ 168 void pw_impl_client_set_busy(struct pw_impl_client *client, bool busy); 169 170 #ifdef __cplusplus 171 } 172 #endif 173 174 #endif /* PIPEWIRE_IMPL_CLIENT_H */ 175