Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

xpc_object(3)            BSD Library Functions Manual            xpc_object(3)

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

     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  Objec-tive-C Objective-C
           tive-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:
                     •   xpc_data_get_bytes_ptr(3), xpc_string_get_string_ptr(3), xpc_uuid_get_bytes (3)
                     •   xpc_array_get_data (3), xpc_array_get_string(3), xpc_array_get_uuid (3)
                     •   xpc_dictionary_get_data (3),                           xpc_dictionary_get_string(3),
                         xpc_dictionary_get_uuid(3)

           -   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  han-dler handler
               dler 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 with Objective-C Garbage Collection or for the legacy Objective-C runtime.
           It  can also be disabled manually by using compiler options to define the OS_OBJECT_USE_OBJC pre-processor preprocessor
           processor 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_get_fd(3), xpc_array_set_fd(3), xpc_array_get_fd (3)
           •   xpc_dictionary_set_connection (3), xpc_dictionary_get_connection(3),
               xpc_array_set_connection(3), xpc_array_get_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 addi-tional additional
     tional 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 underlyin value in order to determine equality.

     Collection types are compared for deep equality, that is to say, two arrays are equal only if they con-tain contain
     tain 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 pro-cesses processes
     cesses 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.

SEE ALSO
     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)

Darwin                           1 March, 2012                          Darwin