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. May be NULL if length is zero. After calling this
1477 * method, the XPC object corresponding to the primitive value inserted may be
1478 * safely retrieved with {@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
1485void
1486xpc_array_set_data(xpc_object_t xarray, size_t index,
1487 const void *XPC_SIZEDBY(length) _Nullable 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. May be NULL if length is zero. After calling this method,
2235 * the XPC object corresponding to the primitive value inserted may be safely
2236 * retrieved with {@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
2243void
2244xpc_dictionary_set_data(xpc_object_t xdict, const char *key,
2245 const void *XPC_SIZEDBY(length) _Nullable 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, tvos, watchos)
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, tvos, watchos)
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, tvos, watchos)
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, tvos, watchos)
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__