XPC Services xpc.h Reference

Declared in
xpc/xpc.h

Overview

Included Headers

  • <Availability.h>

  • <dispatch/dispatch.h>

  • <sys/mman.h>

  • <uuid/uuid.h>

  • <bsm/audit.h>

  • <stdarg.h>

  • <stdbool.h>

  • <stdint.h>

  • <stdlib.h>

  • <stdio.h>

  • <string.h>

  • <unistd.h>

  • <fcntl.h>

  • <xpc/base.h>

  • <xpc/endpoint.h>

  • <xpc/connection.h>

Functions

See the Overview for header-level documentation.

xpc_array_append_value

Appends an object to an XPC array.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_array_append_value(
   xpc_object_t xarray,
   xpc_object_t value);
Parameters
xarray

The array object which is to be manipulated.

value

The object to append. This object is retained by the array.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_array_apply

Invokes the given block for every value in the array.

#ifdef __BLOCKS__
__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  bool xpc_array_apply(
   xpc_object_t xarray,
   xpc_array_applier_t applier);
#endif
/* __BLOCKS__ */
Parameters
xarray

The array object which is to be examined.

applier

The block which this function applies to every element in the array.

Return Value

A Boolean indicating whether iteration of the array completed successfully. Iteration will only fail if the applier block returns false.

Discussion

You should not modify an array's contents during iteration. The array indexes are iterated in order.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_array_create

Creates an XPC object representing an array of XPC objects.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_object_t xpc_array_create(
   const xpc_object_t *objects,
   size_t count);
Parameters
objects

An array of XPC objects which is to be boxed. The order of this array is preserved in the object. If this array contains a NULL value, the behavior is undefined. This parameter may be NULL only if the count is 0.

count

The number of objects in the given array. If the number passed is less than the actual number of values in the array, only the specified number of items are inserted into the resulting array. If the number passed is more than the the actual number of values, the behavior is undefined.

Return Value

A new array object.

Discussion

This array must be contiguous and cannot contain any NULL values. If you wish to insert the equivalent of a NULL value, you may use the result of xpc_null_create.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_array_create_connection

Creates a connection object from an array directly.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_connection_t xpc_array_create_connection(
   xpc_object_t xarray,
   size_t index);
Parameters
xarray

The array which is to be examined.

index

The index of the value to obtain. This value must lie within the index space of the array (0 to N-1 inclusive, where N is the count of the array). If the index is outside that range, the behavior is undefined.

Return Value

A new connection created from the value at the specified index. You are responsible for calling xpc_release() on the returned connection. NULL if the value at the specified index is not an endpoint containing a connection. Each call to this method for the same index in the same array will yield a different connection. See xpc_connection_create_from_endpoint() for discussion as to the responsibilities when dealing with the returned connection.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_array_dup_fd

Gets a file descriptor from an array directly.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  int xpc_array_dup_fd(
   xpc_object_t xarray,
   size_t index);
Parameters
xarray

The array which is to be examined.

index

The index of the value to obtain. This value must lie within the index space of the array (0 to N-1 inclusive, where N is the count of the array). If the index is outside that range, the behavior is undefined.

Return Value

A new file descriptor created from the value at the specified index. You are responsible for close(2)ing this descriptor. -1 if the value at the specified index is not a file descriptor value.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_array_get_bool

Gets a bool primitive value from an array directly.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  bool xpc_array_get_bool(
   xpc_object_t xarray,
   size_t index);
Parameters
xarray

The array which is to be examined.

index

The index of the value to obtain. This value must lie within the index space of the array (0 to N-1 inclusive, where N is the count of the array). If the index is outside that range, the behavior is undefined.

Return Value

The underlying bool value at the specified index. false if the value at the specified index is not a Boolean value.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_array_get_count

Returns the count of values currently in the array.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  size_t xpc_array_get_count(
   xpc_object_t xarray);
Parameters
xarray

The array object which is to be examined.

Return Value

The count of values in the array.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_array_get_data

Gets a pointer to the raw bytes of a data object from an array directly.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  const void * xpc_array_get_data(
   xpc_object_t xarray,
   size_t index,
   size_t *length);
Parameters
xarray

The array which is to be examined.

index

The index of the value to obtain. This value must lie within the index space of the array (0 to N-1 inclusive, where N is the count of the array). If the index is outside that range, the behavior is undefined.

length

Upon return output, will contain the length of the data corresponding to the specified key.

Return Value

The underlying bytes at the specified index. NULL if the value at the specified index is not a data value.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_array_get_date

Gets a date interval from an array directly.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  int64_t xpc_array_get_date(
   xpc_object_t xarray,
   size_t index);
Parameters
xarray

The array which is to be examined.

index

The index of the value to obtain. This value must lie within the index space of the array (0 to N-1 inclusive, where N is the count of the array). If the index is outside that range, the behavior is undefined.

Return Value

The underlying date interval at the specified index. 0 if the value at the specified index is not a date value.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_array_get_double

Gets a double primitive value from an array directly.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  double xpc_array_get_double(
   xpc_object_t xarray,
   size_t index);
Parameters
xarray

The array which is to be examined.

index

The index of the value to obtain. This value must lie within the index space of the array (0 to N-1 inclusive, where N is the count of the array). If the index is outside that range, the behavior is undefined.

Return Value

The underlying double value at the specified index. NAN if the value at the specified index is not a floating point value.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_array_get_int64

Gets an int64_t primitive value from an array directly.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  int64_t xpc_array_get_int64(
   xpc_object_t xarray,
   size_t index);
Parameters
xarray

The array which is to be examined.

index

The index of the value to obtain. This value must lie within the index space of the array (0 to N-1 inclusive, where N is the count of the array). If the index is outside that range, the behavior is undefined.

Return Value

The underlying int64_t value at the specified index. 0 if the value at the specified index is not a signed integer value.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_array_get_string

Gets a C string value from an array directly.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  const char * xpc_array_get_string(
   xpc_object_t xarray,
   size_t index);
Parameters
xarray

The array which is to be examined.

index

The index of the value to obtain. This value must lie within the index space of the array (0 to N-1 inclusive, where N is the count of the array). If the index is outside that range, the behavior is undefined.

Return Value

The underlying C string at the specified index. NULL if the value at the specified index is not a C string value.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_array_get_uint64

Gets a uint64_t primitive value from an array directly.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  uint64_t xpc_array_get_uint64(
   xpc_object_t xarray,
   size_t index);
Parameters
xarray

The array which is to be examined.

index

The index of the value to obtain. This value must lie within the index space of the array (0 to N-1 inclusive, where N is the count of the array). If the index is outside that range, the behavior is undefined.

Return Value

The underlying uint64_t value at the specified index. 0 if the value at the specified index is not an unsigned integer value.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_array_get_uuid

Gets a uuid_t value from an array directly.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  const uint8_t * xpc_array_get_uuid(
   xpc_object_t xarray,
   size_t index);
Parameters
xarray

The array which is to be examined.

index

The index of the value to obtain. This value must lie within the index space of the array (0 to N-1 inclusive, where N is the count of the array). If the index is outside that range, the behavior is undefined.

Return Value

The underlying uuid_t value at the specified index. The null UUID if the value at the specified index is not a UUID value. The returned pointer may be safely passed to the uuid(3) APIs.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_array_get_value

Returns the value at the specified index in the array.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_object_t xpc_array_get_value(
   xpc_object_t xarray,
   size_t index);
Parameters
xarray

The array object which is to be examined.

index

The index of the value to obtain. This value must lie within the range of indexes as specified in xpc_array_set_value().

Return Value

The object at the specified index within the array.

Discussion

This method does not grant the caller a reference to the underlying object, and thus the caller is not responsible for releasing the object.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_array_set_bool

Inserts a bool (primitive) value into an array.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_array_set_bool(
   xpc_object_t xarray,
   size_t index,
   bool value);
Parameters
xarray

The array object which is to be manipulated.

index

The index at which to insert the value. This value must lie within the index space of the array (0 to N-1 inclusive, where N is the count of the array) or be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is undefined.

value

The bool value to insert. After calling this method, the XPC object corresponding to the primitive value inserted may be safely retrieved with xpc_array_get_value().

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_array_set_connection

Inserts a connection into an array.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_array_set_connection(
   xpc_object_t xarray,
   size_t index,
   xpc_connection_t connection);
Parameters
xarray

The array object which is to be manipulated.

index

The index at which to insert the value. This value must lie within the index space of the array (0 to N-1 inclusive, where N is the count of the array) or be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is undefined.

connection

The connection to insert. After calling this method, the XPC object corresponding to the primitive value inserted may be safely retrieved with xpc_array_get_value(). The connection is NOT retained by the array.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_array_set_data

Inserts a raw data value into an array.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_array_set_data(
   xpc_object_t xarray,
   size_t index,
   const void *bytes,
   size_t length);
Parameters
xarray

The array object which is to be manipulated.

index

The index at which to insert the value. This value must lie within the index space of the array (0 to N-1 inclusive, where N is the count of the array) or be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is undefined.

bytes

The raw data to insert. After calling this method, the XPC object corresponding to the primitive value inserted may be safely retrieved with xpc_array_get_value().

length

The length of the data.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_array_set_date

Inserts a date value into an array.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_array_set_date(
   xpc_object_t xarray,
   size_t index,
   int64_t value);
Parameters
xarray

The array object which is to be manipulated.

index

The index at which to insert the value. This value must lie within the index space of the array (0 to N-1 inclusive, where N is the count of the array) or be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is undefined.

value

The double value to insert. After calling this method, the XPC object corresponding to the primitive value inserted may be safely retrieved with xpc_array_get_value().

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_array_set_double

Inserts a double (primitive) value into an array.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_array_set_double(
   xpc_object_t xarray,
   size_t index,
   double value);
Parameters
xarray

The array object which is to be manipulated.

index

The index at which to insert the value. This value must lie within the index space of the array (0 to N-1 inclusive, where N is the count of the array) or be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is undefined.

value

The double value to insert. After calling this method, the XPC object corresponding to the primitive value inserted may be safely retrieved with xpc_array_get_value().

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_array_set_fd

Inserts a file descriptor into an array.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_array_set_fd(
   xpc_object_t xarray,
   size_t index,
   int fd);
Parameters
xarray

The array object which is to be manipulated.

index

The index at which to insert the value. This value must lie within the index space of the array (0 to N-1 inclusive, where N is the count of the array) or be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is undefined.

fd

The file descriptor to insert. After calling this method, the XPC object corresponding to the primitive value inserted may be safely retrieved with xpc_array_get_value().

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_array_set_int64

Inserts an int64_t (primitive) value into an array.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_array_set_int64(
   xpc_object_t xarray,
   size_t index,
   int64_t value);
Parameters
xarray

The array object which is to be manipulated.

index

The index at which to insert the value. This value must lie within the index space of the array (0 to N-1 inclusive, where N is the count of the array) or be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is undefined.

value

The int64_t value to insert. After calling this method, the XPC object corresponding to the primitive value inserted may be safely retrieved with xpc_array_get_value().

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_array_set_string

Inserts a C string into an array.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_array_set_string(
   xpc_object_t xarray,
   size_t index,
   const char *string);
Parameters
xarray

The array object which is to be manipulated.

index

The index at which to insert the value. This value must lie within the index space of the array (0 to N-1 inclusive, where N is the count of the array) or be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is undefined.

string

The C string to insert. After calling this method, the XPC object corresponding to the primitive value inserted may be safely retrieved with xpc_array_get_value().

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_array_set_uint64

Inserts a uint64_t (primitive) value into an array.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_array_set_uint64(
   xpc_object_t xarray,
   size_t index,
   uint64_t value);
Parameters
xarray

The array object which is to be manipulated.

index

The index at which to insert the value. This value must lie within the index space of the array (0 to N-1 inclusive, where N is the count of the array) or be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is undefined.

value

The uint64_t value to insert. After calling this method, the XPC object corresponding to the primitive value inserted may be safely retrieved with xpc_array_get_value().

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_array_set_uuid

Inserts a uuid_t (primitive) value into an array.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_array_set_uuid(
   xpc_object_t xarray,
   size_t index,
   const uuid_t uuid);
Parameters
xarray

The array object which is to be manipulated.

index

The index at which to insert the value. This value must lie within the index space of the array (0 to N-1 inclusive, where N is the count of the array) or be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is undefined.

uuid

The UUID primitive to insert. After calling this method, the XPC object corresponding to the primitive value inserted may be safely retrieved with xpc_array_get_value().

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_array_set_value

Inserts the specified object into the array at the specified index.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_array_set_value(
   xpc_object_t xarray,
   size_t index,
   xpc_object_t value);
Parameters
xarray

The array object which is to be manipulated.

index

The index at which to insert the value. This value must lie within the index space of the array (0 to N-1 inclusive, where N is the count of the array). If the index is outside that range, the behavior is undefined.

value

The object to insert. This value is retained by the array and cannot be NULL. If there is already a value at the specified index, it is released, and the new value is inserted in its place.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_bool_create

Creates an XPC Boolean object.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_object_t xpc_bool_create(
   bool value);
Parameters
value

The Boolean primitive value which is to be boxed.

Return Value

A new Boolean object.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_bool_get_value

Returns the underlying Boolean value from the object.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern bool xpc_bool_get_value(
   xpc_object_t xbool);
Parameters
xbool

The Boolean object which is to be examined.

Return Value

The underlying Boolean value.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_copy

Creates a copy of the object.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_object_t xpc_copy(
   xpc_object_t object);
Parameters
object

The object to copy.

Return Value

The new object. NULL if the object type does not support copying or if sufficient memory for the copy could not be allocated. Service objects do not support copying.

Discussion

When called on an array or dictionary, xpc_copy() will perform a deep copy.

The object returned is not necessarily guaranteed to be a new object, and whether it is will depend on the implementation of the object being copied.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_copy_description

Copies a debug string describing the object.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  char * xpc_copy_description(
   xpc_object_t object);
Parameters
object

The object which is to be examined.

Return Value

A string describing object which contains information useful for debugging. This string should be disposed of with free(3) when done.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_data_create

Creates an XPC object representing buffer of bytes.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_object_t xpc_data_create(
   const void *bytes,
   size_t length);
Parameters
bytes

The buffer of bytes which is to be boxed. You may create an empty data object by passing NULL for this parameter and 0 for the length. Passing NULL with any other length will result in undefined behavior.

length

The number of bytes which are to be boxed.

Return Value

A new data object.

Discussion

This method will copy the buffer given into internal storage. After calling this method, it is safe to dispose of the given buffer.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_data_create_with_dispatch_data

Creates an XPC object representing buffer of bytes described by the given GCD data object.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_object_t xpc_data_create_with_dispatch_data(
   dispatch_data_t ddata);
Parameters
ddata

The GCD data object containing the bytes which are to be boxed. This object is retained by the data object.

Return Value

A new data object.

Discussion

The object returned by this method will refer to the buffer returned by dispatch_data_create_map(). The point where XPC will make the call to dispatch_data_create_map() is undefined.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_data_get_bytes

Copies the bytes stored in an data objects into the specified buffer.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  size_t xpc_data_get_bytes(
   xpc_object_t xdata,
   void *buffer,
   size_t off,
   size_t length);
Parameters
xdata

The data object which is to be examined.

buffer

The buffer in which to copy the data object's bytes.

off

The offset at which to begin the copy. If this offset is greater than the length of the data element, nothing is copied. Pass 0 to start the copy at the beginning of the buffer.

length

The length of the destination buffer.

Return Value

The number of bytes that were copied into the buffer.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_data_get_bytes_ptr

Returns a pointer to the internal storage of a data object.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  const void * xpc_data_get_bytes_ptr(
   xpc_object_t xdata);
Parameters
xdata

The data object which is to be examined.

Return Value

A pointer to the underlying boxed data.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_data_get_length

Returns the length of the data encapsulated by an XPC data object.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  size_t xpc_data_get_length(
   xpc_object_t xdata);
Parameters
xdata

The data object which is to be examined.

Return Value

The length of the underlying boxed data.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_date_create

Creates an XPC date object.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_object_t xpc_date_create(
   int64_t interval);
Parameters
interval

The date interval which is to be boxed. Negative values indicate the number of nanoseconds before the epoch. Positive values indicate the number of nanoseconds after the epoch.

Return Value

A new date object.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_date_create_from_current

Creates an XPC date object representing the current date.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_object_t xpc_date_create_from_current(
   void);
Return Value

A new date object representing the current date.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_date_get_value

Returns the underlying date interval from an object.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  int64_t xpc_date_get_value(
   xpc_object_t xdate);
Parameters
xdate

The date object which is to be examined.

Return Value

The underlying date interval.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_apply

Invokes the given block for every key/value pair in the dictionary.

#ifdef __BLOCKS__
__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  bool xpc_dictionary_apply(
   xpc_object_t xdict,
   xpc_dictionary_applier_t applier);
#endif
/* __BLOCKS__ */
Parameters
xdict

The dictionary object which is to be examined.

applier

The block which this function applies to every key/value pair in the dictionary.

Return Value

A Boolean indicating whether iteration of the dictionary completed successfully. Iteration will only fail if the applier block returns false.

Discussion

You should not modify a dictionary's contents during iteration. There is no guaranteed order of iteration over dictionaries.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_create

Creates an XPC object representing a dictionary of XPC objects keyed to C-strings.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_object_t xpc_dictionary_create(
   const char **keys,
   const xpc_object_t *values,
   size_t count);
Parameters
keys

An array of C-strings that are to be the keys for the values to be inserted. Each element of this array is copied into the dictionary's internal storage. If any element of this array is NULL, the behavior is undefined.

values

A C-array that is parallel to the array of keys, consisting of objects that are to be inserted. Each element in this array is retained. Elements in this array may be NULL.

count

The number of key/value pairs in the given arrays. If the count is less than the actual count of values, only that many key/value pairs will be inserted into the dictionary.

If the count is more than the the actual count of key/value pairs, the behavior is undefined. If one array is NULL and the other is not, the behavior is undefined. If both arrays are NULL and the count is non-0, the behavior is undefined.

Return Value

The new dictionary object.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_create_connection

Creates a connection from a dictionary directly.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_connection_t xpc_dictionary_create_connection(
   xpc_object_t xdict,
   const char *key);
Parameters
xdict

The dictionary object which is to be examined.

key

The key whose value is to be obtained.

Return Value

A new connection created from the value for the specified key. You are responsible for calling xpc_release() on the returned connection. NULL if the value for the specified key is not an endpoint containing a connection or if there is no value for the specified key. Each call to this method for the same key in the same dictionary will yield a different connection. See xpc_connection_create_from_endpoint() for discussion as to the responsibilities when dealing with the returned connection.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_create_reply

Creates a dictionary that is in reply to the given dictionary.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_object_t xpc_dictionary_create_reply(
   xpc_object_t original);
Parameters
original

The original dictionary that is to be replied to.

Return Value

The new dictionary object. NULL if the dictionary did not come from the wire with a reply context.

Discussion

After completing successfully on a dictionary, this method may not be called again on that same dictionary. Attempts to do so will return NULL.

When this dictionary is sent across the reply connection, the remote end's reply handler is invoked.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_dup_fd

Creates a file descriptor from a dictionary directly.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  int xpc_dictionary_dup_fd(
   xpc_object_t xdict,
   const char *key);
Parameters
xdict

The dictionary object which is to be examined.

key

The key whose value is to be obtained.

Return Value

A new file descriptor created from the value for the specified key. You are responsible for close(2)ing this descriptor. -1 if the value for the specified key is not a file descriptor value or if there is no value for the specified key.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_get_bool

Gets a bool primitive value from a dictionary directly.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  bool xpc_dictionary_get_bool(
   xpc_object_t xdict,
   const char *key);
Parameters
xdict

The dictionary object which is to be examined.

key

The key whose value is to be obtained.

Return Value

The underlying bool value for the specified key. false if the the value for the specified key is not a Boolean value or if there is no value for the specified key.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_get_count

Returns the number of values stored in the dictionary.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  size_t xpc_dictionary_get_count(
   xpc_object_t xdict);
Parameters
xdict

The dictionary object which is to be examined.

Return Value

The number of values stored in the dictionary. Calling xpc_dictionary_set_value() with a non-NULL value will increment the count. Calling xpc_dictionary_set_value() with a NULL value will decrement the count.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_get_data

Gets a raw data value from a dictionary directly.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  const void * xpc_dictionary_get_data(
   xpc_object_t xdict,
   const char *key,
   size_t *length);
Parameters
xdict

The dictionary object which is to be examined.

key

The key whose value is to be obtained.

length

For the data type, the third parameter, upon output, will contain the length of the data corresponding to the specified key.

Return Value

The underlying raw data for the specified key. NULL if the value for the specified key is not a data value or if there is no value for the specified key.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_get_date

Gets a date value from a dictionary directly.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  int64_t xpc_dictionary_get_date(
   xpc_object_t xdict,
   const char *key);
Parameters
xdict

The dictionary object which is to be examined.

key

The key whose value is to be obtained.

Return Value

The underlying date interval for the specified key. 0 if the value for the specified key is not a date value or if there is no value for the specified key.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_get_double

Gets a double primitive value from a dictionary directly.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  double xpc_dictionary_get_double(
   xpc_object_t xdict,
   const char *key);
Parameters
xdict

The dictionary object which is to be examined.

key

The key whose value is to be obtained.

Return Value

The underlying double value for the specified key. NAN if the value for the specified key is not a floating point value or if there is no value for the specified key.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_get_int64

Gets an int64 primitive value from a dictionary directly.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  int64_t xpc_dictionary_get_int64(
   xpc_object_t xdict,
   const char *key);
Parameters
xdict

The dictionary object which is to be examined.

key

The key whose value is to be obtained.

Return Value

The underlying int64_t value for the specified key. 0 if the value for the specified key is not a signed integer value or if there is no value for the specified key.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_get_remote_connection

Returns the connection from which the dictionary was received.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_connection_t xpc_dictionary_get_remote_connection(
   xpc_object_t xdict);
Parameters
xdict

The dictionary object which is to be examined.

Return Value

If the dictionary was received by a connection event handler or a dictionary created through xpc_dictionary_create_reply(), a connection object over which a reply message can be sent is returned. For any other dictionary, NULL is returned.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_get_string

Gets a C string value from a dictionary directly.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  const char * xpc_dictionary_get_string(
   xpc_object_t xdict,
   const char *key);
Parameters
xdict

The dictionary object which is to be examined.

key

The key whose value is to be obtained.

Return Value

The underlying C string for the specified key. NULL if the value for the specified key is not a C string value or if there is no value for the specified key.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_get_uint64

Gets a uint64 primitive value from a dictionary directly.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  uint64_t xpc_dictionary_get_uint64(
   xpc_object_t xdict,
   const char *key);
Parameters
xdict

The dictionary object which is to be examined.

key

The key whose value is to be obtained.

Return Value

The underlying uint64_t value for the specified key. 0 if the value for the specified key is not an unsigned integer value or if there is no value for the specified key.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_get_uuid

Gets a uuid value from a dictionary directly.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  const uint8_t * xpc_dictionary_get_uuid(
   xpc_object_t xdict,
   const char *key);
Parameters
xdict

The dictionary object which is to be examined.

key

The key whose value is to be obtained.

Return Value

The underlying uuid_t value for the specified key. NULL is the value at the specified index is not a UUID value. The returned pointer may be safely passed to the uuid(3) APIs.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_get_value

Returns the value for the specified key.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_object_t xpc_dictionary_get_value(
   xpc_object_t xdict,
   const char *key);
Parameters
xdict

The dictionary object which is to be examined.

key

The key whose value is to be obtained.

Return Value

The object for the specified key within the dictionary. NULL if there is no value associated with the specified key.

Discussion

This method does not grant the caller a reference to the underlying object, and thus the caller is not responsible for releasing the object.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_set_bool

Inserts a bool (primitive) value into a dictionary.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_dictionary_set_bool(
   xpc_object_t xdict,
   const char *key,
   bool value);
Parameters
xdict

The dictionary which is to be manipulated.

key

The key for which the primitive value shall be set.

value

The bool value to insert. After calling this method, the XPC object corresponding to the primitive value inserted may be safely retrieved with xpc_dictionary_get_value().

Return Value

Whether the insertion was successful.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_set_connection

Inserts a connection into a dictionary.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_dictionary_set_connection(
   xpc_object_t xdict,
   const char *key,
   xpc_connection_t connection);
Parameters
xdict

The dictionary which is to be manipulated.

key

The key for which the primitive value shall be set.

connection

The connection to insert. After calling this method, the XPC object corresponding to the primitive value inserted may be safely retrieved with xpc_dictionary_get_value(). The connection is NOT retained by the dictionary.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_set_data

Inserts a raw data value into a dictionary.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_dictionary_set_data(
   xpc_object_t xdict,
   const char *key,
   const void *bytes,
   size_t length);
Parameters
xdict

The dictionary which is to be manipulated.

key

The key for which the primitive value shall be set.

bytes

The bytes to insert. After calling this method, the XPC object corresponding to the primitive value inserted may be safely retrieved with xpc_dictionary_get_value().

length

The length of the data.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_set_date

Inserts a date (primitive) value into a dictionary.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_dictionary_set_date(
   xpc_object_t xdict,
   const char *key,
   int64_t value);
Parameters
xdict

The dictionary which is to be manipulated.

key

The key for which the primitive value shall be set.

value

The date value to insert. After calling this method, the XPC object corresponding to the primitive value inserted may be safely retrieved with xpc_dictionary_get_value().

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_set_double

Inserts a double (primitive) value into a dictionary.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_dictionary_set_double(
   xpc_object_t xdict,
   const char *key,
   double value);
Parameters
xdict

The dictionary which is to be manipulated.

key

The key for which the primitive value shall be set.

value

The double value to insert. After calling this method, the XPC object corresponding to the primitive value inserted may be safely retrieved with xpc_dictionary_get_value().

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_set_fd

Inserts a file descriptor into a dictionary.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_dictionary_set_fd(
   xpc_object_t xdict,
   const char *key,
   int fd);
Parameters
xdict

The dictionary which is to be manipulated.

key

The key for which the primitive value shall be set.

fd

The file descriptor to insert. After calling this method, the XPC object corresponding to the primitive value inserted may be safely retrieved with xpc_dictionary_get_value().

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_set_int64

Inserts an int64_t (primitive) value into a dictionary.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_dictionary_set_int64(
   xpc_object_t xdict,
   const char *key,
   int64_t value);
Parameters
xdict

The dictionary which is to be manipulated.

key

The key for which the primitive value shall be set.

value

The int64_t value to insert. After calling this method, the XPC object corresponding to the primitive value inserted may be safely retrieved with xpc_dictionary_get_value().

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_set_string

Inserts a C string value into a dictionary.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_dictionary_set_string(
   xpc_object_t xdict,
   const char *key,
   const char *string);
Parameters
xdict

The dictionary which is to be manipulated.

key

The key for which the primitive value shall be set.

string

The C string to insert. After calling this method, the XPC object corresponding to the primitive value inserted may be safely retrieved with xpc_dictionary_get_value().

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_set_uint64

Inserts a uint64_t (primitive) value into a dictionary.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_dictionary_set_uint64(
   xpc_object_t xdict,
   const char *key,
   uint64_t value);
Parameters
xdict

The dictionary which is to be manipulated.

key

The key for which the primitive value shall be set.

value

The uint64_t value to insert. After calling this method, the XPC object corresponding to the primitive value inserted may be safely retrieved with xpc_dictionary_get_value().

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_set_uuid

Inserts a uuid (primitive) value into an array.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_dictionary_set_uuid(
   xpc_object_t xdict,
   const char *key,
   const uuid_t uuid);
Parameters
xdict

The dictionary which is to be manipulated.

key

The key for which the primitive value shall be set.

uuid

The uuid_t value to insert. After calling this method, the XPC object corresponding to the primitive value inserted may be safely retrieved with xpc_dictionary_get_value().

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_set_value

Sets the value for the specified key to the specified object.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_dictionary_set_value(
   xpc_object_t xdict,
   const char *key,
   xpc_object_t value);
Parameters
xdict

The dictionary object which is to be manipulated.

key

The key for which the value shall be set.

value

The object to insert. The object is retained by the dictionary. If there already exists a value for the specified key, the old value is released and overwritten by the new value. This parameter may be NULL, in which case the value corresponding to the specified key is deleted if present.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_double_create

Creates an XPC double object.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_object_t xpc_double_create(
   double value);
Parameters
value

The floating point quantity which is to be boxed.

Return Value

A new floating point object.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_double_get_value

Returns the underlying double-precision floating point value from an object.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  double xpc_double_get_value(
   xpc_object_t xdouble);
Parameters
xdouble

The floating point object which is to be examined.

Return Value

The underlying floating point value.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_equal

Compares two objects for equality.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  bool xpc_equal(
   xpc_object_t object1,
   xpc_object_t object2);
Parameters
object1

The first object to compare.

object2

The second object to compare.

Return Value

Returns true if the objects are equal, otherwise false. Two objects must be of the same type in order to be equal.

For two arrays to be equal, they must contain the same values at the same indexes. For two dictionaries to be equal, they must contain the same values for the same keys.

Two objects being equal implies that their hashes (as returned by xpc_hash()) are also equal.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_fd_create

Creates an XPC object representing a POSIX file descriptor.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_object_t xpc_fd_create(
   int fd);
Parameters
fd

The file descriptor which is to be boxed.

Return Value

A new file descriptor object. NULL if sufficient memory could not be allocated or if the given file descriptor was not valid.

Discussion

This method performs the equivalent of a dup(2) on the descriptor, and thus it is safe to call close(2) on the descriptor after boxing it with a file descriptor object.

IMPORTANT: Pointer equality is the ONLY valid test for equality between two file descriptor objects. There is no reliable way to determine whether two file descriptors refer to the same inode with the same capabilities, so two file descriptor objects created from the same underlying file descriptor number will not compare equally with xpc_equal(). This is also true of a file descriptor object created using xpc_copy() and the original.

This also implies that two collections containing file descriptor objects cannot be equal unless the exact same object was inserted into both.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_fd_dup

Returns a file descriptor that is equivalent to the one boxed by the file file descriptor object.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  int xpc_fd_dup(
   xpc_object_t xfd);
Parameters
xfd

The file descriptor object which is to be examined.

Return Value

A file descriptor that is equivalent to the one originally given to xpc_fd_create(). If the descriptor could not be created, -1 is returned.

Discussion

Multiple invocations of xpc_fd_dup() will not return the same file descriptor number, but they will return descriptors that are equivalent, as though they had been created by dup(2).

The caller is responsible for calling close(2) on the returned descriptor.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_get_type

Returns the type of an object.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_type_t xpc_get_type(
   xpc_object_t object);
Parameters
object

The object to examine.

Return Value

An opaque pointer describing the type of the object. This pointer is suitable direct comparison to exported type constants with the equality operator.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_hash

Calculates a hash value for the given object.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  size_t xpc_hash(
   xpc_object_t object);
Parameters
object

The object for which to calculate a hash value. This value may be modded with a table size for insertion into a dictionary-like data structure.

Return Value

The calculated hash value.

Discussion

Note that the computed hash values for any particular type and value of an object can change from across releases and platforms and should not be assumed to be constant across all time and space or stored persistently.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_int64_create

Creates an XPC signed integer object.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_object_t xpc_int64_create(
   int64_t value);
Parameters
value

The signed integer value which is to be boxed.

Return Value

A new signed integer object.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_int64_get_value

Returns the underlying signed 64-bit integer value from an object.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  int64_t xpc_int64_get_value(
   xpc_object_t xint);
Parameters
xint

The signed integer object which is to be examined.

Return Value

The underlying signed 64-bit value.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_main

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_main(
   xpc_connection_handler_t handler);
Parameters
handler

The handler with which to accept new connections.

Discussion

The springboard into the XPCService runtime. This function will set up your service bundle's listener connection and manage it automatically. After this initial setup, this function will, by default, call dispatch_main(). You may override this behavior by setting the RunLoopType key in your XPC service bundle's Info.plist under the XPCService dictionary.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_null_create

Creates an XPC object representing the null object.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_object_t xpc_null_create(
   void);
Return Value

A new null object.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_release

Decrements the reference count of an object.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_release(
   xpc_object_t object);
Parameters
object

The object which is to be manipulated.

Discussion

The caller must take care to balance retains and releases. When creating or retaining XPC objects, the creator obtains a reference on the object. Thus, it is the caller's responsibility to call xpc_release() on those objects when they are no longer needed.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_retain

Increments the reference count of an object.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_object_t xpc_retain(
   xpc_object_t object);
Parameters
object

The object which is to be manipulated.

Return Value

The object which was given.

Discussion

Calls to xpc_retain() must be balanced with calls to xpc_release() to avoid leaking memory.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_set_event_stream_handler

#if __BLOCKS__
__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  void xpc_set_event_stream_handler(
   const char *stream,
   dispatch_queue_t targetq,
   xpc_handler_t handler);
#endif
/* __BLOCKS__ */
Parameters
stream

The name of the event stream for which this handler will be invoked.

targetq

The GCD queue to which the event handler block will be submitted. This parameter may be NULL, in which case the connection's target queue will be libdispatch's default target queue, defined as DISPATCH_TARGET_QUEUE_DEFAULT.

handler

The event handler block. The event which this block receives as its first parameter will always be a dictionary which contains the XPC_EVENT_KEY_NAME key. The value for this key will be a string whose value is the name assigned to the XPC event specified in the launchd.plist. Future keys may be added to this dictionary.

Discussion

Multiple calls to this function for the same event stream will result in undefined behavior.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_shmem_create

Creates an XPC object representing the given shared memory region.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_object_t xpc_shmem_create(
   void *region,
   size_t length);
Parameters
region

A pointer to a region of shared memory, created through a call to mmap(2) with the MAP_SHARED flag, which is to be boxed.

length

The length of the region.

Return Value

A new shared memory object.

Discussion

This API is NOT for making a private region of memory shareable. It is to allow for already-shareable regions of memory to be boxed in an XPC object. Do not pass a region allocated with malloc(3) or friends to this API.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_shmem_map

Maps the region boxed by the XPC shared memory object into the caller's address space.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  size_t xpc_shmem_map(
   xpc_object_t xshmem,
   void **region);
Parameters
xshmem

The shared memory object to be examined.

region

On return, this will point to the region at which the shared memory was mapped.

Return Value

The length of the region that was mapped. If the mapping failed, 0 is returned.

Discussion

The resulting region must be disposed of with munmap(2).

It is the responsibility of the caller to manage protections on the new region accordingly.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_string_create

Creates an XPC object representing a NUL-terminated C-string.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_object_t xpc_string_create(
   const char *string);
Parameters
string

The C-string which is to be boxed.

Return Value

A new string object.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_string_create_with_format

Creates an XPC object representing a C-string that is generated from the given format string and arguments.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_object_t xpc_string_create_with_format(
   const char *fmt,
   ...);
Parameters
fmt

The printf(3)-style format string from which to construct the final C-string to be boxed.

...

The arguments which correspond to those specified in the format string.

Return Value

A new string object.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_string_create_with_format_and_arguments

Creates an XPC object representing a C-string that is generated from the given format string and argument list pointer.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_object_t xpc_string_create_with_format_and_arguments(
   const char *fmt,
   va_list ap);
Parameters
fmt

The printf(3)-style format string from which to construct the final C-string to be boxed.

ap

A pointer to the arguments which correspond to those specified in the format string.

Return Value

A new string object.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_string_get_length

Returns the length of the underlying string.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  size_t xpc_string_get_length(
   xpc_object_t xstring);
Parameters
xstring

The string object which is to be examined.

Return Value

The length of the underlying string, not including the NUL-terminator.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_string_get_string_ptr

Returns a pointer to the internal storage of a string object.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  const char * xpc_string_get_string_ptr(
   xpc_object_t xstring);
Parameters
xstring

The string object which is to be examined.

Return Value

A pointer to the string object's internal storage.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_transaction_begin

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern void xpc_transaction_begin(
   void);
Discussion

A service with no outstanding transactions may automatically exit due to inactivity as determined by the system.

This function may be used to manually manage transactions in cases where their automatic management (as described below) does not meet the needs of an XPC service. This function also updates the transaction count used for sudden termination, i.e. vproc_transaction_begin(), and these two interfaces may be used in combination.

The XPC runtime will automatically begin a transaction on behalf of a service when a new message is received. If no reply message is expected, the transaction is automatically ended when the connection event handler returns. If a reply message is created, the transaction will end when the reply message is sent or released. An XPC service may use xpc_transaction_begin() and xpc_transaction_end() to inform the XPC runtime about activity that occurs outside of this common pattern.

When the XPC runtime has determined that the service should exit, the event handlers for all active listening and peer connections will receive XPC_ERROR_TERMINATION_IMMINENT as an indication that they should unwind their existing transactions. After this error is delivered to a connection's event handler, no more messages will be delivered to the connection.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_transaction_end

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern void xpc_transaction_end(
   void);
Discussion

As described in xpc_transaction_begin(), this API may be used interchangeably with vproc_transaction_end().

See the discussion for xpc_transaction_begin() for details regarding the XPC runtime's idle-exit policy.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_uint64_create

Creates an XPC unsigned integer object.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_object_t xpc_uint64_create(
   uint64_t value);
Parameters
value

The unsigned integer value which is to be boxed.

Return Value

A new unsigned integer object.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_uint64_get_value

Returns the underlying unsigned 64-bit integer value from an object.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  uint64_t xpc_uint64_get_value(
   xpc_object_t xuint);
Parameters
xuint

The unsigned integer object which is to be examined.

Return Value

The underlying unsigned integer value.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_uuid_create

Creates an XPC object representing a universally-unique identifier (UUID) as described by uuid(3).

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  xpc_object_t xpc_uuid_create(
   const uuid_t uuid);
Parameters
uuid

The UUID which is to be boxed.

Return Value

A new UUID object.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_uuid_get_bytes

Copies the UUID boxed by an XPC UUID object into the given UUID buffer.

__OSX_AVAILABLE_STARTING(
   __MAC_10_7, __IPHONE_5_0) extern  const uint8_t * xpc_uuid_get_bytes(
   xpc_object_t xuuid);
Parameters
xuuid

The UUID object which is to be examined.

Return Value

The underlying uuid_t bytes. The returned pointer may be safely passed to the uuid(3) APIs.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

Callbacks

See the Overview for header-level documentation.

xpc_array_applier_t

#ifdef __BLOCKS__
typedef bool (^xpc_array_applier_t)(
   size_t index,
   xpc_object_t value);
#endif
/* __BLOCKS__ */

Parameters
index

The current index in the iteration.

value

The current value in the iteration.

Return Value

A Boolean indicating whether iteration should continue.

Discussion

A block to be invoked for every value in the array.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_connection_handler_t

typedef void ( *xpc_connection_handler_t)(
   xpc_connection_t connection);

Parameters
connection

A new connection that is equivalent to one received by a listener connection. See the documentation for xpc_connection_set_event_handler for the semantics associated with the received connection.

Discussion

The type of the function that will be invoked for a bundled XPC service when there is a new connection on the service.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_dictionary_applier_t

#ifdef __BLOCKS__
typedef bool (^xpc_dictionary_applier_t)(
   const char *key,
   xpc_object_t value);
#endif
/* __BLOCKS__ */

Parameters
key

The current key in the iteration.

value

The current value in the iteration.

Return Value

A Boolean indicating whether iteration should continue.

Discussion

A block to be invoked for every key/value pair in the dictionary.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_handler_t

#if __BLOCKS__
typedef void (^xpc_handler_t)(
   xpc_object_t object);
#endif
/* __BLOCKS__ */

Discussion

You are not responsible for releasing the event object.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

Data Types

See the Overview for header-level documentation.

xpc_object_t

typedef void * xpc_object_t;
Discussion

A type that can describe all XPC objects. Dictionaries, arrays, strings, etc. are all described by this type.

XPC objects are created with a retain count of 1, and therefore it is the caller's responsibility to call xpc_release() on them when they are no longer needed.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

xpc_type_t

typedef const struct _xpc_type_s * xpc_type_t;
Discussion

A type that describes XPC object types.

Availability
  • Available in OS X v10.7 and later.
Declared In
xpc/xpc.h

Constants

See the Overview for header-level documentation.

Defines

   
#define XPC_ARRAY_APPEND ((size_t)(-1))
#define XPC_BOOL_FALSE (&_xpc_bool_false)
#define XPC_BOOL_TRUE (&_xpc_bool_true)
#define XPC_ERROR_KEY_DESCRIPTION _xpc_error_key_description
#define XPC_EVENT_KEY_NAME _xpc_event_key_name
#define XPC_TYPE_ARRAY (&_xpc_type_array)
#define XPC_TYPE_BOOL (&_xpc_type_bool)
#define XPC_TYPE_CONNECTION (&_xpc_type_connection)
#define XPC_TYPE_DATA (&_xpc_type_data)
#define XPC_TYPE_DATE (&_xpc_type_date)
#define XPC_TYPE_DICTIONARY (&_xpc_type_dictionary)
#define XPC_TYPE_DOUBLE (&_xpc_type_double)
#define XPC_TYPE_ENDPOINT (&_xpc_type_endpoint)
#define XPC_TYPE_ERROR (&_xpc_type_error)
#define XPC_TYPE_FD (&_xpc_type_fd)
#define XPC_TYPE_INT64 (&_xpc_type_int64)
#define XPC_TYPE_NULL (&_xpc_type_null)
#define XPC_TYPE_SHMEM (&_xpc_type_shmem)
#define XPC_TYPE_STRING (&_xpc_type_string)
#define XPC_TYPE_UINT64 (&_xpc_type_uint64)
#define XPC_TYPE_UUID (&_xpc_type_uuid)
Constants
XPC_ARRAY_APPEND

A constant that may be passed as the destination index to the class of primitive XPC array setters indicating that the given primitive should be appended to the array.

Available in OS X v10.7 and later.

Declared in xpc/xpc.h.

XPC_BOOL_FALSE

A constant representing a Boolean value of false. You may compare a Boolean object against this constant to determine its value.

Available in OS X v10.7 and later.

Declared in xpc/xpc.h.

XPC_BOOL_TRUE

A constant representing a Boolean value of true. You may compare a Boolean object against this constant to determine its value.

Available in OS X v10.7 and later.

Declared in xpc/xpc.h.

XPC_ERROR_KEY_DESCRIPTION

In an error dictionary, querying for this key will return a string object that describes the error in a human-readable way.

Available in OS X v10.7 and later.

Declared in xpc/xpc.h.

XPC_EVENT_KEY_NAME

In an event dictionary, this querying for this key will return a string object that describes the event.

Available in OS X v10.7 and later.

Declared in xpc/xpc.h.

XPC_TYPE_ARRAY

A type representing an array of XPC objects. This array must be contiguous, i.e. it cannot contain NULL values. If you wish to indicate that a slot is empty, you can insert a null object. The array will grow as needed to accommodate more objects.

Available in OS X v10.7 and later.

Declared in xpc/xpc.h.

XPC_TYPE_BOOL

A type representing a Boolean value.

Available in OS X v10.7 and later.

Declared in xpc/xpc.h.

XPC_TYPE_CONNECTION

A type representing a connection to a named service. This connection is bidirectional and can be used to both send and receive messages. A connection carries the credentials of the remote service provider.

Available in OS X v10.7 and later.

Declared in xpc/xpc.h.

XPC_TYPE_DATA

A type representing a an arbitrary buffer of bytes.

Available in OS X v10.7 and later.

Declared in xpc/xpc.h.

XPC_TYPE_DATE

A type representing a date interval. The interval is with respect to the Unix epoch. XPC dates are in UTC and are thus unaware of local time or leap seconds.

Available in OS X v10.7 and later.

Declared in xpc/xpc.h.

XPC_TYPE_DICTIONARY

A type representing a dictionary of XPC objects, keyed off of C-strings. You may insert NULL values into this collection. The dictionary will grow as needed to accommodate more key/value pairs.

Available in OS X v10.7 and later.

Declared in xpc/xpc.h.

XPC_TYPE_DOUBLE

A type representing an IEEE-compliant, double-precision floating point value.

Available in OS X v10.7 and later.

Declared in xpc/xpc.h.

XPC_TYPE_ENDPOINT

A type representing a connection in serialized form. Unlike a connection, an endpoint is an inert object that does not have any runtime activity associated with it. Thus, it is safe to pass an endpoint in a message. Upon receiving an endpoint, the recipient can use xpc_connection_create_from_endpoint() to create as many distinct connections as desired.

Available in OS X v10.7 and later.

Declared in xpc/xpc.h.

XPC_TYPE_ERROR

A type representing an error object. Errors in XPC are dictionaries, but xpc_get_type() will return this type when given an error object. You cannot create an error object directly; XPC will only give them to handlers. These error objects have pointer values that are constant across the lifetime of your process and can be safely compared.

These constants are enumerated in the header for the connection object. Error dictionaries may reserve keys so that they can be queried to obtain more detailed information about the error. Currently, the only reserved key is XPC_ERROR_KEY_DESCRIPTION.

Available in OS X v10.7 and later.

Declared in xpc/xpc.h.

XPC_TYPE_FD

A type representing a POSIX file descriptor.

Available in OS X v10.7 and later.

Declared in xpc/xpc.h.

XPC_TYPE_INT64

A type representing a signed, 64-bit integer value.

Available in OS X v10.7 and later.

Declared in xpc/xpc.h.

XPC_TYPE_NULL

A type representing a null object. This type is useful for disambiguating an unset key in a dictionary and one which has been reserved but set empty. Also, this type is a way to represent a "null" value in dictionaries, which do not accept NULL.

Available in OS X v10.7 and later.

Declared in xpc/xpc.h.

XPC_TYPE_SHMEM

A type representing a region of shared memory.

Available in OS X v10.7 and later.

Declared in xpc/xpc.h.

XPC_TYPE_STRING

A type representing a NUL-terminated C-string.

Available in OS X v10.7 and later.

Declared in xpc/xpc.h.

XPC_TYPE_UINT64

A type representing an unsigned, 64-bit integer value.

Available in OS X v10.7 and later.

Declared in xpc/xpc.h.

XPC_TYPE_UUID

A type representing a Universally Unique Identifier as defined by uuid(3).

Available in OS X v10.7 and later.

Declared in xpc/xpc.h.