xpc/listener.h

@typedef xpc_listener_t @discussion Listeners represent the server side variant of an XPC Session. Listeners are activated and then begin receiving `xpc_session_t` from peers attempting to connect to the server.

OS_OBJECT_DECL_SENDABLE_CLASS(xpc_listener)

API_AVAILABLE(macos(14.0), macCatalyst(17.0)) API_UNAVAILABLE(ios, tvos, watchos) XPC_EXPORT XPC_SWIFT_NOEXPORT XPC_WARN_RESULT char * _Nullable xpc_listener_copy_description(
	xpc_listener_t listener
)

@function xpc_listener_copy_description Copy the string description of the listener. @param listener The listener to be examined. @result The underlying C string description for the provided session. This string should be disposed of with free(3) when done. This will return NULL if a string description could not be generated.

API_AVAILABLE(macos(14.0), macCatalyst(17.0)) API_UNAVAILABLE(ios, tvos, watchos) XPC_EXPORT XPC_SWIFT_NOEXPORT XPC_RETURNS_RETAINED XPC_WARN_RESULT xpc_listener_t _Nullable xpc_listener_create(
	const char * service,
	dispatch_queue_t _Nullable target_queue,
	xpc_listener_create_flags_t flags,
	xpc_listener_incoming_session_handler_t incoming_session_handler,
	xpc_rich_error_t _Nullable XPC_GIVES_REFERENCE * _Nullable error_out
)

@function xpc_listener_create Creates a listener with the service defined by the provided name. @param service The Mach service or XPC Service name to create the listener with. @param target_queue The GCD queue onto which listener events will be submitted. This may be a concurrent queue. This parameter may be NULL, in which case the target queue will be libdispatch's default target queue, defined as DISPATCH_TARGET_QUEUE_DEFAULT. @param flags Additional attributes to create the listener. @param incoming_session_handler The handler block to be called when a peer is attempting to establish a connection with this listener. The incoming session handler is mandatory. Unlike XPC connection listeners that require explicit acceptance, xpc_listener automatically accepts and activates incoming peer sessions when the incoming_session_handler returns, unless the peer session was explicitly rejected using xpc_listener_reject_peer() or cancelled using xpc_session_cancel(). @param error_out An out-parameter that, if set and in the event of an error, will point to an {@link xpc_rich_error_t} describing the details of any errors that occurred. @result On success this returns a new listener object. The returned listener is activated by default and will begin receiving incoming session requests. The caller is responsible for disposing of the returned object with {@link xpc_release} when it is no longer needed. On failure this will return NULL and if set, error_out will be set to an error describing the failure. @discussion This will fail if the specified XPC service is either not found or is unavailable. When the `incoming_session_handler` returns, the peer session will be automatically activated unless the peer session was explicitly cancelled. Before the `incoming_session_handler` returns it must set a message handler on the peer session using `xpc_session_set_incoming_message_handler` or cancel the session using `xpc_session_cancel`. Failure to take one of these two actions will result in an API misuse crash.

API_AVAILABLE(macos(14.0), macCatalyst(17.0)) API_UNAVAILABLE(ios, tvos, watchos) XPC_EXPORT XPC_SWIFT_NOEXPORT bool xpc_listener_activate(
	xpc_listener_t listener,
	xpc_rich_error_t _Nullable XPC_GIVES_REFERENCE * _Nullable error_out
)

@function xpc_listener_activate Activates a listener. @param listener The listener object to activate. @param error_out An out-parameter that, if set and in the event of an error, will point to an {@link xpc_rich_error_t} describing the details of any errors that occurred. @result Returns whether listener activation succeeded. @discussion xpc_listener_activate must not be called on a listener that has been already activated. Releasing the last reference on an inactive listener that was created with an xpc_listener_create() is undefined.

API_AVAILABLE(macos(14.0), macCatalyst(17.0)) API_UNAVAILABLE(ios, tvos, watchos) XPC_EXPORT XPC_SWIFT_NOEXPORT void xpc_listener_cancel(
	xpc_listener_t listener
)

@function xpc_listener_cancel Cancels a listener. @param listener The listener object to cancel. @discussion Cancellation is asynchronous and non-preemptive. Cancelling a listener will cause peers attempting to connect to the service to hang. In general, a listener does not need to be explicitly cancelled and the process can safely terminate without cancelling the listener.

API_AVAILABLE(macos(14.0), macCatalyst(17.0)) API_UNAVAILABLE(ios, tvos, watchos) XPC_EXPORT XPC_SWIFT_NOEXPORT void xpc_listener_reject_peer(
	xpc_session_t peer,
	const char *reason
)

@function xpc_listener_reject_peer Rejects the incoming peer session. @param peer The peer session object to reject. This must be a session that was an argument from an incoming session handler block. @param reason The reason that the peer was rejected. @discussion The peer session will be cancelled and cannot be used after it has been rejected. An incoming session that is not rejected will automatically be accepted after returning from the incoming peer handler.

API_AVAILABLE(macos(14.4)) API_UNAVAILABLE(ios, tvos, watchos) XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT int xpc_listener_set_peer_code_signing_requirement(
	xpc_listener_t listener,
	const char *requirement
)

@function xpc_listener_set_peer_code_signing_requirement Requires that the listener peer satisfies a code signing requirement. @param listener The listener object which is to be modified. @param requirement The code signing requirement to be satisfied by the peer. It is safe to deallocate the requirement string after calling this function. @result 0 on success, non-zero on error @discussion This function will return an error promptly if the code signing requirement string is invalid. It is a programming error to call `xpc_listener_set_peer_*requirement` more than once per listener. All messages received on this listener will be checked to ensure they come from a peer who satisfies the code signing requirement. Requests that do not satisfy the requirement are dropped. @see https://developer.apple.com/documentation/technotes/tn3127-inside-code-signing-requirements

API_AVAILABLE(macos(26.0), ios(26.0)) API_UNAVAILABLE(tvos, watchos) XPC_EXPORT XPC_SWIFT_NOEXPORT XPC_NONNULL_ALL void xpc_listener_set_peer_requirement(
	xpc_listener_t listener,
	xpc_peer_requirement_t requirement
)

@function xpc_listener_set_peer_requirement Requires that the listener peer satisfies a requirement. @param listener The listener object which is to be modified. Must be inactive. @param requirement The requirement to be satisfied by the peer. It will be retained by XPC. @discussion It is a programming error to call `xpc_listener_set_peer_*requirement` more than once per listener. All messages received on this listener will be checked to ensure they come from a peer who satisfies the code signing requirement. Requests that do not satisfy the requirement are dropped. Peer sessions created from the listener do not inherit the requirement.