12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507 |
- // Copyright (c) 2009-2011 Apple Inc. All rights reserved.
- #ifndef __XPC_H__
- #define __XPC_H__
- #include <os/object.h>
- #include <dispatch/dispatch.h>
- #include <sys/mman.h>
- #include <uuid/uuid.h>
- #include <bsm/audit.h>
- #include <stdarg.h>
- #include <stdbool.h>
- #include <stdint.h>
- #include <stdlib.h>
- #include <stdio.h>
- #include <string.h>
- #include <unistd.h>
- #include <fcntl.h>
- __BEGIN_DECLS
- #ifndef __OSX_AVAILABLE_STARTING
- #define __OSX_AVAILABLE_STARTING(x, y)
- #endif
- #ifndef __XPC_INDIRECT__
- #define __XPC_INDIRECT__
- #endif
- #include "base.h"
- #define XPC_API_VERSION 20121012
- /*!
- * @typedef xpc_type_t
- * A type that describes XPC object types.
- */
- typedef const struct _xpc_type_s * xpc_type_t;
- #ifndef __XPC_BUILDING_XPC__
- #define XPC_TYPE(type) const struct _xpc_type_s type
- #endif
- /*!
- * @typedef xpc_object_t
- * 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.
- */
- #if OS_OBJECT_USE_OBJC
- /* By default, XPC objects are declared as Objective-C types when building with
- * an Objective-C compiler. This allows them to participate in ARC, in RR
- * management by the Blocks runtime and in leaks checking by the static
- * analyzer, and enables them to be added to Cocoa collections.
- *
- * See <os/object.h> for details.
- */
- OS_OBJECT_DECL(xpc_object);
- #ifndef __XPC_PROJECT_BUILD__
- #define XPC_DECL(name) typedef xpc_object_t name##_t
- #endif
- #define XPC_GLOBAL_OBJECT(object) ((OS_OBJECT_BRIDGE xpc_object_t)&(object))
- #define XPC_RETURNS_RETAINED OS_OBJECT_RETURNS_RETAINED
- XPC_INLINE XPC_NONNULL_ALL
- void
- _xpc_object_validate(xpc_object_t object) {
- void *isa = *(void * volatile *)(OS_OBJECT_BRIDGE void *)object;
- (void)isa;
- }
- #else
- typedef void * xpc_object_t;
- #define XPC_DECL(name) typedef struct _##name##_s * name##_t
- #define XPC_GLOBAL_OBJECT(object) (&(object))
- #define XPC_RETURNS_RETAINED
- #endif // OS_OBJECT_USE_OBJC
- /*!
- * @typedef xpc_handler_t
- * The type of block that is accepted by the XPC connection APIs.
- *
- * @param object
- * An XPC object that is to be handled. If there was an error, this object will
- * be equal to one of the well-known XPC_ERROR_* dictionaries and can be
- * compared with the equality operator.
- *
- * @discussion
- * You are not responsible for releasing the event object.
- */
- #if __BLOCKS__
- typedef void (^xpc_handler_t)(xpc_object_t object);
- #endif // __BLOCKS__
- /*!
- * @define 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.
- */
- #define XPC_TYPE_CONNECTION (&_xpc_type_connection)
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT
- XPC_TYPE(_xpc_type_connection);
- XPC_DECL(xpc_connection);
- /*!
- * @typedef xpc_connection_handler_t
- * The type of the function that will be invoked for a bundled XPC service when
- * there is a new connection on the service.
- *
- * @param connection
- * A new connection that is equivalent to one received by a listener connection.
- * See the documentation for {@link xpc_connection_set_event_handler} for the
- * semantics associated with the received connection.
- */
- typedef void (*xpc_connection_handler_t)(xpc_connection_t connection);
- /*!
- * @define 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.
- */
- #define XPC_TYPE_ENDPOINT (&_xpc_type_endpoint)
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT
- XPC_TYPE(_xpc_type_endpoint);
- XPC_DECL(xpc_endpoint);
- /*!
- * @define 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.
- */
- #define XPC_TYPE_NULL (&_xpc_type_null)
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT
- XPC_TYPE(_xpc_type_null);
- /*!
- * @define XPC_TYPE_BOOL
- * A type representing a Boolean value.
- */
- #define XPC_TYPE_BOOL (&_xpc_type_bool)
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT
- XPC_TYPE(_xpc_type_bool);
- /*!
- * @define XPC_BOOL_TRUE
- * A constant representing a Boolean value of true. You may compare a Boolean
- * object against this constant to determine its value.
- */
- #define XPC_BOOL_TRUE XPC_GLOBAL_OBJECT(_xpc_bool_true)
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT
- const struct _xpc_bool_s _xpc_bool_true;
- /*!
- * @define XPC_BOOL_FALSE
- * A constant representing a Boolean value of false. You may compare a Boolean
- * object against this constant to determine its value.
- */
- #define XPC_BOOL_FALSE XPC_GLOBAL_OBJECT(_xpc_bool_false)
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT
- const struct _xpc_bool_s _xpc_bool_false;
- /*!
- * @define XPC_TYPE_INT64
- * A type representing a signed, 64-bit integer value.
- */
- #define XPC_TYPE_INT64 (&_xpc_type_int64)
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT
- XPC_TYPE(_xpc_type_int64);
- /*!
- * @define XPC_TYPE_UINT64
- * A type representing an unsigned, 64-bit integer value.
- */
- #define XPC_TYPE_UINT64 (&_xpc_type_uint64)
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT
- XPC_TYPE(_xpc_type_uint64);
- /*!
- * @define XPC_TYPE_DOUBLE
- * A type representing an IEEE-compliant, double-precision floating point value.
- */
- #define XPC_TYPE_DOUBLE (&_xpc_type_double)
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT
- XPC_TYPE(_xpc_type_double);
- /*!
- * @define XPC_TYPE_DATE
- * A type representing a date interval. The interval is with respect to the
- * Unix epoch. XPC dates are in Unix time and are thus unaware of local time
- * or leap seconds.
- */
- #define XPC_TYPE_DATE (&_xpc_type_date)
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT
- XPC_TYPE(_xpc_type_date);
- /*!
- * @define XPC_TYPE_DATA
- * A type representing a an arbitrary buffer of bytes.
- */
- #define XPC_TYPE_DATA (&_xpc_type_data)
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT
- XPC_TYPE(_xpc_type_data);
- /*!
- * @define XPC_TYPE_STRING
- * A type representing a NUL-terminated C-string.
- */
- #define XPC_TYPE_STRING (&_xpc_type_string)
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT
- XPC_TYPE(_xpc_type_string);
- /*!
- * @define XPC_TYPE_UUID
- * A type representing a Universally Unique Identifier as defined by uuid(3).
- */
- #define XPC_TYPE_UUID (&_xpc_type_uuid)
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT
- XPC_TYPE(_xpc_type_uuid);
- /*!
- * @define XPC_TYPE_FD
- * A type representing a POSIX file descriptor.
- */
- #define XPC_TYPE_FD (&_xpc_type_fd)
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT
- XPC_TYPE(_xpc_type_fd);
- /*!
- * @define XPC_TYPE_SHMEM
- * A type representing a region of shared memory.
- */
- #define XPC_TYPE_SHMEM (&_xpc_type_shmem)
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT
- XPC_TYPE(_xpc_type_shmem);
- /*!
- * @define 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.
- */
- #define XPC_TYPE_ARRAY (&_xpc_type_array)
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT
- XPC_TYPE(_xpc_type_array);
- /*!
- * @define 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.
- */
- #define XPC_TYPE_DICTIONARY (&_xpc_type_dictionary)
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT
- XPC_TYPE(_xpc_type_dictionary);
- /*!
- * @define 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.
- */
- #define XPC_TYPE_ERROR (&_xpc_type_error)
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT
- XPC_TYPE(_xpc_type_error);
- /*!
- * @define 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.
- */
- #define XPC_ERROR_KEY_DESCRIPTION _xpc_error_key_description
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT
- const char *const _xpc_error_key_description;
- /*!
- * @define XPC_EVENT_KEY_NAME
- * In an event dictionary, this querying for this key will return a string
- * object that describes the event.
- */
- #define XPC_EVENT_KEY_NAME _xpc_event_key_name
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT
- const char *const _xpc_event_key_name;
- #ifndef __XPC_BUILDING_XPC__
- #include "endpoint.h"
- #include "debug.h"
- #if __BLOCKS__
- #include "connection.h"
- #include "activity.h"
- #endif // __BLOCKS__
- #undef __XPC_INDIRECT__
- #endif // __XPC_BUILDING_XPC__
- #pragma mark XPC Object Protocol
- /*!
- * @function xpc_retain
- *
- * @abstract
- * Increments the reference count of an object.
- *
- * @param object
- * The object which is to be manipulated.
- *
- * @result
- * The object which was given.
- *
- * @discussion
- * Calls to xpc_retain() must be balanced with calls to xpc_release()
- * to avoid leaking memory.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1
- xpc_object_t
- xpc_retain(xpc_object_t object);
- #if OS_OBJECT_USE_OBJC_RETAIN_RELEASE
- #undef xpc_retain
- #define xpc_retain(object) ({ xpc_object_t _o = (object); \
- _xpc_object_validate(_o); [_o retain]; })
- #endif
- /*!
- * @function xpc_release
- *
- * @abstract
- * Decrements the reference count of an object.
- *
- * @param 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1
- void
- xpc_release(xpc_object_t object);
- #if OS_OBJECT_USE_OBJC_RETAIN_RELEASE
- #undef xpc_release
- #define xpc_release(object) ({ xpc_object_t _o = (object); \
- _xpc_object_validate(_o); [_o release]; })
- #endif
- /*!
- * @function xpc_get_type
- *
- * @abstract
- * Returns the type of an object.
- *
- * @param object
- * The object to examine.
- *
- * @result
- * An opaque pointer describing the type of the object. This pointer is suitable
- * direct comparison to exported type constants with the equality operator.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT
- xpc_type_t
- xpc_get_type(xpc_object_t object);
- /*!
- * @function xpc_copy
- *
- * @abstract
- * Creates a copy of the object.
- *
- * @param object
- * The object to copy.
- *
- * @result
- * 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT XPC_RETURNS_RETAINED
- xpc_object_t
- xpc_copy(xpc_object_t object);
- /*!
- * @function xpc_equal
- *
- * @abstract
- * Compares two objects for equality.
- *
- * @param object1
- * The first object to compare.
- *
- * @param object2
- * The second object to compare.
- *
- * @result
- * 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 XPC_WARN_RESULT
- bool
- xpc_equal(xpc_object_t object1, xpc_object_t object2);
- /*!
- * @function xpc_hash
- *
- * @abstract
- * Calculates a hash value for the given object.
- *
- * @param 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.
- *
- * @result
- * 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1 XPC_WARN_RESULT
- size_t
- xpc_hash(xpc_object_t object);
- /*!
- * @function xpc_copy_description
- *
- * @abstract
- * Copies a debug string describing the object.
- *
- * @param object
- * The object which is to be examined.
- *
- * @result
- * A string describing object which contains information useful for debugging.
- * This string should be disposed of with free(3) when done.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_MALLOC XPC_WARN_RESULT XPC_NONNULL1
- char *
- xpc_copy_description(xpc_object_t object);
- #pragma mark XPC Object Types
- #pragma mark Null
- /*!
- * @function xpc_null_create
- *
- * @abstract
- * Creates an XPC object representing the null object.
- *
- * @result
- * A new null object.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_RETURNS_RETAINED XPC_WARN_RESULT
- xpc_object_t
- xpc_null_create(void);
- #pragma mark Boolean
- /*!
- * @function xpc_bool_create
- *
- * @abstract
- * Creates an XPC Boolean object.
- *
- * @param value
- * The Boolean primitive value which is to be boxed.
- *
- * @result
- * A new Boolean object.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_RETURNS_RETAINED XPC_WARN_RESULT
- xpc_object_t
- xpc_bool_create(bool value);
- /*!
- * @function xpc_bool_get_value
- *
- * @abstract
- * Returns the underlying Boolean value from the object.
- *
- * @param xbool
- * The Boolean object which is to be examined.
- *
- * @result
- * The underlying Boolean value.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT
- bool
- xpc_bool_get_value(xpc_object_t xbool);
- #pragma mark Signed Integer
- /*!
- * @function xpc_int64_create
- *
- * @abstract
- * Creates an XPC signed integer object.
- *
- * @param value
- * The signed integer value which is to be boxed.
- *
- * @result
- * A new signed integer object.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT
- xpc_object_t
- xpc_int64_create(int64_t value);
- /*!
- * @function xpc_int64_get_value
- *
- * @abstract
- * Returns the underlying signed 64-bit integer value from an object.
- *
- * @param xint
- * The signed integer object which is to be examined.
- *
- * @result
- * The underlying signed 64-bit value.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
- int64_t
- xpc_int64_get_value(xpc_object_t xint);
- #pragma mark Unsigned Integer
- /*!
- * @function xpc_uint64_create
- *
- * @abstract
- * Creates an XPC unsigned integer object.
- *
- * @param value
- * The unsigned integer value which is to be boxed.
- *
- * @result
- * A new unsigned integer object.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT
- xpc_object_t
- xpc_uint64_create(uint64_t value);
- /*!
- * @function xpc_uint64_get_value
- *
- * @abstract
- * Returns the underlying unsigned 64-bit integer value from an object.
- *
- * @param xuint
- * The unsigned integer object which is to be examined.
- *
- * @result
- * The underlying unsigned integer value.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
- uint64_t
- xpc_uint64_get_value(xpc_object_t xuint);
- #pragma mark Double
- /*!
- * @function xpc_double_create
- *
- * @abstract
- * Creates an XPC double object.
- *
- * @param value
- * The floating point quantity which is to be boxed.
- *
- * @result
- * A new floating point object.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT
- xpc_object_t
- xpc_double_create(double value);
- /*!
- * @function xpc_double_get_value
- *
- * @abstract
- * Returns the underlying double-precision floating point value from an object.
- *
- * @param xdouble
- * The floating point object which is to be examined.
- *
- * @result
- * The underlying floating point value.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
- double
- xpc_double_get_value(xpc_object_t xdouble);
- #pragma mark Date
- /*!
- * @function xpc_date_create
- *
- * @abstract
- * Creates an XPC date object.
- *
- * @param 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.
- *
- * @result
- * A new date object.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT
- xpc_object_t
- xpc_date_create(int64_t interval);
- /*!
- * @function xpc_date_create_from_current
- *
- * @abstract
- * Creates an XPC date object representing the current date.
- *
- * @result
- * A new date object representing the current date.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT
- xpc_object_t
- xpc_date_create_from_current(void);
- /*!
- * @function xpc_date_get_value
- *
- * @abstract
- * Returns the underlying date interval from an object.
- *
- * @param xdate
- * The date object which is to be examined.
- *
- * @result
- * The underlying date interval.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
- int64_t
- xpc_date_get_value(xpc_object_t xdate);
- #pragma mark Data
- /*!
- * @function xpc_data_create
- *
- * @abstract
- * Creates an XPC object representing buffer of bytes.
- *
- * @param 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.
- *
- * @param length
- * The number of bytes which are to be boxed.
- *
- * @result
- * 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT
- xpc_object_t
- xpc_data_create(const void *bytes, size_t length);
- /*!
- * @function xpc_data_create_with_dispatch_data
- *
- * @abstract
- * Creates an XPC object representing buffer of bytes described by the given GCD
- * data object.
- *
- * @param ddata
- * The GCD data object containing the bytes which are to be boxed. This object
- * is retained by the data object.
- *
- * @result
- * 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1
- xpc_object_t
- xpc_data_create_with_dispatch_data(dispatch_data_t ddata);
- /*!
- * @function xpc_data_get_length
- *
- * @abstract
- * Returns the length of the data encapsulated by an XPC data object.
- *
- * @param xdata
- * The data object which is to be examined.
- *
- * @result
- * The length of the underlying boxed data.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
- size_t
- xpc_data_get_length(xpc_object_t xdata);
- /*!
- * @function xpc_data_get_bytes_ptr
- *
- * @abstract
- * Returns a pointer to the internal storage of a data object.
- *
- * @param xdata
- * The data object which is to be examined.
- *
- * @result
- * A pointer to the underlying boxed data.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
- const void *
- xpc_data_get_bytes_ptr(xpc_object_t xdata);
- /*!
- * @function xpc_data_get_bytes
- *
- * @abstract
- * Copies the bytes stored in an data objects into the specified buffer.
- *
- * @param xdata
- * The data object which is to be examined.
- *
- * @param buffer
- * The buffer in which to copy the data object's bytes.
- *
- * @param 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.
- *
- * @param length
- * The length of the destination buffer.
- *
- * @result
- * The number of bytes that were copied into the buffer.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 XPC_NONNULL2
- size_t
- xpc_data_get_bytes(xpc_object_t xdata,
- void *buffer, size_t off, size_t length);
- #pragma mark String
- /*!
- * @function xpc_string_create
- *
- * @abstract
- * Creates an XPC object representing a NUL-terminated C-string.
- *
- * @param string
- * The C-string which is to be boxed.
- *
- * @result
- * A new string object.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1
- xpc_object_t
- xpc_string_create(const char *string);
- /*!
- * @function xpc_string_create_with_format
- *
- * @abstract
- * Creates an XPC object representing a C-string that is generated from the
- * given format string and arguments.
- *
- * @param fmt
- * The printf(3)-style format string from which to construct the final C-string
- * to be boxed.
- *
- * @param ...
- * The arguments which correspond to those specified in the format string.
- *
- * @result
- * A new string object.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1
- XPC_PRINTF(1, 2)
- xpc_object_t
- xpc_string_create_with_format(const char *fmt, ...);
- /*!
- * @function xpc_string_create_with_format_and_arguments
- *
- * @abstract
- * Creates an XPC object representing a C-string that is generated from the
- * given format string and argument list pointer.
- *
- * @param fmt
- * The printf(3)-style format string from which to construct the final C-string
- * to be boxed.
- *
- * @param ap
- * A pointer to the arguments which correspond to those specified in the format
- * string.
- *
- * @result
- * A new string object.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1
- XPC_NONNULL2 XPC_PRINTF(1, 0)
- xpc_object_t
- xpc_string_create_with_format_and_arguments(const char *fmt, va_list ap);
- /*!
- * @function xpc_string_get_length
- *
- * @abstract
- * Returns the length of the underlying string.
- *
- * @param xstring
- * The string object which is to be examined.
- *
- * @result
- * The length of the underlying string, not including the NUL-terminator.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL
- size_t
- xpc_string_get_length(xpc_object_t xstring);
- /*!
- * @function xpc_string_get_string_ptr
- *
- * @abstract
- * Returns a pointer to the internal storage of a string object.
- *
- * @param xstring
- * The string object which is to be examined.
- *
- * @result
- * A pointer to the string object's internal storage.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
- const char *
- xpc_string_get_string_ptr(xpc_object_t xstring);
- #pragma mark UUID
- /*!
- * @function xpc_uuid_create
- *
- * @abstract
- * Creates an XPC object representing a universally-unique identifier (UUID) as
- * described by uuid(3).
- *
- * @param uuid
- * The UUID which is to be boxed.
- *
- * @result
- * A new UUID object.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT
- xpc_object_t
- xpc_uuid_create(const uuid_t uuid);
- /*!
- * @function xpc_uuid_get_bytes
- *
- * @abstract
- * Returns a pointer to the the boxed UUID bytes in an XPC UUID object.
- *
- * @param xuuid
- * The UUID object which is to be examined.
- *
- * @result
- * The underlying <code>uuid_t</code> bytes. The returned pointer may be safely
- * passed to the uuid(3) APIs.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1
- const uint8_t *
- xpc_uuid_get_bytes(xpc_object_t xuuid);
- #pragma mark File Descriptors
- /*!
- * @function xpc_fd_create
- *
- * @abstract
- * Creates an XPC object representing a POSIX file descriptor.
- *
- * @param fd
- * The file descriptor which is to be boxed.
- *
- * @result
- * 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT
- xpc_object_t
- xpc_fd_create(int fd);
- /*!
- * @function xpc_fd_dup
- *
- * @abstract
- * Returns a file descriptor that is equivalent to the one boxed by the file
- * file descriptor object.
- *
- * @param xfd
- * The file descriptor object which is to be examined.
- *
- * @result
- * 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
- int
- xpc_fd_dup(xpc_object_t xfd);
- #pragma mark Shared Memory
- /*!
- * @function xpc_shmem_create
- *
- * @abstract
- * Creates an XPC object representing the given shared memory region.
- *
- * @param 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.
- *
- * @param length
- * The length of the region.
- *
- * @result
- * A new shared memory object.
- *
- * @discussion
- * Only memory regions whose exact characteristics are known to the caller
- * should be boxed using this API. Memory returned from malloc(3) may not be
- * safely shared on either OS X or iOS because the underlying virtual memory
- * objects for malloc(3)ed allocations are owned by the malloc(3) subsystem and
- * not the caller of malloc(3).
- *
- * If you wish to share a memory region that you receive from another subsystem,
- * part of the interface contract with that other subsystem must include how to
- * create the region of memory, or sharing it may be unsafe.
- *
- * Certain operations may internally fragment a region of memory in a way that
- * would truncate the range detected by the shared memory object. vm_copy(), for
- * example, may split the region into multiple parts to avoid copying certain
- * page ranges. For this reason, it is recommended that you delay all VM
- * operations until the shared memory object has been created so that the VM
- * system knows that the entire range is intended for sharing.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1
- xpc_object_t
- xpc_shmem_create(void *region, size_t length);
- /*!
- * @function xpc_shmem_map
- *
- * @abstract
- * Maps the region boxed by the XPC shared memory object into the caller's
- * address space.
- *
- * @param xshmem
- * The shared memory object to be examined.
- *
- * @param region
- * On return, this will point to the region at which the shared memory was
- * mapped.
- *
- * @result
- * The length of the region that was mapped. If the mapping failed, 0 is
- * returned. The length of the mapped region will always be an integral page
- * size, even if the creator of the region specified a non-integral page size.
- *
- * @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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL
- size_t
- xpc_shmem_map(xpc_object_t xshmem, void **region);
- #pragma mark Array
- /*!
- * @typedef xpc_array_applier_t
- * A block to be invoked for every value in the array.
- *
- * @param index
- * The current index in the iteration.
- *
- * @param value
- * The current value in the iteration.
- *
- * @result
- * A Boolean indicating whether iteration should continue.
- */
- #ifdef __BLOCKS__
- typedef bool (^xpc_array_applier_t)(size_t index, xpc_object_t value);
- #endif // __BLOCKS__
- /*!
- * @function xpc_array_create
- *
- * @abstract
- * Creates an XPC object representing an array of XPC objects.
- *
- * @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
- * {@link xpc_null_create}.
- *
- * @param 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.
- *
- * @param 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.
- *
- * @result
- * A new array object.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT
- xpc_object_t
- xpc_array_create(const xpc_object_t *objects, size_t count);
- /*!
- * @function xpc_array_set_value
- *
- * @abstract
- * Inserts the specified object into the array at the specified index.
- *
- * @param xarray
- * The array object which is to be manipulated.
- *
- * @param 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.
- *
- * @param 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1 XPC_NONNULL3
- void
- xpc_array_set_value(xpc_object_t xarray, size_t index, xpc_object_t value);
- /*!
- * @function xpc_array_append_value
- *
- * @abstract
- * Appends an object to an XPC array.
- *
- * @param xarray
- * The array object which is to be manipulated.
- *
- * @param value
- * The object to append. This object is retained by the array.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2
- void
- xpc_array_append_value(xpc_object_t xarray, xpc_object_t value);
- /*!
- * @function xpc_array_get_count
- *
- * @abstract
- * Returns the count of values currently in the array.
- *
- * @param xarray
- * The array object which is to be examined.
- *
- * @result
- * The count of values in the array.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
- size_t
- xpc_array_get_count(xpc_object_t xarray);
- /*!
- * @function xpc_array_get_value
- *
- * @abstract
- * Returns the value at the specified index in the array.
- *
- * @param xarray
- * The array object which is to be examined.
- *
- * @param index
- * The index of the value to obtain. This value must lie within the range of
- * indexes as specified in xpc_array_set_value().
- *
- * @result
- * 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL_ALL
- xpc_object_t
- xpc_array_get_value(xpc_object_t xarray, size_t index);
- /*!
- * @function xpc_array_apply
- *
- * @abstract
- * Invokes the given block for every value in the array.
- *
- * @param xarray
- * The array object which is to be examined.
- *
- * @param applier
- * The block which this function applies to every element in the array.
- *
- * @result
- * 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.
- */
- #ifdef __BLOCKS__
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL_ALL
- bool
- xpc_array_apply(xpc_object_t xarray, xpc_array_applier_t applier);
- #endif // __BLOCKS__
- #pragma mark Array Primitive Setters
- /*!
- * @define 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.
- */
- #define XPC_ARRAY_APPEND ((size_t)(-1))
- /*!
- * @function xpc_array_set_bool
- *
- * @abstract
- * Inserts a <code>bool</code> (primitive) value into an array.
- *
- * @param xarray
- * The array object which is to be manipulated.
- *
- * @param 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.
- *
- * @param value
- * The <code>bool</code> value to insert. After calling this method, the XPC
- * object corresponding to the primitive value inserted may be safely retrieved
- * with {@link xpc_array_get_value()}.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1
- void
- xpc_array_set_bool(xpc_object_t xarray, size_t index, bool value);
- /*!
- * @function xpc_array_set_int64
- *
- * @abstract
- * Inserts an <code>int64_t</code> (primitive) value into an array.
- *
- * @param xarray
- * The array object which is to be manipulated.
- *
- * @param 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.
- *
- * @param value
- * The <code>int64_t</code> value to insert. After calling this method, the XPC
- * object corresponding to the primitive value inserted may be safely retrieved
- * with {@link xpc_array_get_value()}.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1
- void
- xpc_array_set_int64(xpc_object_t xarray, size_t index, int64_t value);
- /*!
- * @function xpc_array_set_uint64
- *
- * @abstract
- * Inserts a <code>uint64_t</code> (primitive) value into an array.
- *
- * @param xarray
- * The array object which is to be manipulated.
- *
- * @param 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.
- *
- * @param value
- * The <code>uint64_t</code> value to insert. After calling this method, the XPC
- * object corresponding to the primitive value inserted may be safely retrieved
- * with {@link xpc_array_get_value()}.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1
- void
- xpc_array_set_uint64(xpc_object_t xarray, size_t index, uint64_t value);
- /*!
- * @function xpc_array_set_double
- *
- * @abstract
- * Inserts a <code>double</code> (primitive) value into an array.
- *
- * @param xarray
- * The array object which is to be manipulated.
- *
- * @param 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.
- *
- * @param value
- * The <code>double</code> value to insert. After calling this method, the XPC
- * object corresponding to the primitive value inserted may be safely retrieved
- * with {@link xpc_array_get_value()}.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1
- void
- xpc_array_set_double(xpc_object_t xarray, size_t index, double value);
- /*!
- * @function xpc_array_set_date
- *
- * @abstract
- * Inserts a date value into an array.
- *
- * @param xarray
- * The array object which is to be manipulated.
- *
- * @param 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.
- *
- * @param value
- * The <code>double</code> value to insert. After calling this method, the XPC
- * object corresponding to the primitive value inserted may be safely retrieved
- * with {@link xpc_array_get_value()}.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1
- void
- xpc_array_set_date(xpc_object_t xarray, size_t index, int64_t value);
- /*!
- * @function xpc_array_set_data
- *
- * @abstract
- * Inserts a raw data value into an array.
- *
- * @param xarray
- * The array object which is to be manipulated.
- *
- * @param 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.
- *
- * @param bytes
- * The raw data to insert. After calling this method, the XPC object
- * corresponding to the primitive value inserted may be safely retrieved with
- * {@link xpc_array_get_value()}.
- *
- * @param length
- * The length of the data.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1 XPC_NONNULL3
- void
- xpc_array_set_data(xpc_object_t xarray, size_t index, const void *bytes,
- size_t length);
- /*!
- * @function xpc_array_set_string
- *
- * @abstract
- * Inserts a C string into an array.
- *
- * @param xarray
- * The array object which is to be manipulated.
- *
- * @param 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.
- *
- * @param string
- * The C string to insert. After calling this method, the XPC object
- * corresponding to the primitive value inserted may be safely retrieved with
- * {@link xpc_array_get_value()}.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1 XPC_NONNULL3
- void
- xpc_array_set_string(xpc_object_t xarray, size_t index, const char *string);
- /*!
- * @function xpc_array_set_uuid
- *
- * @abstract
- * Inserts a <code>uuid_t</code> (primitive) value into an array.
- *
- * @param xarray
- * The array object which is to be manipulated.
- *
- * @param 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.
- *
- * @param uuid
- * The UUID primitive to insert. After calling this method, the XPC object
- * corresponding to the primitive value inserted may be safely retrieved with
- * {@link xpc_array_get_value()}.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1
- void
- xpc_array_set_uuid(xpc_object_t xarray, size_t index, const uuid_t uuid);
- /*!
- * @function xpc_array_set_fd
- *
- * @abstract
- * Inserts a file descriptor into an array.
- *
- * @param xarray
- * The array object which is to be manipulated.
- *
- * @param 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.
- *
- * @param fd
- * The file descriptor to insert. After calling this method, the XPC object
- * corresponding to the primitive value inserted may be safely retrieved with
- * {@link xpc_array_get_value()}.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1
- void
- xpc_array_set_fd(xpc_object_t xarray, size_t index, int fd);
- /*!
- * @function xpc_array_set_connection
- *
- * @abstract
- * Inserts a connection into an array.
- *
- * @param xarray
- * The array object which is to be manipulated.
- *
- * @param 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.
- *
- * @param connection
- * The connection to insert. After calling this method, the XPC object
- * corresponding to the primitive value inserted may be safely retrieved with
- * {@link xpc_array_get_value()}. The connection is NOT retained by the array.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1
- void
- xpc_array_set_connection(xpc_object_t xarray, size_t index,
- xpc_connection_t connection);
- #pragma mark Array Primitive Getters
- /*!
- * @function xpc_array_get_bool
- *
- * @abstract
- * Gets a <code>bool</code> primitive value from an array directly.
- *
- * @param xarray
- * The array which is to be examined.
- *
- * @param 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.
- *
- * @result
- * The underlying <code>bool</code> value at the specified index. false if the
- * value at the specified index is not a Boolean value.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
- bool
- xpc_array_get_bool(xpc_object_t xarray, size_t index);
- /*!
- * @function xpc_array_get_int64
- *
- * @abstract
- * Gets an <code>int64_t</code> primitive value from an array directly.
- *
- * @param xarray
- * The array which is to be examined.
- *
- * @param 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.
- *
- * @result
- * The underlying <code>int64_t</code> value at the specified index. 0 if the
- * value at the specified index is not a signed integer value.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
- int64_t
- xpc_array_get_int64(xpc_object_t xarray, size_t index);
- /*!
- * @function xpc_array_get_uint64
- *
- * @abstract
- * Gets a <code>uint64_t</code> primitive value from an array directly.
- *
- * @param xarray
- * The array which is to be examined.
- *
- * @param 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.
- *
- * @result
- * The underlying <code>uint64_t</code> value at the specified index. 0 if the
- * value at the specified index is not an unsigned integer value.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
- uint64_t
- xpc_array_get_uint64(xpc_object_t xarray, size_t index);
- /*!
- * @function xpc_array_get_double
- *
- * @abstract
- * Gets a <code>double</code> primitive value from an array directly.
- *
- * @param xarray
- * The array which is to be examined.
- *
- * @param 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.
- *
- * @result
- * The underlying <code>double</code> value at the specified index. NAN if the
- * value at the specified index is not a floating point value.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
- double
- xpc_array_get_double(xpc_object_t xarray, size_t index);
- /*!
- * @function xpc_array_get_date
- *
- * @abstract
- * Gets a date interval from an array directly.
- *
- * @param xarray
- * The array which is to be examined.
- *
- * @param 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.
- *
- * @result
- * The underlying date interval at the specified index. 0 if the value at the
- * specified index is not a date value.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
- int64_t
- xpc_array_get_date(xpc_object_t xarray, size_t index);
- /*!
- * @function xpc_array_get_data
- *
- * @abstract
- * Gets a pointer to the raw bytes of a data object from an array directly.
- *
- * @param xarray
- * The array which is to be examined.
- *
- * @param 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.
- *
- * @param length
- * Upon return output, will contain the length of the data corresponding to the
- * specified key.
- *
- * @result
- * The underlying bytes at the specified index. NULL if the value at the
- * specified index is not a data value.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
- const void *
- xpc_array_get_data(xpc_object_t xarray, size_t index, size_t *length);
- /*!
- * @function xpc_array_get_string
- *
- * @abstract
- * Gets a C string value from an array directly.
- *
- * @param xarray
- * The array which is to be examined.
- *
- * @param 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.
- *
- * @result
- * The underlying C string at the specified index. NULL if the value at the
- * specified index is not a C string value.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
- const char *
- xpc_array_get_string(xpc_object_t xarray, size_t index);
- /*!
- * @function xpc_array_get_uuid
- *
- * @abstract
- * Gets a <code>uuid_t</code> value from an array directly.
- *
- * @param xarray
- * The array which is to be examined.
- *
- * @param 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.
- *
- * @result
- * The underlying <code>uuid_t</code> 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
- const uint8_t *
- xpc_array_get_uuid(xpc_object_t xarray, size_t index);
- /*!
- * @function xpc_array_dup_fd
- *
- * @abstract
- * Gets a file descriptor from an array directly.
- *
- * @param xarray
- * The array which is to be examined.
- *
- * @param 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.
- *
- * @result
- * 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
- int
- xpc_array_dup_fd(xpc_object_t xarray, size_t index);
- /*!
- * @function xpc_array_create_connection
- *
- * @abstract
- * Creates a connection object from an array directly.
- *
- * @param xarray
- * The array which is to be examined.
- *
- * @param 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.
- *
- * @result
- * 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 {@link xpc_connection_create_from_endpoint()} for
- * discussion as to the responsibilities when dealing with the returned
- * connection.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1
- xpc_connection_t
- xpc_array_create_connection(xpc_object_t xarray, size_t index);
- #pragma mark Dictionary
- /*!
- * @typedef xpc_dictionary_applier_t
- * A block to be invoked for every key/value pair in the dictionary.
- *
- * @param key
- * The current key in the iteration.
- *
- * @param value
- * The current value in the iteration.
- *
- * @result
- * A Boolean indicating whether iteration should continue.
- */
- #ifdef __BLOCKS__
- typedef bool (^xpc_dictionary_applier_t)(const char *key, xpc_object_t value);
- #endif // __BLOCKS__
- /*!
- * @function xpc_dictionary_create
- *
- * @abstract
- * Creates an XPC object representing a dictionary of XPC objects keyed to
- * C-strings.
- *
- * @param 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.
- *
- * @param 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.
- *
- * @param 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.
- *
- * @result
- * The new dictionary object.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT
- xpc_object_t
- xpc_dictionary_create(const char * const *keys, const xpc_object_t *values,
- size_t count);
- /*!
- * @function xpc_dictionary_create_reply
- *
- * @abstract
- * Creates a dictionary that is in reply to the given dictionary.
- *
- * @param original
- * The original dictionary that is to be replied to.
- *
- * @result
- * 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL_ALL
- xpc_object_t
- xpc_dictionary_create_reply(xpc_object_t original);
- /*!
- * @function xpc_dictionary_set_value
- *
- * @abstract
- * Sets the value for the specified key to the specified object.
- *
- * @param xdict
- * The dictionary object which is to be manipulated.
- *
- * @param key
- * The key for which the value shall be set.
- *
- * @param 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2
- void
- xpc_dictionary_set_value(xpc_object_t xdict, const char *key,
- xpc_object_t value);
- /*!
- * @function xpc_dictionary_get_value
- *
- * @abstract
- * Returns the value for the specified key.
- *
- * @param xdict
- * The dictionary object which is to be examined.
- *
- * @param key
- * The key whose value is to be obtained.
- *
- * @result
- * 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 XPC_NONNULL2
- xpc_object_t
- xpc_dictionary_get_value(xpc_object_t xdict, const char *key);
- /*!
- * @function xpc_dictionary_get_count
- *
- * @abstract
- * Returns the number of values stored in the dictionary.
- *
- * @param xdict
- * The dictionary object which is to be examined.
- *
- * @result
- * 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
- size_t
- xpc_dictionary_get_count(xpc_object_t xdict);
- /*!
- * @function xpc_dictionary_apply
- *
- * @abstract
- * Invokes the given block for every key/value pair in the dictionary.
- *
- * @param xdict
- * The dictionary object which is to be examined.
- *
- * @param applier
- * The block which this function applies to every key/value pair in the
- * dictionary.
- *
- * @result
- * 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.
- */
- #ifdef __BLOCKS__
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL_ALL
- bool
- xpc_dictionary_apply(xpc_object_t xdict, xpc_dictionary_applier_t applier);
- #endif // __BLOCKS__
- /*!
- * @function xpc_dictionary_get_remote_connection
- *
- * @abstract
- * Returns the connection from which the dictionary was received.
- *
- * @param xdict
- * The dictionary object which is to be examined.
- *
- * @result
- * 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL
- xpc_connection_t
- xpc_dictionary_get_remote_connection(xpc_object_t xdict);
- #pragma mark Dictionary Primitive Setters
- /*!
- * @function xpc_dictionary_set_bool
- *
- * @abstract
- * Inserts a <code>bool</code> (primitive) value into a dictionary.
- *
- * @param xdict
- * The dictionary which is to be manipulated.
- *
- * @param key
- * The key for which the primitive value shall be set.
- *
- * @param value
- * The <code>bool</code> value to insert. After calling this method, the XPC
- * object corresponding to the primitive value inserted may be safely retrieved
- * with {@link xpc_dictionary_get_value()}.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2
- void
- xpc_dictionary_set_bool(xpc_object_t xdict, const char *key, bool value);
- /*!
- * @function xpc_dictionary_set_int64
- *
- * @abstract
- * Inserts an <code>int64_t</code> (primitive) value into a dictionary.
- *
- * @param xdict
- * The dictionary which is to be manipulated.
- *
- * @param key
- * The key for which the primitive value shall be set.
- *
- * @param value
- * The <code>int64_t</code> value to insert. After calling this method, the XPC
- * object corresponding to the primitive value inserted may be safely retrieved
- * with {@link xpc_dictionary_get_value()}.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2
- void
- xpc_dictionary_set_int64(xpc_object_t xdict, const char *key, int64_t value);
- /*!
- * @function xpc_dictionary_set_uint64
- *
- * @abstract
- * Inserts a <code>uint64_t</code> (primitive) value into a dictionary.
- *
- * @param xdict
- * The dictionary which is to be manipulated.
- *
- * @param key
- * The key for which the primitive value shall be set.
- *
- * @param value
- * The <code>uint64_t</code> value to insert. After calling this method, the XPC
- * object corresponding to the primitive value inserted may be safely retrieved
- * with {@link xpc_dictionary_get_value()}.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2
- void
- xpc_dictionary_set_uint64(xpc_object_t xdict, const char *key, uint64_t value);
- /*!
- * @function xpc_dictionary_set_double
- *
- * @abstract
- * Inserts a <code>double</code> (primitive) value into a dictionary.
- *
- * @param xdict
- * The dictionary which is to be manipulated.
- *
- * @param key
- * The key for which the primitive value shall be set.
- *
- * @param value
- * The <code>double</code> value to insert. After calling this method, the XPC
- * object corresponding to the primitive value inserted may be safely retrieved
- * with {@link xpc_dictionary_get_value()}.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2
- void
- xpc_dictionary_set_double(xpc_object_t xdict, const char *key, double value);
- /*!
- * @function xpc_dictionary_set_date
- *
- * @abstract
- * Inserts a date (primitive) value into a dictionary.
- *
- * @param xdict
- * The dictionary which is to be manipulated.
- *
- * @param key
- * The key for which the primitive value shall be set.
- *
- * @param value
- * The date value to insert. After calling this method, the XPC object
- * corresponding to the primitive value inserted may be safely retrieved with
- * {@link xpc_dictionary_get_value()}.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2
- void
- xpc_dictionary_set_date(xpc_object_t xdict, const char *key, int64_t value);
- /*!
- * @function xpc_dictionary_set_data
- *
- * @abstract
- * Inserts a raw data value into a dictionary.
- *
- * @param xdict
- * The dictionary which is to be manipulated.
- *
- * @param key
- * The key for which the primitive value shall be set.
- *
- * @param bytes
- * The bytes to insert. After calling this method, the XPC object corresponding
- * to the primitive value inserted may be safely retrieved with
- * {@link xpc_dictionary_get_value()}.
- *
- * @param length
- * The length of the data.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2
- void
- xpc_dictionary_set_data(xpc_object_t xdict, const char *key, const void *bytes,
- size_t length);
- /*!
- * @function xpc_dictionary_set_string
- *
- * @abstract
- * Inserts a C string value into a dictionary.
- *
- * @param xdict
- * The dictionary which is to be manipulated.
- *
- * @param key
- * The key for which the primitive value shall be set.
- *
- * @param string
- * The C string to insert. After calling this method, the XPC object
- * corresponding to the primitive value inserted may be safely retrieved with
- * {@link xpc_dictionary_get_value()}.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2
- void
- xpc_dictionary_set_string(xpc_object_t xdict, const char *key,
- const char *string);
- /*!
- * @function xpc_dictionary_set_uuid
- *
- * @abstract
- * Inserts a uuid (primitive) value into an array.
- *
- * @param xdict
- * The dictionary which is to be manipulated.
- *
- * @param key
- * The key for which the primitive value shall be set.
- *
- * @param uuid
- * The <code>uuid_t</code> value to insert. After calling this method, the XPC
- * object corresponding to the primitive value inserted may be safely retrieved
- * with {@link xpc_dictionary_get_value()}.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2
- void
- xpc_dictionary_set_uuid(xpc_object_t xdict, const char *key, const uuid_t uuid);
- /*!
- * @function xpc_dictionary_set_fd
- *
- * @abstract
- * Inserts a file descriptor into a dictionary.
- *
- * @param xdict
- * The dictionary which is to be manipulated.
- *
- * @param key
- * The key for which the primitive value shall be set.
- *
- * @param fd
- * The file descriptor to insert. After calling this method, the XPC object
- * corresponding to the primitive value inserted may be safely retrieved
- * with {@link xpc_dictionary_get_value()}.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2
- void
- xpc_dictionary_set_fd(xpc_object_t xdict, const char *key, int fd);
- /*!
- * @function xpc_dictionary_set_connection
- *
- * @abstract
- * Inserts a connection into a dictionary.
- *
- * @param xdict
- * The dictionary which is to be manipulated.
- *
- * @param key
- * The key for which the primitive value shall be set.
- *
- * @param connection
- * The connection to insert. After calling this method, the XPC object
- * corresponding to the primitive value inserted may be safely retrieved
- * with {@link xpc_dictionary_get_value()}. The connection is NOT retained by
- * the dictionary.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2
- void
- xpc_dictionary_set_connection(xpc_object_t xdict, const char *key,
- xpc_connection_t connection);
- #pragma mark Dictionary Primitive Getters
- /*!
- * @function xpc_dictionary_get_bool
- *
- * @abstract
- * Gets a <code>bool</code> primitive value from a dictionary directly.
- *
- * @param xdict
- * The dictionary object which is to be examined.
- *
- * @param key
- * The key whose value is to be obtained.
- *
- * @result
- * The underlying <code>bool</code> 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL
- bool
- xpc_dictionary_get_bool(xpc_object_t xdict, const char *key);
- /*!
- * @function xpc_dictionary_get_int64
- *
- * @abstract
- * Gets an <code>int64</code> primitive value from a dictionary directly.
- *
- * @param xdict
- * The dictionary object which is to be examined.
- *
- * @param key
- * The key whose value is to be obtained.
- *
- * @result
- * The underlying <code>int64_t</code> 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL
- int64_t
- xpc_dictionary_get_int64(xpc_object_t xdict, const char *key);
- /*!
- * @function xpc_dictionary_get_uint64
- *
- * @abstract
- * Gets a <code>uint64</code> primitive value from a dictionary directly.
- *
- * @param xdict
- * The dictionary object which is to be examined.
- *
- * @param key
- * The key whose value is to be obtained.
- *
- * @result
- * The underlying <code>uint64_t</code> 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL
- uint64_t
- xpc_dictionary_get_uint64(xpc_object_t xdict, const char *key);
- /*!
- * @function xpc_dictionary_get_double
- *
- * @abstract
- * Gets a <code>double</code> primitive value from a dictionary directly.
- *
- * @param xdict
- * The dictionary object which is to be examined.
- *
- * @param key
- * The key whose value is to be obtained.
- *
- * @result
- * The underlying <code>double</code> 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL
- double
- xpc_dictionary_get_double(xpc_object_t xdict, const char *key);
- /*!
- * @function xpc_dictionary_get_date
- *
- * @abstract
- * Gets a date value from a dictionary directly.
- *
- * @param xdict
- * The dictionary object which is to be examined.
- *
- * @param key
- * The key whose value is to be obtained.
- *
- * @result
- * 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL
- int64_t
- xpc_dictionary_get_date(xpc_object_t xdict, const char *key);
- /*!
- * @function xpc_dictionary_get_data
- *
- * @abstract
- * Gets a raw data value from a dictionary directly.
- *
- * @param xdict
- * The dictionary object which is to be examined.
- *
- * @param key
- * The key whose value is to be obtained.
- *
- * @param length
- * For the data type, the third parameter, upon output, will contain the length
- * of the data corresponding to the specified key.
- *
- * @result
- * 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL
- const void *
- xpc_dictionary_get_data(xpc_object_t xdict, const char *key, size_t *length);
- /*!
- * @function xpc_dictionary_get_string
- *
- * @abstract
- * Gets a C string value from a dictionary directly.
- *
- * @param xdict
- * The dictionary object which is to be examined.
- *
- * @param key
- * The key whose value is to be obtained.
- *
- * @result
- * 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL
- const char *
- xpc_dictionary_get_string(xpc_object_t xdict, const char *key);
- /*!
- * @function xpc_dictionary_get_uuid
- *
- * @abstract
- * Gets a uuid value from a dictionary directly.
- *
- * @param xdict
- * The dictionary object which is to be examined.
- *
- * @param key
- * The key whose value is to be obtained.
- *
- * @result
- * The underlying <code>uuid_t</code> 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 XPC_NONNULL2
- const uint8_t *
- xpc_dictionary_get_uuid(xpc_object_t xdict, const char *key);
- /*!
- * @function xpc_dictionary_dup_fd
- *
- * @abstract
- * Creates a file descriptor from a dictionary directly.
- *
- * @param xdict
- * The dictionary object which is to be examined.
- *
- * @param key
- * The key whose value is to be obtained.
- *
- * @result
- * 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL
- int
- xpc_dictionary_dup_fd(xpc_object_t xdict, const char *key);
- /*!
- * @function xpc_dictionary_create_connection
- *
- * @abstract
- * Creates a connection from a dictionary directly.
- *
- * @param xdict
- * The dictionary object which is to be examined.
- *
- * @param key
- * The key whose value is to be obtained.
- *
- * @result
- * 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
- * {@link xpc_connection_create_from_endpoint()} for discussion as to the
- * responsibilities when dealing with the returned connection.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL_ALL
- xpc_connection_t
- xpc_dictionary_create_connection(xpc_object_t xdict, const char *key);
- #pragma mark Runtime
- /*!
- * @function xpc_main
- * 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.
- *
- * @param handler
- * The handler with which to accept new connections.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- __XPC_IOS_SIMULATOR_AVAILABLE_STARTING(__MAC_10_7)
- XPC_EXPORT XPC_NORETURN XPC_NONNULL1
- void
- xpc_main(xpc_connection_handler_t handler);
- #pragma mark Transactions
- /*!
- * @function xpc_transaction_begin
- * Informs the XPC runtime that a transaction has begun and that the service
- * should not exit due to inactivity.
- *
- * @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 peer connections will receive
- * {@link 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT
- void
- xpc_transaction_begin(void);
- /*!
- * @function xpc_transaction_end
- * Informs the XPC runtime that a transaction has ended.
- *
- * @discussion
- * As described in {@link xpc_transaction_begin()}, this API may be used
- * interchangeably with vproc_transaction_end().
- *
- * See the discussion for {@link xpc_transaction_begin()} for details regarding
- * the XPC runtime's idle-exit policy.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- XPC_EXPORT
- void
- xpc_transaction_end(void);
- #pragma mark XPC Event Stream
- /*!
- * @function xpc_set_event_stream_handler
- * Sets the event handler to invoke when streamed events are received.
- *
- * @param stream
- * The name of the event stream for which this handler will be invoked.
- *
- * @param 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.
- *
- * @param 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.
- */
- #if __BLOCKS__
- __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
- __XPC_IOS_SIMULATOR_AVAILABLE_STARTING(__MAC_10_8)
- XPC_EXPORT XPC_NONNULL1 XPC_NONNULL3
- void
- xpc_set_event_stream_handler(const char *stream, dispatch_queue_t targetq,
- xpc_handler_t handler);
- #endif // __BLOCKS__
- __END_DECLS
- #endif // __XPC_H__
|