Cameron Katri's Manual Page Server

Manual Page Search Parameters
xpc_object(3) Library Functions Manual xpc_object(3)

xpc_object — XPC object protocol

#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);

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

Objects returned by creation functions in the XPC framework may be uniformly retained and released with the functions () and () 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 release this reference, and is responsible for retaining the object for later use if necessary.

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++:

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 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);
});

The () 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:

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:

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

Objects may be copied using the () 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.

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 () function will only perform a simple pointer-equality check for these objects.

Objects may be hashed using the () 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.

The () 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.

dispatch_async(3), xpc_abort(3), xpc_array_create(3), xpc_connection_cancel(3), xpc_connection_create(3), xpc_dictionary_create(3), xpc_endpoint_create(3), xpc_objects(3)

1 March, 2012 Darwin