1// Copyright (c) 2009-2020 Apple Inc. All rights reserved. 
   2
   3#ifndef __XPC_H__
   4#define __XPC_H__
   5
   6#include <os/object.h>
   7#include <dispatch/dispatch.h>
   8
   9#include <sys/mman.h>
  10#include <uuid/uuid.h>
  11#include <bsm/audit.h>
  12#include <stdarg.h>
  13#include <stdbool.h>
  14#include <stdint.h>
  15#include <stdlib.h>
  16#include <stdio.h>
  17#include <string.h>
  18#include <unistd.h>
  19#include <fcntl.h>
  20
  21#ifndef __XPC_INDIRECT__
  22#define __XPC_INDIRECT__
  23#endif // __XPC_INDIRECT__
  24
  25#include <xpc/base.h>
  26
  27#if __has_include(<xpc/xpc_transaction_deprecate.h>)
  28#include <xpc/xpc_transaction_deprecate.h>
  29#else // __has_include(<xpc/transaction_deprecate.h>)
  30#define XPC_TRANSACTION_DEPRECATED
  31#endif // __has_include(<xpc/transaction_deprecate.h>)
  32
  33XPC_ASSUME_NONNULL_BEGIN
  34__BEGIN_DECLS
  35
  36#ifndef __OSX_AVAILABLE_STARTING
  37#define __OSX_AVAILABLE_STARTING(x, y)
  38#endif // __OSX_AVAILABLE_STARTING
  39
  40#define XPC_API_VERSION 20200610
  41
  42/*!
  43 * @typedef xpc_type_t
  44 * A type that describes XPC object types.
  45 */
  46typedef const struct _xpc_type_s * xpc_type_t;
  47#ifndef XPC_TYPE
  48#define XPC_TYPE(type) const struct _xpc_type_s type
  49#endif // XPC_TYPE
  50
  51/*!
  52 * @typedef xpc_object_t
  53 * A type that can describe all XPC objects. Dictionaries, arrays, strings, etc.
  54 * are all described by this type.
  55 *
  56 * XPC objects are created with a retain count of 1, and therefore it is the
  57 * caller's responsibility to call xpc_release() on them when they are no longer
  58 * needed.
  59 */
  60
  61#if OS_OBJECT_USE_OBJC
  62/* By default, XPC objects are declared as Objective-C types when building with
  63 * an Objective-C compiler. This allows them to participate in ARC, in RR
  64 * management by the Blocks runtime and in leaks checking by the static
  65 * analyzer, and enables them to be added to Cocoa collections.
  66 *
  67 * See <os/object.h> for details.
  68 */
  69OS_OBJECT_DECL(xpc_object);
  70#ifndef XPC_DECL
  71#define XPC_DECL(name) typedef xpc_object_t name##_t
  72#endif // XPC_DECL
  73
  74#define XPC_GLOBAL_OBJECT(object) ((OS_OBJECT_BRIDGE xpc_object_t)&(object))
  75#define XPC_RETURNS_RETAINED OS_OBJECT_RETURNS_RETAINED
  76XPC_INLINE XPC_NONNULL_ALL
  77void
  78_xpc_object_validate(xpc_object_t object) {
  79	(void)*(unsigned long volatile *)(OS_OBJECT_BRIDGE void *)object;
  80}
  81#else // OS_OBJECT_USE_OBJC
  82typedef void * xpc_object_t;
  83#define XPC_DECL(name) typedef struct _##name##_s * name##_t
  84#define XPC_GLOBAL_OBJECT(object) (&(object))
  85#define XPC_RETURNS_RETAINED
  86#endif // OS_OBJECT_USE_OBJC 
  87
  88/*!
  89 * @typedef xpc_handler_t
  90 * The type of block that is accepted by the XPC connection APIs.
  91 *
  92 * @param object
  93 * An XPC object that is to be handled. If there was an error, this object will
  94 * be equal to one of the well-known XPC_ERROR_* dictionaries and can be
  95 * compared with the equality operator.
  96 *
  97 * @discussion
  98 * You are not responsible for releasing the event object.
  99 */
 100#if __BLOCKS__
 101typedef void (^xpc_handler_t)(xpc_object_t object);
 102#endif // __BLOCKS__ 
 103
 104/*!
 105 * @define XPC_TYPE_CONNECTION
 106 * A type representing a connection to a named service. This connection is
 107 * bidirectional and can be used to both send and receive messages. A
 108 * connection carries the credentials of the remote service provider.
 109 */
 110#define XPC_TYPE_CONNECTION (&_xpc_type_connection)
 111__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 112XPC_EXPORT
 113XPC_TYPE(_xpc_type_connection);
 114XPC_DECL(xpc_connection);
 115
 116/*!
 117 * @typedef xpc_connection_handler_t
 118 * The type of the function that will be invoked for a bundled XPC service when
 119 * there is a new connection on the service.
 120 *
 121 * @param connection
 122 * A new connection that is equivalent to one received by a listener connection.
 123 * See the documentation for {@link xpc_connection_set_event_handler} for the
 124 * semantics associated with the received connection.
 125 */
 126typedef void (*xpc_connection_handler_t)(xpc_connection_t connection);
 127
 128/*!
 129 * @define XPC_TYPE_ENDPOINT
 130 * A type representing a connection in serialized form. Unlike a connection, an
 131 * endpoint is an inert object that does not have any runtime activity
 132 * associated with it. Thus, it is safe to pass an endpoint in a message. Upon
 133 * receiving an endpoint, the recipient can use
 134 * xpc_connection_create_from_endpoint() to create as many distinct connections
 135 * as desired. 
 136 */
 137#define XPC_TYPE_ENDPOINT (&_xpc_type_endpoint)
 138__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 139XPC_EXPORT
 140XPC_TYPE(_xpc_type_endpoint);
 141XPC_DECL(xpc_endpoint);
 142
 143/*!
 144 * @define XPC_TYPE_NULL
 145 * A type representing a null object. This type is useful for disambiguating
 146 * an unset key in a dictionary and one which has been reserved but set empty.
 147 * Also, this type is a way to represent a "null" value in dictionaries, which
 148 * do not accept NULL.
 149 */
 150#define XPC_TYPE_NULL (&_xpc_type_null)
 151__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 152XPC_EXPORT
 153XPC_TYPE(_xpc_type_null);
 154
 155/*!
 156 * @define XPC_TYPE_BOOL
 157 * A type representing a Boolean value.
 158 */
 159#define XPC_TYPE_BOOL (&_xpc_type_bool)
 160__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 161XPC_EXPORT
 162XPC_TYPE(_xpc_type_bool);
 163
 164/*!
 165 * @define XPC_BOOL_TRUE
 166 * A constant representing a Boolean value of true. You may compare a Boolean
 167 * object against this constant to determine its value.
 168 */
 169#define XPC_BOOL_TRUE XPC_GLOBAL_OBJECT(_xpc_bool_true)
 170__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 171XPC_EXPORT
 172const struct _xpc_bool_s _xpc_bool_true;
 173
 174/*!
 175 * @define XPC_BOOL_FALSE
 176 * A constant representing a Boolean value of false. You may compare a Boolean
 177 * object against this constant to determine its value.
 178 */
 179#define XPC_BOOL_FALSE XPC_GLOBAL_OBJECT(_xpc_bool_false)
 180__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 181XPC_EXPORT
 182const struct _xpc_bool_s _xpc_bool_false;
 183
 184/*!
 185 * @define XPC_TYPE_INT64
 186 * A type representing a signed, 64-bit integer value.
 187 */
 188#define XPC_TYPE_INT64 (&_xpc_type_int64)
 189__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 190XPC_EXPORT
 191XPC_TYPE(_xpc_type_int64);
 192
 193/*!
 194 * @define XPC_TYPE_UINT64
 195 * A type representing an unsigned, 64-bit integer value.
 196 */
 197#define XPC_TYPE_UINT64 (&_xpc_type_uint64)
 198__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 199XPC_EXPORT
 200XPC_TYPE(_xpc_type_uint64);
 201
 202/*!
 203 * @define XPC_TYPE_DOUBLE
 204 * A type representing an IEEE-compliant, double-precision floating point value.
 205 */
 206#define XPC_TYPE_DOUBLE (&_xpc_type_double)
 207__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 208XPC_EXPORT
 209XPC_TYPE(_xpc_type_double);
 210
 211/*!
 212 * @define XPC_TYPE_DATE
 213 * A type representing a date interval. The interval is with respect to the
 214 * Unix epoch. XPC dates are in Unix time and are thus unaware of local time
 215 * or leap seconds.
 216 */
 217#define XPC_TYPE_DATE (&_xpc_type_date)
 218__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 219XPC_EXPORT
 220XPC_TYPE(_xpc_type_date);
 221
 222/*!
 223 * @define XPC_TYPE_DATA
 224 * A type representing an arbitrary buffer of bytes.
 225 */
 226#define XPC_TYPE_DATA (&_xpc_type_data)
 227__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 228XPC_EXPORT
 229XPC_TYPE(_xpc_type_data);
 230
 231/*!
 232 * @define XPC_TYPE_STRING
 233 * A type representing a NUL-terminated C-string.
 234 */
 235#define XPC_TYPE_STRING (&_xpc_type_string)
 236__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 237XPC_EXPORT
 238XPC_TYPE(_xpc_type_string);
 239
 240/*!
 241 * @define XPC_TYPE_UUID
 242 * A type representing a Universally Unique Identifier as defined by uuid(3).
 243 */
 244#define XPC_TYPE_UUID (&_xpc_type_uuid)
 245__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 246XPC_EXPORT
 247XPC_TYPE(_xpc_type_uuid);
 248
 249/*!
 250 * @define XPC_TYPE_FD
 251 * A type representing a POSIX file descriptor.
 252 */
 253#define XPC_TYPE_FD (&_xpc_type_fd)
 254__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 255XPC_EXPORT
 256XPC_TYPE(_xpc_type_fd);
 257
 258/*!
 259 * @define XPC_TYPE_SHMEM
 260 * A type representing a region of shared memory.
 261 */
 262#define XPC_TYPE_SHMEM (&_xpc_type_shmem)
 263__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 264XPC_EXPORT
 265XPC_TYPE(_xpc_type_shmem);
 266
 267/*!
 268 * @define XPC_TYPE_ARRAY
 269 * A type representing an array of XPC objects. This array must be contiguous,
 270 * i.e. it cannot contain NULL values. If you wish to indicate that a slot
 271 * is empty, you can insert a null object. The array will grow as needed to
 272 * accommodate more objects.
 273 */
 274#define XPC_TYPE_ARRAY (&_xpc_type_array)
 275__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 276XPC_EXPORT
 277XPC_TYPE(_xpc_type_array);
 278
 279/*!
 280 * @define XPC_TYPE_DICTIONARY
 281 * A type representing a dictionary of XPC objects, keyed off of C-strings.
 282 * You may insert NULL values into this collection. The dictionary will grow
 283 * as needed to accommodate more key/value pairs.
 284 */
 285#define XPC_TYPE_DICTIONARY (&_xpc_type_dictionary)
 286__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 287XPC_EXPORT
 288XPC_TYPE(_xpc_type_dictionary);
 289
 290/*!
 291 * @define XPC_TYPE_ERROR
 292 * A type representing an error object. Errors in XPC are dictionaries, but
 293 * xpc_get_type() will return this type when given an error object. You
 294 * cannot create an error object directly; XPC will only give them to handlers.
 295 * These error objects have pointer values that are constant across the lifetime
 296 * of your process and can be safely compared.
 297 *
 298 * These constants are enumerated in the header for the connection object. Error
 299 * dictionaries may reserve keys so that they can be queried to obtain more
 300 * detailed information about the error. Currently, the only reserved key is
 301 * XPC_ERROR_KEY_DESCRIPTION.
 302 */
 303#define XPC_TYPE_ERROR (&_xpc_type_error)
 304__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 305XPC_EXPORT
 306XPC_TYPE(_xpc_type_error);
 307
 308/*!
 309 * @define XPC_ERROR_KEY_DESCRIPTION
 310 * In an error dictionary, querying for this key will return a string object
 311 * that describes the error in a human-readable way.
 312 */
 313#define XPC_ERROR_KEY_DESCRIPTION _xpc_error_key_description
 314__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 315XPC_EXPORT
 316const char * const _xpc_error_key_description;
 317
 318/*!
 319 * @define XPC_EVENT_KEY_NAME
 320 * In an event dictionary, this querying for this key will return a string
 321 * object that describes the event.
 322 */
 323#define XPC_EVENT_KEY_NAME _xpc_event_key_name
 324__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 325XPC_EXPORT
 326const char * const _xpc_event_key_name;
 327
 328/*!
 329 * @define XPC_TYPE_RICH_ERROR
 330 *
 331 * @discussion
 332 * Rich errors provide a simple dynamic error type that can indicate whether an
 333 * error is retry-able or not.
 334 */
 335#define XPC_TYPE_RICH_ERROR (&_xpc_type_rich_error)
 336XPC_EXPORT
 337XPC_TYPE(_xpc_type_rich_error);
 338XPC_DECL(xpc_rich_error);
 339
 340__END_DECLS
 341XPC_ASSUME_NONNULL_END
 342#if !defined(__XPC_BUILDING_XPC__) || !__XPC_BUILDING_XPC__
 343#include <xpc/endpoint.h>
 344#include <xpc/debug.h>
 345#if __BLOCKS__
 346#include <xpc/activity.h>
 347#include <xpc/peer_requirement.h>
 348#include <xpc/connection.h>
 349#include <xpc/rich_error.h>
 350#include <xpc/session.h>
 351#include <xpc/listener.h>
 352#endif // __BLOCKS__
 353#undef __XPC_INDIRECT__
 354#if __has_include(<launch.h>)
 355#include <launch.h>
 356#endif // __has_include(<launch.h>)
 357#endif // !defined(__XPC_BUILDING_XPC__) || !__XPC_BUILDING_XPC__
 358XPC_ASSUME_NONNULL_BEGIN
 359__BEGIN_DECLS
 360
 361#pragma mark XPC Object Protocol
 362/*!
 363 * @function xpc_retain
 364 *
 365 * @abstract
 366 * Increments the reference count of an object.
 367 *
 368 * @param object
 369 * The object which is to be manipulated.
 370 *
 371 * @result
 372 * The object which was given.
 373 *
 374 * @discussion
 375 * Calls to xpc_retain() must be balanced with calls to xpc_release()
 376 * to avoid leaking memory.
 377 */
 378__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 379XPC_EXPORT XPC_NONNULL1
 380xpc_object_t
 381xpc_retain(xpc_object_t object);
 382#if OS_OBJECT_USE_OBJC_RETAIN_RELEASE
 383#undef xpc_retain
 384#define xpc_retain(object) ({ xpc_object_t _o = (object); \
 385		_xpc_object_validate(_o); [_o retain]; })
 386#endif // OS_OBJECT_USE_OBJC_RETAIN_RELEASE
 387
 388/*!
 389 * @function xpc_release
 390 *
 391 * @abstract
 392 * Decrements the reference count of an object.
 393 *
 394 * @param object
 395 * The object which is to be manipulated.
 396 *
 397 * @discussion
 398 * The caller must take care to balance retains and releases. When creating or
 399 * retaining XPC objects, the creator obtains a reference on the object. Thus,
 400 * it is the caller's responsibility to call xpc_release() on those objects when
 401 * they are no longer needed.
 402 */
 403__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 404XPC_EXPORT XPC_NONNULL1
 405void
 406xpc_release(xpc_object_t object);
 407#if OS_OBJECT_USE_OBJC_RETAIN_RELEASE
 408#undef xpc_release
 409#define xpc_release(object) ({ xpc_object_t _o = (object); \
 410		_xpc_object_validate(_o); [_o release]; })
 411#endif // OS_OBJECT_USE_OBJC_RETAIN_RELEASE
 412
 413/*!
 414 * @function xpc_get_type
 415 *
 416 * @abstract
 417 * Returns the type of an object.
 418 *
 419 * @param object
 420 * The object to examine.
 421 *
 422 * @result
 423 * An opaque pointer describing the type of the object. This pointer is suitable
 424 * direct comparison to exported type constants with the equality operator.
 425 */
 426__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 427XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT
 428xpc_type_t
 429xpc_get_type(xpc_object_t object);
 430
 431/*!
 432 * @function xpc_type_get_name
 433 *
 434 * @abstract
 435 * Returns a string describing an XPC object type.
 436 *
 437 * @param type
 438 * The type to describe.
 439 *
 440 * @result
 441 * A string describing the type of an object, like "string" or "int64".
 442 * This string should not be freed or modified.
 443 */
 444__OSX_AVAILABLE_STARTING(__MAC_10_15, __IPHONE_13_0)
 445XPC_EXPORT XPC_NONNULL1
 446const char *
 447xpc_type_get_name(xpc_type_t type);
 448
 449/*!
 450 * @function xpc_copy
 451 *
 452 * @abstract
 453 * Creates a copy of the object.
 454 *
 455 * @param object
 456 * The object to copy.
 457 *
 458 * @result
 459 * The new object. NULL if the object type does not support copying or if
 460 * sufficient memory for the copy could not be allocated. Service objects do
 461 * not support copying.
 462 *
 463 * @discussion
 464 * When called on an array or dictionary, xpc_copy() will perform a deep copy.
 465 *
 466 * The object returned is not necessarily guaranteed to be a new object, and
 467 * whether it is will depend on the implementation of the object being copied.
 468 */
 469__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 470XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT XPC_RETURNS_RETAINED
 471xpc_object_t _Nullable
 472xpc_copy(xpc_object_t object);
 473
 474/*!
 475 * @function xpc_equal
 476 *
 477 * @abstract
 478 * Compares two objects for equality.
 479 *
 480 * @param object1
 481 * The first object to compare.
 482 *
 483 * @param object2
 484 * The second object to compare.
 485 *
 486 * @result
 487 * Returns true if the objects are equal, otherwise false. Two objects must be
 488 * of the same type in order to be equal.
 489 *
 490 * For two arrays to be equal, they must contain the same values at the
 491 * same indexes. For two dictionaries to be equal, they must contain the same
 492 * values for the same keys.
 493 *
 494 * Two objects being equal implies that their hashes (as returned by xpc_hash())
 495 * are also equal.
 496 */
 497__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 498XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 XPC_WARN_RESULT
 499bool
 500xpc_equal(xpc_object_t object1, xpc_object_t object2);
 501
 502/*!
 503 * @function xpc_hash
 504 *
 505 * @abstract
 506 * Calculates a hash value for the given object.
 507 *
 508 * @param object
 509 * The object for which to calculate a hash value. This value may be modded
 510 * with a table size for insertion into a dictionary-like data structure.
 511 *
 512 * @result
 513 * The calculated hash value.
 514 *
 515 * @discussion
 516 * Note that the computed hash values for any particular type and value of an
 517 * object can change across releases and platforms and should not be
 518 * assumed to be constant across all time and space or stored persistently.
 519 */
 520__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 521XPC_EXPORT XPC_NONNULL1 XPC_WARN_RESULT
 522size_t
 523xpc_hash(xpc_object_t object);
 524
 525/*!
 526 * @function xpc_copy_description
 527 *
 528 * @abstract
 529 * Copies a debug string describing the object.
 530 *
 531 * @param object
 532 * The object which is to be examined.
 533 *
 534 * @result
 535 * A string describing object which contains information useful for debugging.
 536 * This string should be disposed of with free(3) when done.
 537 */
 538__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 539XPC_EXPORT XPC_MALLOC XPC_WARN_RESULT XPC_NONNULL1
 540char *
 541xpc_copy_description(xpc_object_t object);
 542
 543#pragma mark XPC Object Types
 544#pragma mark Null
 545/*!
 546 * @function xpc_null_create
 547 *
 548 * @abstract
 549 * Creates an XPC object representing the null object.
 550 *
 551 * @result
 552 * A new null object.
 553 */
 554__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 555XPC_EXPORT XPC_RETURNS_RETAINED XPC_WARN_RESULT
 556xpc_object_t
 557xpc_null_create(void);
 558
 559#pragma mark Boolean
 560/*!
 561 * @function xpc_bool_create
 562 *
 563 * @abstract
 564 * Creates an XPC Boolean object.
 565 *
 566 * @param value
 567 * The Boolean primitive value which is to be boxed.
 568 *
 569 * @result
 570 * A new Boolean object.
 571 */
 572__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 573XPC_EXPORT XPC_RETURNS_RETAINED XPC_WARN_RESULT
 574xpc_object_t
 575xpc_bool_create(bool value);
 576
 577/*!
 578 * @function xpc_bool_get_value
 579 *
 580 * @abstract
 581 * Returns the underlying Boolean value from the object.
 582 *
 583 * @param xbool
 584 * The Boolean object which is to be examined.
 585 *
 586 * @result
 587 * The underlying Boolean value or false if the given object was not an XPC
 588 * Boolean object.
 589 */
 590__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 591XPC_EXPORT
 592bool
 593xpc_bool_get_value(xpc_object_t xbool);
 594
 595#pragma mark Signed Integer
 596/*!
 597 * @function xpc_int64_create
 598 *
 599 * @abstract
 600 * Creates an XPC signed integer object.
 601 *
 602 * @param value
 603 * The signed integer value which is to be boxed.
 604 *
 605 * @result
 606 * A new signed integer object.
 607 */
 608__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 609XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT
 610xpc_object_t
 611xpc_int64_create(int64_t value);
 612
 613/*!
 614 * @function xpc_int64_get_value
 615 *
 616 * @abstract
 617 * Returns the underlying signed 64-bit integer value from an object.
 618 *
 619 * @param xint
 620 * The signed integer object which is to be examined.
 621 *
 622 * @result
 623 * The underlying signed 64-bit value or 0 if the given object was not an XPC
 624 * integer object.
 625 */
 626__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 627XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
 628int64_t
 629xpc_int64_get_value(xpc_object_t xint);
 630
 631#pragma mark Unsigned Integer
 632/*!
 633 * @function xpc_uint64_create
 634 *
 635 * @abstract
 636 * Creates an XPC unsigned integer object.
 637 *
 638 * @param value
 639 * The unsigned integer value which is to be boxed.
 640 *
 641 * @result
 642 * A new unsigned integer object.
 643 */
 644__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 645XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT
 646xpc_object_t
 647xpc_uint64_create(uint64_t value);
 648
 649/*!
 650 * @function xpc_uint64_get_value
 651 *
 652 * @abstract
 653 * Returns the underlying unsigned 64-bit integer value from an object.
 654 *
 655 * @param xuint
 656 * The unsigned integer object which is to be examined.
 657 *
 658 * @result
 659 * The underlying unsigned integer value or 0 if the given object was not an XPC
 660 * unsigned integer object.
 661 */
 662__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 663XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
 664uint64_t
 665xpc_uint64_get_value(xpc_object_t xuint);
 666
 667#pragma mark Double
 668/*!
 669 * @function xpc_double_create
 670 *
 671 * @abstract
 672 * Creates an XPC double object.
 673 *
 674 * @param value
 675 * The floating point quantity which is to be boxed.
 676 *
 677 * @result
 678 * A new floating point object.
 679 */
 680__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 681XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT
 682xpc_object_t
 683xpc_double_create(double value);
 684
 685/*!
 686 * @function xpc_double_get_value
 687 *
 688 * @abstract
 689 * Returns the underlying double-precision floating point value from an object.
 690 *
 691 * @param xdouble
 692 * The floating point object which is to be examined.
 693 *
 694 * @result
 695 * The underlying floating point value or NAN if the given object was not an XPC
 696 * floating point object.
 697 */
 698__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 699XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
 700double
 701xpc_double_get_value(xpc_object_t xdouble);
 702
 703#pragma mark Date
 704/*!
 705 * @function xpc_date_create
 706 *
 707 * @abstract
 708 * Creates an XPC date object.
 709 *
 710 * @param interval
 711 * The date interval which is to be boxed. Negative values indicate the number
 712 * of nanoseconds before the epoch. Positive values indicate the number of
 713 * nanoseconds after the epoch. The interval is with respect to the Unix epoch.
 714 * XPC dates are in Unix time and are thus unaware of local time or leap seconds.
 715 *
 716 * @result
 717 * A new date object.
 718 */
 719__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 720XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT
 721xpc_object_t
 722xpc_date_create(int64_t interval);
 723
 724/*!
 725 * @function xpc_date_create_from_current
 726 *
 727 * @abstract
 728 * Creates an XPC date object representing the current date.
 729 *
 730 * @result
 731 * A new date object representing the current date.
 732 */
 733__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 734XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT
 735xpc_object_t
 736xpc_date_create_from_current(void);
 737
 738/*!
 739 * @function xpc_date_get_value
 740 *
 741 * @abstract
 742 * Returns the underlying date interval from an object.
 743 *
 744 * @param xdate
 745 * The date object which is to be examined.
 746 *
 747 * @result
 748 * The underlying date interval or 0 if the given object was not an XPC date
 749 * object. The interval is with respect to the Unix epoch. XPC dates are in
 750 * Unix time and are thus unaware of local time or leap seconds.
 751 */
 752__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 753XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
 754int64_t
 755xpc_date_get_value(xpc_object_t xdate);
 756
 757#pragma mark Data
 758/*!
 759 * @function xpc_data_create
 760 *
 761 * @abstract
 762 * Creates an XPC object representing buffer of bytes.
 763 *
 764 * @param bytes
 765 * The buffer of bytes which is to be boxed. You may create an empty data object
 766 * by passing NULL for this parameter and 0 for the length. Passing NULL with
 767 * any other length will result in undefined behavior.
 768 *
 769 * @param length
 770 * The number of bytes which are to be boxed.
 771 *
 772 * @result
 773 * A new data object.
 774 *
 775 * @discussion
 776 * This method will copy the buffer given into internal storage. After calling
 777 * this method, it is safe to dispose of the given buffer.
 778 */
 779__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 780XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT
 781xpc_object_t
 782xpc_data_create(const void * _Nullable XPC_SIZEDBY(length) bytes, size_t length);
 783
 784/*!
 785 * @function xpc_data_create_with_dispatch_data
 786 *
 787 * @abstract
 788 * Creates an XPC object representing buffer of bytes described by the given GCD
 789 * data object.
 790 *
 791 * @param ddata
 792 * The GCD data object containing the bytes which are to be boxed. This object
 793 * is retained by the data object.
 794 *
 795 * @result
 796 * A new data object.
 797 *
 798 * @discussion
 799 * The object returned by this method will refer to the buffer returned by
 800 * dispatch_data_create_map(). The point where XPC will make the call to
 801 * dispatch_data_create_map() is undefined.
 802 */
 803__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 804XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1
 805xpc_object_t
 806xpc_data_create_with_dispatch_data(dispatch_data_t ddata);
 807
 808/*!
 809 * @function xpc_data_get_length
 810 *
 811 * @abstract
 812 * Returns the length of the data encapsulated by an XPC data object.
 813 *
 814 * @param xdata
 815 * The data object which is to be examined.
 816 *
 817 * @result
 818 * The length of the underlying boxed data or 0 if the given object was not an
 819 * XPC data object.
 820 */
 821__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 822XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
 823size_t
 824xpc_data_get_length(xpc_object_t xdata);
 825
 826/*!
 827 * @function xpc_data_get_bytes_ptr
 828 *
 829 * @abstract
 830 * Returns a pointer to the internal storage of a data object.
 831 *
 832 * @param xdata
 833 * The data object which is to be examined.
 834 *
 835 * @result
 836 * A pointer to the underlying boxed data or NULL if the given object was not an
 837 * XPC data object.
 838 */
 839__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 840XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
 841const void * _Nullable
 842xpc_data_get_bytes_ptr(xpc_object_t xdata);
 843
 844/*!
 845 * @function xpc_data_get_bytes
 846 *
 847 * @abstract
 848 * Copies the bytes stored in a data object into the specified buffer.
 849 *
 850 * @param xdata
 851 * The data object which is to be examined.
 852 *
 853 * @param buffer
 854 * The buffer in which to copy the data object's bytes.
 855 *
 856 * @param off
 857 * The offset at which to begin the copy. If this offset is greater than the
 858 * length of the data element, nothing is copied. Pass 0 to start the copy
 859 * at the beginning of the buffer.
 860 *
 861 * @param length
 862 * The length of the destination buffer.
 863 *
 864 * @result
 865 * The number of bytes that were copied into the buffer or 0 if the given object
 866 * was not an XPC data object.
 867 */
 868__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 869XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 XPC_NONNULL2
 870size_t
 871xpc_data_get_bytes(xpc_object_t xdata, 
 872	void *buffer, size_t off, size_t length);
 873
 874#pragma mark String
 875/*!
 876 * @function xpc_string_create
 877 *
 878 * @abstract
 879 * Creates an XPC object representing a NUL-terminated C-string.
 880 *
 881 * @param string
 882 * The C-string which is to be boxed.
 883 *
 884 * @result
 885 * A new string object.
 886 */
 887__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 888XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1
 889xpc_object_t
 890xpc_string_create(const char *string);
 891
 892/*!
 893 * @function xpc_string_create_with_format
 894 *
 895 * @abstract
 896 * Creates an XPC object representing a C-string that is generated from the
 897 * given format string and arguments.
 898 *
 899 * @param fmt
 900 * The printf(3)-style format string from which to construct the final C-string
 901 * to be boxed.
 902 *
 903 * @param ...
 904 * The arguments which correspond to those specified in the format string.
 905 *
 906 * @result
 907 * A new string object.
 908 */
 909__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 910XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1
 911XPC_PRINTF(1, 2)
 912xpc_object_t
 913xpc_string_create_with_format(const char *fmt, ...);
 914
 915/*!
 916 * @function xpc_string_create_with_format_and_arguments
 917 *
 918 * @abstract
 919 * Creates an XPC object representing a C-string that is generated from the
 920 * given format string and argument list pointer.
 921 *
 922 * @param fmt
 923 * The printf(3)-style format string from which to construct the final C-string
 924 * to be boxed.
 925 *
 926 * @param ap
 927 * A pointer to the arguments which correspond to those specified in the format
 928 * string.
 929 *
 930 * @result
 931 * A new string object.
 932 */
 933__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 934XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1
 935XPC_PRINTF(1, 0)
 936xpc_object_t
 937xpc_string_create_with_format_and_arguments(const char *fmt, va_list ap);
 938
 939/*!
 940 * @function xpc_string_get_length
 941 *
 942 * @abstract
 943 * Returns the length of the underlying string.
 944 *
 945 * @param xstring
 946 * The string object which is to be examined.
 947 *
 948 * @result
 949 * The length of the underlying string, not including the NUL-terminator, or 0
 950 * if the given object was not an XPC string object.
 951 */
 952__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 953XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL
 954size_t
 955xpc_string_get_length(xpc_object_t xstring);
 956
 957/*!
 958 * @function xpc_string_get_string_ptr
 959 *
 960 * @abstract
 961 * Returns a pointer to the internal storage of a string object.
 962 *
 963 * @param xstring
 964 * The string object which is to be examined.
 965 *
 966 * @result
 967 * A pointer to the string object's internal storage or NULL if the given object
 968 * was not an XPC string object.
 969 */
 970__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 971XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
 972const char * _Nullable
 973xpc_string_get_string_ptr(xpc_object_t xstring);
 974
 975#pragma mark UUID
 976/*!
 977 * @function xpc_uuid_create
 978 *
 979 * @abstract
 980 * Creates an XPC object representing a universally-unique identifier (UUID) as
 981 * described by uuid(3).
 982 *
 983 * @param uuid
 984 * The UUID which is to be boxed.
 985 *
 986 * @result
 987 * A new UUID object.
 988 */
 989__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
 990XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1
 991xpc_object_t
 992xpc_uuid_create(const uuid_t XPC_NONNULL_ARRAY uuid);
 993
 994/*!
 995 * @function xpc_uuid_get_bytes
 996 *
 997 * @abstract
 998 * Returns a pointer to the the boxed UUID bytes in an XPC UUID object.
 999 *
1000 * @param xuuid
1001 * The UUID object which is to be examined.
1002 * 
1003 * @result
1004 * The underlying <code>uuid_t</code> bytes or NULL if the given object was not
1005 * an XPC UUID object. The returned pointer may be safely passed to the uuid(3)
1006 * APIs.
1007 */
1008__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1009XPC_EXPORT XPC_NONNULL1
1010const uint8_t * _Nullable
1011xpc_uuid_get_bytes(xpc_object_t xuuid);
1012
1013#pragma mark File Descriptors
1014/*!
1015 * @function xpc_fd_create
1016 *
1017 * @abstract
1018 * Creates an XPC object representing a POSIX file descriptor.
1019 *
1020 * @param fd
1021 * The file descriptor which is to be boxed.
1022 *
1023 * @result
1024 * A new file descriptor object. NULL if sufficient memory could not be
1025 * allocated or if the given file descriptor was not valid.
1026 *
1027 * @discussion
1028 * This method performs the equivalent of a dup(2) on the descriptor, and thus
1029 * it is safe to call close(2) on the descriptor after boxing it with a file
1030 * descriptor object.
1031 *
1032 * IMPORTANT: Pointer equality is the ONLY valid test for equality between two
1033 * file descriptor objects. There is no reliable way to determine whether two
1034 * file descriptors refer to the same inode with the same capabilities, so two
1035 * file descriptor objects created from the same underlying file descriptor
1036 * number will not compare equally with xpc_equal(). This is also true of a
1037 * file descriptor object created using xpc_copy() and the original.
1038 *
1039 * This also implies that two collections containing file descriptor objects
1040 * cannot be equal unless the exact same object was inserted into both.
1041 */
1042__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1043XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT
1044xpc_object_t _Nullable
1045xpc_fd_create(int fd);
1046
1047/*!
1048 * @function xpc_fd_dup
1049 *
1050 * @abstract
1051 * Returns a file descriptor that is equivalent to the one boxed by the file
1052 * file descriptor object.
1053 *
1054 * @param xfd
1055 * The file descriptor object which is to be examined.
1056 *
1057 * @result
1058 * A file descriptor that is equivalent to the one originally given to
1059 * xpc_fd_create(). If the descriptor could not be created or if the given 
1060 * object was not an XPC file descriptor, -1 is returned.
1061 *
1062 * @discussion
1063 * Multiple invocations of xpc_fd_dup() will not return the same file descriptor
1064 * number, but they will return descriptors that are equivalent, as though they
1065 * had been created by dup(2).
1066 *
1067 * The caller is responsible for calling close(2) on the returned descriptor.
1068 */
1069__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1070XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
1071int
1072xpc_fd_dup(xpc_object_t xfd);
1073
1074#pragma mark Shared Memory
1075/*!
1076 * @function xpc_shmem_create
1077 *
1078 * @abstract
1079 * Creates an XPC object representing the given shared memory region.
1080 *
1081 * @param region
1082 * A pointer to a region of shared memory, created through a call to mmap(2)
1083 * with the MAP_SHARED flag, which is to be boxed.
1084 *
1085 * @param length
1086 * The length of the region.
1087 *
1088 * @result
1089 * A new shared memory object.
1090 *
1091 * @discussion
1092 * Only memory regions whose exact characteristics are known to the caller
1093 * should be boxed using this API. Memory returned from malloc(3) may not be
1094 * safely shared on either OS X or iOS because the underlying virtual memory
1095 * objects for malloc(3)ed allocations are owned by the malloc(3) subsystem and
1096 * not the caller of malloc(3).
1097 *
1098 * If you wish to share a memory region that you receive from another subsystem,
1099 * part of the interface contract with that other subsystem must include how to
1100 * create the region of memory, or sharing it may be unsafe.
1101 *
1102 * Certain operations may internally fragment a region of memory in a way that
1103 * would truncate the range detected by the shared memory object. vm_copy(), for
1104 * example, may split the region into multiple parts to avoid copying certain
1105 * page ranges. For this reason, it is recommended that you delay all VM
1106 * operations until the shared memory object has been created so that the VM
1107 * system knows that the entire range is intended for sharing.
1108 */
1109__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1110XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1
1111xpc_object_t
1112xpc_shmem_create(void *region, size_t length);
1113
1114/*!
1115 * @function xpc_shmem_map
1116 *
1117 * @abstract
1118 * Maps the region boxed by the XPC shared memory object into the caller's
1119 * address space.
1120 *
1121 * @param xshmem
1122 * The shared memory object to be examined.
1123 *
1124 * @param region
1125 * On return, this will point to the region at which the shared memory was
1126 * mapped.
1127 *
1128 * @result
1129 * The length of the region that was mapped. If the mapping failed or if the
1130 * given object was not an XPC shared memory object, 0 is returned. The length 
1131 * of the mapped region will always be an integral page size, even if the
1132 * creator of the region specified a non-integral page size.
1133 *
1134 * @discussion
1135 * The resulting region must be disposed of with munmap(2).
1136 *
1137 * It is the responsibility of the caller to manage protections on the new
1138 * region accordingly. 
1139 */
1140__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1141XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL
1142size_t
1143xpc_shmem_map(xpc_object_t xshmem, void * _Nullable * _Nonnull region);
1144
1145#pragma mark Array
1146/*!
1147 * @typedef xpc_array_applier_t
1148 * A block to be invoked for every value in the array.
1149 *
1150 * @param index
1151 * The current index in the iteration.
1152 *
1153 * @param value
1154 * The current value in the iteration.
1155 *
1156 * @result
1157 * A Boolean indicating whether iteration should continue.
1158 */
1159#ifdef __BLOCKS__
1160typedef bool (^xpc_array_applier_t)(size_t index, xpc_object_t _Nonnull value);
1161#endif // __BLOCKS__ 
1162
1163/*!
1164 * @function xpc_array_create
1165 *
1166 * @abstract
1167 * Creates an XPC object representing an array of XPC objects.
1168 *
1169 * @discussion
1170 * This array must be contiguous and cannot contain any NULL values. If you
1171 * wish to insert the equivalent of a NULL value, you may use the result of
1172 * {@link xpc_null_create}.
1173 *
1174 * @param objects
1175 * An array of XPC objects which is to be boxed. The order of this array is
1176 * preserved in the object. If this array contains a NULL value, the behavior
1177 * is undefined. This parameter may be NULL only if the count is 0.
1178 *
1179 * @param count
1180 * The number of objects in the given array. If the number passed is less than
1181 * the actual number of values in the array, only the specified number of items
1182 * are inserted into the resulting array. If the number passed is more than
1183 * the the actual number of values, the behavior is undefined.
1184 *
1185 * @result
1186 * A new array object. 
1187 */
1188__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1189XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT
1190xpc_object_t
1191xpc_array_create(
1192	const xpc_object_t _Nonnull *XPC_COUNTEDBY(count) _Nullable objects,
1193	size_t count);
1194
1195/*!
1196 * @function xpc_array_create_empty
1197 *
1198 * @abstract
1199 * Creates an XPC object representing an array of XPC objects.
1200 *
1201 * @result
1202 * A new array object.
1203 *
1204 * @see
1205 * xpc_array_create
1206 */
1207API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), watchos(7.0))
1208XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT
1209xpc_object_t
1210xpc_array_create_empty(void);
1211
1212/*!
1213 * @function xpc_array_set_value
1214 *
1215 * @abstract
1216 * Inserts the specified object into the array at the specified index.
1217 *
1218 * @param xarray
1219 * The array object which is to be manipulated.
1220 *
1221 * @param index
1222 * The index at which to insert the value. This value must lie within the index
1223 * space of the array (0 to N-1 inclusive, where N is the count of the array).
1224 * If the index is outside that range, the behavior is undefined.
1225 * 
1226 * @param value
1227 * The object to insert. This value is retained by the array and cannot be
1228 * NULL. If there is already a value at the specified index, it is released,
1229 * and the new value is inserted in its place.
1230 */
1231__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1232XPC_EXPORT XPC_NONNULL1 XPC_NONNULL3
1233void
1234xpc_array_set_value(xpc_object_t xarray, size_t index, xpc_object_t value);
1235
1236/*!
1237 * @function xpc_array_append_value
1238 *
1239 * @abstract
1240 * Appends an object to an XPC array.
1241 *
1242 * @param xarray
1243 * The array object which is to be manipulated.
1244 *
1245 * @param value
1246 * The object to append. This object is retained by the array.
1247 */
1248__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1249XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2
1250void
1251xpc_array_append_value(xpc_object_t xarray, xpc_object_t value);
1252
1253/*!
1254 * @function xpc_array_get_count
1255 *
1256 * @abstract
1257 * Returns the count of values currently in the array.
1258 *
1259 * @param xarray
1260 * The array object which is to be examined.
1261 *
1262 * @result
1263 * The count of values in the array or 0 if the given object was not an XPC 
1264 * array.
1265 */
1266__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1267XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
1268size_t
1269xpc_array_get_count(xpc_object_t xarray);
1270
1271/*!
1272 * @function xpc_array_get_value
1273 *
1274 * @abstract
1275 * Returns the value at the specified index in the array.
1276 *
1277 * @param xarray
1278 * The array object which is to be examined.
1279 *
1280 * @param index
1281 * The index of the value to obtain. This value must lie within the range of
1282 * indexes as specified in xpc_array_set_value().
1283 * 
1284 * @result
1285 * The object at the specified index within the array or NULL if the given
1286 * object was not an XPC array.
1287 *
1288 * @discussion
1289 * This method does not grant the caller a reference to the underlying object,
1290 * and thus the caller is not responsible for releasing the object.
1291 */
1292__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1293XPC_EXPORT XPC_NONNULL_ALL
1294xpc_object_t
1295xpc_array_get_value(xpc_object_t xarray, size_t index);
1296
1297/*!
1298 * @function xpc_array_apply
1299 *
1300 * @abstract
1301 * Invokes the given block for every value in the array.
1302 *
1303 * @param xarray
1304 * The array object which is to be examined.
1305 *
1306 * @param applier
1307 * The block which this function applies to every element in the array.
1308 * 
1309 * @result
1310 * A Boolean indicating whether iteration of the array completed successfully.
1311 * Iteration will only fail if the applier block returns false.
1312 *
1313 * @discussion
1314 * You should not modify an array's contents during iteration. The array indexes
1315 * are iterated in order.
1316 */
1317#ifdef __BLOCKS__
1318__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1319XPC_EXPORT XPC_NONNULL_ALL
1320bool
1321xpc_array_apply(xpc_object_t xarray, XPC_NOESCAPE xpc_array_applier_t applier);
1322#endif // __BLOCKS__ 
1323
1324#pragma mark Array Primitive Setters
1325/*!
1326 * @define XPC_ARRAY_APPEND
1327 * A constant that may be passed as the destination index to the class of
1328 * primitive XPC array setters indicating that the given primitive should be
1329 * appended to the array.
1330 */
1331#define XPC_ARRAY_APPEND ((size_t)(-1))
1332
1333/*!
1334 * @function xpc_array_set_bool
1335 *
1336 * @abstract
1337 * Inserts a <code>bool</code> (primitive) value into an array.
1338 *
1339 * @param xarray
1340 * The array object which is to be manipulated.
1341 *
1342 * @param index
1343 * The index at which to insert the value. This value must lie within the index
1344 * space of the array (0 to N-1 inclusive, where N is the count of the array) or
1345 * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is
1346 * undefined.
1347 *
1348 * @param value
1349 * The <code>bool</code> value to insert. After calling this method, the XPC
1350 * object corresponding to the primitive value inserted may be safely retrieved
1351 * with {@link xpc_array_get_value()}.
1352 */
1353__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1354XPC_EXPORT XPC_NONNULL1
1355void
1356xpc_array_set_bool(xpc_object_t xarray, size_t index, bool value);
1357
1358/*!
1359 * @function xpc_array_set_int64
1360 *
1361 * @abstract
1362 * Inserts an <code>int64_t</code> (primitive) value into an array.
1363 *
1364 * @param xarray
1365 * The array object which is to be manipulated.
1366 *
1367 * @param index
1368 * The index at which to insert the value. This value must lie within the index
1369 * space of the array (0 to N-1 inclusive, where N is the count of the array) or
1370 * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is
1371 * undefined.
1372 *
1373 * @param value
1374 * The <code>int64_t</code> value to insert. After calling this method, the XPC
1375 * object corresponding to the primitive value inserted may be safely retrieved
1376 * with {@link xpc_array_get_value()}.
1377 */
1378__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1379XPC_EXPORT XPC_NONNULL1
1380void
1381xpc_array_set_int64(xpc_object_t xarray, size_t index, int64_t value);
1382
1383/*!
1384 * @function xpc_array_set_uint64
1385 *
1386 * @abstract
1387 * Inserts a <code>uint64_t</code> (primitive) value into an array.
1388 *
1389 * @param xarray
1390 * The array object which is to be manipulated.
1391 *
1392 * @param index
1393 * The index at which to insert the value. This value must lie within the index
1394 * space of the array (0 to N-1 inclusive, where N is the count of the array) or
1395 * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is
1396 * undefined.
1397 *
1398 * @param value
1399 * The <code>uint64_t</code> value to insert. After calling this method, the XPC
1400 * object corresponding to the primitive value inserted may be safely retrieved
1401 * with {@link xpc_array_get_value()}.
1402 */
1403__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1404XPC_EXPORT XPC_NONNULL1
1405void
1406xpc_array_set_uint64(xpc_object_t xarray, size_t index, uint64_t value);
1407
1408/*!
1409 * @function xpc_array_set_double
1410 *
1411 * @abstract
1412 * Inserts a <code>double</code> (primitive) value into an array.
1413 *
1414 * @param xarray
1415 * The array object which is to be manipulated.
1416 *
1417 * @param index
1418 * The index at which to insert the value. This value must lie within the index
1419 * space of the array (0 to N-1 inclusive, where N is the count of the array) or
1420 * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is
1421 * undefined.
1422 *
1423 * @param value
1424 * The <code>double</code> value to insert. After calling this method, the XPC
1425 * object corresponding to the primitive value inserted may be safely retrieved
1426 * with {@link xpc_array_get_value()}.
1427 */
1428__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1429XPC_EXPORT XPC_NONNULL1
1430void
1431xpc_array_set_double(xpc_object_t xarray, size_t index, double value);
1432
1433/*!
1434 * @function xpc_array_set_date
1435 *
1436 * @abstract
1437 * Inserts a date value into an array.
1438 *
1439 * @param xarray
1440 * The array object which is to be manipulated.
1441 *
1442 * @param index
1443 * The index at which to insert the value. This value must lie within the index
1444 * space of the array (0 to N-1 inclusive, where N is the count of the array) or
1445 * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is
1446 * undefined.
1447 *
1448 * @param value
1449 * The date value to insert, represented as an <code>int64_t</code>. The
1450 * interval is with respect to the Unix epoch. XPC dates are in Unix time and
1451 * are thus unaware of local time or leap seconds. After calling this method,
1452 * the XPC object corresponding to the primitive value inserted may be safely
1453 * retrieved with {@link xpc_array_get_value()}.
1454 */
1455__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1456XPC_EXPORT XPC_NONNULL1
1457void
1458xpc_array_set_date(xpc_object_t xarray, size_t index, int64_t value);
1459
1460/*!
1461 * @function xpc_array_set_data
1462 *
1463 * @abstract
1464 * Inserts a raw data value into an array.
1465 *
1466 * @param xarray
1467 * The array object which is to be manipulated.
1468 *
1469 * @param index
1470 * The index at which to insert the value. This value must lie within the index
1471 * space of the array (0 to N-1 inclusive, where N is the count of the array) or
1472 * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is
1473 * undefined.
1474 *
1475 * @param bytes
1476 * The raw data to insert. After calling this method, the XPC object
1477 * corresponding to the primitive value inserted may be safely retrieved with
1478 * {@link xpc_array_get_value()}.
1479 *
1480 * @param length
1481 * The length of the data.
1482 */
1483__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1484XPC_EXPORT XPC_NONNULL1 XPC_NONNULL3
1485void
1486xpc_array_set_data(xpc_object_t xarray, size_t index,
1487	const void *XPC_SIZEDBY(length) bytes, size_t length);
1488
1489/*!
1490 * @function xpc_array_set_string
1491 *
1492 * @abstract
1493 * Inserts a C string into an array.
1494 *
1495 * @param xarray
1496 * The array object which is to be manipulated.
1497 *
1498 * @param index
1499 * The index at which to insert the value. This value must lie within the index
1500 * space of the array (0 to N-1 inclusive, where N is the count of the array) or
1501 * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is
1502 * undefined.
1503 *
1504 * @param string
1505 * The C string to insert. After calling this method, the XPC object
1506 * corresponding to the primitive value inserted may be safely retrieved with
1507 * {@link xpc_array_get_value()}.
1508 */
1509__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1510XPC_EXPORT XPC_NONNULL1 XPC_NONNULL3
1511void
1512xpc_array_set_string(xpc_object_t xarray, size_t index, const char *string);
1513
1514/*!
1515 * @function xpc_array_set_uuid
1516 *
1517 * @abstract
1518 * Inserts a <code>uuid_t</code> (primitive) value into an array.
1519 *
1520 * @param xarray
1521 * The array object which is to be manipulated.
1522 *
1523 * @param index
1524 * The index at which to insert the value. This value must lie within the index
1525 * space of the array (0 to N-1 inclusive, where N is the count of the array) or
1526 * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is
1527 * undefined.
1528 *
1529 * @param uuid
1530 * The UUID primitive to insert. After calling this method, the XPC object
1531 * corresponding to the primitive value inserted may be safely retrieved with
1532 * {@link xpc_array_get_value()}.
1533 */
1534__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1535XPC_EXPORT XPC_NONNULL1 XPC_NONNULL3
1536void
1537xpc_array_set_uuid(xpc_object_t xarray, size_t index,
1538	const uuid_t XPC_NONNULL_ARRAY uuid);
1539
1540/*!
1541 * @function xpc_array_set_fd
1542 *
1543 * @abstract
1544 * Inserts a file descriptor into an array.
1545 *
1546 * @param xarray
1547 * The array object which is to be manipulated.
1548 *
1549 * @param index
1550 * The index at which to insert the value. This value must lie within the index
1551 * space of the array (0 to N-1 inclusive, where N is the count of the array) or
1552 * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is
1553 * undefined.
1554 *
1555 * @param fd
1556 * The file descriptor to insert. After calling this method, the XPC object
1557 * corresponding to the primitive value inserted may be safely retrieved with
1558 * {@link xpc_array_get_value()}.
1559 */
1560__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1561XPC_EXPORT XPC_NONNULL1
1562void
1563xpc_array_set_fd(xpc_object_t xarray, size_t index, int fd);
1564
1565/*!
1566 * @function xpc_array_set_connection
1567 *
1568 * @abstract
1569 * Inserts a connection into an array.
1570 *
1571 * @param xarray
1572 * The array object which is to be manipulated.
1573 *
1574 * @param index
1575 * The index at which to insert the value. This value must lie within the index
1576 * space of the array (0 to N-1 inclusive, where N is the count of the array) or
1577 * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is
1578 * undefined.
1579 *
1580 * @param connection
1581 * The connection to insert. After calling this method, the XPC object
1582 * corresponding to the primitive value inserted may be safely retrieved with
1583 * {@link xpc_array_get_value()}. The connection is NOT retained by the array.
1584 */
1585__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1586XPC_EXPORT XPC_NONNULL1 XPC_NONNULL3
1587void
1588xpc_array_set_connection(xpc_object_t xarray, size_t index,
1589	xpc_connection_t connection);
1590
1591#pragma mark Array Primitive Getters
1592/*!
1593 * @function xpc_array_get_bool
1594 *
1595 * @abstract
1596 * Gets a <code>bool</code> primitive value from an array directly.
1597 *
1598 * @param xarray
1599 * The array which is to be examined.
1600 *
1601 * @param index
1602 * The index of the value to obtain. This value must lie within the index space
1603 * of the array (0 to N-1 inclusive, where N is the count of the array). If the
1604 * index is outside that range, the behavior is undefined.
1605 *
1606 * @result
1607 * The underlying <code>bool</code> value at the specified index. false if the
1608 * value at the specified index is not a Boolean value.
1609 */
1610__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1611XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
1612bool
1613xpc_array_get_bool(xpc_object_t xarray, size_t index);
1614
1615/*!
1616 * @function xpc_array_get_int64
1617 *
1618 * @abstract
1619 * Gets an <code>int64_t</code> primitive value from an array directly.
1620 *
1621 * @param xarray
1622 * The array which is to be examined.
1623 *
1624 * @param index
1625 * The index of the value to obtain. This value must lie within the index space
1626 * of the array (0 to N-1 inclusive, where N is the count of the array). If the
1627 * index is outside that range, the behavior is undefined.
1628 *
1629 * @result
1630 * The underlying <code>int64_t</code> value at the specified index. 0 if the
1631 * value at the specified index is not a signed integer value.
1632 */
1633__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1634XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
1635int64_t
1636xpc_array_get_int64(xpc_object_t xarray, size_t index);
1637
1638/*!
1639 * @function xpc_array_get_uint64
1640 *
1641 * @abstract
1642 * Gets a <code>uint64_t</code> primitive value from an array directly.
1643 *
1644 * @param xarray
1645 * The array which is to be examined.
1646 *
1647 * @param index
1648 * The index of the value to obtain. This value must lie within the index space
1649 * of the array (0 to N-1 inclusive, where N is the count of the array). If the
1650 * index is outside that range, the behavior is undefined.
1651 *
1652 * @result
1653 * The underlying <code>uint64_t</code> value at the specified index. 0 if the
1654 * value at the specified index is not an unsigned integer value.
1655 */
1656__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1657XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
1658uint64_t
1659xpc_array_get_uint64(xpc_object_t xarray, size_t index);
1660
1661/*!
1662 * @function xpc_array_get_double
1663 *
1664 * @abstract
1665 * Gets a <code>double</code> primitive value from an array directly.
1666 *
1667 * @param xarray
1668 * The array which is to be examined.
1669 *
1670 * @param index
1671 * The index of the value to obtain. This value must lie within the index space
1672 * of the array (0 to N-1 inclusive, where N is the count of the array). If the
1673 * index is outside that range, the behavior is undefined.
1674 *
1675 * @result
1676 * The underlying <code>double</code> value at the specified index. NAN if the
1677 * value at the specified index is not a floating point value.
1678 */
1679__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1680XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
1681double
1682xpc_array_get_double(xpc_object_t xarray, size_t index);
1683
1684/*!
1685 * @function xpc_array_get_date
1686 *
1687 * @abstract
1688 * Gets a date interval from an array directly.
1689 *
1690 * @param xarray
1691 * The array which is to be examined.
1692 *
1693 * @param index
1694 * The index of the value to obtain. This value must lie within the index space
1695 * of the array (0 to N-1 inclusive, where N is the count of the array). If the
1696 * index is outside that range, the behavior is undefined.
1697 *
1698 * @result
1699 * The underlying date interval at the specified index. The interval is with
1700 * respect to the Unix epoch. XPC dates are in Unix time and are thus unaware
1701 * of local time or leap seconds. 0 if the value at the specified index is not
1702 * a date value.
1703 */
1704__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1705XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
1706int64_t
1707xpc_array_get_date(xpc_object_t xarray, size_t index);
1708
1709/*!
1710 * @function xpc_array_get_data
1711 *
1712 * @abstract
1713 * Gets a pointer to the raw bytes of a data object from an array directly.
1714 *
1715 * @param xarray
1716 * The array which is to be examined.
1717 *
1718 * @param index
1719 * The index of the value to obtain. This value must lie within the index space
1720 * of the array (0 to N-1 inclusive, where N is the count of the array). If the
1721 * index is outside that range, the behavior is undefined.
1722 *
1723 * @param length
1724 * Upon return, will contain the length of the data corresponding to the
1725 * specified key.
1726 *
1727 * @result
1728 * The underlying bytes at the specified index. NULL if the value at the
1729 * specified index is not a data value.
1730 */
1731__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1732XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
1733const void * _Nullable
1734xpc_array_get_data(xpc_object_t xarray, size_t index,
1735	size_t * _Nullable length);
1736
1737/*!
1738 * @function xpc_array_get_string
1739 *
1740 * @abstract
1741 * Gets a C string value from an array directly.
1742 *
1743 * @param xarray
1744 * The array which is to be examined.
1745 *
1746 * @param index
1747 * The index of the value to obtain. This value must lie within the index space
1748 * of the array (0 to N-1 inclusive, where N is the count of the array). If the
1749 * index is outside that range, the behavior is undefined.
1750 *
1751 * @result
1752 * The underlying C string at the specified index. NULL if the value at the
1753 * specified index is not a C string value.
1754 */
1755__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1756XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
1757const char * _Nullable
1758xpc_array_get_string(xpc_object_t xarray, size_t index);
1759
1760/*!
1761 * @function xpc_array_get_uuid
1762 *
1763 * @abstract
1764 * Gets a <code>uuid_t</code> value from an array directly.
1765 *
1766 * @param xarray
1767 * The array which is to be examined.
1768 *
1769 * @param index
1770 * The index of the value to obtain. This value must lie within the index space
1771 * of the array (0 to N-1 inclusive, where N is the count of the array). If the
1772 * index is outside that range, the behavior is undefined.
1773 *
1774 * @result
1775 * The underlying <code>uuid_t</code> value at the specified index. The null
1776 * UUID if the value at the specified index is not a UUID value. The returned
1777 * pointer may be safely passed to the uuid(3) APIs.
1778 */
1779__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1780XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
1781const uint8_t * _Nullable
1782xpc_array_get_uuid(xpc_object_t xarray, size_t index);
1783
1784/*!
1785 * @function xpc_array_dup_fd
1786 *
1787 * @abstract
1788 * Gets a file descriptor from an array directly.
1789 *
1790 * @param xarray
1791 * The array which is to be examined.
1792 *
1793 * @param index
1794 * The index of the value to obtain. This value must lie within the index space
1795 * of the array (0 to N-1 inclusive, where N is the count of the array). If the
1796 * index is outside that range, the behavior is undefined.
1797 *
1798 * @result
1799 * A new file descriptor created from the value at the specified index. You are
1800 * responsible for close(2)ing this descriptor. -1 if the value at the specified
1801 * index is not a file descriptor value.
1802 */
1803__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1804XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
1805int
1806xpc_array_dup_fd(xpc_object_t xarray, size_t index);
1807
1808/*!
1809 * @function xpc_array_create_connection
1810 *
1811 * @abstract
1812 * Creates a connection object from an array directly.
1813 *
1814 * @param xarray
1815 * The array which is to be examined.
1816 *
1817 * @param index
1818 * The index of the value to obtain. This value must lie within the index space
1819 * of the array (0 to N-1 inclusive, where N is the count of the array). If the
1820 * index is outside that range, the behavior is undefined.
1821 *
1822 * @result
1823 * A new connection created from the value at the specified index. You are
1824 * responsible for calling xpc_release() on the returned connection. NULL if the
1825 * value at the specified index is not an endpoint containing a connection. Each
1826 * call to this method for the same index in the same array will yield a
1827 * different connection. See {@link xpc_connection_create_from_endpoint()} for
1828 * discussion as to the responsibilities when dealing with the returned
1829 * connection.
1830 */
1831__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1832XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1
1833xpc_connection_t _Nullable
1834xpc_array_create_connection(xpc_object_t xarray, size_t index);
1835
1836/*!
1837 * @function xpc_array_get_dictionary
1838 *
1839 * @abstract
1840 * Returns the dictionary at the specified index in the array.
1841 *
1842 * @param xarray
1843 * The array object which is to be examined.
1844 *
1845 * @param index
1846 * The index of the value to obtain. This value must lie within the range of
1847 * indexes as specified in xpc_array_set_value().
1848 * 
1849 * @result
1850 * The object at the specified index within the array or NULL if the given
1851 * object was not an XPC array or if the value at the specified index was
1852 * not a dictionary.
1853 *
1854 * @discussion
1855 * This method does not grant the caller a reference to the underlying object,
1856 * and thus the caller is not responsible for releasing the object.
1857 */
1858__OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0)
1859XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL
1860xpc_object_t _Nullable
1861xpc_array_get_dictionary(xpc_object_t xarray, size_t index);
1862
1863/*!
1864 * @function xpc_array_get_array
1865 *
1866 * @abstract
1867 * Returns the array at the specified index in the array.
1868 *
1869 * @param xarray
1870 * The array object which is to be examined.
1871 *
1872 * @param index
1873 * The index of the value to obtain. This value must lie within the range of
1874 * indexes as specified in xpc_array_set_value().
1875 * 
1876 * @result
1877 * The object at the specified index within the array or NULL if the given
1878 * object was not an XPC array or if the value at the specified index was
1879 * not an array.
1880 *
1881 * @discussion
1882 * This method does not grant the caller a reference to the underlying object,
1883 * and thus the caller is not responsible for releasing the object.
1884 */
1885__OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0)
1886XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL
1887xpc_object_t _Nullable
1888xpc_array_get_array(xpc_object_t xarray, size_t index);
1889
1890#pragma mark Dictionary
1891/*!
1892 * @typedef xpc_dictionary_applier_t
1893 * A block to be invoked for every key/value pair in the dictionary.
1894 *
1895 * @param key
1896 * The current key in the iteration.
1897 *
1898 * @param value
1899 * The current value in the iteration.
1900 *
1901 * @result
1902 * A Boolean indicating whether iteration should continue.
1903 */
1904#ifdef __BLOCKS__
1905typedef bool (^xpc_dictionary_applier_t)(const char * _Nonnull key,
1906		xpc_object_t _Nonnull value);
1907#endif // __BLOCKS__ 
1908
1909/*!
1910 * @function xpc_dictionary_create
1911 *
1912 * @abstract
1913 * Creates an XPC object representing a dictionary of XPC objects keyed to
1914 * C-strings.
1915 *
1916 * @param keys
1917 * An array of C-strings that are to be the keys for the values to be inserted.
1918 * Each element of this array is copied into the dictionary's internal storage.
1919 * Elements of this array may NOT be NULL.
1920 *
1921 * @param values
1922 * A C-array that is parallel to the array of keys, consisting of objects that
1923 * are to be inserted. Each element in this array is retained. Elements in this
1924 * array may be NULL.
1925 *
1926 * @param count
1927 * The number of key/value pairs in the given arrays. If the count is less than
1928 * the actual count of values, only that many key/value pairs will be inserted
1929 * into the dictionary.
1930 *
1931 * If the count is more than the actual count of key/value pairs, the
1932 * behavior is undefined. If one array is NULL and the other is not, the 
1933 * behavior is undefined. If both arrays are NULL and the count is non-0, the
1934 * behavior is undefined.
1935 *
1936 * @result
1937 * The new dictionary object.
1938 */
1939__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1940XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT
1941xpc_object_t
1942xpc_dictionary_create(
1943	const char *XPC_CSTRING _Nonnull const *XPC_COUNTEDBY(count) _Nullable keys,
1944	const xpc_object_t _Nullable *XPC_COUNTEDBY(count) _Nullable values, size_t count);
1945
1946/*!
1947 * @function xpc_dictionary_create_empty
1948 *
1949 * @abstract
1950 * Creates an XPC object representing a dictionary of XPC objects keyed to
1951 * C-strings.
1952 *
1953 * @result
1954 * The new dictionary object.
1955 *
1956 * @see
1957 * xpc_dictionary_create
1958 */
1959API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), watchos(7.0))
1960XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT
1961xpc_object_t
1962xpc_dictionary_create_empty(void);
1963
1964/*!
1965 * @function xpc_dictionary_create_reply
1966 * 
1967 * @abstract
1968 * Creates a dictionary that is in reply to the given dictionary.
1969 *
1970 * @param original
1971 * The original dictionary that is to be replied to.
1972 *
1973 * @result
1974 * The new dictionary object. NULL if the object was not a dictionary with a
1975 * reply context.
1976 *
1977 * @discussion
1978 * After completing successfully on a dictionary, this method may not be called
1979 * again on that same dictionary. Attempts to do so will return NULL.
1980 *
1981 * When this dictionary is sent across the reply connection, the remote end's
1982 * reply handler is invoked.
1983 */
1984__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
1985XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL_ALL
1986xpc_object_t _Nullable
1987xpc_dictionary_create_reply(xpc_object_t original);
1988
1989/*!
1990 * @function xpc_dictionary_set_value
1991 *
1992 * @abstract
1993 * Sets the value for the specified key to the specified object.
1994 *
1995 * @param xdict
1996 * The dictionary object which is to be manipulated.
1997 *
1998 * @param key
1999 * The key for which the value shall be set.
2000 *
2001 * @param value
2002 * The object to insert. The object is retained by the dictionary. If there
2003 * already exists a value for the specified key, the old value is released
2004 * and overwritten by the new value. This parameter may be NULL, in which case
2005 * the value corresponding to the specified key is deleted if present.
2006 */
2007__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2008XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2
2009void
2010xpc_dictionary_set_value(xpc_object_t xdict, const char *key,
2011	xpc_object_t _Nullable value);
2012
2013/*!
2014 * @function xpc_dictionary_get_value
2015 *
2016 * @abstract
2017 * Returns the value for the specified key.
2018 *
2019 * @param xdict
2020 * The dictionary object which is to be examined.
2021 *
2022 * @param key
2023 * The key whose value is to be obtained.
2024 * 
2025 * @result
2026 * The object for the specified key within the dictionary. NULL if there is no
2027 * value associated with the specified key or if the given object was not an
2028 * XPC dictionary.
2029 *
2030 * @discussion
2031 * This method does not grant the caller a reference to the underlying object,
2032 * and thus the caller is not responsible for releasing the object.
2033 */
2034__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2035XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 XPC_NONNULL2
2036xpc_object_t _Nullable
2037xpc_dictionary_get_value(xpc_object_t xdict, const char *key);
2038
2039/*!
2040 * @function xpc_dictionary_get_count
2041 *
2042 * @abstract
2043 * Returns the number of values stored in the dictionary.
2044 *
2045 * @param xdict
2046 * The dictionary object which is to be examined.
2047 *
2048 * @result
2049 * The number of values stored in the dictionary or 0 if the given object was
2050 * not an XPC dictionary. Calling xpc_dictionary_set_value() with a non-NULL
2051 * value will increment the count. Calling xpc_dictionary_set_value() with a 
2052 * NULL value will decrement the count.
2053 */
2054__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2055XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
2056size_t
2057xpc_dictionary_get_count(xpc_object_t xdict);
2058
2059/*!
2060 * @function xpc_dictionary_apply
2061 *
2062 * @abstract
2063 * Invokes the given block for every key/value pair in the dictionary.
2064 *
2065 * @param xdict
2066 * The dictionary object which is to be examined.
2067 *
2068 * @param applier
2069 * The block which this function applies to every key/value pair in the 
2070 * dictionary.
2071 * 
2072 * @result
2073 * A Boolean indicating whether iteration of the dictionary completed
2074 * successfully. Iteration will only fail if the applier block returns false.
2075 *
2076 * @discussion
2077 * You should not modify a dictionary's contents during iteration. There is no
2078 * guaranteed order of iteration over dictionaries.
2079 */
2080#ifdef __BLOCKS__
2081__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2082XPC_EXPORT XPC_NONNULL_ALL
2083bool
2084xpc_dictionary_apply(xpc_object_t xdict,
2085		XPC_NOESCAPE xpc_dictionary_applier_t applier);
2086#endif // __BLOCKS__ 
2087
2088/*!
2089 * @function xpc_dictionary_get_remote_connection
2090 *
2091 * @abstract
2092 * Returns the connection from which the dictionary was received.
2093 *
2094 * @param xdict
2095 * The dictionary object which is to be examined.
2096 *
2097 * @result
2098 * If the dictionary was received by a connection event handler or a dictionary
2099 * created through xpc_dictionary_create_reply(), a connection object over which
2100 * a reply message can be sent is returned. For any other dictionary, NULL is
2101 * returned.
2102 */
2103__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2104XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL
2105xpc_connection_t _Nullable
2106xpc_dictionary_get_remote_connection(xpc_object_t xdict);
2107
2108#pragma mark Dictionary Primitive Setters
2109/*!
2110 * @function xpc_dictionary_set_bool
2111 *
2112 * @abstract
2113 * Inserts a <code>bool</code> (primitive) value into a dictionary.
2114 *
2115 * @param xdict
2116 * The dictionary which is to be manipulated.
2117 *
2118 * @param key
2119 * The key for which the primitive value shall be set.
2120 *
2121 * @param value
2122 * The <code>bool</code> value to insert. After calling this method, the XPC
2123 * object corresponding to the primitive value inserted may be safely retrieved
2124 * with {@link xpc_dictionary_get_value()}.
2125 */
2126__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2127XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2
2128void
2129xpc_dictionary_set_bool(xpc_object_t xdict, const char *key, bool value);
2130
2131/*!
2132 * @function xpc_dictionary_set_int64
2133 *
2134 * @abstract
2135 * Inserts an <code>int64_t</code> (primitive) value into a dictionary.
2136 *
2137 * @param xdict
2138 * The dictionary which is to be manipulated.
2139 *
2140 * @param key
2141 * The key for which the primitive value shall be set.
2142 *
2143 * @param value
2144 * The <code>int64_t</code> value to insert. After calling this method, the XPC
2145 * object corresponding to the primitive value inserted may be safely retrieved
2146 * with {@link xpc_dictionary_get_value()}.
2147 */
2148__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2149XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2
2150void
2151xpc_dictionary_set_int64(xpc_object_t xdict, const char *key, int64_t value);
2152
2153/*!
2154 * @function xpc_dictionary_set_uint64
2155 *
2156 * @abstract
2157 * Inserts a <code>uint64_t</code> (primitive) value into a dictionary.
2158 *
2159 * @param xdict
2160 * The dictionary which is to be manipulated.
2161 *
2162 * @param key
2163 * The key for which the primitive value shall be set.
2164 *
2165 * @param value
2166 * The <code>uint64_t</code> value to insert. After calling this method, the XPC
2167 * object corresponding to the primitive value inserted may be safely retrieved
2168 * with {@link xpc_dictionary_get_value()}.
2169 */
2170__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2171XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2
2172void
2173xpc_dictionary_set_uint64(xpc_object_t xdict, const char *key, uint64_t value);
2174
2175/*!
2176 * @function xpc_dictionary_set_double
2177 *
2178 * @abstract
2179 * Inserts a <code>double</code> (primitive) value into a dictionary.
2180 *
2181 * @param xdict
2182 * The dictionary which is to be manipulated.
2183 *
2184 * @param key
2185 * The key for which the primitive value shall be set.
2186 *
2187 * @param value
2188 * The <code>double</code> value to insert. After calling this method, the XPC
2189 * object corresponding to the primitive value inserted may be safely retrieved
2190 * with {@link xpc_dictionary_get_value()}.
2191 */
2192__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2193XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2
2194void
2195xpc_dictionary_set_double(xpc_object_t xdict, const char *key, double value);
2196
2197/*!
2198 * @function xpc_dictionary_set_date
2199 *
2200 * @abstract
2201 * Inserts a date value into a dictionary.
2202 *
2203 * @param xdict
2204 * The dictionary which is to be manipulated.
2205 *
2206 * @param key
2207 * The key for which the value shall be set.
2208 *
2209 * @param value
2210 * The date value to insert, represented as an <code>int64_t</code>. The
2211 * interval is with respect to the Unix epoch. XPC dates are in Unix time and
2212 * are thus unaware of local time or leap seconds. After calling this method,
2213 * the XPC object corresponding to the primitive value inserted may be safely
2214 * retrieved with {@link xpc_dictionary_get_value()}.
2215 */
2216__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2217XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2
2218void
2219xpc_dictionary_set_date(xpc_object_t xdict, const char *key, int64_t value);
2220
2221/*!
2222 * @function xpc_dictionary_set_data
2223 *
2224 * @abstract
2225 * Inserts a raw data value into a dictionary.
2226 *
2227 * @param xdict
2228 * The dictionary which is to be manipulated.
2229 *
2230 * @param key
2231 * The key for which the primitive value shall be set.
2232 *
2233 * @param bytes
2234 * The bytes to insert. After calling this method, the XPC object corresponding
2235 * to the primitive value inserted may be safely retrieved with
2236 * {@link xpc_dictionary_get_value()}.
2237 *
2238 * @param length
2239 * The length of the data.
2240 */
2241__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2242XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 XPC_NONNULL3
2243void
2244xpc_dictionary_set_data(xpc_object_t xdict, const char *key,
2245	const void *XPC_SIZEDBY(length) bytes, size_t length);
2246
2247/*!
2248 * @function xpc_dictionary_set_string
2249 *
2250 * @abstract
2251 * Inserts a C string value into a dictionary.
2252 *
2253 * @param xdict
2254 * The dictionary which is to be manipulated.
2255 *
2256 * @param key
2257 * The key for which the primitive value shall be set.
2258 *
2259 * @param string
2260 * The C string to insert. After calling this method, the XPC object 
2261 * corresponding to the primitive value inserted may be safely retrieved with
2262 * {@link xpc_dictionary_get_value()}.
2263 */
2264__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2265XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 XPC_NONNULL3
2266void
2267xpc_dictionary_set_string(xpc_object_t xdict, const char *key,
2268	const char *string);
2269
2270/*!
2271 * @function xpc_dictionary_set_uuid
2272 *
2273 * @abstract
2274 * Inserts a UUID (primitive) value into a dictionary.
2275 *
2276 * @param xdict
2277 * The dictionary which is to be manipulated.
2278 *
2279 * @param key
2280 * The key for which the primitive value shall be set.
2281 *
2282 * @param uuid
2283 * The <code>uuid_t</code> value to insert. After calling this method, the XPC
2284 * object corresponding to the primitive value inserted may be safely retrieved
2285 * with {@link xpc_dictionary_get_value()}.
2286 */
2287__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2288XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 XPC_NONNULL3
2289void
2290xpc_dictionary_set_uuid(xpc_object_t xdict, const char *key,
2291	const uuid_t XPC_NONNULL_ARRAY uuid);
2292
2293/*!
2294 * @function xpc_dictionary_set_fd
2295 *
2296 * @abstract
2297 * Inserts a file descriptor into a dictionary.
2298 *
2299 * @param xdict
2300 * The dictionary which is to be manipulated.
2301 *
2302 * @param key
2303 * The key for which the primitive value shall be set.
2304 *
2305 * @param fd
2306 * The file descriptor to insert. After calling this method, the XPC object
2307 * corresponding to the primitive value inserted may be safely retrieved
2308 * with {@link xpc_dictionary_get_value()}.
2309 */
2310__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2311XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2
2312void
2313xpc_dictionary_set_fd(xpc_object_t xdict, const char *key, int fd);
2314
2315/*!
2316 * @function xpc_dictionary_set_connection
2317 *
2318 * @abstract
2319 * Inserts a connection into a dictionary.
2320 *
2321 * @param xdict
2322 * The dictionary which is to be manipulated.
2323 *
2324 * @param key
2325 * The key for which the primitive value shall be set.
2326 *
2327 * @param connection
2328 * The connection to insert. After calling this method, the XPC object
2329 * corresponding to the primitive value inserted may be safely retrieved
2330 * with {@link xpc_dictionary_get_value()}. The connection is NOT retained by
2331 * the dictionary.
2332 */
2333__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2334XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 XPC_NONNULL3
2335void
2336xpc_dictionary_set_connection(xpc_object_t xdict, const char *key,
2337	xpc_connection_t connection);
2338
2339/*!
2340 * @function xpc_dictionary_set_mach_send
2341 *
2342 * @abstract
2343 * Inserts a send right into a dictionary.
2344 *
2345 * @param xdict
2346 * The dictionary which is to be manipulated.
2347 *
2348 * @param key
2349 * The key for which the primitive value shall be set.
2350 *
2351 * @param p
2352 * The port to insert. After calling this method, the XPC object
2353 * corresponding to the primitive value inserted may be safely retrieved
2354 * with {@link xpc_dictionary_copy_mach_send()}.
2355 *
2356 * @discussion
2357 * The XPC runtime sends the port with disposition `MACH_MSG_TYPE_COPY_SEND`
2358 */
2359__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2360XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2
2361void
2362xpc_dictionary_set_mach_send(xpc_object_t xdict, const char *key,
2363	mach_port_t p);
2364
2365#pragma mark Dictionary Primitive Getters
2366/*!
2367 * @function xpc_dictionary_get_bool
2368 *
2369 * @abstract
2370 * Gets a <code>bool</code> primitive value from a dictionary directly.
2371 *
2372 * @param xdict
2373 * The dictionary object which is to be examined.
2374 *
2375 * @param key
2376 * The key whose value is to be obtained.
2377 *
2378 * @result
2379 * The underlying <code>bool</code> value for the specified key. false if the
2380 * the value for the specified key is not a Boolean value or if there is no
2381 * value for the specified key.
2382 */
2383__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2384XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL
2385bool
2386xpc_dictionary_get_bool(xpc_object_t xdict, const char *key);
2387
2388/*!
2389 * @function xpc_dictionary_get_int64
2390 *
2391 * @abstract
2392 * Gets an <code>int64_t</code> primitive value from a dictionary directly.
2393 *
2394 * @param xdict
2395 * The dictionary object which is to be examined.
2396 *
2397 * @param key
2398 * The key whose value is to be obtained.
2399 *
2400 * @result
2401 * The underlying <code>int64_t</code> value for the specified key. 0 if the
2402 * value for the specified key is not a signed integer value or if there is no
2403 * value for the specified key.
2404 */
2405__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2406XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL
2407int64_t
2408xpc_dictionary_get_int64(xpc_object_t xdict, const char *key);
2409
2410/*!
2411 * @function xpc_dictionary_get_uint64
2412 *
2413 * @abstract
2414 * Gets a <code>uint64_t</code> primitive value from a dictionary directly.
2415 *
2416 * @param xdict
2417 * The dictionary object which is to be examined.
2418 *
2419 * @param key
2420 * The key whose value is to be obtained.
2421 *
2422 * @result
2423 * The underlying <code>uint64_t</code> value for the specified key. 0 if the
2424 * value for the specified key is not an unsigned integer value or if there is
2425 * no value for the specified key.
2426 */
2427__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2428XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL
2429uint64_t
2430xpc_dictionary_get_uint64(xpc_object_t xdict, const char *key);
2431
2432/*!
2433 * @function xpc_dictionary_get_double
2434 *
2435 * @abstract
2436 * Gets a <code>double</code> primitive value from a dictionary directly.
2437 *
2438 * @param xdict
2439 * The dictionary object which is to be examined.
2440 *
2441 * @param key
2442 * The key whose value is to be obtained.
2443 *
2444 * @result
2445 * The underlying <code>double</code> value for the specified key. NAN if the
2446 * value for the specified key is not a floating point value or if there is no
2447 * value for the specified key.
2448 */
2449__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2450XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL
2451double
2452xpc_dictionary_get_double(xpc_object_t xdict, const char *key);
2453
2454/*!
2455 * @function xpc_dictionary_get_date
2456 *
2457 * @abstract
2458 * Gets a date value from a dictionary directly.
2459 *
2460 * @param xdict
2461 * The dictionary object which is to be examined.
2462 *
2463 * @param key
2464 * The key whose value is to be obtained.
2465 *
2466 * @result
2467 * The underlying date interval for the specified key. The interval is with
2468 * respect to the Unix epoch. XPC dates are in Unix time and are thus unaware
2469 * of local time or leap seconds. 0 if the value for the specified key is not a
2470 * date value or if there is no value for the specified key.
2471 */
2472__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2473XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL
2474int64_t
2475xpc_dictionary_get_date(xpc_object_t xdict, const char *key);
2476
2477/*!
2478 * @function xpc_dictionary_get_data
2479 *
2480 * @abstract
2481 * Gets a raw data value from a dictionary directly.
2482 *
2483 * @param xdict
2484 * The dictionary object which is to be examined.
2485 *
2486 * @param key
2487 * The key whose value is to be obtained.
2488 *
2489 * @param length
2490 * For the data type, the third parameter, upon output, will contain the length
2491 * of the data corresponding to the specified key. May be NULL.
2492 *
2493 * @result
2494 * The underlying raw data for the specified key. NULL if the value for the
2495 * specified key is not a data value or if there is no value for the specified
2496 * key.
2497 */
2498__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2499XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
2500const void * _Nullable
2501xpc_dictionary_get_data(xpc_object_t xdict, const char *key,
2502	size_t * _Nullable length);
2503
2504/*!
2505 * @function xpc_dictionary_get_string
2506 *
2507 * @abstract
2508 * Gets a C string value from a dictionary directly.
2509 *
2510 * @param xdict
2511 * The dictionary object which is to be examined.
2512 *
2513 * @param key
2514 * The key whose value is to be obtained.
2515 *
2516 * @result
2517 * The underlying C string for the specified key. NULL if the value for the
2518 * specified key is not a C string value or if there is no value for the
2519 * specified key.
2520 */
2521__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2522XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL
2523const char * _Nullable
2524xpc_dictionary_get_string(xpc_object_t xdict, const char *key);
2525
2526/*!
2527 * @function xpc_dictionary_get_uuid
2528 *
2529 * @abstract
2530 * Gets a uuid value from a dictionary directly.
2531 *
2532 * @param xdict
2533 * The dictionary object which is to be examined.
2534 *
2535 * @param key
2536 * The key whose value is to be obtained.
2537 *
2538 * @result
2539 * The underlying <code>uuid_t</code> value for the specified key. NULL if the
2540 * value at the specified index is not a UUID value. The returned pointer may be
2541 * safely passed to the uuid(3) APIs.
2542 */
2543__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2544XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 XPC_NONNULL2
2545const uint8_t * _Nullable
2546xpc_dictionary_get_uuid(xpc_object_t xdict, const char *key);
2547
2548/*!
2549 * @function xpc_dictionary_dup_fd
2550 *
2551 * @abstract
2552 * Creates a file descriptor from a dictionary directly.
2553 *
2554 * @param xdict
2555 * The dictionary object which is to be examined.
2556 *
2557 * @param key
2558 * The key whose value is to be obtained.
2559 *
2560 * @result
2561 * A new file descriptor created from the value for the specified key. You are
2562 * responsible for close(2)ing this descriptor. -1 if the value for the
2563 * specified key is not a file descriptor value or if there is no value for the
2564 * specified key.
2565 */
2566__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2567XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL
2568int
2569xpc_dictionary_dup_fd(xpc_object_t xdict, const char *key);
2570
2571/*!
2572 * @function xpc_dictionary_create_connection
2573 *
2574 * @abstract
2575 * Creates a connection from a dictionary directly.
2576 *
2577 * @param xdict
2578 * The dictionary object which is to be examined.
2579 *
2580 * @param key
2581 * The key whose value is to be obtained.
2582 *
2583 * @result
2584 * A new connection created from the value for the specified key. You are
2585 * responsible for calling xpc_release() on the returned connection. NULL if the
2586 * value for the specified key is not an endpoint containing a connection or if
2587 * there is no value for the specified key. Each call to this method for the
2588 * same key in the same dictionary will yield a different connection. See
2589 * {@link xpc_connection_create_from_endpoint()} for discussion as to the
2590 * responsibilities when dealing with the returned connection.
2591 */
2592__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2593XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL_ALL
2594xpc_connection_t _Nullable
2595xpc_dictionary_create_connection(xpc_object_t xdict, const char *key);
2596
2597/*!
2598 * @function xpc_dictionary_get_dictionary
2599 *
2600 * @abstract
2601 * Returns the dictionary value for the specified key.
2602 *
2603 * @param xdict
2604 * The dictionary object which is to be examined.
2605 *
2606 * @param key
2607 * The key whose value is to be obtained.
2608 * 
2609 * @result
2610 * The object for the specified key within the dictionary. NULL if there is no
2611 * value associated with the specified key, if the given object was not an
2612 * XPC dictionary, or if the object for the specified key is not a dictionary.
2613 *
2614 * @discussion
2615 * This method does not grant the caller a reference to the underlying object,
2616 * and thus the caller is not responsible for releasing the object.
2617 */
2618__OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0)
2619XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL
2620xpc_object_t _Nullable
2621xpc_dictionary_get_dictionary(xpc_object_t xdict, const char *key);
2622
2623/*!
2624 * @function xpc_dictionary_get_array
2625 *
2626 * @abstract
2627 * Returns the array value for the specified key.
2628 *
2629 * @param xdict
2630 * The dictionary object which is to be examined.
2631 *
2632 * @param key
2633 * The key whose value is to be obtained.
2634 * 
2635 * @result
2636 * The object for the specified key within the dictionary. NULL if there is no
2637 * value associated with the specified key, if the given object was not an
2638 * XPC dictionary, or if the object for the specified key is not an array.
2639 *
2640 * @discussion
2641 * This method does not grant the caller a reference to the underlying object,
2642 * and thus the caller is not responsible for releasing the object.
2643 */
2644__OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0)
2645XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL
2646xpc_object_t _Nullable
2647xpc_dictionary_get_array(xpc_object_t xdict, const char *key);
2648
2649/*!
2650 * @function xpc_dictionary_copy_mach_send
2651 *
2652 * @abstract
2653 * Returns a send right to the mach port.
2654 *
2655 * @param xdict
2656 * The dictionary object which is to be examined.
2657 *
2658 * @param key
2659 * The key whose value is to be obtained.
2660 *
2661 * @result
2662 * The object for the specified key within the dictionary. `MACH_PORT_NULL`
2663 * if there is no value associated with the specified key, if the given object
2664 * was not an XPC dictionary, or if the object for the specified key is not a send
2665 * right.
2666 *
2667 * @discussion
2668 * The XPC runtime will copy the send right using `mach_port_mod_refs`
2669 * before returning the port
2670 */
2671__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
2672XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 XPC_NONNULL2
2673mach_port_t
2674xpc_dictionary_copy_mach_send(xpc_object_t xdict, const char *key);
2675
2676#pragma mark Runtime
2677/*!
2678 * @function xpc_main
2679 * The springboard into the XPCService runtime. This function will set up your
2680 * service bundle's listener connection and manage it automatically. After this
2681 * initial setup, this function will, by default, call dispatch_main(). You may
2682 * override this behavior by setting the RunLoopType key in your XPC service
2683 * bundle's Info.plist under the XPCService dictionary.
2684 *
2685 * @param handler
2686 * The handler with which to accept new connections. This handler is called for
2687 * each new connection established with the service. The handler must either
2688 * accept the connection by setting an event handler with
2689 * xpc_connection_set_event_handler() and calling xpc_connection_resume(), or
2690 * reject the connection by calling xpc_connection_cancel(). Failure to take
2691 * one of these actions will result in the connection remaining in an undefined
2692 * state, potentially causing resource leaks or transaction issues.
2693 */
2694API_AVAILABLE(macos(10.7), macCatalyst(5.0))
2695API_UNAVAILABLE(ios)
2696XPC_EXPORT XPC_NORETURN XPC_NONNULL1
2697void
2698xpc_main(xpc_connection_handler_t handler);
2699
2700#pragma mark Transactions
2701/*!
2702 * @function xpc_transaction_begin
2703 * Informs the XPC runtime that a transaction has begun and that the service
2704 * should not exit due to inactivity.
2705 * 
2706 * @discussion
2707 * A service with no outstanding transactions may automatically exit due to
2708 * inactivity as determined by the system.
2709 *
2710 * This function may be used to manually manage transactions in cases where
2711 * their automatic management (as described below) does not meet the needs of an
2712 * XPC service. This function also updates the transaction count used for sudden
2713 * termination, i.e. vproc_transaction_begin(), and these two interfaces may be
2714 * used in combination.
2715 *
2716 * The XPC runtime will automatically begin a transaction on behalf of a service
2717 * when a new message is received. If no reply message is expected, the
2718 * transaction is automatically ended when the last reference to the message is released.
2719 * If a reply message is created, the transaction will end when the reply
2720 * message is sent or released. An XPC service may use xpc_transaction_begin()
2721 * and xpc_transaction_end() to inform the XPC runtime about activity that
2722 * occurs outside of this common pattern.
2723 *
2724 * On macOS, when the XPC runtime has determined that the service should exit,
2725 * the event handlers for all active peer connections will receive
2726 * {@link XPC_ERROR_TERMINATION_IMMINENT} as an indication that they should
2727 * unwind their existing transactions. After this error is delivered to a
2728 * connection's event handler, no more messages will be delivered to the
2729 * connection.
2730 */
2731API_AVAILABLE(macos(10.7))
2732API_UNAVAILABLE(ios)
2733XPC_TRANSACTION_DEPRECATED
2734XPC_EXPORT
2735void
2736xpc_transaction_begin(void);
2737
2738/*!
2739 * @function xpc_transaction_end
2740 * Informs the XPC runtime that a transaction has ended.
2741 * 
2742 * @discussion
2743 * As described in {@link xpc_transaction_begin()}, this API may be used
2744 * interchangeably with vproc_transaction_end().
2745 *
2746 * See the discussion for {@link xpc_transaction_begin()} for details regarding
2747 * the XPC runtime's idle-exit policy.
2748 */
2749API_AVAILABLE(macos(10.7))
2750API_UNAVAILABLE(ios)
2751XPC_TRANSACTION_DEPRECATED
2752XPC_EXPORT
2753void
2754xpc_transaction_end(void);
2755
2756#pragma mark XPC Event Stream
2757/*!
2758 * @function xpc_set_event_stream_handler
2759 * Sets the event handler to invoke when streamed events are received.
2760 *
2761 * @param stream
2762 * The name of the event stream for which this handler will be invoked.
2763 *
2764 * @param targetq
2765 * The GCD queue to which the event handler block will be submitted. This
2766 * parameter may be NULL, in which case the connection's target queue will be
2767 * libdispatch's default target queue, defined as DISPATCH_TARGET_QUEUE_DEFAULT.
2768 * 
2769 * @param handler
2770 * The event handler block. The event which this block receives as its first
2771 * parameter will always be a dictionary which contains the XPC_EVENT_KEY_NAME
2772 * key. The value for this key will be a string whose value is the name assigned
2773 * to the XPC event specified in the launchd.plist. Future keys may be added to
2774 * this dictionary.
2775 *
2776 * @discussion
2777 * Multiple calls to this function for the same event stream will result in
2778 * undefined behavior.
2779 *
2780 * There is no API to pause delivery of XPC events. If a process that
2781 * has set an XPC event handler exits, events may be dropped due to races
2782 * between the event handler running and the process exiting.
2783 */
2784#if __BLOCKS__
2785API_AVAILABLE(macos(10.7))
2786API_UNAVAILABLE(ios)
2787XPC_EXPORT XPC_NONNULL1 XPC_NONNULL3
2788void
2789xpc_set_event_stream_handler(const char *stream,
2790	dispatch_queue_t _Nullable targetq, XPC_SWIFT_SENDABLE xpc_handler_t handler);
2791#endif // __BLOCKS__ 
2792
2793__END_DECLS
2794XPC_ASSUME_NONNULL_END
2795
2796#endif // __XPC_H__