NAME

xpc_object — XPC object protocol

SYNOPSIS

#include <xpc/xpc.h>

xpc_object_t
xpc_retain(xpc_object_t object);

void
xpc_release(xpc_object_t object);

xpc_type_t
xpc_get_type(xpc_object_t object);

xpc_object_t
xpc_copy(xpc_object_t object);

bool
xpc_equal(xpc_object_t object1, xpc_object_t object2);

size_t
xpc_hash(xpc_object_t object);

char *
xpc_copy_description(xpc_object_t object);

DESCRIPTION

XPC objects share functions for coordinating memory management, type checking, comparing for equality, and hashing.

MEMORY MANAGEMENT

Objects returned by creation functions in the XPC framework may be uniformly retained and released with the functions xpc_retain() and xpc_release() respectively.

The XPC framework does not guarantee that any given client has the last or only reference to a given object. Objects may be retained internally by the system.

Functions which return objects follow the conventional create, copy and get naming rules:

• create: A new object with a single reference is returned. This reference should be released by the caller.
• copy: A copy or retained object reference is returned. This reference should be released by the caller.
• get: An unretained reference to an existing object is returned. The caller must not release this reference, and is responsible for retaining the object for later use if necessary.

INTEGRATION WITH OBJECTIVE-C

When building with an Objective-C or Objective-C++ compiler, XPC objects are declared as Objective-C types. This results in the following differences compared to building as plain C/C++:

if Objective-C Automated Reference Counting is enabled, XPC objects are memory managed by the Objective-C runtime and explicit calls to the xpc_retain() and xpc_release() functions will produce build errors.
Note: when ARC is enabled, care needs to be taken with XPC API returning an interior pointer that is only valid as long as an associated object has not been released. If that object is held in a variable with automatic storage, it may need to be annotated with the objc_precise_lifetime attribute, or stored in a __strong instance variable instead, to ensure that the object is not prematurely released. The functions returning interior pointers are:
the Blocks runtime automatically retains and releases XPC objects captured by blocks upon Block_copy() and Block_release(), e.g. as performed during asynchronous execution of a block via dispatch_async(3).
Note: retain cycles may be encountered if XPC connection objects are captured by their handler blocks; these cycles can be broken by declaring the captured object __weak or by calling xpc_connection_cancel(3) to cause its handler blocks to be released explicitly.
XPC objects can be added directly to Cocoa collections, and their lifetime is tracked by the Objective-C static analyzer.

Integration of XPC objects with Objective-C requires targeting Mac OS X 10.8 or later, and is disabled when building for the legacy Objective-C runtime. It can also be disabled manually by using compiler options to define the OS_OBJECT_USE_OBJC preprocessor macro to 0.

Important: When building with a plain C/C++ compiler or when integration with Objective-C is disabled, XPC objects are not automatically retained and released when captured by a block. Therefore, when a XPC object is captured by a block that will be executed asynchronously, the object must be manually retained and released:

xpc_retain(object);
dispatch_async(queue, ^{
	do_something_with_object(object);
	xpc_release(object);
});

TYPES

The xpc_get_type() function returns the type of an XPC object as a pointer of type xpc_type t. The returned type may be compared against the type constants defined by the XPC framework with simple pointer equality.

Type constants:

XPC_TYPE_CONNECTION
XPC_TYPE_ENDPOINT
XPC_TYPE_NULL
XPC_TYPE_BOOL
XPC_TYPE_INT64
XPC_TYPE_UINT64
XPC_TYPE_DOUBLE
XPC_TYPE_DATE
XPC_TYPE_DATA
XPC_TYPE_STRING
XPC_TYPE_UUID
XPC_TYPE_FD
XPC_TYPE_SHMEM
XPC_TYPE_ARRAY
XPC_TYPE_DICTIONARY

BOXED OBJECTS AND COLLECTIONS

Most XPC object types are boxed representations of primitive C language types or low-level operating system handles. These boxed objects are immutable.

The XPC framework provides two collection types: dictionaries and arrays. These types are mutable and may have boxed objects added or removed from the collection.

A suite of primitive get and set functions are available for the dictionary and array types. These functions allow for the insertion and extraction of primitive values from the collection directly, without the need for intermediate boxed objects.

The following is a list of primitive get and set functions for the dictionary collection type:

xpc_dictionary_set_bool(3), xpc_dictionary_get_bool(3), xpc_array_set_bool(3), xpc_array_get_bool(3)
xpc_dictionary_set_int64(3), xpc_dictionary_get_int64(3), xpc_array_set_int64(3), xpc_array_get_int64(3)
xpc_dictionary_set_uint64(3), xpc_dictionary_set_uint64(3), xpc_array_set_uint64(3), xpc_array_get_uint64(3)
xpc_dictionary_set_double(3), xpc_dictionary_set_double(3), xpc_array_set_double(3), xpc_array_get_double(3)
xpc_dictionary_set_date(3), xpc_dictionary_set_date(3), xpc_array_set_date(3), xpc_array_get_date(3)
xpc_dictionary_set_data(3), xpc_dictionary_get_data(3), xpc_array_set_data(3), xpc_array_get_data(3)
xpc_dictionary_set_string(3), xpc_dictionary_get_string(3), xpc_array_set_string(3), xpc_array_get_string(3)
xpc_dictionary_set_uuid(3), xpc_dictionary_get_uuid(3), xpc_array_set_uuid(3), xpc_array_get_uuid(3)
xpc_dictionary_set_fd(3), xpc_dictionary_dup_fd(3), xpc_array_set_fd(3), xpc_array_dup_fd(3)
xpc_dictionary_set_connection(3), xpc_array_set_connection(3)

When the requested key or index is not present in the collection, or if the value for the requested key or index is not of the expected type, these functions will return sensible default values:

• bool: false
• int64: 0
• uint64: 0
• double: NAN
• date: 0
• data: NULL
• uuid: NULL
• string: NULL
• fd: -1
• connection: NULL

COPYING

Objects may be copied using the xpc_copy() function. The result of xpc_copy() may or may not be a brand new object (i.e. a different pointer). The system may choose to return the same object with an additional reference rather than doing a complete copy for efficiency reasons.

EQUALITY

Two objects may be compared for equality using the xpc_equal() function. Objects must be of the same type as returned by xpc_get_type() in order to be considered equal. No casting or transformation is performed on the underlying value in order to determine equality.

Collection types are compared for deep equality, that is to say, two arrays are equal only if they contain the same values in the same order, and two dictionaries are equal only if they contain the same values for the same keys.

Important: File descriptors and shared memory objects cannot be reliably compared for equality, and therefore the xpc_equal() function will only perform a simple pointer-equality check for these objects.

Objects may be hashed using the xpc_hash() function. The result of the hash function is guaranteed to be identical for objects which compare to be equal using xpc_equal().

Important: The hash value for a given object should not be considered portable across multiple processes or releases of the operating system and as a result should not be stored in a permanent fashion.

OBJECT DESCRIPTIONS

The xpc_copy_description() function may be used to produce a human-readable description of an object. The returned C-string must be freed by the caller using free(3).

Important: The format of this description is not guaranteed to remain consistent across releases, and the output should only be used for debugging purposes.