session.h (15517B) - Raw
1 #ifndef __XPC_SESSION_H__ 2 #define __XPC_SESSION_H__ 3 4 #ifndef __XPC_INDIRECT__ 5 #error "Please #include <xpc/xpc.h> instead of this file directly." 6 // For HeaderDoc. 7 #include <xpc/base.h> 8 #endif // __XPC_INDIRECT__ 9 10 #ifndef __BLOCKS__ 11 #error "XPC Session require Blocks support." 12 #endif // __BLOCKS__ 13 14 XPC_ASSUME_NONNULL_BEGIN 15 __BEGIN_DECLS 16 17 /*! 18 * @define XPC_TYPE_SESSION 19 * 20 * @discussion 21 * Sessions represent a stateful connection between a client and a service. When either end of the connection 22 * disconnects, the entire session will be invalidated. In this case the system will make no attempt to 23 * reestablish the connection or relaunch the service. 24 * 25 * Clients can initiate a session with a service that accepts xpc_connection_t connections but session 26 * semantics will be maintained. 27 * 28 */ 29 OS_OBJECT_DECL_CLASS(xpc_session); 30 31 #pragma mark Constants 32 /*! 33 * @typedef xpc_session_create_flags_t 34 * Constants representing different options available when creating an XPC 35 * Session. 36 * 37 * @const XPC_SESSION_CREATE_INACTIVE 38 * Indicates that the session should not be activated during its creation. The 39 * returned session must be manually activated using 40 * {@link xpc_session_activate} before it can be used. 41 * 42 * @const XPC_SESSION_CREATE_MACH_PRIVILEGED 43 * Passed to {@link xpc_session_create_mach_service} to indicate that the job 44 * advertising the service name in its launchd.plist(5) should be in the 45 * privileged Mach bootstrap. This is typically accomplished by placing your 46 * launchd.plist(5) in /Library/LaunchDaemons. 47 */ 48 XPC_SWIFT_NOEXPORT 49 XPC_FLAGS_ENUM(xpc_session_create_flags, uint64_t, 50 XPC_SESSION_CREATE_NONE XPC_SWIFT_NAME("none") = 0, 51 XPC_SESSION_CREATE_INACTIVE XPC_SWIFT_NAME("inactive") = (1 << 0), 52 XPC_SESSION_CREATE_MACH_PRIVILEGED XPC_SWIFT_NAME("privileged") = (1 << 1) 53 ); 54 55 #pragma mark Handlers 56 typedef void (^xpc_session_cancel_handler_t)(xpc_rich_error_t error) XPC_SWIFT_NOEXPORT; 57 typedef void (^xpc_session_incoming_message_handler_t)(xpc_object_t message) XPC_SWIFT_NOEXPORT; 58 typedef void (^xpc_session_reply_handler_t)(xpc_object_t _Nullable reply, 59 xpc_rich_error_t _Nullable error) XPC_SWIFT_NOEXPORT; 60 61 #pragma mark Helpers 62 /*! 63 * @function xpc_session_copy_description 64 * Copy the string description of the session. 65 * 66 * @param session 67 * The session to be examined. 68 * 69 * @result 70 * The underlying C string description for the provided session. This string 71 * should be disposed of with free(3) when done. This will return NULL if a 72 * string description could not be generated. 73 */ 74 API_AVAILABLE(macos(13.0), ios(16.0), tvos(16.0), watchos(9.0)) 75 XPC_EXPORT XPC_SWIFT_NOEXPORT XPC_WARN_RESULT 76 char * _Nullable 77 xpc_session_copy_description(xpc_session_t session); 78 79 #pragma mark Client Session Creation 80 /*! 81 * @function xpc_session_create_xpc_service 82 * Creates a new session object representing a connection to the named service. 83 * 84 * @param name 85 * The name of the service to create a session with. 86 * 87 * @param target_queue 88 * The GCD queue onto which session events will be submitted. This may be a 89 * concurrent queue. This parameter may be NULL, in which case the target queue 90 * will be libdispatch's default target queue, defined as 91 * DISPATCH_TARGET_QUEUE_DEFAULT. 92 * 93 * @param flags 94 * Additional attributes which which to create the session. 95 * 96 * @param error_out 97 * An out-parameter that, if set and in the event of an error, will point to an 98 * {@link xpc_rich_error_t} describing the details of any errors that occurred. 99 * 100 * @result 101 * On success this returns a new session object. The returned session is 102 * activated by default and can be used to send messages. The caller is 103 * responsible for disposing of the returned object with {@link xpc_release} 104 * when it is no longer needed. On failure this will return NULL and if set, 105 * error_out will be set to an error describing the failure. 106 * 107 * @discussion 108 * This will fail if the specified XPC service is either not found or is 109 * unavailable. 110 */ 111 API_AVAILABLE(macos(13.0), macCatalyst(16.0)) 112 API_UNAVAILABLE(ios, tvos, watchos) 113 XPC_EXPORT XPC_SWIFT_NOEXPORT XPC_RETURNS_RETAINED XPC_WARN_RESULT 114 xpc_session_t _Nullable 115 xpc_session_create_xpc_service(const char *name, 116 dispatch_queue_t _Nullable target_queue, 117 xpc_session_create_flags_t flags, 118 xpc_rich_error_t _Nullable * _Nullable error_out); 119 120 /*! 121 * @function xpc_session_create_mach_service 122 * Creates a session with the service defined by the provided Mach service name. 123 * 124 * @param mach_service 125 * The Mach service to create a session with. The service name must exist in the 126 * Mach bootstrap that is accessible to the process and be advertised in a 127 * launchd.plist. 128 * 129 * @param target_queue 130 * The GCD queue onto which session events will be submitted. This may be a 131 * concurrent queue. This parameter may be NULL, in which case the target queue 132 * will be libdispatch's default target queue, defined as 133 * DISPATCH_TARGET_QUEUE_DEFAULT. 134 * 135 * @param flags 136 * Additional attributes which which to create the session. 137 * 138 * @param error_out 139 * An out-parameter that, if set and in the event of an error, will point to an 140 * {@link xpc_rich_error_t} describing the details of any errors that occurred. 141 * 142 * @result 143 * On success this returns a new session object. The returned session is 144 * activated by default and can be used to send messages. The caller is 145 * responsible for disposing of the returned object with {@link xpc_release} 146 * when it is no longer needed. On failure this will return NULL and if set, 147 * error_out will be set to an error describing the failure. 148 * 149 * @discussion 150 * This will fail if the specified Mach service is either not found in the 151 * bootstrap or is otherwise unavailable. 152 * 153 */ 154 API_AVAILABLE(macos(13.0), macCatalyst(16.0)) 155 API_UNAVAILABLE(ios, tvos, watchos) 156 XPC_EXPORT XPC_SWIFT_NOEXPORT XPC_RETURNS_RETAINED XPC_WARN_RESULT 157 xpc_session_t _Nullable 158 xpc_session_create_mach_service(const char *mach_service, 159 dispatch_queue_t _Nullable target_queue, 160 xpc_session_create_flags_t flags, 161 xpc_rich_error_t _Nullable * _Nullable error_out); 162 163 #pragma mark Session Configuration 164 /*! 165 * @function xpc_session_set_incoming_message_handler 166 * Set an incoming message handler for a session. 167 * 168 * @param session 169 * The session to set the handler for. 170 * 171 * @param handler 172 * The handler block to be called when a message originated by the peer is 173 * received through the provided session. 174 * 175 * @discussion 176 * This can only be called on an inactive session. Calling this on a session 177 * with an existing event handler will replace it. 178 */ 179 API_AVAILABLE(macos(13.0), ios(16.0), tvos(16.0), watchos(9.0)) 180 XPC_EXPORT XPC_SWIFT_NOEXPORT 181 void 182 xpc_session_set_incoming_message_handler(xpc_session_t session, 183 xpc_session_incoming_message_handler_t handler); 184 185 /*! 186 * @function xpc_session_set_cancel_handler 187 * Set the cancel handler for a session. 188 * 189 * @param session 190 * The session to set the cancel handler for. 191 * 192 * @param cancel_handler 193 * The cancel handler block that will be executed when this session is canceled. 194 * 195 * @discussion 196 * This can only be called on an inactive session. Calling this on a session 197 * with an existing cancel handler will replace the existing cancel handler with 198 * the one provided. 199 */ 200 API_AVAILABLE(macos(13.0), ios(16.0), tvos(16.0), watchos(9.0)) 201 XPC_EXPORT XPC_SWIFT_NOEXPORT 202 void 203 xpc_session_set_cancel_handler(xpc_session_t session, 204 xpc_session_cancel_handler_t cancel_handler); 205 206 /*! 207 * @function xpc_session_set_target_queue 208 * Set the target queue for a session. 209 * 210 * @param session 211 * The session to set the target queue for. 212 * 213 * @param target_queue 214 * The GCD queue onto which session events will be submitted. This may be a 215 * concurrent queue. This parameter may be NULL, in which case the target queue 216 * will be libdispatch's default target queue, defined as 217 * DISPATCH_TARGET_QUEUE_DEFAULT. 218 * 219 * @discussion 220 * This can only be called on an inactive session. Calling this on a session 221 * with an existing target queue will replace the existing target queue with 222 * the one provided. 223 */ 224 API_AVAILABLE(macos(14.0), ios(17.0), tvos(17.0), watchos(10.0)) 225 XPC_EXPORT XPC_SWIFT_NOEXPORT 226 void 227 xpc_session_set_target_queue(xpc_session_t session, 228 dispatch_queue_t _Nullable target_queue); 229 230 #pragma mark Lifecycle 231 /*! 232 * @function xpc_session_activate 233 * Activates a session. 234 * 235 * @param session 236 * The session object to activate. 237 * 238 * @param error_out 239 * An out-parameter that, if set and in the event of an error, will point to an 240 * {@link xpc_rich_error_t} describing the details of any errors that occurred. 241 * 242 * @result 243 * Returns whether session activation succeeded. 244 * 245 * @discussion 246 * xpc_session_activate must not be called on a session that has been already 247 * activated. Releasing the last reference on an inactive session that was 248 * created with an xpc_session_create*() will trigger an API misuse crash. 249 * 250 * If activation fails, the session is automatically cancelled. 251 */ 252 API_AVAILABLE(macos(13.0), ios(16.0), tvos(16.0), watchos(9.0)) 253 XPC_EXPORT XPC_SWIFT_NOEXPORT 254 bool 255 xpc_session_activate(xpc_session_t session, 256 xpc_rich_error_t _Nullable * _Nullable error_out); 257 258 /*! 259 * @function xpc_session_cancel 260 * Cancels the session. After this call, any messages that have not yet been 261 * sent will be discarded, and the connection will be unwound. If there are 262 * messages that are awaiting replies, they will have their reply handlers 263 * invoked with an appropriate {@link xpc_rich_error_t}. 264 * 265 * @param session 266 * The session object to cancel. 267 * 268 * @discussion 269 * Session must have been activated to be canceled. Cancellation is asynchronous 270 * and non-preemptive. 271 */ 272 API_AVAILABLE(macos(13.0), ios(16.0), tvos(16.0), watchos(9.0)) 273 XPC_EXPORT XPC_SWIFT_NOEXPORT 274 void 275 xpc_session_cancel(xpc_session_t session); 276 277 #pragma mark Message Send 278 /*! 279 * @function xpc_session_send_message 280 * Sends a message over the session to the destination service. 281 * 282 * @param session 283 * The session to send the message over. 284 * 285 * @param message 286 * The message to send. This must be a dictionary object. 287 * 288 * @result 289 * In the event of an error this will return an {@link xpc_rich_error_t} 290 * detailing the reasons for the failure. On success this return value will be 291 * NULL. 292 * 293 * @discussion 294 * Messages are delivered in FIFO order. This API is safe to call from multiple 295 * GCD queues. There is no indication that a message was delivered successfully. 296 * This is because even once the message has been successfully enqueued on the 297 * remote end, there are no guarantees about when the runtime will dequeue the 298 * message and invoke the other session's event handler block. 299 * 300 * If this is invoked on an inactive session, one created using the 301 * XPC_SESSION_CREATE_INACTIVE flag and hasn't yet been activated, the process 302 * will crash. 303 */ 304 API_AVAILABLE(macos(13.0), ios(16.0), tvos(16.0), watchos(9.0)) 305 XPC_EXPORT XPC_SWIFT_NOEXPORT XPC_RETURNS_RETAINED XPC_WARN_RESULT 306 xpc_rich_error_t _Nullable 307 xpc_session_send_message(xpc_session_t session, xpc_object_t message); 308 309 /*! 310 * @function xpc_session_send_message_with_reply_sync 311 * Sends a message over the session to the destination service and blocks the 312 * caller until a reply is received. 313 * 314 * @param session 315 * The session over which the message will be sent. 316 * 317 * @param message 318 * The message to send. This must be a dictionary object. 319 * 320 * @param error_out 321 * If this parameter is provided, in the event of a failure it will point to an 322 * {@link xpc_rich_error_t} describing the details of the error. 323 * 324 * @result 325 * On success, this will return the reply message as an {@link xpc_object_t}. 326 * Otherwise NULL is returned. 327 * 328 * @discussion 329 * This API supports priority inversion avoidance and should be used instead of 330 * combining xpc_session_send_message_with_reply_async with a semaphore. 331 * 332 * If this is invoked on an inactive session, for example one created using the 333 * XPC_SESSION_CREATE_INACTIVE flag that hasn't yet been activated, the process 334 * will crash. 335 * 336 * Invoking this API while the target queue is blocked would lead to deadlocks 337 * in certain scenarios. For that reason, invoking it from the target queue 338 * results in a crash. 339 * 340 * Be judicious about your use of this API. It can block indefinitely, so if you 341 * are using it to implement an API that can be called from the main queue, you 342 * may wish to consider allowing the API to take a queue and callback block so 343 * that results may be delivered asynchronously if possible. 344 */ 345 API_AVAILABLE(macos(13.0), ios(16.0), tvos(16.0), watchos(9.0)) 346 XPC_EXPORT XPC_SWIFT_NOEXPORT XPC_RETURNS_RETAINED XPC_WARN_RESULT 347 xpc_object_t _Nullable 348 xpc_session_send_message_with_reply_sync(xpc_session_t session, 349 xpc_object_t message, xpc_rich_error_t _Nullable * _Nullable error_out); 350 351 /*! 352 * @function xpc_session_send_message_with_reply_async 353 * Sends a message over the session to the destination service and executes the 354 * provided callback when a reply is received. 355 * 356 * @param session 357 * The session over which the message will be sent. 358 * 359 * @param message 360 * The message to send. This must be a dictionary object. 361 * 362 * @param reply_handler 363 * The handler block to invoke when a reply to the message is received from the 364 * session. If the session is torn down before the reply was received, for 365 * example if the remote service exits prematurely, this handler will be 366 * executed and passed an appropriate {@link xpc_rich_error_t} object describing 367 * the failure. 368 * 369 * @discussion 370 * If this is invoked on an inactive session, for example one created using the 371 * XPC_SESSION_CREATE_INACTIVE flag that hasn't yet been activated, the process 372 * will crash. 373 * 374 * If this is invoked on a cancelled session, this will generate a simulated 375 * crash. 376 */ 377 API_AVAILABLE(macos(13.0), ios(16.0), tvos(16.0), watchos(9.0)) 378 XPC_EXPORT XPC_SWIFT_NOEXPORT 379 void 380 xpc_session_send_message_with_reply_async(xpc_session_t session, 381 xpc_object_t message, xpc_session_reply_handler_t reply_handler); 382 383 /*! 384 * @function xpc_session_set_peer_code_signing_requirement 385 * Requires that the session peer satisfies a code signing requirement. 386 * 387 * @param session 388 * The session object which is to be modified. 389 * 390 * @param requirement 391 * The code signing requirement to be satisfied by the peer 392 * It is safe to deallocate the requirement string after calling `xpc_session_set_peer_code_signing_requirement` 393 * 394 * @result 395 * 0 on success, non-zero on error 396 * 397 * @discussion 398 * This function will return an error promptly if the code signing requirement string is invalid. 399 * 400 * It is a programming error to call `xpc_session_set_peer_code_signing_requirement` more than once per session. 401 * 402 * All messages received on this session will be checked to ensure they come from a peer who satisfies 403 * the code signing requirement. When message or a reply is received on the session and the peer does 404 * not satisfy the requirement the session will be cancelled. 405 * 406 * @see https://developer.apple.com/documentation/technotes/tn3127-inside-code-signing-requirements 407 */ 408 API_AVAILABLE(macos(14.4)) 409 API_UNAVAILABLE(ios, tvos, watchos) 410 XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT 411 int 412 xpc_session_set_peer_code_signing_requirement(xpc_session_t session, const char *requirement); 413 414 /* This is included for compatibility and should not be used in new code */ 415 #define XPC_TYPE_SESSION (&_xpc_type_session) 416 XPC_EXPORT 417 XPC_TYPE(_xpc_type_session); 418 419 __END_DECLS 420 XPC_ASSUME_NONNULL_END 421 422 #endif // __XPC_SESSION_H__