├── .gitignore ├── assets └── IMG_1.png ├── packages └── net.limneos.oslog_0.0.4.1_iphoneos-arm.deb ├── headers ├── xpc │ ├── XPC.apinotes │ ├── module.modulemap │ ├── endpoint.h │ ├── debug.h │ ├── availability.h │ ├── base.h │ ├── activity.h │ ├── connection.h │ └── xpc.h └── launch.h ├── control ├── Makefile ├── ents.xml ├── README.md ├── LICENSE.TXT ├── ActivityStreamAPI.h └── main.mm /.gitignore: -------------------------------------------------------------------------------- 1 | .theos/ 2 | packages/ -------------------------------------------------------------------------------- /assets/IMG_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NoisyFlake/oslog/HEAD/assets/IMG_1.png -------------------------------------------------------------------------------- /packages/net.limneos.oslog_0.0.4.1_iphoneos-arm.deb: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NoisyFlake/oslog/HEAD/packages/net.limneos.oslog_0.0.4.1_iphoneos-arm.deb -------------------------------------------------------------------------------- /headers/xpc/XPC.apinotes: -------------------------------------------------------------------------------- 1 | Name: XPC 2 | Functions: 3 | # xpc_object 4 | - Name: xpc_retain 5 | Availability: nonswift 6 | - Name: xpc_release 7 | Availability: nonswift 8 | -------------------------------------------------------------------------------- /control: -------------------------------------------------------------------------------- 1 | Package: net.limneos.oslog 2 | Name: oslog 3 | Version: 0.0.4.3 4 | Architecture: iphoneos-arm 5 | Description: os_log implementation for iOS 6 | Maintainer: NoisyFlake 7 | Author: Elias Limneos 8 | Section: System 9 | Tag: role::hacker 10 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | include $(THEOS)/makefiles/common.mk 2 | 3 | ARCHS = arm64 arm64e 4 | 5 | TOOL_NAME = oslog 6 | oslog_FILES = main.mm 7 | oslog_CFLAGS = -fobjc-arc -Iheaders 8 | oslog_CODESIGN_FLAGS = -Sents.xml 9 | 10 | include $(THEOS_MAKE_PATH)/tool.mk 11 | -------------------------------------------------------------------------------- /headers/xpc/module.modulemap: -------------------------------------------------------------------------------- 1 | module XPC [system] [extern_c] { 2 | header "xpc.h" 3 | header "availability.h" 4 | header "base.h" 5 | header "activity.h" 6 | header "connection.h" 7 | header "debug.h" 8 | header "endpoint.h" 9 | export * 10 | } 11 | -------------------------------------------------------------------------------- /headers/xpc/endpoint.h: -------------------------------------------------------------------------------- 1 | #ifndef __XPC_ENDPOINT_H__ 2 | #define __XPC_ENDPOINT_H__ 3 | 4 | /*! 5 | * @function xpc_endpoint_create 6 | * Creates a new endpoint from a connection that is suitable for embedding into 7 | * messages. 8 | * 9 | * @param connection 10 | * Only connections obtained through calls to xpc_connection_create*() may be 11 | * given to this API. Passing any other type of connection is not supported and 12 | * will result in undefined behavior. 13 | * 14 | * @result 15 | * A new endpoint object. 16 | */ 17 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 18 | XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1 19 | xpc_endpoint_t _Nonnull 20 | xpc_endpoint_create(xpc_connection_t _Nonnull connection); 21 | 22 | #endif // __XPC_ENDPOINT_H__ 23 | -------------------------------------------------------------------------------- /headers/xpc/debug.h: -------------------------------------------------------------------------------- 1 | #ifndef __XPC_DEBUG_H__ 2 | #define __XPC_DEBUG_H__ 3 | 4 | /*! 5 | * @function xpc_debugger_api_misuse_info 6 | * Returns a pointer to a string describing the reason XPC aborted the calling 7 | * process. On OS X, this will be the same string present in the "Application 8 | * Specific Information" section of the crash report. 9 | * 10 | * @result 11 | * A pointer to the human-readable string describing the reason the caller was 12 | * aborted. If XPC was not responsible for the program's termination, NULL will 13 | * be returned. 14 | * 15 | * @discussion 16 | * This function is only callable from within a debugger. It is not meant to be 17 | * called by the program directly. 18 | */ 19 | XPC_DEBUGGER_EXCL 20 | const char * 21 | xpc_debugger_api_misuse_info(void); 22 | 23 | #endif // __XPC_DEBUG_H__ 24 | -------------------------------------------------------------------------------- /ents.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | com.apple.private.debug_port 6 | 7 | com.apple.private.iosurfaceinfo 8 | 9 | com.apple.private.logging.admin 10 | 11 | com.apple.private.logging.diagnostic 12 | 13 | com.apple.private.logging.stream 14 | 15 | com.apple.private.security.no-container 16 | 17 | com.apple.private.set-atm-diagnostic-flag 18 | 19 | com.apple.security.iokit-user-client-class 20 | 21 | IOSurfaceRootUserClient 22 | 23 | com.apple.system-task-ports 24 | 25 | platform-application 26 | 27 | task_for_pid-allow 28 | 29 | 30 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ## Note: 2 | this is a fork of the original project created by limneos, in this version I’ve adjusted and added the following features: 3 | 4 | 1. Color integration 5 | 2. Updated the entitlements to support a wider range API’s 6 | 3. Updated the project’s build hierarchy to be compatible with modern versions of Theos + very minor adjustments to the code to improve all around usability (date view, usage, etc.) 7 | 4. Removed `log_message->category` as it's uninitialized since iOS 14.5 and will segfault 8 | 5. Removed `log_message->format` as it's uninitialized since iOS 15 and will segfault 9 | 10 | ## Example output: 11 | ![](assets/IMG_1.png) 12 | 13 | # oslog 14 | os_log command line tool implementation for iOS 15 | 16 | A tool that shows os_log stream info/activity directly on iOS devices 17 | 18 | usage: 19 | 20 | oslog [—info|—debug] [ -p pid ] [—noLevelInfo] [—noSubsystemInfo] 21 | 22 | Examples: 23 | oslog 24 | oslog —debug 25 | oslog -p SpringBoard 26 | 27 | 28 | -------------------------------------------------------------------------------- /LICENSE.TXT: -------------------------------------------------------------------------------- 1 | University of Illinois/NCSA 2 | Open Source License 3 | 4 | Copyright (c) 2010 Apple Inc. 5 | All rights reserved. 6 | 7 | Developed by: 8 | 9 | LLDB Team 10 | 11 | http://lldb.llvm.org/ 12 | 13 | Permission is hereby granted, free of charge, to any person obtaining a copy of 14 | this software and associated documentation files (the "Software"), to deal with 15 | the Software without restriction, including without limitation the rights to 16 | use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies 17 | of the Software, and to permit persons to whom the Software is furnished to do 18 | so, subject to the following conditions: 19 | 20 | * Redistributions of source code must retain the above copyright notice, 21 | this list of conditions and the following disclaimers. 22 | 23 | * Redistributions in binary form must reproduce the above copyright notice, 24 | this list of conditions and the following disclaimers in the 25 | documentation and/or other materials provided with the distribution. 26 | 27 | * Neither the names of the LLDB Team, copyright holders, nor the names of 28 | its contributors may be used to endorse or promote products derived from 29 | this Software without specific prior written permission. 30 | 31 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 32 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS 33 | FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 34 | CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 35 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 36 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS WITH THE 37 | SOFTWARE. 38 | 39 | -------------------------------------------------------------------------------- /headers/xpc/availability.h: -------------------------------------------------------------------------------- 1 | #ifndef __XPC_AVAILABILITY_H__ 2 | #define __XPC_AVAILABILITY_H__ 3 | 4 | #include 5 | 6 | // Certain parts of the project use all the project's headers but have to build 7 | // against newer OSX SDKs than ebuild uses -- liblaunch_host being the example. 8 | // So we need to define these. 9 | #ifndef __MAC_10_13 10 | #define __MAC_10_13 101300 11 | #define __AVAILABILITY_INTERNAL__MAC_10_13 \ 12 | __attribute__((availability(macosx, introduced=10.13))) 13 | #endif // __MAC_10_13 14 | 15 | #ifndef __MAC_10_12 16 | #define __MAC_10_12 101200 17 | #define __AVAILABILITY_INTERNAL__MAC_10_12 \ 18 | __attribute__((availability(macosx, introduced=10.12))) 19 | #endif // __MAC_10_12 20 | 21 | #ifndef __MAC_10_11 22 | #define __MAC_10_11 101100 23 | #define __AVAILABILITY_INTERNAL__MAC_10_11 \ 24 | __attribute__((availability(macosx, introduced=10.11))) 25 | #endif // __MAC_10_11 26 | 27 | #ifndef __AVAILABILITY_INTERNAL__MAC_10_2_DEP__MAC_10_11 28 | #define __AVAILABILITY_INTERNAL__MAC_10_2_DEP__MAC_10_11 29 | #endif // __AVAILABILITY_INTERNAL__MAC_10_2_DEP__MAC_10_11 30 | 31 | #ifndef __AVAILABILITY_INTERNAL__MAC_10_3_DEP__MAC_10_11 32 | #define __AVAILABILITY_INTERNAL__MAC_10_3_DEP__MAC_10_11 33 | #endif // __AVAILABILITY_INTERNAL__MAC_10_3_DEP__MAC_10_11 34 | 35 | #ifndef __AVAILABILITY_INTERNAL__MAC_10_4_DEP__MAC_10_11 36 | #define __AVAILABILITY_INTERNAL__MAC_10_4_DEP__MAC_10_11 37 | #endif // __AVAILABILITY_INTERNAL__MAC_10_4_DEP__MAC_10_11 38 | 39 | #ifndef __AVAILABILITY_INTERNAL__MAC_10_5_DEP__MAC_10_11 40 | #define __AVAILABILITY_INTERNAL__MAC_10_5_DEP__MAC_10_11 41 | #endif // __AVAILABILITY_INTERNAL__MAC_10_5_DEP__MAC_10_11 42 | 43 | #ifndef __AVAILABILITY_INTERNAL__MAC_10_6_DEP__MAC_10_11 44 | #define __AVAILABILITY_INTERNAL__MAC_10_6_DEP__MAC_10_11 45 | #endif // __AVAILABILITY_INTERNAL__MAC_10_6_DEP__MAC_10_11 46 | 47 | #ifndef __AVAILABILITY_INTERNAL__MAC_10_7_DEP__MAC_10_11 48 | #define __AVAILABILITY_INTERNAL__MAC_10_7_DEP__MAC_10_11 49 | #endif // __AVAILABILITY_INTERNAL__MAC_10_7_DEP__MAC_10_11 50 | 51 | #ifndef __AVAILABILITY_INTERNAL__MAC_10_8_DEP__MAC_10_11 52 | #define __AVAILABILITY_INTERNAL__MAC_10_8_DEP__MAC_10_11 53 | #endif // __AVAILABILITY_INTERNAL__MAC_10_8_DEP__MAC_10_11 54 | 55 | #ifndef __AVAILABILITY_INTERNAL__MAC_10_9_DEP__MAC_10_11 56 | #define __AVAILABILITY_INTERNAL__MAC_10_9_DEP__MAC_10_11 57 | #endif // __AVAILABILITY_INTERNAL__MAC_10_9_DEP__MAC_10_11 58 | 59 | #ifndef __AVAILABILITY_INTERNAL__MAC_10_10_DEP__MAC_10_11 60 | #define __AVAILABILITY_INTERNAL__MAC_10_10_DEP__MAC_10_11 61 | #endif // __AVAILABILITY_INTERNAL__MAC_10_10_DEP__MAC_10_11 62 | 63 | #ifndef __AVAILABILITY_INTERNAL__MAC_10_11_DEP__MAC_10_11 64 | #define __AVAILABILITY_INTERNAL__MAC_10_11_DEP__MAC_10_11 65 | #endif // __AVAILABILITY_INTERNAL__MAC_10_11_DEP__MAC_10_11 66 | 67 | #ifndef __AVAILABILITY_INTERNAL__MAC_10_6_DEP__MAC_10_13 68 | #define __AVAILABILITY_INTERNAL__MAC_10_6_DEP__MAC_10_13 69 | #endif // __AVAILABILITY_INTERNAL__MAC_10_6_DEP__MAC_10_13 70 | 71 | #if __has_include() 72 | #include 73 | #else // __has_include() 74 | #ifndef IPHONE_SIMULATOR_HOST_MIN_VERSION_REQUIRED 75 | #define IPHONE_SIMULATOR_HOST_MIN_VERSION_REQUIRED 999999 76 | #endif // IPHONE_SIMULATOR_HOST_MIN_VERSION_REQUIRED 77 | #endif // __has_include() 78 | 79 | #ifndef __WATCHOS_UNAVAILABLE 80 | #define __WATCHOS_UNAVAILABLE 81 | #endif 82 | 83 | #ifndef __TVOS_UNAVAILABLE 84 | #define __TVOS_UNAVAILABLE 85 | #endif 86 | 87 | // simulator host-side bits build against SDKs not having __*_AVAILABLE() yet 88 | #ifndef __OSX_AVAILABLE 89 | #define __OSX_AVAILABLE(...) 90 | #endif 91 | 92 | #ifndef __IOS_AVAILABLE 93 | #define __IOS_AVAILABLE(...) 94 | #endif 95 | 96 | #ifndef __TVOS_AVAILABLE 97 | #define __TVOS_AVAILABLE(...) 98 | #endif 99 | 100 | #ifndef __WATCHOS_AVAILABLE 101 | #define __WATCHOS_AVAILABLE(...) 102 | #endif 103 | 104 | #ifndef __API_AVAILABLE 105 | #define __API_AVAILABLE(...) 106 | #endif 107 | 108 | #endif // __XPC_AVAILABILITY_H__ 109 | -------------------------------------------------------------------------------- /ActivityStreamAPI.h: -------------------------------------------------------------------------------- 1 | //===-- ActivityStreamAPI.h -------------------------------------*- C++ -*-===// 2 | // 3 | // The LLVM Compiler Infrastructure 4 | // 5 | // This file is distributed under the University of Illinois Open Source 6 | // License. See LICENSE.TXT for details. 7 | // 8 | //===----------------------------------------------------------------------===// 9 | 10 | #ifndef ActivityStreamSPI_h 11 | #define ActivityStreamSPI_h 12 | 13 | #include 14 | #include 15 | 16 | #define OS_ACTIVITY_MAX_CALLSTACK 32 17 | 18 | // Enums 19 | 20 | enum { 21 | OS_ACTIVITY_STREAM_PROCESS_ONLY = 0x00000001, 22 | OS_ACTIVITY_STREAM_SKIP_DECODE = 0x00000002, 23 | OS_ACTIVITY_STREAM_PAYLOAD = 0x00000004, 24 | OS_ACTIVITY_STREAM_HISTORICAL = 0x00000008, 25 | OS_ACTIVITY_STREAM_CALLSTACK = 0x00000010, 26 | OS_ACTIVITY_STREAM_DEBUG = 0x00000020, 27 | OS_ACTIVITY_STREAM_BUFFERED = 0x00000040, 28 | OS_ACTIVITY_STREAM_NO_SENSITIVE = 0x00000080, 29 | OS_ACTIVITY_STREAM_INFO = 0x00000100, 30 | OS_ACTIVITY_STREAM_PROMISCUOUS = 0x00000200, 31 | OS_ACTIVITY_STREAM_PRECISE_TIMESTAMPS = 0x00000200 32 | }; 33 | typedef uint32_t os_activity_stream_flag_t; 34 | 35 | enum { 36 | OS_ACTIVITY_STREAM_TYPE_ACTIVITY_CREATE = 0x0201, 37 | OS_ACTIVITY_STREAM_TYPE_ACTIVITY_TRANSITION = 0x0202, 38 | OS_ACTIVITY_STREAM_TYPE_ACTIVITY_USERACTION = 0x0203, 39 | 40 | OS_ACTIVITY_STREAM_TYPE_TRACE_MESSAGE = 0x0300, 41 | 42 | OS_ACTIVITY_STREAM_TYPE_LOG_MESSAGE = 0x0400, 43 | OS_ACTIVITY_STREAM_TYPE_LEGACY_LOG_MESSAGE = 0x0480, 44 | 45 | OS_ACTIVITY_STREAM_TYPE_SIGNPOST_BEGIN = 0x0601, 46 | OS_ACTIVITY_STREAM_TYPE_SIGNPOST_END = 0x0602, 47 | OS_ACTIVITY_STREAM_TYPE_SIGNPOST_EVENT = 0x0603, 48 | 49 | OS_ACTIVITY_STREAM_TYPE_STATEDUMP_EVENT = 0x0A00, 50 | }; 51 | typedef uint32_t os_activity_stream_type_t; 52 | 53 | enum { 54 | OS_ACTIVITY_STREAM_EVENT_STARTED = 1, 55 | OS_ACTIVITY_STREAM_EVENT_STOPPED = 2, 56 | OS_ACTIVITY_STREAM_EVENT_FAILED = 3, 57 | OS_ACTIVITY_STREAM_EVENT_CHUNK_STARTED = 4, 58 | OS_ACTIVITY_STREAM_EVENT_CHUNK_FINISHED = 5, 59 | }; 60 | typedef uint32_t os_activity_stream_event_t; 61 | 62 | // Types 63 | 64 | typedef uint64_t os_activity_id_t; 65 | typedef struct os_activity_stream_s *os_activity_stream_t; 66 | typedef struct os_activity_stream_entry_s *os_activity_stream_entry_t; 67 | 68 | #define OS_ACTIVITY_STREAM_COMMON() \ 69 | uint64_t trace_id; \ 70 | uint64_t timestamp; \ 71 | uint64_t thread; \ 72 | const uint8_t *image_uuid; \ 73 | const char *image_path; \ 74 | struct timeval tv_gmt; \ 75 | struct timezone tz; \ 76 | uint32_t offset 77 | 78 | typedef struct os_activity_stream_common_s { 79 | OS_ACTIVITY_STREAM_COMMON(); 80 | } * os_activity_stream_common_t; 81 | 82 | struct os_activity_create_s { 83 | OS_ACTIVITY_STREAM_COMMON(); 84 | const char *name; 85 | os_activity_id_t creator_aid; 86 | uint64_t unique_pid; 87 | }; 88 | 89 | struct os_activity_transition_s { 90 | OS_ACTIVITY_STREAM_COMMON(); 91 | os_activity_id_t transition_id; 92 | }; 93 | 94 | typedef struct os_log_message_s { 95 | OS_ACTIVITY_STREAM_COMMON(); 96 | const char *format; 97 | const uint8_t *buffer; 98 | size_t buffer_sz; 99 | const uint8_t *privdata; 100 | size_t privdata_sz; 101 | const char *subsystem; 102 | const char *category; 103 | uint32_t oversize_id; 104 | uint8_t ttl; 105 | bool persisted; 106 | } * os_log_message_t; 107 | 108 | typedef struct os_trace_message_v2_s { 109 | OS_ACTIVITY_STREAM_COMMON(); 110 | const char *format; 111 | const void *buffer; 112 | size_t bufferLen; 113 | xpc_object_t __unsafe_unretained payload; 114 | } * os_trace_message_v2_t; 115 | 116 | typedef struct os_activity_useraction_s { 117 | OS_ACTIVITY_STREAM_COMMON(); 118 | const char *action; 119 | bool persisted; 120 | } * os_activity_useraction_t; 121 | 122 | typedef struct os_signpost_s { 123 | OS_ACTIVITY_STREAM_COMMON(); 124 | const char *format; 125 | const uint8_t *buffer; 126 | size_t buffer_sz; 127 | const uint8_t *privdata; 128 | size_t privdata_sz; 129 | const char *subsystem; 130 | const char *category; 131 | uint64_t duration_nsec; 132 | uint32_t callstack_depth; 133 | uint64_t callstack[OS_ACTIVITY_MAX_CALLSTACK]; 134 | } * os_signpost_t; 135 | 136 | typedef struct os_activity_statedump_s { 137 | OS_ACTIVITY_STREAM_COMMON(); 138 | char *message; 139 | size_t message_size; 140 | char image_path_buffer[PATH_MAX]; 141 | } * os_activity_statedump_t; 142 | 143 | struct os_activity_stream_entry_s { 144 | os_activity_stream_type_t type; 145 | 146 | // information about the process streaming the data 147 | pid_t pid; 148 | uint64_t proc_id; 149 | const uint8_t *proc_imageuuid; 150 | const char *proc_imagepath; 151 | 152 | // the activity associated with this streamed event 153 | os_activity_id_t activity_id; 154 | os_activity_id_t parent_id; 155 | 156 | union { 157 | struct os_activity_stream_common_s common; 158 | struct os_activity_create_s activity_create; 159 | struct os_activity_transition_s activity_transition; 160 | struct os_log_message_s log_message; 161 | struct os_trace_message_v2_s trace_message; 162 | struct os_activity_useraction_s useraction; 163 | struct os_signpost_s signpost; 164 | struct os_activity_statedump_s statedump; 165 | }; 166 | 167 | }; 168 | 169 | // Blocks 170 | 171 | typedef bool (^os_activity_stream_block_t)(os_activity_stream_entry_t entry, 172 | int error); 173 | 174 | typedef void (^os_activity_stream_event_block_t)( 175 | os_activity_stream_t stream, os_activity_stream_event_t event); 176 | 177 | // SPI entry point prototypes 178 | 179 | typedef os_activity_stream_t (*os_activity_stream_for_pid_t)( 180 | pid_t pid, os_activity_stream_flag_t flags, 181 | os_activity_stream_block_t stream_block); 182 | 183 | typedef void (*os_activity_stream_resume_t)(os_activity_stream_t stream); 184 | 185 | typedef void (*os_activity_stream_cancel_t)(os_activity_stream_t stream); 186 | 187 | typedef char *(*os_log_copy_formatted_message_t)(os_log_message_t log_message); 188 | 189 | typedef void (*os_activity_stream_set_event_handler_t)( 190 | os_activity_stream_t stream, os_activity_stream_event_block_t block); 191 | 192 | #endif /* ActivityStreamSPI_h */ -------------------------------------------------------------------------------- /headers/xpc/base.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2009-2011 Apple Inc. All rights reserved. 2 | 3 | #ifndef __XPC_BASE_H__ 4 | #define __XPC_BASE_H__ 5 | 6 | #include 7 | 8 | __BEGIN_DECLS 9 | 10 | #if !defined(__has_include) 11 | #define __has_include(x) 0 12 | #endif // !defined(__has_include) 13 | 14 | #if !defined(__has_attribute) 15 | #define __has_attribute(x) 0 16 | #endif // !defined(__has_attribute) 17 | 18 | #if !defined(__has_feature) 19 | #define __has_feature(x) 0 20 | #endif // !defined(__has_feature) 21 | 22 | #if !defined(__has_extension) 23 | #define __has_extension(x) 0 24 | #endif // !defined(__has_extension) 25 | 26 | #if __has_include() 27 | #include 28 | #else // __has_include() 29 | #include 30 | #endif // __has_include() 31 | 32 | #if XPC_SERVICE_MAIN_IN_LIBXPC 33 | #define XPC_HOSTING_OLD_MAIN 1 34 | #else // XPC_SERVICE_MAIN_IN_LIBXPC 35 | #define XPC_HOSTING_OLD_MAIN 0 36 | #endif // XPC_SERVICE_MAIN_IN_LIBXPC 37 | 38 | #ifndef __XPC_INDIRECT__ 39 | #error "Please #include instead of this file directly." 40 | #endif // __XPC_INDIRECT__ 41 | 42 | #pragma mark Attribute Shims 43 | #ifdef __GNUC__ 44 | #define XPC_CONSTRUCTOR __attribute__((constructor)) 45 | #define XPC_NORETURN __attribute__((__noreturn__)) 46 | #define XPC_NOTHROW __attribute__((__nothrow__)) 47 | #define XPC_NONNULL1 __attribute__((__nonnull__(1))) 48 | #define XPC_NONNULL2 __attribute__((__nonnull__(2))) 49 | #define XPC_NONNULL3 __attribute__((__nonnull__(3))) 50 | #define XPC_NONNULL4 __attribute__((__nonnull__(4))) 51 | #define XPC_NONNULL5 __attribute__((__nonnull__(5))) 52 | #define XPC_NONNULL6 __attribute__((__nonnull__(6))) 53 | #define XPC_NONNULL7 __attribute__((__nonnull__(7))) 54 | #define XPC_NONNULL8 __attribute__((__nonnull__(8))) 55 | #define XPC_NONNULL9 __attribute__((__nonnull__(9))) 56 | #define XPC_NONNULL10 __attribute__((__nonnull__(10))) 57 | #define XPC_NONNULL11 __attribute__((__nonnull__(11))) 58 | #define XPC_NONNULL_ALL __attribute__((__nonnull__)) 59 | #define XPC_SENTINEL __attribute__((__sentinel__)) 60 | #define XPC_PURE __attribute__((__pure__)) 61 | #define XPC_WARN_RESULT __attribute__((__warn_unused_result__)) 62 | #define XPC_MALLOC __attribute__((__malloc__)) 63 | #define XPC_UNUSED __attribute__((__unused__)) 64 | #define XPC_USED __attribute__((__used__)) 65 | #define XPC_PACKED __attribute__((__packed__)) 66 | #define XPC_PRINTF(m, n) __attribute__((format(printf, m, n))) 67 | #define XPC_INLINE static __inline__ __attribute__((__always_inline__)) 68 | #define XPC_NOINLINE __attribute__((noinline)) 69 | #define XPC_NOIMPL __attribute__((unavailable)) 70 | 71 | #if __has_attribute(noescape) 72 | #define XPC_NOESCAPE __attribute__((__noescape__)) 73 | #else 74 | #define XPC_NOESCAPE 75 | #endif 76 | 77 | #if __has_extension(attribute_unavailable_with_message) 78 | #define XPC_UNAVAILABLE(m) __attribute__((unavailable(m))) 79 | #else // __has_extension(attribute_unavailable_with_message) 80 | #define XPC_UNAVAILABLE(m) XPC_NOIMPL 81 | #endif // __has_extension(attribute_unavailable_with_message) 82 | 83 | #define XPC_EXPORT extern __attribute__((visibility("default"))) 84 | #define XPC_NOEXPORT __attribute__((visibility("hidden"))) 85 | #define XPC_WEAKIMPORT extern __attribute__((weak_import)) 86 | #define XPC_DEBUGGER_EXCL XPC_NOEXPORT XPC_USED 87 | #define XPC_TRANSPARENT_UNION __attribute__((transparent_union)) 88 | #if __clang__ 89 | #define XPC_DEPRECATED(m) __attribute__((deprecated(m))) 90 | #else // __clang__ 91 | #define XPC_DEPRECATED(m) __attribute__((deprecated)) 92 | #endif // __clang 93 | 94 | #if __XPC_TEST__ 95 | #define XPC_TESTSTATIC 96 | #else // __XPC_TEST__ 97 | #define XPC_TESTSTATIC static 98 | #endif // __XPC_TEST__ 99 | 100 | #if __has_feature(objc_arc) 101 | #define XPC_GIVES_REFERENCE __strong 102 | #define XPC_UNRETAINED __unsafe_unretained 103 | #define XPC_BRIDGE(xo) ((__bridge void *)(xo)) 104 | #define XPC_BRIDGEREF_BEGIN(xo) ((__bridge_retained void *)(xo)) 105 | #define XPC_BRIDGEREF_BEGIN_WITH_REF(xo) ((__bridge void *)(xo)) 106 | #define XPC_BRIDGEREF_MIDDLE(xo) ((__bridge id)(xo)) 107 | #define XPC_BRIDGEREF_END(xo) ((__bridge_transfer id)(xo)) 108 | #else // __has_feature(objc_arc) 109 | #define XPC_GIVES_REFERENCE 110 | #define XPC_UNRETAINED 111 | #define XPC_BRIDGE(xo) (xo) 112 | #define XPC_BRIDGEREF_BEGIN(xo) (xo) 113 | #define XPC_BRIDGEREF_BEGIN_WITH_REF(xo) (xo) 114 | #define XPC_BRIDGEREF_MIDDLE(xo) (xo) 115 | #define XPC_BRIDGEREF_END(xo) (xo) 116 | #endif // __has_feature(objc_arc) 117 | 118 | #define _xpc_unreachable() __builtin_unreachable() 119 | #else // __GNUC__ 120 | /*! @parseOnly */ 121 | #define XPC_CONSTRUCTOR 122 | /*! @parseOnly */ 123 | #define XPC_NORETURN 124 | /*! @parseOnly */ 125 | #define XPC_NOTHROW 126 | /*! @parseOnly */ 127 | #define XPC_NONNULL1 128 | /*! @parseOnly */ 129 | #define XPC_NONNULL2 130 | /*! @parseOnly */ 131 | #define XPC_NONNULL3 132 | /*! @parseOnly */ 133 | #define XPC_NONNULL4 134 | /*! @parseOnly */ 135 | #define XPC_NONNULL5 136 | /*! @parseOnly */ 137 | #define XPC_NONNULL6 138 | /*! @parseOnly */ 139 | #define XPC_NONNULL7 140 | /*! @parseOnly */ 141 | #define XPC_NONNULL8 142 | /*! @parseOnly */ 143 | #define XPC_NONNULL9 144 | /*! @parseOnly */ 145 | #define XPC_NONNULL10 146 | /*! @parseOnly */ 147 | #define XPC_NONNULL11 148 | /*! @parseOnly */ 149 | #define XPC_NONNULL(n) 150 | /*! @parseOnly */ 151 | #define XPC_NONNULL_ALL 152 | /*! @parseOnly */ 153 | #define XPC_SENTINEL 154 | /*! @parseOnly */ 155 | #define XPC_PURE 156 | /*! @parseOnly */ 157 | #define XPC_WARN_RESULT 158 | /*! @parseOnly */ 159 | #define XPC_MALLOC 160 | /*! @parseOnly */ 161 | #define XPC_UNUSED 162 | /*! @parseOnly */ 163 | #define XPC_PACKED 164 | /*! @parseOnly */ 165 | #define XPC_PRINTF(m, n) 166 | /*! @parseOnly */ 167 | #define XPC_INLINE static inline 168 | /*! @parseOnly */ 169 | #define XPC_NOINLINE 170 | /*! @parseOnly */ 171 | #define XPC_NOIMPL 172 | /*! @parseOnly */ 173 | #define XPC_EXPORT extern 174 | /*! @parseOnly */ 175 | #define XPC_WEAKIMPORT 176 | /*! @parseOnly */ 177 | #define XPC_DEPRECATED 178 | /*! @parseOnly */ 179 | #define XPC_UNAVAILABLE(m) 180 | /*! @parseOnly */ 181 | #define XPC_NOESCAPE 182 | #endif // __GNUC__ 183 | 184 | #if __has_feature(assume_nonnull) 185 | #define XPC_ASSUME_NONNULL_BEGIN _Pragma("clang assume_nonnull begin") 186 | #define XPC_ASSUME_NONNULL_END _Pragma("clang assume_nonnull end") 187 | #else 188 | #define XPC_ASSUME_NONNULL_BEGIN 189 | #define XPC_ASSUME_NONNULL_END 190 | #endif 191 | 192 | #if __has_feature(nullability_on_arrays) 193 | #define XPC_NONNULL_ARRAY _Nonnull 194 | #else 195 | #define XPC_NONNULL_ARRAY 196 | #endif 197 | 198 | __END_DECLS 199 | 200 | #endif // __XPC_BASE_H__ 201 | -------------------------------------------------------------------------------- /main.mm: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | #include 4 | #include 5 | #include 6 | #include "ActivityStreamAPI.h" 7 | #import 8 | 9 | 10 | static BOOL canPrint=NO; 11 | static int filterPid=-1; 12 | static BOOL levelInfo=YES; 13 | static int (*m_proc_name)(int pid,char *buffer, unsigned int size); 14 | static os_activity_stream_for_pid_t s_os_activity_stream_for_pid; 15 | static os_activity_stream_resume_t s_os_activity_stream_resume; 16 | static os_activity_stream_cancel_t s_os_activity_stream_cancel; 17 | static os_activity_stream_set_event_handler_t s_os_activity_stream_set_event_handler; 18 | static os_log_copy_formatted_message_t s_os_log_copy_formatted_message; 19 | static uint8_t (*m_os_log_get_type)(void *log); 20 | static int (*m_proc_listpids)(uint32_t type, uint32_t typeinfo, void *buffer, int buffersize); 21 | 22 | 23 | void printUsage(){ 24 | printf("\033[1;36mUsage: \033[1;37moslog [--info|--debug] [-p ] [--noLevelInfo]\x1b[0m\n"); 25 | } 26 | 27 | 28 | struct ActivityInfo { 29 | ActivityInfo(const char *name, os_activity_id_t activity_id, 30 | os_activity_id_t parent_activity_id) 31 | : m_name(name), m_id(activity_id), m_parent_id(parent_activity_id) {} 32 | 33 | const char* m_name; 34 | const os_activity_id_t m_id; 35 | const os_activity_id_t m_parent_id; 36 | }; 37 | 38 | 39 | bool LookupSPICalls() { 40 | 41 | static bool s_has_spi=NO; 42 | 43 | dlopen ("/System/Library/PrivateFrameworks/LoggingSupport.framework/LoggingSupport", RTLD_NOW); 44 | s_os_activity_stream_for_pid = (os_activity_stream_for_pid_t)dlsym(RTLD_DEFAULT, "os_activity_stream_for_pid"); 45 | s_os_activity_stream_resume = (os_activity_stream_resume_t)dlsym(RTLD_DEFAULT, "os_activity_stream_resume"); 46 | s_os_activity_stream_cancel = (os_activity_stream_cancel_t)dlsym(RTLD_DEFAULT, "os_activity_stream_cancel"); 47 | s_os_log_copy_formatted_message = (os_log_copy_formatted_message_t)dlsym(RTLD_DEFAULT, "os_log_copy_formatted_message"); 48 | s_os_activity_stream_set_event_handler = (os_activity_stream_set_event_handler_t)dlsym(RTLD_DEFAULT, "os_activity_stream_set_event_handler"); 49 | m_proc_name=(int(*)(int,char *, unsigned int))dlsym(RTLD_DEFAULT, "proc_name"); 50 | m_proc_listpids=(int(*)(uint32_t,uint32_t,void*,int))dlsym(RTLD_DEFAULT,"proc_listpids"); 51 | m_os_log_get_type=(uint8_t(*)(void *))dlsym(RTLD_DEFAULT, "os_log_get_type"); 52 | 53 | s_has_spi = (s_os_activity_stream_for_pid != NULL) && 54 | (s_os_activity_stream_resume != NULL) && 55 | (s_os_activity_stream_cancel != NULL) && 56 | (s_os_log_copy_formatted_message != NULL) && 57 | (s_os_activity_stream_set_event_handler != NULL) && 58 | (m_os_log_get_type != NULL) && 59 | (m_proc_name != NULL); 60 | 61 | return s_has_spi; 62 | 63 | } 64 | 65 | 66 | 67 | BOOL handleStreamEntry(os_activity_stream_entry_t entry, int error){ 68 | 69 | if ((filterPid!=-1 && entry->pid!=filterPid) || !canPrint){ 70 | 71 | return YES; 72 | } 73 | 74 | if ((error == 0) && (entry != NULL) ) { 75 | 76 | if (entry->type==OS_ACTIVITY_STREAM_TYPE_ACTIVITY_CREATE){ 77 | 78 | } 79 | 80 | 81 | if (entry->type==OS_ACTIVITY_STREAM_TYPE_LOG_MESSAGE) { 82 | 83 | os_log_message_t log_message = &entry->log_message; 84 | 85 | 86 | // Get date/time 87 | char timebuffer[30]; 88 | struct timeval tv; 89 | time_t curtime; 90 | gettimeofday(&tv, NULL); 91 | curtime=tv.tv_sec; 92 | strftime(timebuffer,30,"%T",localtime(&curtime)); 93 | 94 | // Get hostname 95 | char hostname[64]; 96 | gethostname(hostname,sizeof(hostname)); 97 | 98 | // Get process name 99 | char procname[32]; 100 | m_proc_name(entry->pid,procname,sizeof(procname)); 101 | 102 | // get log message text 103 | char *messageText=s_os_log_copy_formatted_message(log_message); 104 | 105 | uint8_t logLevel=m_os_log_get_type(log_message); 106 | const char * level=NULL; 107 | switch (logLevel){ 108 | case 0x00: 109 | level=" "; 110 | break; 111 | case 0x01: 112 | level=" "; 113 | break; 114 | case 0x2: 115 | level=" "; 116 | break; 117 | case 0x10: 118 | level="\033[1;33m\033[0m "; 119 | break; 120 | case 0x11: 121 | break; 122 | level="\033[1;31m\033[0m "; 123 | default: 124 | level=""; 125 | break; 126 | } 127 | 128 | 129 | if (messageText){ 130 | printf("%s%s ""\033[1;36m""%s""\033[1;37m""[%d]\033[0m: %s\n", levelInfo ? level : "", timebuffer, (char *)procname, entry->pid, messageText); 131 | } 132 | 133 | } 134 | } 135 | return YES; 136 | } 137 | 138 | 139 | static void NoteExitKQueueCallback(CFFileDescriptorRef f,CFOptionFlags callBackTypes, void *info) 140 | { 141 | struct kevent event; 142 | (void) kevent( CFFileDescriptorGetNativeDescriptor(f), NULL, 0, &event, 1, NULL); 143 | NSLog(@" === oslog: monitored pid [%d] terminated", (int) (pid_t) event.ident); 144 | exit(0); 145 | } 146 | 147 | int main(int argc, char **argv, char **envp) { 148 | 149 | 150 | if (!LookupSPICalls()){ 151 | printf("\tError: Could not find oslog required functions. iOS >=10 is required.\n"); 152 | return -1; 153 | } 154 | 155 | os_activity_stream_block_t block =^bool(os_activity_stream_entry_t entry, int error) { 156 | return handleStreamEntry(entry,error); 157 | }; 158 | 159 | os_activity_stream_event_block_t stream_event_block = ^void(os_activity_stream_t stream, os_activity_stream_event_t event) { 160 | 161 | switch (event) { 162 | 163 | case OS_ACTIVITY_STREAM_EVENT_STARTED: 164 | char timebuffer[30]; 165 | struct timeval tv; 166 | time_t curtime; 167 | gettimeofday(&tv, NULL); 168 | curtime=tv.tv_sec; 169 | strftime(timebuffer,30,"%b %e %T",localtime(&curtime)); 170 | char hostname[64]; 171 | gethostname(hostname,sizeof(hostname)); 172 | printf("%s %s: ======\n",timebuffer,hostname); 173 | canPrint=YES; 174 | break; 175 | case OS_ACTIVITY_STREAM_EVENT_STOPPED: 176 | printf("======\n"); 177 | break; 178 | case OS_ACTIVITY_STREAM_EVENT_FAILED: 179 | printf("======\n"); 180 | break; 181 | case OS_ACTIVITY_STREAM_EVENT_CHUNK_STARTED: 182 | break; 183 | case OS_ACTIVITY_STREAM_EVENT_CHUNK_FINISHED: 184 | printf("======\n"); 185 | break; 186 | 187 | } 188 | 189 | }; 190 | 191 | 192 | NSArray *arguments=[[NSProcessInfo processInfo] arguments]; 193 | NSMutableArray *argumentsToUse=[arguments mutableCopy]; 194 | [argumentsToUse removeObjectAtIndex:0]; 195 | 196 | int argCount=[arguments count]; 197 | 198 | if (argCount<1){ 199 | printUsage(); 200 | return 0; 201 | } 202 | 203 | uint32_t activity_stream_flags = 0; 204 | 205 | for (NSString *arg in arguments){ 206 | 207 | if ([arg isEqual:@"--info"]){ 208 | activity_stream_flags |= OS_ACTIVITY_STREAM_INFO; 209 | [argumentsToUse removeObject:arg]; 210 | } 211 | 212 | if ([arg isEqual:@"--debug"]){ 213 | activity_stream_flags |= OS_ACTIVITY_STREAM_DEBUG; 214 | [argumentsToUse removeObject:arg]; 215 | } 216 | 217 | if ([arg isEqual:@"--noLevelInfo"]){ 218 | levelInfo=NO; 219 | [argumentsToUse removeObject:arg]; 220 | } 221 | 222 | 223 | if ([arg isEqual:@"-p"]){ 224 | 225 | int argIndex=[arguments indexOfObject:arg]; 226 | if (argIndex==argCount-1){ 227 | printUsage(); 228 | return 0; 229 | } 230 | NSNumber *nspid=[arguments objectAtIndex:argIndex+1]; 231 | int pid = [nspid intValue]; 232 | BOOL isNameInsteadOfPid=NO; 233 | if (pid==0 && ![[arguments objectAtIndex:argIndex+1] isEqual:@"0"]){ 234 | isNameInsteadOfPid=YES; 235 | } 236 | 237 | int bufsize = m_proc_listpids(1, 0, NULL, 0); 238 | pid_t pids[2 * bufsize / sizeof(pid_t)]; 239 | bufsize = m_proc_listpids(1, 0, pids, sizeof(pids)); 240 | size_t num_pids = bufsize / sizeof(pid_t); 241 | BOOL foundPid=NO; 242 | for (int i=0; i0){ 270 | printUsage(); 271 | return 0; 272 | } 273 | 274 | os_activity_stream_t activity_stream = (*s_os_activity_stream_for_pid)(filterPid, activity_stream_flags , block); 275 | 276 | if (filterPid!=-1){ 277 | 278 | int kq; 279 | struct kevent changes; 280 | CFFileDescriptorContext context = { 0, NULL, NULL, NULL, NULL }; 281 | CFRunLoopSourceRef rls; 282 | 283 | kq = kqueue(); 284 | 285 | EV_SET(&changes, filterPid, EVFILT_PROC, EV_ADD | EV_RECEIPT, NOTE_EXIT, 0, NULL); 286 | (void) kevent(kq, &changes, 1, &changes, 1, NULL); 287 | 288 | CFFileDescriptorRef noteExitKQueueRef = CFFileDescriptorCreate(NULL, kq, true, NoteExitKQueueCallback, &context); 289 | rls = CFFileDescriptorCreateRunLoopSource(NULL, noteExitKQueueRef, 0); 290 | CFRunLoopAddSource(CFRunLoopGetCurrent(), rls, kCFRunLoopDefaultMode); 291 | CFRelease(rls); 292 | 293 | CFFileDescriptorEnableCallBacks(noteExitKQueueRef, kCFFileDescriptorReadCallBack); 294 | 295 | } 296 | 297 | (*s_os_activity_stream_set_event_handler)(activity_stream, stream_event_block); 298 | 299 | (*s_os_activity_stream_resume)(activity_stream); 300 | 301 | [[NSRunLoop currentRunLoop] run]; 302 | 303 | 304 | (*s_os_activity_stream_cancel)(activity_stream); 305 | 306 | return 0; 307 | } 308 | -------------------------------------------------------------------------------- /headers/launch.h: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2005 Apple Computer, Inc. All rights reserved. 3 | * 4 | * @APPLE_APACHE_LICENSE_HEADER_START@ 5 | * 6 | * Licensed under the Apache License, Version 2.0 (the "License"); 7 | * you may not use this file except in compliance with the License. 8 | * You may obtain a copy of the License at 9 | * 10 | * http://www.apache.org/licenses/LICENSE-2.0 11 | * 12 | * Unless required by applicable law or agreed to in writing, software 13 | * distributed under the License is distributed on an "AS IS" BASIS, 14 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 | * See the License for the specific language governing permissions and 16 | * limitations under the License. 17 | * 18 | * @APPLE_APACHE_LICENSE_HEADER_END@ 19 | */ 20 | 21 | #ifndef __LAUNCH_H__ 22 | #define __LAUNCH_H__ 23 | 24 | #include 25 | #include 26 | #include 27 | #include 28 | 29 | #pragma GCC visibility push(default) 30 | 31 | __BEGIN_DECLS 32 | 33 | #ifdef __GNUC__ 34 | #define __ld_normal __attribute__((__nothrow__)) 35 | #define __ld_setter __attribute__((__nothrow__, __nonnull__)) 36 | #define __ld_getter __attribute__((__nothrow__, __nonnull__, __pure__, __warn_unused_result__)) 37 | #define __ld_iterator(x, y) __attribute__((__nonnull__(x, y))) 38 | #define __ld_allocator __attribute__((__nothrow__, __malloc__, __nonnull__, __warn_unused_result__)) 39 | #else 40 | #define __ld_normal 41 | #define __ld_setter 42 | #define __ld_getter 43 | #define __ld_iterator(x, y) 44 | #define __ld_allocator 45 | #endif 46 | 47 | #define LAUNCH_KEY_SUBMITJOB "SubmitJob" 48 | #define LAUNCH_KEY_REMOVEJOB "RemoveJob" 49 | #define LAUNCH_KEY_STARTJOB "StartJob" 50 | #define LAUNCH_KEY_STOPJOB "StopJob" 51 | #define LAUNCH_KEY_GETJOB "GetJob" 52 | #define LAUNCH_KEY_GETJOBS "GetJobs" 53 | #define LAUNCH_KEY_CHECKIN "CheckIn" 54 | 55 | #define LAUNCH_JOBKEY_LABEL "Label" 56 | #define LAUNCH_JOBKEY_DISABLED "Disabled" 57 | #define LAUNCH_JOBKEY_USERNAME "UserName" 58 | #define LAUNCH_JOBKEY_GROUPNAME "GroupName" 59 | #define LAUNCH_JOBKEY_TIMEOUT "TimeOut" 60 | #define LAUNCH_JOBKEY_EXITTIMEOUT "ExitTimeOut" 61 | #define LAUNCH_JOBKEY_INITGROUPS "InitGroups" 62 | #define LAUNCH_JOBKEY_SOCKETS "Sockets" 63 | #define LAUNCH_JOBKEY_MACHSERVICES "MachServices" 64 | #define LAUNCH_JOBKEY_MACHSERVICELOOKUPPOLICIES "MachServiceLookupPolicies" 65 | #define LAUNCH_JOBKEY_INETDCOMPATIBILITY "inetdCompatibility" 66 | #define LAUNCH_JOBKEY_ENABLEGLOBBING "EnableGlobbing" 67 | #define LAUNCH_JOBKEY_PROGRAMARGUMENTS "ProgramArguments" 68 | #define LAUNCH_JOBKEY_PROGRAM "Program" 69 | #define LAUNCH_JOBKEY_ONDEMAND "OnDemand" 70 | #define LAUNCH_JOBKEY_KEEPALIVE "KeepAlive" 71 | #define LAUNCH_JOBKEY_LIMITLOADTOHOSTS "LimitLoadToHosts" 72 | #define LAUNCH_JOBKEY_LIMITLOADFROMHOSTS "LimitLoadFromHosts" 73 | #define LAUNCH_JOBKEY_LIMITLOADTOSESSIONTYPE "LimitLoadToSessionType" 74 | #define LAUNCH_JOBKEY_LIMITLOADTOHARDWARE "LimitLoadToHardware" 75 | #define LAUNCH_JOBKEY_LIMITLOADFROMHARDWARE "LimitLoadFromHardware" 76 | #define LAUNCH_JOBKEY_RUNATLOAD "RunAtLoad" 77 | #define LAUNCH_JOBKEY_ROOTDIRECTORY "RootDirectory" 78 | #define LAUNCH_JOBKEY_WORKINGDIRECTORY "WorkingDirectory" 79 | #define LAUNCH_JOBKEY_ENVIRONMENTVARIABLES "EnvironmentVariables" 80 | #define LAUNCH_JOBKEY_USERENVIRONMENTVARIABLES "UserEnvironmentVariables" 81 | #define LAUNCH_JOBKEY_UMASK "Umask" 82 | #define LAUNCH_JOBKEY_NICE "Nice" 83 | #define LAUNCH_JOBKEY_HOPEFULLYEXITSFIRST "HopefullyExitsFirst" 84 | #define LAUNCH_JOBKEY_HOPEFULLYEXITSLAST "HopefullyExitsLast" 85 | #define LAUNCH_JOBKEY_LOWPRIORITYIO "LowPriorityIO" 86 | #define LAUNCH_JOBKEY_SESSIONCREATE "SessionCreate" 87 | #define LAUNCH_JOBKEY_STARTONMOUNT "StartOnMount" 88 | #define LAUNCH_JOBKEY_SOFTRESOURCELIMITS "SoftResourceLimits" 89 | #define LAUNCH_JOBKEY_HARDRESOURCELIMITS "HardResourceLimits" 90 | #define LAUNCH_JOBKEY_STANDARDINPATH "StandardInPath" 91 | #define LAUNCH_JOBKEY_STANDARDOUTPATH "StandardOutPath" 92 | #define LAUNCH_JOBKEY_STANDARDERRORPATH "StandardErrorPath" 93 | #define LAUNCH_JOBKEY_DEBUG "Debug" 94 | #define LAUNCH_JOBKEY_WAITFORDEBUGGER "WaitForDebugger" 95 | #define LAUNCH_JOBKEY_QUEUEDIRECTORIES "QueueDirectories" 96 | #define LAUNCH_JOBKEY_WATCHPATHS "WatchPaths" 97 | #define LAUNCH_JOBKEY_STARTINTERVAL "StartInterval" 98 | #define LAUNCH_JOBKEY_STARTCALENDARINTERVAL "StartCalendarInterval" 99 | #define LAUNCH_JOBKEY_BONJOURFDS "BonjourFDs" 100 | #define LAUNCH_JOBKEY_LASTEXITSTATUS "LastExitStatus" 101 | #define LAUNCH_JOBKEY_PID "PID" 102 | #define LAUNCH_JOBKEY_THROTTLEINTERVAL "ThrottleInterval" 103 | #define LAUNCH_JOBKEY_LAUNCHONLYONCE "LaunchOnlyOnce" 104 | #define LAUNCH_JOBKEY_ABANDONPROCESSGROUP "AbandonProcessGroup" 105 | #define LAUNCH_JOBKEY_IGNOREPROCESSGROUPATSHUTDOWN "IgnoreProcessGroupAtShutdown" 106 | #define LAUNCH_JOBKEY_POLICIES "Policies" 107 | #define LAUNCH_JOBKEY_ENABLETRANSACTIONS "EnableTransactions" 108 | 109 | #define LAUNCH_JOBPOLICY_DENYCREATINGOTHERJOBS "DenyCreatingOtherJobs" 110 | 111 | #define LAUNCH_JOBINETDCOMPATIBILITY_WAIT "Wait" 112 | 113 | #define LAUNCH_JOBKEY_MACH_RESETATCLOSE "ResetAtClose" 114 | #define LAUNCH_JOBKEY_MACH_HIDEUNTILCHECKIN "HideUntilCheckIn" 115 | #define LAUNCH_JOBKEY_MACH_DRAINMESSAGESONCRASH "DrainMessagesOnCrash" 116 | #define LAUNCH_JOBKEY_MACH_PINGEVENTUPDATES "PingEventUpdates" 117 | 118 | #define LAUNCH_JOBKEY_KEEPALIVE_SUCCESSFULEXIT "SuccessfulExit" 119 | #define LAUNCH_JOBKEY_KEEPALIVE_NETWORKSTATE "NetworkState" 120 | #define LAUNCH_JOBKEY_KEEPALIVE_PATHSTATE "PathState" 121 | #define LAUNCH_JOBKEY_KEEPALIVE_OTHERJOBACTIVE "OtherJobActive" 122 | #define LAUNCH_JOBKEY_KEEPALIVE_OTHERJOBENABLED "OtherJobEnabled" 123 | #define LAUNCH_JOBKEY_KEEPALIVE_AFTERINITIALDEMAND "AfterInitialDemand" 124 | #define LAUNCH_JOBKEY_KEEPALIVE_CRASHED "Crashed" 125 | 126 | #define LAUNCH_JOBKEY_LAUNCHEVENTS "LaunchEvents" 127 | 128 | #define LAUNCH_JOBKEY_CAL_MINUTE "Minute" 129 | #define LAUNCH_JOBKEY_CAL_HOUR "Hour" 130 | #define LAUNCH_JOBKEY_CAL_DAY "Day" 131 | #define LAUNCH_JOBKEY_CAL_WEEKDAY "Weekday" 132 | #define LAUNCH_JOBKEY_CAL_MONTH "Month" 133 | 134 | #define LAUNCH_JOBKEY_RESOURCELIMIT_CORE "Core" 135 | #define LAUNCH_JOBKEY_RESOURCELIMIT_CPU "CPU" 136 | #define LAUNCH_JOBKEY_RESOURCELIMIT_DATA "Data" 137 | #define LAUNCH_JOBKEY_RESOURCELIMIT_FSIZE "FileSize" 138 | #define LAUNCH_JOBKEY_RESOURCELIMIT_MEMLOCK "MemoryLock" 139 | #define LAUNCH_JOBKEY_RESOURCELIMIT_NOFILE "NumberOfFiles" 140 | #define LAUNCH_JOBKEY_RESOURCELIMIT_NPROC "NumberOfProcesses" 141 | #define LAUNCH_JOBKEY_RESOURCELIMIT_RSS "ResidentSetSize" 142 | #define LAUNCH_JOBKEY_RESOURCELIMIT_STACK "Stack" 143 | 144 | #define LAUNCH_JOBKEY_DISABLED_MACHINETYPE "MachineType" 145 | #define LAUNCH_JOBKEY_DISABLED_MODELNAME "ModelName" 146 | 147 | #define LAUNCH_JOBSOCKETKEY_TYPE "SockType" 148 | #define LAUNCH_JOBSOCKETKEY_PASSIVE "SockPassive" 149 | #define LAUNCH_JOBSOCKETKEY_BONJOUR "Bonjour" 150 | #define LAUNCH_JOBSOCKETKEY_SECUREWITHKEY "SecureSocketWithKey" 151 | #define LAUNCH_JOBSOCKETKEY_PATHNAME "SockPathName" 152 | #define LAUNCH_JOBSOCKETKEY_PATHMODE "SockPathMode" 153 | #define LAUNCH_JOBSOCKETKEY_NODENAME "SockNodeName" 154 | #define LAUNCH_JOBSOCKETKEY_SERVICENAME "SockServiceName" 155 | #define LAUNCH_JOBSOCKETKEY_FAMILY "SockFamily" 156 | #define LAUNCH_JOBSOCKETKEY_PROTOCOL "SockProtocol" 157 | #define LAUNCH_JOBSOCKETKEY_MULTICASTGROUP "MulticastGroup" 158 | 159 | /* These APIs are NOT suitable for general use. Their use should be constrained 160 | * to checking into launchd to obtain socket file descriptors using the 161 | * LAUNCH_CHECK_IN message type. 162 | */ 163 | typedef struct _launch_data *launch_data_t; 164 | 165 | typedef enum { 166 | LAUNCH_DATA_DICTIONARY = 1, 167 | LAUNCH_DATA_ARRAY, 168 | LAUNCH_DATA_FD, 169 | LAUNCH_DATA_INTEGER, 170 | LAUNCH_DATA_REAL, 171 | LAUNCH_DATA_BOOL, 172 | LAUNCH_DATA_STRING, 173 | LAUNCH_DATA_OPAQUE, 174 | LAUNCH_DATA_ERRNO, 175 | LAUNCH_DATA_MACHPORT, 176 | } launch_data_type_t; 177 | 178 | __ld_allocator 179 | launch_data_t 180 | launch_data_alloc(launch_data_type_t); 181 | 182 | __ld_allocator 183 | launch_data_t 184 | launch_data_copy(launch_data_t); 185 | 186 | __ld_getter 187 | launch_data_type_t 188 | launch_data_get_type(const launch_data_t); 189 | 190 | __ld_setter 191 | void 192 | launch_data_free(launch_data_t); 193 | 194 | __ld_setter 195 | bool 196 | launch_data_dict_insert(launch_data_t, const launch_data_t, const char *); 197 | 198 | __ld_getter 199 | launch_data_t 200 | launch_data_dict_lookup(const launch_data_t, const char *); 201 | 202 | __ld_setter 203 | bool 204 | launch_data_dict_remove(launch_data_t, const char *); 205 | 206 | __ld_iterator(1, 2) 207 | void 208 | launch_data_dict_iterate(const launch_data_t, 209 | void (*)(const launch_data_t, const char *, void *), void *); 210 | 211 | __ld_getter 212 | size_t 213 | launch_data_dict_get_count(const launch_data_t); 214 | 215 | __ld_setter 216 | bool 217 | launch_data_array_set_index(launch_data_t, const launch_data_t, size_t); 218 | 219 | __ld_getter 220 | launch_data_t 221 | launch_data_array_get_index(const launch_data_t, size_t); 222 | 223 | __ld_getter 224 | size_t 225 | launch_data_array_get_count(const launch_data_t); 226 | 227 | __ld_allocator 228 | launch_data_t 229 | launch_data_new_fd(int); 230 | 231 | __ld_allocator 232 | launch_data_t 233 | launch_data_new_machport(mach_port_t); 234 | 235 | __ld_allocator 236 | launch_data_t 237 | launch_data_new_integer(long long); 238 | 239 | __ld_allocator 240 | launch_data_t 241 | launch_data_new_bool(bool); 242 | 243 | __ld_allocator 244 | launch_data_t 245 | launch_data_new_real(double); 246 | 247 | __ld_allocator 248 | launch_data_t 249 | launch_data_new_string(const char *); 250 | 251 | __ld_allocator 252 | launch_data_t 253 | launch_data_new_opaque(const void *, size_t); 254 | 255 | __ld_setter 256 | bool 257 | launch_data_set_fd(launch_data_t, int); 258 | 259 | __ld_setter 260 | bool 261 | launch_data_set_machport(launch_data_t, mach_port_t); 262 | 263 | __ld_setter 264 | bool 265 | launch_data_set_integer(launch_data_t, long long); 266 | 267 | __ld_setter 268 | bool 269 | launch_data_set_bool(launch_data_t, bool); 270 | 271 | __ld_setter 272 | bool 273 | launch_data_set_real(launch_data_t, double); 274 | 275 | __ld_setter 276 | bool 277 | launch_data_set_string(launch_data_t, const char *); 278 | 279 | __ld_setter 280 | bool 281 | launch_data_set_opaque(launch_data_t, const void *, size_t); 282 | 283 | __ld_getter 284 | int 285 | launch_data_get_fd(const launch_data_t); 286 | 287 | __ld_getter 288 | mach_port_t 289 | launch_data_get_machport(const launch_data_t); 290 | 291 | __ld_getter 292 | long long 293 | launch_data_get_integer(const launch_data_t); 294 | 295 | __ld_getter 296 | bool 297 | launch_data_get_bool(const launch_data_t); 298 | 299 | __ld_getter 300 | double 301 | launch_data_get_real(const launch_data_t); 302 | 303 | __ld_getter 304 | const char * 305 | launch_data_get_string(const launch_data_t); 306 | 307 | __ld_getter 308 | void * 309 | launch_data_get_opaque(const launch_data_t); 310 | 311 | __ld_getter 312 | size_t 313 | launch_data_get_opaque_size(const launch_data_t); 314 | 315 | __ld_getter 316 | int 317 | launch_data_get_errno(const launch_data_t); 318 | 319 | 320 | /* launch_get_fd() 321 | * 322 | * Use this to get the FD if you're doing asynchronous I/O with select(), 323 | * poll() or kevent(). 324 | */ 325 | __ld_normal 326 | int 327 | launch_get_fd(void); 328 | 329 | /* launch_msg() 330 | * 331 | * Use this API to check in. Nothing else. 332 | */ 333 | __ld_normal 334 | launch_data_t 335 | launch_msg(const launch_data_t); 336 | 337 | __END_DECLS 338 | 339 | #pragma GCC visibility pop 340 | 341 | #endif /* __LAUNCH_H__ */ 342 | -------------------------------------------------------------------------------- /headers/xpc/activity.h: -------------------------------------------------------------------------------- 1 | #ifndef __XPC_ACTIVITY_H__ 2 | #define __XPC_ACTIVITY_H__ 3 | 4 | #ifndef __XPC_INDIRECT__ 5 | #error "Please #include instead of this file directly." 6 | // For HeaderDoc. 7 | #include 8 | #endif // __XPC_INDIRECT__ 9 | 10 | #ifdef __BLOCKS__ 11 | 12 | XPC_ASSUME_NONNULL_BEGIN 13 | __BEGIN_DECLS 14 | 15 | /* 16 | * The following are a collection of keys and values used to set an activity's 17 | * execution criteria. 18 | */ 19 | 20 | /*! 21 | * @constant XPC_ACTIVITY_INTERVAL 22 | * An integer property indicating the desired time interval (in seconds) of the 23 | * activity. The activity will not be run more than once per time interval. 24 | * Due to the nature of XPC Activity finding an opportune time to run 25 | * the activity, any two occurrences may be more or less than 'interval' 26 | * seconds apart, but on average will be 'interval' seconds apart. 27 | * The presence of this key implies the following, unless overridden: 28 | * - XPC_ACTIVITY_REPEATING with a value of true 29 | * - XPC_ACTIVITY_DELAY with a value of half the 'interval' 30 | * The delay enforces a minimum distance between any two occurrences. 31 | * - XPC_ACTIVITY_GRACE_PERIOD with a value of half the 'interval'. 32 | * The grace period is the amount of time allowed to pass after the end of 33 | * the interval before more aggressive scheduling occurs. The grace period 34 | * does not increase the size of the interval. 35 | */ 36 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 37 | XPC_EXPORT 38 | const char *XPC_ACTIVITY_INTERVAL; 39 | 40 | /*! 41 | * @constant XPC_ACTIVITY_REPEATING 42 | * A boolean property indicating whether this is a repeating activity. 43 | */ 44 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 45 | XPC_EXPORT 46 | const char *XPC_ACTIVITY_REPEATING; 47 | 48 | /*! 49 | * @constant XPC_ACTIVITY_DELAY 50 | * An integer property indicating the number of seconds to delay before 51 | * beginning the activity. 52 | */ 53 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 54 | XPC_EXPORT 55 | const char *XPC_ACTIVITY_DELAY; 56 | 57 | /*! 58 | * @constant XPC_ACTIVITY_GRACE_PERIOD 59 | * An integer property indicating the number of seconds to allow as a grace 60 | * period before the scheduling of the activity becomes more aggressive. 61 | */ 62 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 63 | XPC_EXPORT 64 | const char *XPC_ACTIVITY_GRACE_PERIOD; 65 | 66 | 67 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 68 | XPC_EXPORT 69 | const int64_t XPC_ACTIVITY_INTERVAL_1_MIN; 70 | 71 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 72 | XPC_EXPORT 73 | const int64_t XPC_ACTIVITY_INTERVAL_5_MIN; 74 | 75 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 76 | XPC_EXPORT 77 | const int64_t XPC_ACTIVITY_INTERVAL_15_MIN; 78 | 79 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 80 | XPC_EXPORT 81 | const int64_t XPC_ACTIVITY_INTERVAL_30_MIN; 82 | 83 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 84 | XPC_EXPORT 85 | const int64_t XPC_ACTIVITY_INTERVAL_1_HOUR; 86 | 87 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 88 | XPC_EXPORT 89 | const int64_t XPC_ACTIVITY_INTERVAL_4_HOURS; 90 | 91 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 92 | XPC_EXPORT 93 | const int64_t XPC_ACTIVITY_INTERVAL_8_HOURS; 94 | 95 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 96 | XPC_EXPORT 97 | const int64_t XPC_ACTIVITY_INTERVAL_1_DAY; 98 | 99 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 100 | XPC_EXPORT 101 | const int64_t XPC_ACTIVITY_INTERVAL_7_DAYS; 102 | 103 | /*! 104 | * @constant XPC_ACTIVITY_PRIORITY 105 | * A string property indicating the priority of the activity. 106 | */ 107 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 108 | XPC_EXPORT 109 | const char *XPC_ACTIVITY_PRIORITY; 110 | 111 | /*! 112 | * @constant XPC_ACTIVITY_PRIORITY_MAINTENANCE 113 | * A string indicating activity is maintenance priority. 114 | * Maintenance priority is intended for user-invisible maintenance tasks 115 | * such as garbage collection or optimization. 116 | */ 117 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 118 | XPC_EXPORT 119 | const char *XPC_ACTIVITY_PRIORITY_MAINTENANCE; 120 | 121 | /*! 122 | * @constant XPC_ACTIVITY_PRIORITY_UTILITY 123 | * A string indicating activity is utility priority. 124 | * Utility priority is intended for user-visible tasks such as fetching data 125 | * from the network, copying files, or importing data. 126 | */ 127 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 128 | XPC_EXPORT 129 | const char *XPC_ACTIVITY_PRIORITY_UTILITY; 130 | 131 | /*! 132 | * @constant XPC_ACTIVITY_ALLOW_BATTERY 133 | * A Boolean value indicating whether the activity should be allowed to run 134 | * while the computer is on battery power. The default value is false for 135 | * maintenance priority activity and true for utility priority activity. 136 | */ 137 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 138 | XPC_EXPORT 139 | const char *XPC_ACTIVITY_ALLOW_BATTERY; 140 | 141 | /*! 142 | * @constant XPC_ACTIVITY_REQUIRE_SCREEN_SLEEP 143 | * A Boolean value indicating whether the activity should only be performed 144 | * while device appears to be asleep. Note that the definition of screen sleep 145 | * may very by platform and may include states where the device is known to be 146 | * idle despite the fact that the display itself is still powered. Defaults to 147 | * false. 148 | */ 149 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 150 | XPC_EXPORT 151 | const char *XPC_ACTIVITY_REQUIRE_SCREEN_SLEEP; // bool 152 | 153 | /*! 154 | * @constant XPC_ACTIVITY_REQUIRE_BATTERY_LEVEL 155 | * An integer percentage of minimum battery charge required to allow the 156 | * activity to run. A default minimum battery level is determined by the 157 | * system. 158 | */ 159 | __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_9, __MAC_10_9, __IPHONE_7_0, __IPHONE_7_0, 160 | "REQUIRE_BATTERY_LEVEL is not implemented") 161 | XPC_EXPORT 162 | const char *XPC_ACTIVITY_REQUIRE_BATTERY_LEVEL; // int (%) 163 | 164 | /*! 165 | * @constant XPC_ACTIVITY_REQUIRE_HDD_SPINNING 166 | * A Boolean value indicating whether the activity should only be performed 167 | * while the hard disk drive (HDD) is spinning. Computers with flash storage 168 | * are considered to be equivalent to HDD spinning. Defaults to false. 169 | */ 170 | __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_9, __MAC_10_9, __IPHONE_7_0, __IPHONE_7_0, 171 | "REQUIRE_HDD_SPINNING is not implemented") 172 | XPC_EXPORT 173 | const char *XPC_ACTIVITY_REQUIRE_HDD_SPINNING; // bool 174 | 175 | /*! 176 | * @define XPC_TYPE_ACTIVITY 177 | * A type representing the XPC activity object. 178 | */ 179 | #define XPC_TYPE_ACTIVITY (&_xpc_type_activity) 180 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 181 | XPC_EXPORT 182 | XPC_TYPE(_xpc_type_activity); 183 | 184 | /*! 185 | * @typedef xpc_activity_t 186 | * 187 | * @abstract 188 | * An XPC activity object. 189 | * 190 | * @discussion 191 | * This object represents a set of execution criteria and a current execution 192 | * state for background activity on the system. Once an activity is registered, 193 | * the system will evaluate its criteria to determine whether the activity is 194 | * eligible to run under current system conditions. When an activity becomes 195 | * eligible to run, its execution state will be updated and an invocation of 196 | * its handler block will be made. 197 | */ 198 | XPC_DECL(xpc_activity); 199 | 200 | /*! 201 | * @typedef xpc_activity_handler_t 202 | * 203 | * @abstract 204 | * A block that is called when an XPC activity becomes eligible to run. 205 | */ 206 | XPC_NONNULL1 207 | typedef void (^xpc_activity_handler_t)(xpc_activity_t activity); 208 | 209 | /*! 210 | * @constant XPC_ACTIVITY_CHECK_IN 211 | * This constant may be passed to xpc_activity_register() as the criteria 212 | * dictionary in order to check in with the system for previously registered 213 | * activity using the same identifier (for example, an activity taken from a 214 | * launchd property list). 215 | */ 216 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 217 | XPC_EXPORT 218 | const xpc_object_t XPC_ACTIVITY_CHECK_IN; 219 | 220 | /*! 221 | * @function xpc_activity_register 222 | * 223 | * @abstract 224 | * Registers an activity with the system. 225 | * 226 | * @discussion 227 | * Registers a new activity with the system. The criteria of the activity are 228 | * described by the dictionary passed to this function. If an activity with the 229 | * same identifier already exists, the criteria provided override the existing 230 | * criteria unless the special dictionary XPC_ACTIVITY_CHECK_IN is used. The 231 | * XPC_ACTIVITY_CHECK_IN dictionary instructs the system to first look up an 232 | * existing activity without modifying its criteria. Once the existing activity 233 | * is found (or a new one is created with an empty set of criteria) the handler 234 | * will be called with an activity object in the XPC_ACTIVITY_STATE_CHECK_IN 235 | * state. 236 | * 237 | * @param identifier 238 | * A unique identifier for the activity. Each application has its own namespace. 239 | * The identifier should remain constant across registrations, relaunches of 240 | * the application, and reboots. It should identify the kind of work being done, 241 | * not a particular invocation of the work. 242 | * 243 | * @param criteria 244 | * A dictionary of criteria for the activity. 245 | * 246 | * @param handler 247 | * The handler block to be called when the activity changes state to one of the 248 | * following states: 249 | * - XPC_ACTIVITY_STATE_CHECK_IN (optional) 250 | * - XPC_ACTIVITY_STATE_RUN 251 | * 252 | * The handler block is never invoked reentrantly. It will be invoked on a 253 | * dispatch queue with an appropriate priority to perform the activity. 254 | */ 255 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 256 | XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 XPC_NONNULL3 257 | void 258 | xpc_activity_register(const char *identifier, xpc_object_t criteria, 259 | xpc_activity_handler_t handler); 260 | 261 | /*! 262 | * @function xpc_activity_copy_criteria 263 | * 264 | * @abstract 265 | * Returns an XPC dictionary describing the execution criteria of an activity. 266 | * This will return NULL in cases where the activity has already completed, e.g. 267 | * when checking in to an event that finished and was not rescheduled. 268 | */ 269 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 270 | XPC_EXPORT XPC_WARN_RESULT XPC_RETURNS_RETAINED XPC_NONNULL1 271 | xpc_object_t _Nullable 272 | xpc_activity_copy_criteria(xpc_activity_t activity); 273 | 274 | /*! 275 | * @function xpc_activity_set_criteria 276 | * 277 | * @abstract 278 | * Modifies the execution criteria of an activity. 279 | */ 280 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 281 | XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 282 | void 283 | xpc_activity_set_criteria(xpc_activity_t activity, xpc_object_t criteria); 284 | 285 | /*! 286 | * @enum xpc_activity_state_t 287 | * An activity is defined to be in one of the following states. Applications 288 | * may check the current state of the activity using xpc_activity_get_state() 289 | * in the handler block provided to xpc_activity_register(). 290 | * 291 | * The application can modify the state of the activity by calling 292 | * xpc_activity_set_state() with one of the following: 293 | * - XPC_ACTIVITY_STATE_DEFER 294 | * - XPC_ACTIVITY_STATE_CONTINUE 295 | * - XPC_ACTIVITY_STATE_DONE 296 | * 297 | * @constant XPC_ACTIVITY_STATE_CHECK_IN 298 | * An activity in this state has just completed a checkin with the system after 299 | * XPC_ACTIVITY_CHECK_IN was provided as the criteria dictionary to 300 | * xpc_activity_register. The state gives the application an opportunity to 301 | * inspect and modify the activity's criteria. 302 | * 303 | * @constant XPC_ACTIVITY_STATE_WAIT 304 | * An activity in this state is waiting for an opportunity to run. This value 305 | * is never returned within the activity's handler block, as the block is 306 | * invoked in response to XPC_ACTIVITY_STATE_CHECK_IN or XPC_ACTIVITY_STATE_RUN. 307 | * 308 | * Note: 309 | * A launchd job may idle exit while an activity is in the wait state and be 310 | * relaunched in response to the activity becoming runnable. The launchd job 311 | * simply needs to re-register for the activity on its next launch by passing 312 | * XPC_ACTIVITY_STATE_CHECK_IN to xpc_activity_register(). 313 | * 314 | * @constant XPC_ACTIVITY_STATE_RUN 315 | * An activity in this state is eligible to run based on its criteria. 316 | * 317 | * @constant XPC_ACTIVITY_STATE_DEFER 318 | * An application may pass this value to xpc_activity_set_state() to indicate 319 | * that the activity should be deferred (placed back into the WAIT state) until 320 | * a time when its criteria are met again. Deferring an activity does not reset 321 | * any of its time-based criteria (in other words, it will remain past due). 322 | * 323 | * IMPORTANT: 324 | * This should be done in response to observing xpc_activity_should_defer(). 325 | * It should not be done unilaterally. If you determine that conditions are bad 326 | * to do your activity's work for reasons you can't express in a criteria 327 | * dictionary, you should set the activity's state to XPC_ACTIVITY_STATE_DONE. 328 | * 329 | * 330 | * @constant XPC_ACTIVITY_STATE_CONTINUE 331 | * An application may pass this value to xpc_activity_set_state() to indicate 332 | * that the activity will continue its operation beyond the return of its 333 | * handler block. This can be used to extend an activity to include asynchronous 334 | * operations. The activity's handler block will not be invoked again until the 335 | * state has been updated to either XPC_ACTIVITY_STATE_DEFER or, in the case 336 | * of repeating activity, XPC_ACTIVITY_STATE_DONE. 337 | * 338 | * @constant XPC_ACTIVITY_STATE_DONE 339 | * An application may pass this value to xpc_activity_set_state() to indicate 340 | * that the activity has completed. For non-repeating activity, the resources 341 | * associated with the activity will be automatically released upon return from 342 | * the handler block. For repeating activity, timers present in the activity's 343 | * criteria will be reset. 344 | */ 345 | enum { 346 | XPC_ACTIVITY_STATE_CHECK_IN, 347 | XPC_ACTIVITY_STATE_WAIT, 348 | XPC_ACTIVITY_STATE_RUN, 349 | XPC_ACTIVITY_STATE_DEFER, 350 | XPC_ACTIVITY_STATE_CONTINUE, 351 | XPC_ACTIVITY_STATE_DONE, 352 | }; 353 | typedef long xpc_activity_state_t; 354 | 355 | /*! 356 | * @function xpc_activity_get_state 357 | * 358 | * @abstract 359 | * Returns the current state of an activity. 360 | */ 361 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 362 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 363 | xpc_activity_state_t 364 | xpc_activity_get_state(xpc_activity_t activity); 365 | 366 | /*! 367 | * @function xpc_activity_set_state 368 | * 369 | * @abstract 370 | * Updates the current state of an activity. 371 | * 372 | * @return 373 | * Returns true if the state was successfully updated; otherwise, returns 374 | * false if the requested state transition is not valid. 375 | */ 376 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 377 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 378 | bool 379 | xpc_activity_set_state(xpc_activity_t activity, xpc_activity_state_t state); 380 | 381 | /*! 382 | * @function xpc_activity_should_defer 383 | * 384 | * @abstract 385 | * Test whether an activity should be deferred. 386 | * 387 | * @discussion 388 | * This function may be used to test whether the criteria of a long-running 389 | * activity are still satisfied. If not, the system indicates that the 390 | * application should defer the activity. The application may acknowledge the 391 | * deferral by calling xpc_activity_set_state() with XPC_ACTIVITY_STATE_DEFER. 392 | * Once deferred, the system will place the activity back into the WAIT state 393 | * and re-invoke the handler block at the earliest opportunity when the criteria 394 | * are once again satisfied. 395 | * 396 | * @return 397 | * Returns true if the activity should be deferred. 398 | */ 399 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 400 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 401 | bool 402 | xpc_activity_should_defer(xpc_activity_t activity); 403 | 404 | /*! 405 | * @function xpc_activity_unregister 406 | * 407 | * @abstract 408 | * Unregisters an activity found by its identifier. 409 | * 410 | * @discussion 411 | * A dynamically registered activity will be deleted in response to this call. 412 | * Statically registered activity (from a launchd property list) will be 413 | * deleted until the job is next loaded (e.g. at next boot). 414 | * 415 | * Unregistering an activity has no effect on any outstanding xpc_activity_t 416 | * objects or any currently executing xpc_activity_handler_t blocks; however, 417 | * no new handler block invocations will be made after it is unregistered. 418 | * 419 | * @param identifier 420 | * The identifier of the activity to unregister. 421 | */ 422 | __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) 423 | XPC_EXPORT XPC_NONNULL1 424 | void 425 | xpc_activity_unregister(const char *identifier); 426 | 427 | __END_DECLS 428 | XPC_ASSUME_NONNULL_END 429 | 430 | #endif // __BLOCKS__ 431 | 432 | #endif // __XPC_ACTIVITY_H__ 433 | 434 | -------------------------------------------------------------------------------- /headers/xpc/connection.h: -------------------------------------------------------------------------------- 1 | #ifndef __XPC_CONNECTION_H__ 2 | #define __XPC_CONNECTION_H__ 3 | 4 | #ifndef __XPC_INDIRECT__ 5 | #error "Please #include instead of this file directly." 6 | // For HeaderDoc. 7 | #include 8 | #endif // __XPC_INDIRECT__ 9 | 10 | #ifndef __BLOCKS__ 11 | #error "XPC connections require Blocks support." 12 | #endif // __BLOCKS__ 13 | 14 | XPC_ASSUME_NONNULL_BEGIN 15 | __BEGIN_DECLS 16 | 17 | /*! 18 | * @constant XPC_ERROR_CONNECTION_INTERRUPTED 19 | * Will be delivered to the connection's event handler if the remote service 20 | * exited. The connection is still live even in this case, and resending a 21 | * message will cause the service to be launched on-demand. This error serves 22 | * as a client's indication that it should resynchronize any state that it had 23 | * given the service. 24 | * 25 | * Any messages in the queue to be sent will be unwound and canceled when this 26 | * error occurs. In the case where a message waiting to be sent has a reply 27 | * handler, that handler will be invoked with this error. In the context of the 28 | * reply handler, this error indicates that a reply to the message will never 29 | * arrive. 30 | * 31 | * Messages that do not have reply handlers associated with them will be 32 | * silently disposed of. This error will only be given to peer connections. 33 | */ 34 | #define XPC_ERROR_CONNECTION_INTERRUPTED \ 35 | XPC_GLOBAL_OBJECT(_xpc_error_connection_interrupted) 36 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 37 | XPC_EXPORT 38 | const struct _xpc_dictionary_s _xpc_error_connection_interrupted; 39 | 40 | /*! 41 | * @constant XPC_ERROR_CONNECTION_INVALID 42 | * Will be delivered to the connection's event handler if the named service 43 | * provided to xpc_connection_create() could not be found in the XPC service 44 | * namespace. The connection is useless and should be disposed of. 45 | * 46 | * Any messages in the queue to be sent will be unwound and canceled when this 47 | * error occurs, similarly to the behavior when XPC_ERROR_CONNECTION_INTERRUPTED 48 | * occurs. The only difference is that the XPC_ERROR_CONNECTION_INVALID will be 49 | * given to outstanding reply handlers and the connection's event handler. 50 | * 51 | * This error may be given to any type of connection. 52 | */ 53 | #define XPC_ERROR_CONNECTION_INVALID \ 54 | XPC_GLOBAL_OBJECT(_xpc_error_connection_invalid) 55 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 56 | XPC_EXPORT 57 | const struct _xpc_dictionary_s _xpc_error_connection_invalid; 58 | 59 | /*! 60 | * @constant XPC_ERROR_TERMINATION_IMMINENT 61 | * On macOS, this error will be delivered to a peer connection's event handler 62 | * when the XPC runtime has determined that the program should exit and that 63 | * all outstanding transactions must be wound down, and no new transactions can 64 | * be opened. 65 | * 66 | * After this error has been delivered to the event handler, no more messages 67 | * will be received by the connection. The runtime will still attempt to deliver 68 | * outgoing messages, but this error should be treated as an indication that 69 | * the program will exit very soon, and any outstanding business over the 70 | * connection should be wrapped up as quickly as possible and the connection 71 | * canceled shortly thereafter. 72 | * 73 | * This error will only be delivered to peer connections received through a 74 | * listener or the xpc_main() event handler. 75 | */ 76 | #define XPC_ERROR_TERMINATION_IMMINENT \ 77 | XPC_GLOBAL_OBJECT(_xpc_error_termination_imminent) 78 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 79 | XPC_EXPORT 80 | const struct _xpc_dictionary_s _xpc_error_termination_imminent; 81 | 82 | /*! 83 | * @constant XPC_CONNECTION_MACH_SERVICE_LISTENER 84 | * Passed to xpc_connection_create_mach_service(). This flag indicates that the 85 | * caller is the listener for the named service. This flag may only be passed 86 | * for services which are advertised in the process' launchd.plist(5). You may 87 | * not use this flag to dynamically add services to the Mach bootstrap 88 | * namespace. 89 | */ 90 | #define XPC_CONNECTION_MACH_SERVICE_LISTENER (1 << 0) 91 | 92 | /*! 93 | * @constant XPC_CONNECTION_MACH_SERVICE_PRIVILEGED 94 | * Passed to xpc_connection_create_mach_service(). This flag indicates that the 95 | * job advertising the service name in its launchd.plist(5) should be in the 96 | * privileged Mach bootstrap. This is typically accomplished by placing your 97 | * launchd.plist(5) in /Library/LaunchDaemons. If specified alongside the 98 | * XPC_CONNECTION_MACH_SERVICE_LISTENER flag, this flag is a no-op. 99 | */ 100 | #define XPC_CONNECTION_MACH_SERVICE_PRIVILEGED (1 << 1) 101 | 102 | /*! 103 | * @typedef xpc_finalizer_f 104 | * A function that is invoked when a connection is being torn down and its 105 | * context needs to be freed. The sole argument is the value that was given to 106 | * {@link xpc_connection_set_context} or NULL if no context has been set. It is 107 | * not safe to reference the connection from within this function. 108 | * 109 | * @param value 110 | * The context object that is to be disposed of. 111 | */ 112 | typedef void (*xpc_finalizer_t)(void * _Nullable value); 113 | 114 | /*! 115 | * @function xpc_connection_create 116 | * Creates a new connection object. 117 | * 118 | * @param name 119 | * If non-NULL, the name of the service with which to connect. The returned 120 | * connection will be a peer. 121 | * 122 | * If NULL, an anonymous listener connection will be created. You can embed the 123 | * ability to create new peer connections in an endpoint, which can be inserted 124 | * into a message and sent to another process . 125 | * 126 | * @param targetq 127 | * The GCD queue to which the event handler block will be submitted. This 128 | * parameter may be NULL, in which case the connection's target queue will be 129 | * libdispatch's default target queue, defined as DISPATCH_TARGET_QUEUE_DEFAULT. 130 | * The target queue may be changed later with a call to 131 | * xpc_connection_set_target_queue(). 132 | * 133 | * @result 134 | * A new connection object. The caller is responsible for disposing of the 135 | * returned object with {@link xpc_release} when it is no longer needed. 136 | * 137 | * @discussion 138 | * This method will succeed even if the named service does not exist. This is 139 | * because the XPC namespace is not queried for the service name until the 140 | * connection has been activated. See {@link xpc_connection_activate()}. 141 | * 142 | * XPC connections, like dispatch sources, are returned in an inactive state, so 143 | * you must call {@link xpc_connection_activate()} in order to begin receiving 144 | * events from the connection. Also like dispatch sources, connections must be 145 | * activated and not suspended in order to be safely released. It is 146 | * a programming error to release an inactive or suspended connection. 147 | */ 148 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 149 | XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT 150 | xpc_connection_t 151 | xpc_connection_create(const char * _Nullable name, 152 | dispatch_queue_t _Nullable targetq); 153 | 154 | /*! 155 | * @function xpc_connection_create_mach_service 156 | * Creates a new connection object representing a Mach service. 157 | * 158 | * @param name 159 | * The name of the remote service with which to connect. The service name must 160 | * exist in a Mach bootstrap that is accessible to the process and be advertised 161 | * in a launchd.plist. 162 | * 163 | * @param targetq 164 | * The GCD queue to which the event handler block will be submitted. This 165 | * parameter may be NULL, in which case the connection's target queue will be 166 | * libdispatch's default target queue, defined as DISPATCH_TARGET_QUEUE_DEFAULT. 167 | * The target queue may be changed later with a call to 168 | * xpc_connection_set_target_queue(). 169 | * 170 | * @param flags 171 | * Additional attributes with which to create the connection. 172 | * 173 | * @result 174 | * A new connection object. 175 | * 176 | * @discussion 177 | * If the XPC_CONNECTION_MACH_SERVICE_LISTENER flag is given to this method, 178 | * then the connection returned will be a listener connection. Otherwise, a peer 179 | * connection will be returned. See the documentation for 180 | * {@link xpc_connection_set_event_handler()} for the semantics of listener 181 | * connections versus peer connections. 182 | * 183 | * This method will succeed even if the named service does not exist. This is 184 | * because the Mach namespace is not queried for the service name until the 185 | * connection has been activated. See {@link xpc_connection_activate()}. 186 | */ 187 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 188 | XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1 189 | xpc_connection_t 190 | xpc_connection_create_mach_service(const char *name, 191 | dispatch_queue_t _Nullable targetq, uint64_t flags); 192 | 193 | /*! 194 | * @function xpc_connection_create_from_endpoint 195 | * Creates a new connection from the given endpoint. 196 | * 197 | * @param endpoint 198 | * The endpoint from which to create the new connection. 199 | * 200 | * @result 201 | * A new peer connection to the listener represented by the given endpoint. 202 | * 203 | * The same responsibilities of setting an event handler and activating the 204 | * connection after calling xpc_connection_create() apply to the connection 205 | * returned by this API. Since the connection yielded by this API is not 206 | * associated with a name (and therefore is not rediscoverable), this connection 207 | * will receive XPC_ERROR_CONNECTION_INVALID if the listening side crashes, 208 | * exits or cancels the listener connection. 209 | */ 210 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 211 | XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL_ALL 212 | xpc_connection_t 213 | xpc_connection_create_from_endpoint(xpc_endpoint_t endpoint); 214 | 215 | /*! 216 | * @function xpc_connection_set_target_queue 217 | * Sets the target queue of the given connection. 218 | * 219 | * @param connection 220 | * The connection object which is to be manipulated. 221 | * 222 | * @param targetq 223 | * The GCD queue to which the event handler block will be submitted. This 224 | * parameter may be NULL, in which case the connection's target queue will be 225 | * libdispatch's default target queue, defined as DISPATCH_TARGET_QUEUE_DEFAULT. 226 | * 227 | * @discussion 228 | * Setting the target queue is asynchronous and non-preemptive and therefore 229 | * this method will not interrupt the execution of an already-running event 230 | * handler block. Setting the target queue may be likened to issuing a barrier 231 | * to the connection which does the actual work of changing the target queue. 232 | * 233 | * The XPC runtime guarantees this non-preemptiveness even for concurrent target 234 | * queues. If the target queue is a concurrent queue, then XPC still guarantees 235 | * that there will never be more than one invocation of the connection's event 236 | * handler block executing concurrently. If you wish to process events 237 | * concurrently, you can dispatch_async(3) to a concurrent queue from within 238 | * the event handler. 239 | * 240 | * IMPORTANT: When called from within the event handler block, 241 | * dispatch_get_current_queue(3) is NOT guaranteed to return a pointer to the 242 | * queue set with this method. 243 | * 244 | * Despite this seeming inconsistency, the XPC runtime guarantees that, when the 245 | * target queue is a serial queue, the event handler block will execute 246 | * synchonously with respect to other blocks submitted to that same queue. When 247 | * the target queue is a concurrent queue, the event handler block may run 248 | * concurrently with other blocks submitted to that queue, but it will never run 249 | * concurrently with other invocations of itself for the same connection, as 250 | * discussed previously. 251 | */ 252 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 253 | XPC_EXPORT XPC_NONNULL1 254 | void 255 | xpc_connection_set_target_queue(xpc_connection_t connection, 256 | dispatch_queue_t _Nullable targetq); 257 | 258 | /*! 259 | * @function xpc_connection_set_event_handler 260 | * Sets the event handler block for the connection. 261 | * 262 | * @param connection 263 | * The connection object which is to be manipulated. 264 | * 265 | * @param handler 266 | * The event handler block. 267 | * 268 | * @discussion 269 | * Setting the event handler is asynchronous and non-preemptive, and therefore 270 | * this method will not interrupt the execution of an already-running event 271 | * handler block. If the event handler is executing at the time of this call, it 272 | * will finish, and then the connection's event handler will be changed before 273 | * the next invocation of the event handler. The XPC runtime guarantees this 274 | * non-preemptiveness even for concurrent target queues. 275 | * 276 | * Connection event handlers are non-reentrant, so it is safe to call 277 | * xpc_connection_set_event_handler() from within the event handler block. 278 | * 279 | * The event handler's execution should be treated as a barrier to all 280 | * connection activity. When it is executing, the connection will not attempt to 281 | * send or receive messages, including reply messages. Thus, it is not safe to 282 | * call xpc_connection_send_message_with_reply_sync() on the connection from 283 | * within the event handler. 284 | * 285 | * You do not hold a reference on the object received as the event handler's 286 | * only argument. Regardless of the type of object received, it is safe to call 287 | * xpc_retain() on the object to obtain a reference to it. 288 | * 289 | * A connection may receive different events depending upon whether it is a 290 | * listener or not. Any connection may receive an error in its event handler. 291 | * But while normal connections may receive messages in addition to errors, 292 | * listener connections will receive connections and and not messages. 293 | * 294 | * Connections received by listeners are equivalent to those returned by 295 | * xpc_connection_create() with a non-NULL name argument and a NULL targetq 296 | * argument with the exception that you do not hold a reference on them. 297 | * You must set an event handler and activate the connection. If you do not wish 298 | * to accept the connection, you may simply call xpc_connection_cancel() on it 299 | * and return. The runtime will dispose of it for you. 300 | * 301 | * If there is an error in the connection, this handler will be invoked with the 302 | * error dictionary as its argument. This dictionary will be one of the well- 303 | * known XPC_ERROR_* dictionaries. 304 | * 305 | * Regardless of the type of event, ownership of the event object is NOT 306 | * implicitly transferred. Thus, the object will be released and deallocated at 307 | * some point in the future after the event handler returns. If you wish the 308 | * event's lifetime to persist, you must retain it with xpc_retain(). 309 | * 310 | * Connections received through the event handler will be released and 311 | * deallocated after the connection has gone invalid and delivered that event to 312 | * its event handler. 313 | */ 314 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 315 | XPC_EXPORT XPC_NONNULL_ALL 316 | void 317 | xpc_connection_set_event_handler(xpc_connection_t connection, 318 | xpc_handler_t handler); 319 | 320 | /*! 321 | * @function xpc_connection_activate 322 | * Activates the connection. Connections start in an inactive state, so you must 323 | * call xpc_connection_activate() on a connection before it will send or receive 324 | * any messages. 325 | * 326 | * @param connection 327 | * The connection object which is to be manipulated. 328 | * 329 | * @discussion 330 | * Calling xpc_connection_activate() on an active connection has no effect. 331 | * Releasing the last reference on an inactive connection that was created with 332 | * an xpc_connection_create*() call is undefined. 333 | * 334 | * For backward compatibility reasons, xpc_connection_resume() on an inactive 335 | * and not otherwise suspended xpc connection has the same effect as calling 336 | * xpc_connection_activate(). For new code, using xpc_connection_activate() 337 | * is preferred. 338 | */ 339 | __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) 340 | __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0) 341 | XPC_EXPORT XPC_NONNULL_ALL 342 | void 343 | xpc_connection_activate(xpc_connection_t connection); 344 | 345 | /*! 346 | * @function xpc_connection_suspend 347 | * Suspends the connection so that the event handler block will not fire and 348 | * that the connection will not attempt to send any messages it has in its 349 | * queue. All calls to xpc_connection_suspend() must be balanced with calls to 350 | * xpc_connection_resume() before releasing the last reference to the 351 | * connection. 352 | * 353 | * @param connection 354 | * The connection object which is to be manipulated. 355 | * 356 | * @discussion 357 | * Suspension is asynchronous and non-preemptive, and therefore this method will 358 | * not interrupt the execution of an already-running event handler block. If 359 | * the event handler is executing at the time of this call, it will finish, and 360 | * then the connection will be suspended before the next scheduled invocation 361 | * of the event handler. The XPC runtime guarantees this non-preemptiveness even 362 | * for concurrent target queues. 363 | * 364 | * Connection event handlers are non-reentrant, so it is safe to call 365 | * xpc_connection_suspend() from within the event handler block. 366 | */ 367 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 368 | XPC_EXPORT XPC_NONNULL_ALL 369 | void 370 | xpc_connection_suspend(xpc_connection_t connection); 371 | 372 | /*! 373 | * @function xpc_connection_resume 374 | * Resumes the connection. 375 | * 376 | * @param connection 377 | * The connection object which is to be manipulated. 378 | * 379 | * @discussion 380 | * In order for a connection to become live, every call to 381 | * xpc_connection_suspend() must be balanced with a call to 382 | * xpc_connection_resume(). 383 | * 384 | * For backward compatibility reasons, xpc_connection_resume() on an inactive 385 | * and not otherwise suspended xpc connection has the same effect as calling 386 | * xpc_connection_activate(). For new code, using xpc_connection_activate() 387 | * is preferred. 388 | * 389 | * Calling xpc_connection_resume() more times than xpc_connection_suspend() 390 | * has been called is otherwise considered an error. 391 | */ 392 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 393 | XPC_EXPORT XPC_NONNULL_ALL 394 | void 395 | xpc_connection_resume(xpc_connection_t connection); 396 | 397 | /*! 398 | * @function xpc_connection_send_message 399 | * Sends a message over the connection to the destination service. 400 | * 401 | * @param connection 402 | * The connection over which the message shall be sent. 403 | * 404 | * @param message 405 | * The message to send. This must be a dictionary object. This dictionary is 406 | * logically copied by the connection, so it is safe to modify the dictionary 407 | * after this call. 408 | * 409 | * @discussion 410 | * Messages are delivered in FIFO order. This API is safe to call from multiple 411 | * GCD queues. There is no indication that a message was delivered successfully. 412 | * This is because even once the message has been successfully enqueued on the 413 | * remote end, there are no guarantees about when the runtime will dequeue the 414 | * message and invoke the other connection's event handler block. 415 | * 416 | * If this API is used to send a message that is in reply to another message, 417 | * there is no guarantee of ordering between the invocations of the connection's 418 | * event handler and the reply handler for that message, even if they are 419 | * targeted to the same queue. 420 | * 421 | * After extensive study, we have found that clients who are interested in 422 | * the state of the message on the server end are typically holding open 423 | * transactions related to that message. And the only reliable way to track the 424 | * lifetime of that transaction is at the protocol layer. So the server should 425 | * send a reply message, which upon receiving, will cause the client to close 426 | * its transaction. 427 | */ 428 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 429 | XPC_EXPORT XPC_NONNULL_ALL 430 | void 431 | xpc_connection_send_message(xpc_connection_t connection, xpc_object_t message); 432 | 433 | /*! 434 | * @function xpc_connection_send_barrier 435 | * Issues a barrier against the connection's message-send activity. 436 | * 437 | * @param connection 438 | * The connection against which the barrier is to be issued. 439 | * 440 | * @param barrier 441 | * The barrier block to issue. This barrier prevents concurrent message-send 442 | * activity on the connection. No messages will be sent while the barrier block 443 | * is executing. 444 | * 445 | * @discussion 446 | * XPC guarantees that, even if the connection's target queue is a concurrent 447 | * queue, there are no other messages being sent concurrently while the barrier 448 | * block is executing. XPC does not guarantee that the reciept of messages 449 | * (either through the connection's event handler or through reply handlers) 450 | * will be suspended while the barrier is executing. 451 | * 452 | * A barrier is issued relative to the message-send queue. Thus, if you call 453 | * xpc_connection_send_message() five times and then call 454 | * xpc_connection_send_barrier(), the barrier will be invoked after the fifth 455 | * message has been sent and its memory disposed of. You may safely cancel a 456 | * connection from within a barrier block. 457 | * 458 | * If a barrier is issued after sending a message which expects a reply, the 459 | * behavior is the same as described above. The receipt of a reply message will 460 | * not influence when the barrier runs. 461 | * 462 | * A barrier block can be useful for throttling resource consumption on the 463 | * connected side of a connection. For example, if your connection sends many 464 | * large messages, you can use a barrier to limit the number of messages that 465 | * are inflight at any given time. This can be particularly useful for messages 466 | * that contain kernel resources (like file descriptors) which have a system- 467 | * wide limit. 468 | * 469 | * If a barrier is issued on a canceled connection, it will be invoked 470 | * immediately. If a connection has been canceled and still has outstanding 471 | * barriers, those barriers will be invoked as part of the connection's 472 | * unwinding process. 473 | * 474 | * It is important to note that a barrier block's execution order is not 475 | * guaranteed with respect to other blocks that have been scheduled on the 476 | * target queue of the connection. Or said differently, 477 | * xpc_connection_send_barrier(3) is not equivalent to dispatch_async(3). 478 | */ 479 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 480 | XPC_EXPORT XPC_NONNULL_ALL 481 | void 482 | xpc_connection_send_barrier(xpc_connection_t connection, 483 | dispatch_block_t barrier); 484 | 485 | /*! 486 | * @function xpc_connection_send_message_with_reply 487 | * Sends a message over the connection to the destination service and associates 488 | * a handler to be invoked when the remote service sends a reply message. 489 | * 490 | * @param connection 491 | * The connection over which the message shall be sent. 492 | * 493 | * @param message 494 | * The message to send. This must be a dictionary object. 495 | * 496 | * @param replyq 497 | * The GCD queue to which the reply handler will be submitted. This may be a 498 | * concurrent queue. 499 | * 500 | * @param handler 501 | * The handler block to invoke when a reply to the message is received from 502 | * the connection. If the remote service exits prematurely before the reply was 503 | * received, the XPC_ERROR_CONNECTION_INTERRUPTED error will be returned. 504 | * If the connection went invalid before the message could be sent, the 505 | * XPC_ERROR_CONNECTION_INVALID error will be returned. 506 | * 507 | * @discussion 508 | * If the given GCD queue is a concurrent queue, XPC cannot guarantee that there 509 | * will not be multiple reply handlers being invoked concurrently. XPC does not 510 | * guarantee any ordering for the invocation of reply handers. So if multiple 511 | * messages are waiting for replies and the connection goes invalid, there is no 512 | * guarantee that the reply handlers will be invoked in FIFO order. Similarly, 513 | * XPC does not guarantee that reply handlers will not run concurrently with 514 | * the connection's event handler in the case that the reply queue and the 515 | * connection's target queue are the same concurrent queue. 516 | */ 517 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 518 | XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 XPC_NONNULL4 519 | void 520 | xpc_connection_send_message_with_reply(xpc_connection_t connection, 521 | xpc_object_t message, dispatch_queue_t _Nullable replyq, 522 | xpc_handler_t handler); 523 | 524 | /*! 525 | * @function xpc_connection_send_message_with_reply_sync 526 | * Sends a message over the connection and blocks the caller until a reply is 527 | * received. 528 | * 529 | * @param connection 530 | * The connection over which the message shall be sent. 531 | * 532 | * @param message 533 | * The message to send. This must be a dictionary object. 534 | * 535 | * @result 536 | * The message that the remote service sent in reply to the original message. 537 | * If the remote service exits prematurely before the reply was received, the 538 | * XPC_ERROR_CONNECTION_INTERRUPTED error will be returned. If the connection 539 | * went invalid before the message could be sent, the 540 | * XPC_ERROR_CONNECTION_INVALID error will be returned. 541 | * 542 | * You are responsible for releasing the returned object. 543 | * 544 | * @discussion 545 | * This API is primarily for transitional purposes. Its implementation is 546 | * conceptually equivalent to calling xpc_connection_send_message_with_reply() 547 | * and then immediately blocking the calling thread on a semaphore and 548 | * signaling the semaphore from the reply block. 549 | * 550 | * Be judicious about your use of this API. It can block indefinitely, so if you 551 | * are using it to implement an API that can be called from the main thread, you 552 | * may wish to consider allowing the API to take a queue and callback block so 553 | * that results may be delivered asynchronously if possible. 554 | */ 555 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 556 | XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT XPC_RETURNS_RETAINED 557 | xpc_object_t 558 | xpc_connection_send_message_with_reply_sync(xpc_connection_t connection, 559 | xpc_object_t message); 560 | 561 | /*! 562 | * @function xpc_connection_cancel 563 | * Cancels the connection and ensures that its event handler will not fire 564 | * again. After this call, any messages that have not yet been sent will be 565 | * discarded, and the connection will be unwound. If there are messages that are 566 | * awaiting replies, they will have their reply handlers invoked with the 567 | * XPC_ERROR_CONNECTION_INVALID error. 568 | * 569 | * @param connection 570 | * The connection object which is to be manipulated. 571 | * 572 | * @discussion 573 | * Cancellation is asynchronous and non-preemptive and therefore this method 574 | * will not interrupt the execution of an already-running event handler block. 575 | * If the event handler is executing at the time of this call, it will finish, 576 | * and then the connection will be canceled, causing a final invocation of the 577 | * event handler to be scheduled with the XPC_ERROR_CONNECTION_INVALID error. 578 | * After that invocation, there will be no further invocations of the event 579 | * handler. 580 | * 581 | * The XPC runtime guarantees this non-preemptiveness even for concurrent target 582 | * queues. 583 | */ 584 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 585 | XPC_EXPORT XPC_NONNULL_ALL 586 | void 587 | xpc_connection_cancel(xpc_connection_t connection); 588 | 589 | /*! 590 | * @function xpc_connection_get_name 591 | * Returns the name of the service with which the connections was created. 592 | * 593 | * @param connection 594 | * The connection object which is to be examined. 595 | * 596 | * @result 597 | * The name of the remote service. If you obtained the connection through an 598 | * invocation of another connection's event handler, NULL is returned. 599 | */ 600 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 601 | XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT 602 | const char * _Nullable 603 | xpc_connection_get_name(xpc_connection_t connection); 604 | 605 | /*! 606 | * @function xpc_connection_get_euid 607 | * Returns the EUID of the remote peer. 608 | * 609 | * @param connection 610 | * The connection object which is to be examined. 611 | * 612 | * @result 613 | * The EUID of the remote peer at the time the connection was made. 614 | */ 615 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 616 | XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT 617 | uid_t 618 | xpc_connection_get_euid(xpc_connection_t connection); 619 | 620 | /*! 621 | * @function xpc_connection_get_egid 622 | * Returns the EGID of the remote peer. 623 | * 624 | * @param connection 625 | * The connection object which is to be examined. 626 | * 627 | * @result 628 | * The EGID of the remote peer at the time the connection was made. 629 | */ 630 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 631 | XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT 632 | gid_t 633 | xpc_connection_get_egid(xpc_connection_t connection); 634 | 635 | /*! 636 | * @function xpc_connection_get_pid 637 | * Returns the PID of the remote peer. 638 | * 639 | * @param connection 640 | * The connection object which is to be examined. 641 | * 642 | * @result 643 | * The PID of the remote peer. 644 | * 645 | * @discussion 646 | * A given PID is not guaranteed to be unique across an entire boot cycle. 647 | * Great care should be taken when dealing with this information, as it can go 648 | * stale after the connection is established. OS X recycles PIDs, and therefore 649 | * another process could spawn and claim the PID before a message is actually 650 | * received from the connection. 651 | * 652 | * XPC will deliver an error to your event handler if the remote process goes 653 | * away, but there are no guarantees as to the timing of this notification's 654 | * delivery either at the kernel layer or at the XPC layer. 655 | */ 656 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 657 | XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT 658 | pid_t 659 | xpc_connection_get_pid(xpc_connection_t connection); 660 | 661 | /*! 662 | * @function xpc_connection_get_asid 663 | * Returns the audit session identifier of the remote peer. 664 | * 665 | * @param connection 666 | * The connection object which is to be examined. 667 | * 668 | * @result 669 | * The audit session ID of the remote peer at the time the connection was made. 670 | */ 671 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 672 | XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT 673 | au_asid_t 674 | xpc_connection_get_asid(xpc_connection_t connection); 675 | 676 | /*! 677 | * @function xpc_connection_set_context 678 | * Sets context on an connection. 679 | * 680 | * @param connection 681 | * The connection which is to be manipulated. 682 | * 683 | * @param context 684 | * The context to associate with the connection. 685 | * 686 | * @discussion 687 | * If you must manage the memory of the context object, you must set a finalizer 688 | * to dispose of it. If this method is called on a connection which already has 689 | * context associated with it, the finalizer will NOT be invoked. The finalizer 690 | * is only invoked when the connection is being deallocated. 691 | * 692 | * It is recommended that, instead of changing the actual context pointer 693 | * associated with the object, you instead change the state of the context 694 | * object itself. 695 | */ 696 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 697 | XPC_EXPORT XPC_NONNULL1 698 | void 699 | xpc_connection_set_context(xpc_connection_t connection, 700 | void * _Nullable context); 701 | 702 | /*! 703 | * @function xpc_connection_get_context 704 | * Returns the context associated with the connection. 705 | * 706 | * @param connection 707 | * The connection which is to be examined. 708 | * 709 | * @result 710 | * The context associated with the connection. NULL if there has been no context 711 | * associated with the object. 712 | */ 713 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 714 | XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT 715 | void * _Nullable 716 | xpc_connection_get_context(xpc_connection_t connection); 717 | 718 | /*! 719 | * @function xpc_connection_set_finalizer_f 720 | * Sets the finalizer for the given connection. 721 | * 722 | * @param connection 723 | * The connection on which to set the finalizer. 724 | * 725 | * @param finalizer 726 | * The function that will be invoked when the connection's retain count has 727 | * dropped to zero and is being torn down. 728 | * 729 | * @discussion 730 | * This method disposes of the context value associated with a connection, as 731 | * set by {@link xpc_connection_set_context}. 732 | * 733 | * For many uses of context objects, this API allows for a convenient shorthand 734 | * for freeing them. For example, for a context object allocated with malloc(3): 735 | * 736 | * xpc_connection_set_finalizer_f(object, free); 737 | */ 738 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 739 | XPC_EXPORT XPC_NONNULL1 740 | void 741 | xpc_connection_set_finalizer_f(xpc_connection_t connection, 742 | xpc_finalizer_t _Nullable finalizer); 743 | 744 | __END_DECLS 745 | XPC_ASSUME_NONNULL_END 746 | 747 | #endif // __XPC_CONNECTION_H__ 748 | -------------------------------------------------------------------------------- /headers/xpc/xpc.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2009-2011 Apple Inc. All rights reserved. 2 | 3 | #ifndef __XPC_H__ 4 | #define __XPC_H__ 5 | 6 | #include 7 | #include 8 | 9 | #include 10 | #include 11 | #include 12 | #include 13 | #include 14 | #include 15 | #include 16 | #include 17 | #include 18 | #include 19 | #include 20 | 21 | #ifndef __XPC_INDIRECT__ 22 | #define __XPC_INDIRECT__ 23 | #endif // __XPC_INDIRECT__ 24 | 25 | #include 26 | 27 | XPC_ASSUME_NONNULL_BEGIN 28 | __BEGIN_DECLS 29 | 30 | #ifndef __OSX_AVAILABLE_STARTING 31 | #define __OSX_AVAILABLE_STARTING(x, y) 32 | #endif // __OSX_AVAILABLE_STARTING 33 | 34 | #define XPC_API_VERSION 20121012 35 | 36 | /*! 37 | * @typedef xpc_type_t 38 | * A type that describes XPC object types. 39 | */ 40 | typedef const struct _xpc_type_s * xpc_type_t; 41 | #ifndef __XPC_BUILDING_XPC__ 42 | #define XPC_TYPE(type) const struct _xpc_type_s type 43 | #endif // __XPC_BUILDING_XPC__ 44 | 45 | /*! 46 | * @typedef xpc_object_t 47 | * A type that can describe all XPC objects. Dictionaries, arrays, strings, etc. 48 | * are all described by this type. 49 | * 50 | * XPC objects are created with a retain count of 1, and therefore it is the 51 | * caller's responsibility to call xpc_release() on them when they are no longer 52 | * needed. 53 | */ 54 | 55 | #if OS_OBJECT_USE_OBJC 56 | /* By default, XPC objects are declared as Objective-C types when building with 57 | * an Objective-C compiler. This allows them to participate in ARC, in RR 58 | * management by the Blocks runtime and in leaks checking by the static 59 | * analyzer, and enables them to be added to Cocoa collections. 60 | * 61 | * See for details. 62 | */ 63 | OS_OBJECT_DECL(xpc_object); 64 | #ifndef __XPC_PROJECT_BUILD__ 65 | #define XPC_DECL(name) typedef xpc_object_t name##_t 66 | #endif // __XPC_PROJECT_BUILD__ 67 | 68 | #define XPC_GLOBAL_OBJECT(object) ((OS_OBJECT_BRIDGE xpc_object_t)&(object)) 69 | #define XPC_RETURNS_RETAINED OS_OBJECT_RETURNS_RETAINED 70 | XPC_INLINE XPC_NONNULL_ALL 71 | void 72 | _xpc_object_validate(xpc_object_t object) { 73 | void *isa = *(void * volatile *)(OS_OBJECT_BRIDGE void *)object; 74 | (void)isa; 75 | } 76 | #else // OS_OBJECT_USE_OBJC 77 | typedef void * xpc_object_t; 78 | #define XPC_DECL(name) typedef struct _##name##_s * name##_t 79 | #define XPC_GLOBAL_OBJECT(object) (&(object)) 80 | #define XPC_RETURNS_RETAINED 81 | #endif // OS_OBJECT_USE_OBJC 82 | 83 | /*! 84 | * @typedef xpc_handler_t 85 | * The type of block that is accepted by the XPC connection APIs. 86 | * 87 | * @param object 88 | * An XPC object that is to be handled. If there was an error, this object will 89 | * be equal to one of the well-known XPC_ERROR_* dictionaries and can be 90 | * compared with the equality operator. 91 | * 92 | * @discussion 93 | * You are not responsible for releasing the event object. 94 | */ 95 | #if __BLOCKS__ 96 | typedef void (^xpc_handler_t)(xpc_object_t object); 97 | #endif // __BLOCKS__ 98 | 99 | /*! 100 | * @define XPC_TYPE_CONNECTION 101 | * A type representing a connection to a named service. This connection is 102 | * bidirectional and can be used to both send and receive messages. A 103 | * connection carries the credentials of the remote service provider. 104 | */ 105 | #define XPC_TYPE_CONNECTION (&_xpc_type_connection) 106 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 107 | XPC_EXPORT 108 | XPC_TYPE(_xpc_type_connection); 109 | XPC_DECL(xpc_connection); 110 | 111 | /*! 112 | * @typedef xpc_connection_handler_t 113 | * The type of the function that will be invoked for a bundled XPC service when 114 | * there is a new connection on the service. 115 | * 116 | * @param connection 117 | * A new connection that is equivalent to one received by a listener connection. 118 | * See the documentation for {@link xpc_connection_set_event_handler} for the 119 | * semantics associated with the received connection. 120 | */ 121 | typedef void (*xpc_connection_handler_t)(xpc_connection_t connection); 122 | 123 | /*! 124 | * @define XPC_TYPE_ENDPOINT 125 | * A type representing a connection in serialized form. Unlike a connection, an 126 | * endpoint is an inert object that does not have any runtime activity 127 | * associated with it. Thus, it is safe to pass an endpoint in a message. Upon 128 | * receiving an endpoint, the recipient can use 129 | * xpc_connection_create_from_endpoint() to create as many distinct connections 130 | * as desired. 131 | */ 132 | #define XPC_TYPE_ENDPOINT (&_xpc_type_endpoint) 133 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 134 | XPC_EXPORT 135 | XPC_TYPE(_xpc_type_endpoint); 136 | XPC_DECL(xpc_endpoint); 137 | 138 | /*! 139 | * @define XPC_TYPE_NULL 140 | * A type representing a null object. This type is useful for disambiguating 141 | * an unset key in a dictionary and one which has been reserved but set empty. 142 | * Also, this type is a way to represent a "null" value in dictionaries, which 143 | * do not accept NULL. 144 | */ 145 | #define XPC_TYPE_NULL (&_xpc_type_null) 146 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 147 | XPC_EXPORT 148 | XPC_TYPE(_xpc_type_null); 149 | 150 | /*! 151 | * @define XPC_TYPE_BOOL 152 | * A type representing a Boolean value. 153 | */ 154 | #define XPC_TYPE_BOOL (&_xpc_type_bool) 155 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 156 | XPC_EXPORT 157 | XPC_TYPE(_xpc_type_bool); 158 | 159 | /*! 160 | * @define XPC_BOOL_TRUE 161 | * A constant representing a Boolean value of true. You may compare a Boolean 162 | * object against this constant to determine its value. 163 | */ 164 | #define XPC_BOOL_TRUE XPC_GLOBAL_OBJECT(_xpc_bool_true) 165 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 166 | XPC_EXPORT 167 | const struct _xpc_bool_s _xpc_bool_true; 168 | 169 | /*! 170 | * @define XPC_BOOL_FALSE 171 | * A constant representing a Boolean value of false. You may compare a Boolean 172 | * object against this constant to determine its value. 173 | */ 174 | #define XPC_BOOL_FALSE XPC_GLOBAL_OBJECT(_xpc_bool_false) 175 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 176 | XPC_EXPORT 177 | const struct _xpc_bool_s _xpc_bool_false; 178 | 179 | /*! 180 | * @define XPC_TYPE_INT64 181 | * A type representing a signed, 64-bit integer value. 182 | */ 183 | #define XPC_TYPE_INT64 (&_xpc_type_int64) 184 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 185 | XPC_EXPORT 186 | XPC_TYPE(_xpc_type_int64); 187 | 188 | /*! 189 | * @define XPC_TYPE_UINT64 190 | * A type representing an unsigned, 64-bit integer value. 191 | */ 192 | #define XPC_TYPE_UINT64 (&_xpc_type_uint64) 193 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 194 | XPC_EXPORT 195 | XPC_TYPE(_xpc_type_uint64); 196 | 197 | /*! 198 | * @define XPC_TYPE_DOUBLE 199 | * A type representing an IEEE-compliant, double-precision floating point value. 200 | */ 201 | #define XPC_TYPE_DOUBLE (&_xpc_type_double) 202 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 203 | XPC_EXPORT 204 | XPC_TYPE(_xpc_type_double); 205 | 206 | /*! 207 | * @define XPC_TYPE_DATE 208 | * A type representing a date interval. The interval is with respect to the 209 | * Unix epoch. XPC dates are in Unix time and are thus unaware of local time 210 | * or leap seconds. 211 | */ 212 | #define XPC_TYPE_DATE (&_xpc_type_date) 213 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 214 | XPC_EXPORT 215 | XPC_TYPE(_xpc_type_date); 216 | 217 | /*! 218 | * @define XPC_TYPE_DATA 219 | * A type representing a an arbitrary buffer of bytes. 220 | */ 221 | #define XPC_TYPE_DATA (&_xpc_type_data) 222 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 223 | XPC_EXPORT 224 | XPC_TYPE(_xpc_type_data); 225 | 226 | /*! 227 | * @define XPC_TYPE_STRING 228 | * A type representing a NUL-terminated C-string. 229 | */ 230 | #define XPC_TYPE_STRING (&_xpc_type_string) 231 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 232 | XPC_EXPORT 233 | XPC_TYPE(_xpc_type_string); 234 | 235 | /*! 236 | * @define XPC_TYPE_UUID 237 | * A type representing a Universally Unique Identifier as defined by uuid(3). 238 | */ 239 | #define XPC_TYPE_UUID (&_xpc_type_uuid) 240 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 241 | XPC_EXPORT 242 | XPC_TYPE(_xpc_type_uuid); 243 | 244 | /*! 245 | * @define XPC_TYPE_FD 246 | * A type representing a POSIX file descriptor. 247 | */ 248 | #define XPC_TYPE_FD (&_xpc_type_fd) 249 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 250 | XPC_EXPORT 251 | XPC_TYPE(_xpc_type_fd); 252 | 253 | /*! 254 | * @define XPC_TYPE_SHMEM 255 | * A type representing a region of shared memory. 256 | */ 257 | #define XPC_TYPE_SHMEM (&_xpc_type_shmem) 258 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 259 | XPC_EXPORT 260 | XPC_TYPE(_xpc_type_shmem); 261 | 262 | /*! 263 | * @define XPC_TYPE_ARRAY 264 | * A type representing an array of XPC objects. This array must be contiguous, 265 | * i.e. it cannot contain NULL values. If you wish to indicate that a slot 266 | * is empty, you can insert a null object. The array will grow as needed to 267 | * accommodate more objects. 268 | */ 269 | #define XPC_TYPE_ARRAY (&_xpc_type_array) 270 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 271 | XPC_EXPORT 272 | XPC_TYPE(_xpc_type_array); 273 | 274 | /*! 275 | * @define XPC_TYPE_DICTIONARY 276 | * A type representing a dictionary of XPC objects, keyed off of C-strings. 277 | * You may insert NULL values into this collection. The dictionary will grow 278 | * as needed to accommodate more key/value pairs. 279 | */ 280 | #define XPC_TYPE_DICTIONARY (&_xpc_type_dictionary) 281 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 282 | XPC_EXPORT 283 | XPC_TYPE(_xpc_type_dictionary); 284 | 285 | /*! 286 | * @define XPC_TYPE_ERROR 287 | * A type representing an error object. Errors in XPC are dictionaries, but 288 | * xpc_get_type() will return this type when given an error object. You 289 | * cannot create an error object directly; XPC will only give them to handlers. 290 | * These error objects have pointer values that are constant across the lifetime 291 | * of your process and can be safely compared. 292 | * 293 | * These constants are enumerated in the header for the connection object. Error 294 | * dictionaries may reserve keys so that they can be queried to obtain more 295 | * detailed information about the error. Currently, the only reserved key is 296 | * XPC_ERROR_KEY_DESCRIPTION. 297 | */ 298 | #define XPC_TYPE_ERROR (&_xpc_type_error) 299 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 300 | XPC_EXPORT 301 | XPC_TYPE(_xpc_type_error); 302 | 303 | /*! 304 | * @define XPC_ERROR_KEY_DESCRIPTION 305 | * In an error dictionary, querying for this key will return a string object 306 | * that describes the error in a human-readable way. 307 | */ 308 | #define XPC_ERROR_KEY_DESCRIPTION _xpc_error_key_description 309 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 310 | XPC_EXPORT 311 | const char *const _xpc_error_key_description; 312 | 313 | /*! 314 | * @define XPC_EVENT_KEY_NAME 315 | * In an event dictionary, this querying for this key will return a string 316 | * object that describes the event. 317 | */ 318 | #define XPC_EVENT_KEY_NAME _xpc_event_key_name 319 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 320 | XPC_EXPORT 321 | const char *const _xpc_event_key_name; 322 | 323 | XPC_ASSUME_NONNULL_END 324 | #ifndef __XPC_BUILDING_XPC__ 325 | #include 326 | #include 327 | #if __BLOCKS__ 328 | #include 329 | #include 330 | #endif // __BLOCKS__ 331 | #undef __XPC_INDIRECT__ 332 | #include 333 | #endif // __XPC_BUILDING_XPC__ 334 | XPC_ASSUME_NONNULL_BEGIN 335 | 336 | #pragma mark XPC Object Protocol 337 | /*! 338 | * @function xpc_retain 339 | * 340 | * @abstract 341 | * Increments the reference count of an object. 342 | * 343 | * @param object 344 | * The object which is to be manipulated. 345 | * 346 | * @result 347 | * The object which was given. 348 | * 349 | * @discussion 350 | * Calls to xpc_retain() must be balanced with calls to xpc_release() 351 | * to avoid leaking memory. 352 | */ 353 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 354 | XPC_EXPORT XPC_NONNULL1 355 | xpc_object_t 356 | xpc_retain(xpc_object_t object); 357 | #if OS_OBJECT_USE_OBJC_RETAIN_RELEASE 358 | #undef xpc_retain 359 | #define xpc_retain(object) ({ xpc_object_t _o = (object); \ 360 | _xpc_object_validate(_o); [_o retain]; }) 361 | #endif // OS_OBJECT_USE_OBJC_RETAIN_RELEASE 362 | 363 | /*! 364 | * @function xpc_release 365 | * 366 | * @abstract 367 | * Decrements the reference count of an object. 368 | * 369 | * @param object 370 | * The object which is to be manipulated. 371 | * 372 | * @discussion 373 | * The caller must take care to balance retains and releases. When creating or 374 | * retaining XPC objects, the creator obtains a reference on the object. Thus, 375 | * it is the caller's responsibility to call xpc_release() on those objects when 376 | * they are no longer needed. 377 | */ 378 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 379 | XPC_EXPORT XPC_NONNULL1 380 | void 381 | xpc_release(xpc_object_t object); 382 | #if OS_OBJECT_USE_OBJC_RETAIN_RELEASE 383 | #undef xpc_release 384 | #define xpc_release(object) ({ xpc_object_t _o = (object); \ 385 | _xpc_object_validate(_o); [_o release]; }) 386 | #endif // OS_OBJECT_USE_OBJC_RETAIN_RELEASE 387 | 388 | /*! 389 | * @function xpc_get_type 390 | * 391 | * @abstract 392 | * Returns the type of an object. 393 | * 394 | * @param object 395 | * The object to examine. 396 | * 397 | * @result 398 | * An opaque pointer describing the type of the object. This pointer is suitable 399 | * direct comparison to exported type constants with the equality operator. 400 | */ 401 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 402 | XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT 403 | xpc_type_t 404 | xpc_get_type(xpc_object_t object); 405 | 406 | /*! 407 | * @function xpc_copy 408 | * 409 | * @abstract 410 | * Creates a copy of the object. 411 | * 412 | * @param object 413 | * The object to copy. 414 | * 415 | * @result 416 | * The new object. NULL if the object type does not support copying or if 417 | * sufficient memory for the copy could not be allocated. Service objects do 418 | * not support copying. 419 | * 420 | * @discussion 421 | * When called on an array or dictionary, xpc_copy() will perform a deep copy. 422 | * 423 | * The object returned is not necessarily guaranteed to be a new object, and 424 | * whether it is will depend on the implementation of the object being copied. 425 | */ 426 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 427 | XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT XPC_RETURNS_RETAINED 428 | xpc_object_t _Nullable 429 | xpc_copy(xpc_object_t object); 430 | 431 | /*! 432 | * @function xpc_equal 433 | * 434 | * @abstract 435 | * Compares two objects for equality. 436 | * 437 | * @param object1 438 | * The first object to compare. 439 | * 440 | * @param object2 441 | * The second object to compare. 442 | * 443 | * @result 444 | * Returns true if the objects are equal, otherwise false. Two objects must be 445 | * of the same type in order to be equal. 446 | * 447 | * For two arrays to be equal, they must contain the same values at the 448 | * same indexes. For two dictionaries to be equal, they must contain the same 449 | * values for the same keys. 450 | * 451 | * Two objects being equal implies that their hashes (as returned by xpc_hash()) 452 | * are also equal. 453 | */ 454 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 455 | XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 XPC_WARN_RESULT 456 | bool 457 | xpc_equal(xpc_object_t object1, xpc_object_t object2); 458 | 459 | /*! 460 | * @function xpc_hash 461 | * 462 | * @abstract 463 | * Calculates a hash value for the given object. 464 | * 465 | * @param object 466 | * The object for which to calculate a hash value. This value may be modded 467 | * with a table size for insertion into a dictionary-like data structure. 468 | * 469 | * @result 470 | * The calculated hash value. 471 | * 472 | * @discussion 473 | * Note that the computed hash values for any particular type and value of an 474 | * object can change from across releases and platforms and should not be 475 | * assumed to be constant across all time and space or stored persistently. 476 | */ 477 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 478 | XPC_EXPORT XPC_NONNULL1 XPC_WARN_RESULT 479 | size_t 480 | xpc_hash(xpc_object_t object); 481 | 482 | /*! 483 | * @function xpc_copy_description 484 | * 485 | * @abstract 486 | * Copies a debug string describing the object. 487 | * 488 | * @param object 489 | * The object which is to be examined. 490 | * 491 | * @result 492 | * A string describing object which contains information useful for debugging. 493 | * This string should be disposed of with free(3) when done. 494 | */ 495 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 496 | XPC_EXPORT XPC_MALLOC XPC_WARN_RESULT XPC_NONNULL1 497 | char * 498 | xpc_copy_description(xpc_object_t object); 499 | 500 | #pragma mark XPC Object Types 501 | #pragma mark Null 502 | /*! 503 | * @function xpc_null_create 504 | * 505 | * @abstract 506 | * Creates an XPC object representing the null object. 507 | * 508 | * @result 509 | * A new null object. 510 | */ 511 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 512 | XPC_EXPORT XPC_RETURNS_RETAINED XPC_WARN_RESULT 513 | xpc_object_t 514 | xpc_null_create(void); 515 | 516 | #pragma mark Boolean 517 | /*! 518 | * @function xpc_bool_create 519 | * 520 | * @abstract 521 | * Creates an XPC Boolean object. 522 | * 523 | * @param value 524 | * The Boolean primitive value which is to be boxed. 525 | * 526 | * @result 527 | * A new Boolean object. 528 | */ 529 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 530 | XPC_EXPORT XPC_RETURNS_RETAINED XPC_WARN_RESULT 531 | xpc_object_t 532 | xpc_bool_create(bool value); 533 | 534 | /*! 535 | * @function xpc_bool_get_value 536 | * 537 | * @abstract 538 | * Returns the underlying Boolean value from the object. 539 | * 540 | * @param xbool 541 | * The Boolean object which is to be examined. 542 | * 543 | * @result 544 | * The underlying Boolean value or false if the given object was not an XPC 545 | * Boolean object. 546 | */ 547 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 548 | XPC_EXPORT 549 | bool 550 | xpc_bool_get_value(xpc_object_t xbool); 551 | 552 | #pragma mark Signed Integer 553 | /*! 554 | * @function xpc_int64_create 555 | * 556 | * @abstract 557 | * Creates an XPC signed integer object. 558 | * 559 | * @param value 560 | * The signed integer value which is to be boxed. 561 | * 562 | * @result 563 | * A new signed integer object. 564 | */ 565 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 566 | XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT 567 | xpc_object_t 568 | xpc_int64_create(int64_t value); 569 | 570 | /*! 571 | * @function xpc_int64_get_value 572 | * 573 | * @abstract 574 | * Returns the underlying signed 64-bit integer value from an object. 575 | * 576 | * @param xint 577 | * The signed integer object which is to be examined. 578 | * 579 | * @result 580 | * The underlying signed 64-bit value or 0 if the given object was not an XPC 581 | * integer object. 582 | */ 583 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 584 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 585 | int64_t 586 | xpc_int64_get_value(xpc_object_t xint); 587 | 588 | #pragma mark Unsigned Integer 589 | /*! 590 | * @function xpc_uint64_create 591 | * 592 | * @abstract 593 | * Creates an XPC unsigned integer object. 594 | * 595 | * @param value 596 | * The unsigned integer value which is to be boxed. 597 | * 598 | * @result 599 | * A new unsigned integer object. 600 | */ 601 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 602 | XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT 603 | xpc_object_t 604 | xpc_uint64_create(uint64_t value); 605 | 606 | /*! 607 | * @function xpc_uint64_get_value 608 | * 609 | * @abstract 610 | * Returns the underlying unsigned 64-bit integer value from an object. 611 | * 612 | * @param xuint 613 | * The unsigned integer object which is to be examined. 614 | * 615 | * @result 616 | * The underlying unsigned integer value or 0 if the given object was not an XPC 617 | * unsigned integer object. 618 | */ 619 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 620 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 621 | uint64_t 622 | xpc_uint64_get_value(xpc_object_t xuint); 623 | 624 | #pragma mark Double 625 | /*! 626 | * @function xpc_double_create 627 | * 628 | * @abstract 629 | * Creates an XPC double object. 630 | * 631 | * @param value 632 | * The floating point quantity which is to be boxed. 633 | * 634 | * @result 635 | * A new floating point object. 636 | */ 637 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 638 | XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT 639 | xpc_object_t 640 | xpc_double_create(double value); 641 | 642 | /*! 643 | * @function xpc_double_get_value 644 | * 645 | * @abstract 646 | * Returns the underlying double-precision floating point value from an object. 647 | * 648 | * @param xdouble 649 | * The floating point object which is to be examined. 650 | * 651 | * @result 652 | * The underlying floating point value or NAN if the given object was not an XPC 653 | * floating point object. 654 | */ 655 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 656 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 657 | double 658 | xpc_double_get_value(xpc_object_t xdouble); 659 | 660 | #pragma mark Date 661 | /*! 662 | * @function xpc_date_create 663 | * 664 | * @abstract 665 | * Creates an XPC date object. 666 | * 667 | * @param interval 668 | * The date interval which is to be boxed. Negative values indicate the number 669 | * of nanoseconds before the epoch. Positive values indicate the number of 670 | * nanoseconds after the epoch. 671 | * 672 | * @result 673 | * A new date object. 674 | */ 675 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 676 | XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT 677 | xpc_object_t 678 | xpc_date_create(int64_t interval); 679 | 680 | /*! 681 | * @function xpc_date_create_from_current 682 | * 683 | * @abstract 684 | * Creates an XPC date object representing the current date. 685 | * 686 | * @result 687 | * A new date object representing the current date. 688 | */ 689 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 690 | XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT 691 | xpc_object_t 692 | xpc_date_create_from_current(void); 693 | 694 | /*! 695 | * @function xpc_date_get_value 696 | * 697 | * @abstract 698 | * Returns the underlying date interval from an object. 699 | * 700 | * @param xdate 701 | * The date object which is to be examined. 702 | * 703 | * @result 704 | * The underlying date interval or 0 if the given object was not an XPC date 705 | * object. 706 | */ 707 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 708 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 709 | int64_t 710 | xpc_date_get_value(xpc_object_t xdate); 711 | 712 | #pragma mark Data 713 | /*! 714 | * @function xpc_data_create 715 | * 716 | * @abstract 717 | * Creates an XPC object representing buffer of bytes. 718 | * 719 | * @param bytes 720 | * The buffer of bytes which is to be boxed. You may create an empty data object 721 | * by passing NULL for this parameter and 0 for the length. Passing NULL with 722 | * any other length will result in undefined behavior. 723 | * 724 | * @param length 725 | * The number of bytes which are to be boxed. 726 | * 727 | * @result 728 | * A new data object. 729 | * 730 | * @discussion 731 | * This method will copy the buffer given into internal storage. After calling 732 | * this method, it is safe to dispose of the given buffer. 733 | */ 734 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 735 | XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT 736 | xpc_object_t 737 | xpc_data_create(const void * _Nullable bytes, size_t length); 738 | 739 | /*! 740 | * @function xpc_data_create_with_dispatch_data 741 | * 742 | * @abstract 743 | * Creates an XPC object representing buffer of bytes described by the given GCD 744 | * data object. 745 | * 746 | * @param ddata 747 | * The GCD data object containing the bytes which are to be boxed. This object 748 | * is retained by the data object. 749 | * 750 | * @result 751 | * A new data object. 752 | * 753 | * @discussion 754 | * The object returned by this method will refer to the buffer returned by 755 | * dispatch_data_create_map(). The point where XPC will make the call to 756 | * dispatch_data_create_map() is undefined. 757 | */ 758 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 759 | XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1 760 | xpc_object_t 761 | xpc_data_create_with_dispatch_data(dispatch_data_t ddata); 762 | 763 | /*! 764 | * @function xpc_data_get_length 765 | * 766 | * @abstract 767 | * Returns the length of the data encapsulated by an XPC data object. 768 | * 769 | * @param xdata 770 | * The data object which is to be examined. 771 | * 772 | * @result 773 | * The length of the underlying boxed data or 0 if the given object was not an 774 | * XPC data object. 775 | */ 776 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 777 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 778 | size_t 779 | xpc_data_get_length(xpc_object_t xdata); 780 | 781 | /*! 782 | * @function xpc_data_get_bytes_ptr 783 | * 784 | * @abstract 785 | * Returns a pointer to the internal storage of a data object. 786 | * 787 | * @param xdata 788 | * The data object which is to be examined. 789 | * 790 | * @result 791 | * A pointer to the underlying boxed data or NULL if the given object was not an 792 | * XPC data object. 793 | */ 794 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 795 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 796 | const void * _Nullable 797 | xpc_data_get_bytes_ptr(xpc_object_t xdata); 798 | 799 | /*! 800 | * @function xpc_data_get_bytes 801 | * 802 | * @abstract 803 | * Copies the bytes stored in an data objects into the specified buffer. 804 | * 805 | * @param xdata 806 | * The data object which is to be examined. 807 | * 808 | * @param buffer 809 | * The buffer in which to copy the data object's bytes. 810 | * 811 | * @param off 812 | * The offset at which to begin the copy. If this offset is greater than the 813 | * length of the data element, nothing is copied. Pass 0 to start the copy 814 | * at the beginning of the buffer. 815 | * 816 | * @param length 817 | * The length of the destination buffer. 818 | * 819 | * @result 820 | * The number of bytes that were copied into the buffer or 0 if the given object 821 | * was not an XPC data object. 822 | */ 823 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 824 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 XPC_NONNULL2 825 | size_t 826 | xpc_data_get_bytes(xpc_object_t xdata, 827 | void *buffer, size_t off, size_t length); 828 | 829 | #pragma mark String 830 | /*! 831 | * @function xpc_string_create 832 | * 833 | * @abstract 834 | * Creates an XPC object representing a NUL-terminated C-string. 835 | * 836 | * @param string 837 | * The C-string which is to be boxed. 838 | * 839 | * @result 840 | * A new string object. 841 | */ 842 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 843 | XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1 844 | xpc_object_t 845 | xpc_string_create(const char *string); 846 | 847 | /*! 848 | * @function xpc_string_create_with_format 849 | * 850 | * @abstract 851 | * Creates an XPC object representing a C-string that is generated from the 852 | * given format string and arguments. 853 | * 854 | * @param fmt 855 | * The printf(3)-style format string from which to construct the final C-string 856 | * to be boxed. 857 | * 858 | * @param ... 859 | * The arguments which correspond to those specified in the format string. 860 | * 861 | * @result 862 | * A new string object. 863 | */ 864 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 865 | XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1 866 | XPC_PRINTF(1, 2) 867 | xpc_object_t 868 | xpc_string_create_with_format(const char *fmt, ...); 869 | 870 | /*! 871 | * @function xpc_string_create_with_format_and_arguments 872 | * 873 | * @abstract 874 | * Creates an XPC object representing a C-string that is generated from the 875 | * given format string and argument list pointer. 876 | * 877 | * @param fmt 878 | * The printf(3)-style format string from which to construct the final C-string 879 | * to be boxed. 880 | * 881 | * @param ap 882 | * A pointer to the arguments which correspond to those specified in the format 883 | * string. 884 | * 885 | * @result 886 | * A new string object. 887 | */ 888 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 889 | XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1 890 | XPC_PRINTF(1, 0) 891 | xpc_object_t 892 | xpc_string_create_with_format_and_arguments(const char *fmt, va_list ap); 893 | 894 | /*! 895 | * @function xpc_string_get_length 896 | * 897 | * @abstract 898 | * Returns the length of the underlying string. 899 | * 900 | * @param xstring 901 | * The string object which is to be examined. 902 | * 903 | * @result 904 | * The length of the underlying string, not including the NUL-terminator, or 0 905 | * if the given object was not an XPC string object. 906 | */ 907 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 908 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL 909 | size_t 910 | xpc_string_get_length(xpc_object_t xstring); 911 | 912 | /*! 913 | * @function xpc_string_get_string_ptr 914 | * 915 | * @abstract 916 | * Returns a pointer to the internal storage of a string object. 917 | * 918 | * @param xstring 919 | * The string object which is to be examined. 920 | * 921 | * @result 922 | * A pointer to the string object's internal storage or NULL if the given object 923 | * was not an XPC string object. 924 | */ 925 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 926 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 927 | const char * _Nullable 928 | xpc_string_get_string_ptr(xpc_object_t xstring); 929 | 930 | #pragma mark UUID 931 | /*! 932 | * @function xpc_uuid_create 933 | * 934 | * @abstract 935 | * Creates an XPC object representing a universally-unique identifier (UUID) as 936 | * described by uuid(3). 937 | * 938 | * @param uuid 939 | * The UUID which is to be boxed. 940 | * 941 | * @result 942 | * A new UUID object. 943 | */ 944 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 945 | XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1 946 | xpc_object_t 947 | xpc_uuid_create(const uuid_t XPC_NONNULL_ARRAY uuid); 948 | 949 | /*! 950 | * @function xpc_uuid_get_bytes 951 | * 952 | * @abstract 953 | * Returns a pointer to the the boxed UUID bytes in an XPC UUID object. 954 | * 955 | * @param xuuid 956 | * The UUID object which is to be examined. 957 | * 958 | * @result 959 | * The underlying uuid_t bytes or NULL if the given object was not 960 | * an XPC UUID object. The returned pointer may be safely passed to the uuid(3) 961 | * APIs. 962 | */ 963 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 964 | XPC_EXPORT XPC_NONNULL1 965 | const uint8_t * _Nullable 966 | xpc_uuid_get_bytes(xpc_object_t xuuid); 967 | 968 | #pragma mark File Descriptors 969 | /*! 970 | * @function xpc_fd_create 971 | * 972 | * @abstract 973 | * Creates an XPC object representing a POSIX file descriptor. 974 | * 975 | * @param fd 976 | * The file descriptor which is to be boxed. 977 | * 978 | * @result 979 | * A new file descriptor object. NULL if sufficient memory could not be 980 | * allocated or if the given file descriptor was not valid. 981 | * 982 | * @discussion 983 | * This method performs the equivalent of a dup(2) on the descriptor, and thus 984 | * it is safe to call close(2) on the descriptor after boxing it with a file 985 | * descriptor object. 986 | * 987 | * IMPORTANT: Pointer equality is the ONLY valid test for equality between two 988 | * file descriptor objects. There is no reliable way to determine whether two 989 | * file descriptors refer to the same inode with the same capabilities, so two 990 | * file descriptor objects created from the same underlying file descriptor 991 | * number will not compare equally with xpc_equal(). This is also true of a 992 | * file descriptor object created using xpc_copy() and the original. 993 | * 994 | * This also implies that two collections containing file descriptor objects 995 | * cannot be equal unless the exact same object was inserted into both. 996 | */ 997 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 998 | XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT 999 | xpc_object_t _Nullable 1000 | xpc_fd_create(int fd); 1001 | 1002 | /*! 1003 | * @function xpc_fd_dup 1004 | * 1005 | * @abstract 1006 | * Returns a file descriptor that is equivalent to the one boxed by the file 1007 | * file descriptor object. 1008 | * 1009 | * @param xfd 1010 | * The file descriptor object which is to be examined. 1011 | * 1012 | * @result 1013 | * A file descriptor that is equivalent to the one originally given to 1014 | * xpc_fd_create(). If the descriptor could not be created or if the given 1015 | * object was not an XPC file descriptor, -1 is returned. 1016 | * 1017 | * @discussion 1018 | * Multiple invocations of xpc_fd_dup() will not return the same file descriptor 1019 | * number, but they will return descriptors that are equivalent, as though they 1020 | * had been created by dup(2). 1021 | * 1022 | * The caller is responsible for calling close(2) on the returned descriptor. 1023 | */ 1024 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1025 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 1026 | int 1027 | xpc_fd_dup(xpc_object_t xfd); 1028 | 1029 | #pragma mark Shared Memory 1030 | /*! 1031 | * @function xpc_shmem_create 1032 | * 1033 | * @abstract 1034 | * Creates an XPC object representing the given shared memory region. 1035 | * 1036 | * @param region 1037 | * A pointer to a region of shared memory, created through a call to mmap(2) 1038 | * with the MAP_SHARED flag, which is to be boxed. 1039 | * 1040 | * @param length 1041 | * The length of the region. 1042 | * 1043 | * @result 1044 | * A new shared memory object. 1045 | * 1046 | * @discussion 1047 | * Only memory regions whose exact characteristics are known to the caller 1048 | * should be boxed using this API. Memory returned from malloc(3) may not be 1049 | * safely shared on either OS X or iOS because the underlying virtual memory 1050 | * objects for malloc(3)ed allocations are owned by the malloc(3) subsystem and 1051 | * not the caller of malloc(3). 1052 | * 1053 | * If you wish to share a memory region that you receive from another subsystem, 1054 | * part of the interface contract with that other subsystem must include how to 1055 | * create the region of memory, or sharing it may be unsafe. 1056 | * 1057 | * Certain operations may internally fragment a region of memory in a way that 1058 | * would truncate the range detected by the shared memory object. vm_copy(), for 1059 | * example, may split the region into multiple parts to avoid copying certain 1060 | * page ranges. For this reason, it is recommended that you delay all VM 1061 | * operations until the shared memory object has been created so that the VM 1062 | * system knows that the entire range is intended for sharing. 1063 | */ 1064 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1065 | XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1 1066 | xpc_object_t 1067 | xpc_shmem_create(void *region, size_t length); 1068 | 1069 | /*! 1070 | * @function xpc_shmem_map 1071 | * 1072 | * @abstract 1073 | * Maps the region boxed by the XPC shared memory object into the caller's 1074 | * address space. 1075 | * 1076 | * @param xshmem 1077 | * The shared memory object to be examined. 1078 | * 1079 | * @param region 1080 | * On return, this will point to the region at which the shared memory was 1081 | * mapped. 1082 | * 1083 | * @result 1084 | * The length of the region that was mapped. If the mapping failed or if the 1085 | * given object was not an XPC shared memory object, 0 is returned. The length 1086 | * of the mapped region will always be an integral page size, even if the 1087 | * creator of the region specified a non-integral page size. 1088 | * 1089 | * @discussion 1090 | * The resulting region must be disposed of with munmap(2). 1091 | * 1092 | * It is the responsibility of the caller to manage protections on the new 1093 | * region accordingly. 1094 | */ 1095 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1096 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL 1097 | size_t 1098 | xpc_shmem_map(xpc_object_t xshmem, void * _Nullable * _Nonnull region); 1099 | 1100 | #pragma mark Array 1101 | /*! 1102 | * @typedef xpc_array_applier_t 1103 | * A block to be invoked for every value in the array. 1104 | * 1105 | * @param index 1106 | * The current index in the iteration. 1107 | * 1108 | * @param value 1109 | * The current value in the iteration. 1110 | * 1111 | * @result 1112 | * A Boolean indicating whether iteration should continue. 1113 | */ 1114 | #ifdef __BLOCKS__ 1115 | typedef bool (^xpc_array_applier_t)(size_t index, xpc_object_t _Nonnull value); 1116 | #endif // __BLOCKS__ 1117 | 1118 | /*! 1119 | * @function xpc_array_create 1120 | * 1121 | * @abstract 1122 | * Creates an XPC object representing an array of XPC objects. 1123 | * 1124 | * @discussion 1125 | * This array must be contiguous and cannot contain any NULL values. If you 1126 | * wish to insert the equivalent of a NULL value, you may use the result of 1127 | * {@link xpc_null_create}. 1128 | * 1129 | * @param objects 1130 | * An array of XPC objects which is to be boxed. The order of this array is 1131 | * preserved in the object. If this array contains a NULL value, the behavior 1132 | * is undefined. This parameter may be NULL only if the count is 0. 1133 | * 1134 | * @param count 1135 | * The number of objects in the given array. If the number passed is less than 1136 | * the actual number of values in the array, only the specified number of items 1137 | * are inserted into the resulting array. If the number passed is more than 1138 | * the the actual number of values, the behavior is undefined. 1139 | * 1140 | * @result 1141 | * A new array object. 1142 | */ 1143 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1144 | XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT 1145 | xpc_object_t 1146 | xpc_array_create(const xpc_object_t _Nonnull * _Nullable objects, size_t count); 1147 | 1148 | /*! 1149 | * @function xpc_array_set_value 1150 | * 1151 | * @abstract 1152 | * Inserts the specified object into the array at the specified index. 1153 | * 1154 | * @param xarray 1155 | * The array object which is to be manipulated. 1156 | * 1157 | * @param index 1158 | * The index at which to insert the value. This value must lie within the index 1159 | * space of the array (0 to N-1 inclusive, where N is the count of the array). 1160 | * If the index is outside that range, the behavior is undefined. 1161 | * 1162 | * @param value 1163 | * The object to insert. This value is retained by the array and cannot be 1164 | * NULL. If there is already a value at the specified index, it is released, 1165 | * and the new value is inserted in its place. 1166 | */ 1167 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1168 | XPC_EXPORT XPC_NONNULL1 XPC_NONNULL3 1169 | void 1170 | xpc_array_set_value(xpc_object_t xarray, size_t index, xpc_object_t value); 1171 | 1172 | /*! 1173 | * @function xpc_array_append_value 1174 | * 1175 | * @abstract 1176 | * Appends an object to an XPC array. 1177 | * 1178 | * @param xarray 1179 | * The array object which is to be manipulated. 1180 | * 1181 | * @param value 1182 | * The object to append. This object is retained by the array. 1183 | */ 1184 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1185 | XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 1186 | void 1187 | xpc_array_append_value(xpc_object_t xarray, xpc_object_t value); 1188 | 1189 | /*! 1190 | * @function xpc_array_get_count 1191 | * 1192 | * @abstract 1193 | * Returns the count of values currently in the array. 1194 | * 1195 | * @param xarray 1196 | * The array object which is to be examined. 1197 | * 1198 | * @result 1199 | * The count of values in the array or 0 if the given object was not an XPC 1200 | * array. 1201 | */ 1202 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1203 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 1204 | size_t 1205 | xpc_array_get_count(xpc_object_t xarray); 1206 | 1207 | /*! 1208 | * @function xpc_array_get_value 1209 | * 1210 | * @abstract 1211 | * Returns the value at the specified index in the array. 1212 | * 1213 | * @param xarray 1214 | * The array object which is to be examined. 1215 | * 1216 | * @param index 1217 | * The index of the value to obtain. This value must lie within the range of 1218 | * indexes as specified in xpc_array_set_value(). 1219 | * 1220 | * @result 1221 | * The object at the specified index within the array or NULL if the given 1222 | * object was not an XPC array. 1223 | * 1224 | * @discussion 1225 | * This method does not grant the caller a reference to the underlying object, 1226 | * and thus the caller is not responsible for releasing the object. 1227 | */ 1228 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1229 | XPC_EXPORT XPC_NONNULL_ALL 1230 | xpc_object_t 1231 | xpc_array_get_value(xpc_object_t xarray, size_t index); 1232 | 1233 | /*! 1234 | * @function xpc_array_apply 1235 | * 1236 | * @abstract 1237 | * Invokes the given block for every value in the array. 1238 | * 1239 | * @param xarray 1240 | * The array object which is to be examined. 1241 | * 1242 | * @param applier 1243 | * The block which this function applies to every element in the array. 1244 | * 1245 | * @result 1246 | * A Boolean indicating whether iteration of the array completed successfully. 1247 | * Iteration will only fail if the applier block returns false. 1248 | * 1249 | * @discussion 1250 | * You should not modify an array's contents during iteration. The array indexes 1251 | * are iterated in order. 1252 | */ 1253 | #ifdef __BLOCKS__ 1254 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1255 | XPC_EXPORT XPC_NONNULL_ALL 1256 | bool 1257 | xpc_array_apply(xpc_object_t xarray, XPC_NOESCAPE xpc_array_applier_t applier); 1258 | #endif // __BLOCKS__ 1259 | 1260 | #pragma mark Array Primitive Setters 1261 | /*! 1262 | * @define XPC_ARRAY_APPEND 1263 | * A constant that may be passed as the destination index to the class of 1264 | * primitive XPC array setters indicating that the given primitive should be 1265 | * appended to the array. 1266 | */ 1267 | #define XPC_ARRAY_APPEND ((size_t)(-1)) 1268 | 1269 | /*! 1270 | * @function xpc_array_set_bool 1271 | * 1272 | * @abstract 1273 | * Inserts a bool (primitive) value into an array. 1274 | * 1275 | * @param xarray 1276 | * The array object which is to be manipulated. 1277 | * 1278 | * @param index 1279 | * The index at which to insert the value. This value must lie within the index 1280 | * space of the array (0 to N-1 inclusive, where N is the count of the array) or 1281 | * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is 1282 | * undefined. 1283 | * 1284 | * @param value 1285 | * The bool value to insert. After calling this method, the XPC 1286 | * object corresponding to the primitive value inserted may be safely retrieved 1287 | * with {@link xpc_array_get_value()}. 1288 | */ 1289 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1290 | XPC_EXPORT XPC_NONNULL1 1291 | void 1292 | xpc_array_set_bool(xpc_object_t xarray, size_t index, bool value); 1293 | 1294 | /*! 1295 | * @function xpc_array_set_int64 1296 | * 1297 | * @abstract 1298 | * Inserts an int64_t (primitive) value into an array. 1299 | * 1300 | * @param xarray 1301 | * The array object which is to be manipulated. 1302 | * 1303 | * @param index 1304 | * The index at which to insert the value. This value must lie within the index 1305 | * space of the array (0 to N-1 inclusive, where N is the count of the array) or 1306 | * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is 1307 | * undefined. 1308 | * 1309 | * @param value 1310 | * The int64_t value to insert. After calling this method, the XPC 1311 | * object corresponding to the primitive value inserted may be safely retrieved 1312 | * with {@link xpc_array_get_value()}. 1313 | */ 1314 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1315 | XPC_EXPORT XPC_NONNULL1 1316 | void 1317 | xpc_array_set_int64(xpc_object_t xarray, size_t index, int64_t value); 1318 | 1319 | /*! 1320 | * @function xpc_array_set_uint64 1321 | * 1322 | * @abstract 1323 | * Inserts a uint64_t (primitive) value into an array. 1324 | * 1325 | * @param xarray 1326 | * The array object which is to be manipulated. 1327 | * 1328 | * @param index 1329 | * The index at which to insert the value. This value must lie within the index 1330 | * space of the array (0 to N-1 inclusive, where N is the count of the array) or 1331 | * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is 1332 | * undefined. 1333 | * 1334 | * @param value 1335 | * The uint64_t value to insert. After calling this method, the XPC 1336 | * object corresponding to the primitive value inserted may be safely retrieved 1337 | * with {@link xpc_array_get_value()}. 1338 | */ 1339 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1340 | XPC_EXPORT XPC_NONNULL1 1341 | void 1342 | xpc_array_set_uint64(xpc_object_t xarray, size_t index, uint64_t value); 1343 | 1344 | /*! 1345 | * @function xpc_array_set_double 1346 | * 1347 | * @abstract 1348 | * Inserts a double (primitive) value into an array. 1349 | * 1350 | * @param xarray 1351 | * The array object which is to be manipulated. 1352 | * 1353 | * @param index 1354 | * The index at which to insert the value. This value must lie within the index 1355 | * space of the array (0 to N-1 inclusive, where N is the count of the array) or 1356 | * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is 1357 | * undefined. 1358 | * 1359 | * @param value 1360 | * The double value to insert. After calling this method, the XPC 1361 | * object corresponding to the primitive value inserted may be safely retrieved 1362 | * with {@link xpc_array_get_value()}. 1363 | */ 1364 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1365 | XPC_EXPORT XPC_NONNULL1 1366 | void 1367 | xpc_array_set_double(xpc_object_t xarray, size_t index, double value); 1368 | 1369 | /*! 1370 | * @function xpc_array_set_date 1371 | * 1372 | * @abstract 1373 | * Inserts a date value into an array. 1374 | * 1375 | * @param xarray 1376 | * The array object which is to be manipulated. 1377 | * 1378 | * @param index 1379 | * The index at which to insert the value. This value must lie within the index 1380 | * space of the array (0 to N-1 inclusive, where N is the count of the array) or 1381 | * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is 1382 | * undefined. 1383 | * 1384 | * @param value 1385 | * The date value to insert, represented as an int64_t. After 1386 | * calling this method, the XPC object corresponding to the primitive value 1387 | * inserted may be safely retrieved with {@link xpc_array_get_value()}. 1388 | */ 1389 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1390 | XPC_EXPORT XPC_NONNULL1 1391 | void 1392 | xpc_array_set_date(xpc_object_t xarray, size_t index, int64_t value); 1393 | 1394 | /*! 1395 | * @function xpc_array_set_data 1396 | * 1397 | * @abstract 1398 | * Inserts a raw data value into an array. 1399 | * 1400 | * @param xarray 1401 | * The array object which is to be manipulated. 1402 | * 1403 | * @param index 1404 | * The index at which to insert the value. This value must lie within the index 1405 | * space of the array (0 to N-1 inclusive, where N is the count of the array) or 1406 | * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is 1407 | * undefined. 1408 | * 1409 | * @param bytes 1410 | * The raw data to insert. After calling this method, the XPC object 1411 | * corresponding to the primitive value inserted may be safely retrieved with 1412 | * {@link xpc_array_get_value()}. 1413 | * 1414 | * @param length 1415 | * The length of the data. 1416 | */ 1417 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1418 | XPC_EXPORT XPC_NONNULL1 XPC_NONNULL3 1419 | void 1420 | xpc_array_set_data(xpc_object_t xarray, size_t index, const void *bytes, 1421 | size_t length); 1422 | 1423 | /*! 1424 | * @function xpc_array_set_string 1425 | * 1426 | * @abstract 1427 | * Inserts a C string into an array. 1428 | * 1429 | * @param xarray 1430 | * The array object which is to be manipulated. 1431 | * 1432 | * @param index 1433 | * The index at which to insert the value. This value must lie within the index 1434 | * space of the array (0 to N-1 inclusive, where N is the count of the array) or 1435 | * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is 1436 | * undefined. 1437 | * 1438 | * @param string 1439 | * The C string to insert. After calling this method, the XPC object 1440 | * corresponding to the primitive value inserted may be safely retrieved with 1441 | * {@link xpc_array_get_value()}. 1442 | */ 1443 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1444 | XPC_EXPORT XPC_NONNULL1 XPC_NONNULL3 1445 | void 1446 | xpc_array_set_string(xpc_object_t xarray, size_t index, const char *string); 1447 | 1448 | /*! 1449 | * @function xpc_array_set_uuid 1450 | * 1451 | * @abstract 1452 | * Inserts a uuid_t (primitive) value into an array. 1453 | * 1454 | * @param xarray 1455 | * The array object which is to be manipulated. 1456 | * 1457 | * @param index 1458 | * The index at which to insert the value. This value must lie within the index 1459 | * space of the array (0 to N-1 inclusive, where N is the count of the array) or 1460 | * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is 1461 | * undefined. 1462 | * 1463 | * @param uuid 1464 | * The UUID primitive to insert. After calling this method, the XPC object 1465 | * corresponding to the primitive value inserted may be safely retrieved with 1466 | * {@link xpc_array_get_value()}. 1467 | */ 1468 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1469 | XPC_EXPORT XPC_NONNULL1 XPC_NONNULL3 1470 | void 1471 | xpc_array_set_uuid(xpc_object_t xarray, size_t index, 1472 | const uuid_t XPC_NONNULL_ARRAY uuid); 1473 | 1474 | /*! 1475 | * @function xpc_array_set_fd 1476 | * 1477 | * @abstract 1478 | * Inserts a file descriptor into an array. 1479 | * 1480 | * @param xarray 1481 | * The array object which is to be manipulated. 1482 | * 1483 | * @param index 1484 | * The index at which to insert the value. This value must lie within the index 1485 | * space of the array (0 to N-1 inclusive, where N is the count of the array) or 1486 | * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is 1487 | * undefined. 1488 | * 1489 | * @param fd 1490 | * The file descriptor to insert. After calling this method, the XPC object 1491 | * corresponding to the primitive value inserted may be safely retrieved with 1492 | * {@link xpc_array_get_value()}. 1493 | */ 1494 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1495 | XPC_EXPORT XPC_NONNULL1 1496 | void 1497 | xpc_array_set_fd(xpc_object_t xarray, size_t index, int fd); 1498 | 1499 | /*! 1500 | * @function xpc_array_set_connection 1501 | * 1502 | * @abstract 1503 | * Inserts a connection into an array. 1504 | * 1505 | * @param xarray 1506 | * The array object which is to be manipulated. 1507 | * 1508 | * @param index 1509 | * The index at which to insert the value. This value must lie within the index 1510 | * space of the array (0 to N-1 inclusive, where N is the count of the array) or 1511 | * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is 1512 | * undefined. 1513 | * 1514 | * @param connection 1515 | * The connection to insert. After calling this method, the XPC object 1516 | * corresponding to the primitive value inserted may be safely retrieved with 1517 | * {@link xpc_array_get_value()}. The connection is NOT retained by the array. 1518 | */ 1519 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1520 | XPC_EXPORT XPC_NONNULL1 XPC_NONNULL3 1521 | void 1522 | xpc_array_set_connection(xpc_object_t xarray, size_t index, 1523 | xpc_connection_t connection); 1524 | 1525 | #pragma mark Array Primitive Getters 1526 | /*! 1527 | * @function xpc_array_get_bool 1528 | * 1529 | * @abstract 1530 | * Gets a bool primitive value from an array directly. 1531 | * 1532 | * @param xarray 1533 | * The array which is to be examined. 1534 | * 1535 | * @param index 1536 | * The index of the value to obtain. This value must lie within the index space 1537 | * of the array (0 to N-1 inclusive, where N is the count of the array). If the 1538 | * index is outside that range, the behavior is undefined. 1539 | * 1540 | * @result 1541 | * The underlying bool value at the specified index. false if the 1542 | * value at the specified index is not a Boolean value. 1543 | */ 1544 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1545 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 1546 | bool 1547 | xpc_array_get_bool(xpc_object_t xarray, size_t index); 1548 | 1549 | /*! 1550 | * @function xpc_array_get_int64 1551 | * 1552 | * @abstract 1553 | * Gets an int64_t primitive value from an array directly. 1554 | * 1555 | * @param xarray 1556 | * The array which is to be examined. 1557 | * 1558 | * @param index 1559 | * The index of the value to obtain. This value must lie within the index space 1560 | * of the array (0 to N-1 inclusive, where N is the count of the array). If the 1561 | * index is outside that range, the behavior is undefined. 1562 | * 1563 | * @result 1564 | * The underlying int64_t value at the specified index. 0 if the 1565 | * value at the specified index is not a signed integer value. 1566 | */ 1567 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1568 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 1569 | int64_t 1570 | xpc_array_get_int64(xpc_object_t xarray, size_t index); 1571 | 1572 | /*! 1573 | * @function xpc_array_get_uint64 1574 | * 1575 | * @abstract 1576 | * Gets a uint64_t primitive value from an array directly. 1577 | * 1578 | * @param xarray 1579 | * The array which is to be examined. 1580 | * 1581 | * @param index 1582 | * The index of the value to obtain. This value must lie within the index space 1583 | * of the array (0 to N-1 inclusive, where N is the count of the array). If the 1584 | * index is outside that range, the behavior is undefined. 1585 | * 1586 | * @result 1587 | * The underlying uint64_t value at the specified index. 0 if the 1588 | * value at the specified index is not an unsigned integer value. 1589 | */ 1590 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1591 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 1592 | uint64_t 1593 | xpc_array_get_uint64(xpc_object_t xarray, size_t index); 1594 | 1595 | /*! 1596 | * @function xpc_array_get_double 1597 | * 1598 | * @abstract 1599 | * Gets a double primitive value from an array directly. 1600 | * 1601 | * @param xarray 1602 | * The array which is to be examined. 1603 | * 1604 | * @param index 1605 | * The index of the value to obtain. This value must lie within the index space 1606 | * of the array (0 to N-1 inclusive, where N is the count of the array). If the 1607 | * index is outside that range, the behavior is undefined. 1608 | * 1609 | * @result 1610 | * The underlying double value at the specified index. NAN if the 1611 | * value at the specified index is not a floating point value. 1612 | */ 1613 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1614 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 1615 | double 1616 | xpc_array_get_double(xpc_object_t xarray, size_t index); 1617 | 1618 | /*! 1619 | * @function xpc_array_get_date 1620 | * 1621 | * @abstract 1622 | * Gets a date interval from an array directly. 1623 | * 1624 | * @param xarray 1625 | * The array which is to be examined. 1626 | * 1627 | * @param index 1628 | * The index of the value to obtain. This value must lie within the index space 1629 | * of the array (0 to N-1 inclusive, where N is the count of the array). If the 1630 | * index is outside that range, the behavior is undefined. 1631 | * 1632 | * @result 1633 | * The underlying date interval at the specified index. 0 if the value at the 1634 | * specified index is not a date value. 1635 | */ 1636 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1637 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 1638 | int64_t 1639 | xpc_array_get_date(xpc_object_t xarray, size_t index); 1640 | 1641 | /*! 1642 | * @function xpc_array_get_data 1643 | * 1644 | * @abstract 1645 | * Gets a pointer to the raw bytes of a data object from an array directly. 1646 | * 1647 | * @param xarray 1648 | * The array which is to be examined. 1649 | * 1650 | * @param index 1651 | * The index of the value to obtain. This value must lie within the index space 1652 | * of the array (0 to N-1 inclusive, where N is the count of the array). If the 1653 | * index is outside that range, the behavior is undefined. 1654 | * 1655 | * @param length 1656 | * Upon return output, will contain the length of the data corresponding to the 1657 | * specified key. 1658 | * 1659 | * @result 1660 | * The underlying bytes at the specified index. NULL if the value at the 1661 | * specified index is not a data value. 1662 | */ 1663 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1664 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 1665 | const void * _Nullable 1666 | xpc_array_get_data(xpc_object_t xarray, size_t index, 1667 | size_t * _Nullable length); 1668 | 1669 | /*! 1670 | * @function xpc_array_get_string 1671 | * 1672 | * @abstract 1673 | * Gets a C string value from an array directly. 1674 | * 1675 | * @param xarray 1676 | * The array which is to be examined. 1677 | * 1678 | * @param index 1679 | * The index of the value to obtain. This value must lie within the index space 1680 | * of the array (0 to N-1 inclusive, where N is the count of the array). If the 1681 | * index is outside that range, the behavior is undefined. 1682 | * 1683 | * @result 1684 | * The underlying C string at the specified index. NULL if the value at the 1685 | * specified index is not a C string value. 1686 | */ 1687 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1688 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 1689 | const char * _Nullable 1690 | xpc_array_get_string(xpc_object_t xarray, size_t index); 1691 | 1692 | /*! 1693 | * @function xpc_array_get_uuid 1694 | * 1695 | * @abstract 1696 | * Gets a uuid_t value from an array directly. 1697 | * 1698 | * @param xarray 1699 | * The array which is to be examined. 1700 | * 1701 | * @param index 1702 | * The index of the value to obtain. This value must lie within the index space 1703 | * of the array (0 to N-1 inclusive, where N is the count of the array). If the 1704 | * index is outside that range, the behavior is undefined. 1705 | * 1706 | * @result 1707 | * The underlying uuid_t value at the specified index. The null 1708 | * UUID if the value at the specified index is not a UUID value. The returned 1709 | * pointer may be safely passed to the uuid(3) APIs. 1710 | */ 1711 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1712 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 1713 | const uint8_t * _Nullable 1714 | xpc_array_get_uuid(xpc_object_t xarray, size_t index); 1715 | 1716 | /*! 1717 | * @function xpc_array_dup_fd 1718 | * 1719 | * @abstract 1720 | * Gets a file descriptor from an array directly. 1721 | * 1722 | * @param xarray 1723 | * The array which is to be examined. 1724 | * 1725 | * @param index 1726 | * The index of the value to obtain. This value must lie within the index space 1727 | * of the array (0 to N-1 inclusive, where N is the count of the array). If the 1728 | * index is outside that range, the behavior is undefined. 1729 | * 1730 | * @result 1731 | * A new file descriptor created from the value at the specified index. You are 1732 | * responsible for close(2)ing this descriptor. -1 if the value at the specified 1733 | * index is not a file descriptor value. 1734 | */ 1735 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1736 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 1737 | int 1738 | xpc_array_dup_fd(xpc_object_t xarray, size_t index); 1739 | 1740 | /*! 1741 | * @function xpc_array_create_connection 1742 | * 1743 | * @abstract 1744 | * Creates a connection object from an array directly. 1745 | * 1746 | * @param xarray 1747 | * The array which is to be examined. 1748 | * 1749 | * @param index 1750 | * The index of the value to obtain. This value must lie within the index space 1751 | * of the array (0 to N-1 inclusive, where N is the count of the array). If the 1752 | * index is outside that range, the behavior is undefined. 1753 | * 1754 | * @result 1755 | * A new connection created from the value at the specified index. You are 1756 | * responsible for calling xpc_release() on the returned connection. NULL if the 1757 | * value at the specified index is not an endpoint containing a connection. Each 1758 | * call to this method for the same index in the same array will yield a 1759 | * different connection. See {@link xpc_connection_create_from_endpoint()} for 1760 | * discussion as to the responsibilities when dealing with the returned 1761 | * connection. 1762 | */ 1763 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1764 | XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1 1765 | xpc_connection_t _Nullable 1766 | xpc_array_create_connection(xpc_object_t xarray, size_t index); 1767 | 1768 | /*! 1769 | * @function xpc_array_get_dictionary 1770 | * 1771 | * @abstract 1772 | * Returns the dictionary at the specified index in the array. 1773 | * 1774 | * @param xarray 1775 | * The array object which is to be examined. 1776 | * 1777 | * @param index 1778 | * The index of the value to obtain. This value must lie within the range of 1779 | * indexes as specified in xpc_array_set_value(). 1780 | * 1781 | * @result 1782 | * The object at the specified index within the array or NULL if the given 1783 | * object was not an XPC array or if the the value at the specified index was 1784 | * not a dictionary. 1785 | * 1786 | * @discussion 1787 | * This method does not grant the caller a reference to the underlying object, 1788 | * and thus the caller is not responsible for releasing the object. 1789 | */ 1790 | __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0) 1791 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL 1792 | xpc_object_t _Nullable 1793 | xpc_array_get_dictionary(xpc_object_t self, size_t index); 1794 | 1795 | /*! 1796 | * @function xpc_array_get_array 1797 | * 1798 | * @abstract 1799 | * Returns the array at the specified index in the array. 1800 | * 1801 | * @param xarray 1802 | * The array object which is to be examined. 1803 | * 1804 | * @param index 1805 | * The index of the value to obtain. This value must lie within the range of 1806 | * indexes as specified in xpc_array_set_value(). 1807 | * 1808 | * @result 1809 | * The object at the specified index within the array or NULL if the given 1810 | * object was not an XPC array or if the the value at the specified index was 1811 | * not an array. 1812 | * 1813 | * @discussion 1814 | * This method does not grant the caller a reference to the underlying object, 1815 | * and thus the caller is not responsible for releasing the object. 1816 | */ 1817 | __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0) 1818 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL 1819 | xpc_object_t _Nullable 1820 | xpc_array_get_array(xpc_object_t self, size_t index); 1821 | 1822 | #pragma mark Dictionary 1823 | /*! 1824 | * @typedef xpc_dictionary_applier_t 1825 | * A block to be invoked for every key/value pair in the dictionary. 1826 | * 1827 | * @param key 1828 | * The current key in the iteration. 1829 | * 1830 | * @param value 1831 | * The current value in the iteration. 1832 | * 1833 | * @result 1834 | * A Boolean indicating whether iteration should continue. 1835 | */ 1836 | #ifdef __BLOCKS__ 1837 | typedef bool (^xpc_dictionary_applier_t)(const char * _Nonnull key, 1838 | xpc_object_t _Nonnull value); 1839 | #endif // __BLOCKS__ 1840 | 1841 | /*! 1842 | * @function xpc_dictionary_create 1843 | * 1844 | * @abstract 1845 | * Creates an XPC object representing a dictionary of XPC objects keyed to 1846 | * C-strings. 1847 | * 1848 | * @param keys 1849 | * An array of C-strings that are to be the keys for the values to be inserted. 1850 | * Each element of this array is copied into the dictionary's internal storage. 1851 | * Elements of this array may NOT be NULL. 1852 | * 1853 | * @param values 1854 | * A C-array that is parallel to the array of keys, consisting of objects that 1855 | * are to be inserted. Each element in this array is retained. Elements in this 1856 | * array may be NULL. 1857 | * 1858 | * @param count 1859 | * The number of key/value pairs in the given arrays. If the count is less than 1860 | * the actual count of values, only that many key/value pairs will be inserted 1861 | * into the dictionary. 1862 | * 1863 | * If the count is more than the the actual count of key/value pairs, the 1864 | * behavior is undefined. If one array is NULL and the other is not, the 1865 | * behavior is undefined. If both arrays are NULL and the count is non-0, the 1866 | * behavior is undefined. 1867 | * 1868 | * @result 1869 | * The new dictionary object. 1870 | */ 1871 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1872 | XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT 1873 | xpc_object_t 1874 | xpc_dictionary_create(const char * _Nonnull const * _Nullable keys, 1875 | const xpc_object_t _Nullable * _Nullable values, size_t count); 1876 | 1877 | /*! 1878 | * @function xpc_dictionary_create_reply 1879 | * 1880 | * @abstract 1881 | * Creates a dictionary that is in reply to the given dictionary. 1882 | * 1883 | * @param original 1884 | * The original dictionary that is to be replied to. 1885 | * 1886 | * @result 1887 | * The new dictionary object. NULL if the object was not a dictionary with a 1888 | * reply context. 1889 | * 1890 | * @discussion 1891 | * After completing successfully on a dictionary, this method may not be called 1892 | * again on that same dictionary. Attempts to do so will return NULL. 1893 | * 1894 | * When this dictionary is sent across the reply connection, the remote end's 1895 | * reply handler is invoked. 1896 | */ 1897 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1898 | XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL_ALL 1899 | xpc_object_t _Nullable 1900 | xpc_dictionary_create_reply(xpc_object_t original); 1901 | 1902 | /*! 1903 | * @function xpc_dictionary_set_value 1904 | * 1905 | * @abstract 1906 | * Sets the value for the specified key to the specified object. 1907 | * 1908 | * @param xdict 1909 | * The dictionary object which is to be manipulated. 1910 | * 1911 | * @param key 1912 | * The key for which the value shall be set. 1913 | * 1914 | * @param value 1915 | * The object to insert. The object is retained by the dictionary. If there 1916 | * already exists a value for the specified key, the old value is released 1917 | * and overwritten by the new value. This parameter may be NULL, in which case 1918 | * the value corresponding to the specified key is deleted if present. 1919 | */ 1920 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1921 | XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 1922 | void 1923 | xpc_dictionary_set_value(xpc_object_t xdict, const char *key, 1924 | xpc_object_t _Nullable value); 1925 | 1926 | /*! 1927 | * @function xpc_dictionary_get_value 1928 | * 1929 | * @abstract 1930 | * Returns the value for the specified key. 1931 | * 1932 | * @param xdict 1933 | * The dictionary object which is to be examined. 1934 | * 1935 | * @param key 1936 | * The key whose value is to be obtained. 1937 | * 1938 | * @result 1939 | * The object for the specified key within the dictionary. NULL if there is no 1940 | * value associated with the specified key or if the given object was not an 1941 | * XPC dictionary. 1942 | * 1943 | * @discussion 1944 | * This method does not grant the caller a reference to the underlying object, 1945 | * and thus the caller is not responsible for releasing the object. 1946 | */ 1947 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1948 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 XPC_NONNULL2 1949 | xpc_object_t _Nullable 1950 | xpc_dictionary_get_value(xpc_object_t xdict, const char *key); 1951 | 1952 | /*! 1953 | * @function xpc_dictionary_get_count 1954 | * 1955 | * @abstract 1956 | * Returns the number of values stored in the dictionary. 1957 | * 1958 | * @param xdict 1959 | * The dictionary object which is to be examined. 1960 | * 1961 | * @result 1962 | * The number of values stored in the dictionary or 0 if the given object was 1963 | * not an XPC dictionary. Calling xpc_dictionary_set_value() with a non-NULL 1964 | * value will increment the count. Calling xpc_dictionary_set_value() with a 1965 | * NULL value will decrement the count. 1966 | */ 1967 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1968 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 1969 | size_t 1970 | xpc_dictionary_get_count(xpc_object_t xdict); 1971 | 1972 | /*! 1973 | * @function xpc_dictionary_apply 1974 | * 1975 | * @abstract 1976 | * Invokes the given block for every key/value pair in the dictionary. 1977 | * 1978 | * @param xdict 1979 | * The dictionary object which is to be examined. 1980 | * 1981 | * @param applier 1982 | * The block which this function applies to every key/value pair in the 1983 | * dictionary. 1984 | * 1985 | * @result 1986 | * A Boolean indicating whether iteration of the dictionary completed 1987 | * successfully. Iteration will only fail if the applier block returns false. 1988 | * 1989 | * @discussion 1990 | * You should not modify a dictionary's contents during iteration. There is no 1991 | * guaranteed order of iteration over dictionaries. 1992 | */ 1993 | #ifdef __BLOCKS__ 1994 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 1995 | XPC_EXPORT XPC_NONNULL_ALL 1996 | bool 1997 | xpc_dictionary_apply(xpc_object_t xdict, 1998 | XPC_NOESCAPE xpc_dictionary_applier_t applier); 1999 | #endif // __BLOCKS__ 2000 | 2001 | /*! 2002 | * @function xpc_dictionary_get_remote_connection 2003 | * 2004 | * @abstract 2005 | * Returns the connection from which the dictionary was received. 2006 | * 2007 | * @param xdict 2008 | * The dictionary object which is to be examined. 2009 | * 2010 | * @result 2011 | * If the dictionary was received by a connection event handler or a dictionary 2012 | * created through xpc_dictionary_create_reply(), a connection object over which 2013 | * a reply message can be sent is returned. For any other dictionary, NULL is 2014 | * returned. 2015 | */ 2016 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 2017 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL 2018 | xpc_connection_t _Nullable 2019 | xpc_dictionary_get_remote_connection(xpc_object_t xdict); 2020 | 2021 | #pragma mark Dictionary Primitive Setters 2022 | /*! 2023 | * @function xpc_dictionary_set_bool 2024 | * 2025 | * @abstract 2026 | * Inserts a bool (primitive) value into a dictionary. 2027 | * 2028 | * @param xdict 2029 | * The dictionary which is to be manipulated. 2030 | * 2031 | * @param key 2032 | * The key for which the primitive value shall be set. 2033 | * 2034 | * @param value 2035 | * The bool value to insert. After calling this method, the XPC 2036 | * object corresponding to the primitive value inserted may be safely retrieved 2037 | * with {@link xpc_dictionary_get_value()}. 2038 | */ 2039 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 2040 | XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 2041 | void 2042 | xpc_dictionary_set_bool(xpc_object_t xdict, const char *key, bool value); 2043 | 2044 | /*! 2045 | * @function xpc_dictionary_set_int64 2046 | * 2047 | * @abstract 2048 | * Inserts an int64_t (primitive) value into a dictionary. 2049 | * 2050 | * @param xdict 2051 | * The dictionary which is to be manipulated. 2052 | * 2053 | * @param key 2054 | * The key for which the primitive value shall be set. 2055 | * 2056 | * @param value 2057 | * The int64_t value to insert. After calling this method, the XPC 2058 | * object corresponding to the primitive value inserted may be safely retrieved 2059 | * with {@link xpc_dictionary_get_value()}. 2060 | */ 2061 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 2062 | XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 2063 | void 2064 | xpc_dictionary_set_int64(xpc_object_t xdict, const char *key, int64_t value); 2065 | 2066 | /*! 2067 | * @function xpc_dictionary_set_uint64 2068 | * 2069 | * @abstract 2070 | * Inserts a uint64_t (primitive) value into a dictionary. 2071 | * 2072 | * @param xdict 2073 | * The dictionary which is to be manipulated. 2074 | * 2075 | * @param key 2076 | * The key for which the primitive value shall be set. 2077 | * 2078 | * @param value 2079 | * The uint64_t value to insert. After calling this method, the XPC 2080 | * object corresponding to the primitive value inserted may be safely retrieved 2081 | * with {@link xpc_dictionary_get_value()}. 2082 | */ 2083 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 2084 | XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 2085 | void 2086 | xpc_dictionary_set_uint64(xpc_object_t xdict, const char *key, uint64_t value); 2087 | 2088 | /*! 2089 | * @function xpc_dictionary_set_double 2090 | * 2091 | * @abstract 2092 | * Inserts a double (primitive) value into a dictionary. 2093 | * 2094 | * @param xdict 2095 | * The dictionary which is to be manipulated. 2096 | * 2097 | * @param key 2098 | * The key for which the primitive value shall be set. 2099 | * 2100 | * @param value 2101 | * The double value to insert. After calling this method, the XPC 2102 | * object corresponding to the primitive value inserted may be safely retrieved 2103 | * with {@link xpc_dictionary_get_value()}. 2104 | */ 2105 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 2106 | XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 2107 | void 2108 | xpc_dictionary_set_double(xpc_object_t xdict, const char *key, double value); 2109 | 2110 | /*! 2111 | * @function xpc_dictionary_set_date 2112 | * 2113 | * @abstract 2114 | * Inserts a date (primitive) value into a dictionary. 2115 | * 2116 | * @param xdict 2117 | * The dictionary which is to be manipulated. 2118 | * 2119 | * @param key 2120 | * The key for which the primitive value shall be set. 2121 | * 2122 | * @param value 2123 | * The date value to insert. After calling this method, the XPC object 2124 | * corresponding to the primitive value inserted may be safely retrieved with 2125 | * {@link xpc_dictionary_get_value()}. 2126 | */ 2127 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 2128 | XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 2129 | void 2130 | xpc_dictionary_set_date(xpc_object_t xdict, const char *key, int64_t value); 2131 | 2132 | /*! 2133 | * @function xpc_dictionary_set_data 2134 | * 2135 | * @abstract 2136 | * Inserts a raw data value into a dictionary. 2137 | * 2138 | * @param xdict 2139 | * The dictionary which is to be manipulated. 2140 | * 2141 | * @param key 2142 | * The key for which the primitive value shall be set. 2143 | * 2144 | * @param bytes 2145 | * The bytes to insert. After calling this method, the XPC object corresponding 2146 | * to the primitive value inserted may be safely retrieved with 2147 | * {@link xpc_dictionary_get_value()}. 2148 | * 2149 | * @param length 2150 | * The length of the data. 2151 | */ 2152 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 2153 | XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 XPC_NONNULL3 2154 | void 2155 | xpc_dictionary_set_data(xpc_object_t xdict, const char *key, const void *bytes, 2156 | size_t length); 2157 | 2158 | /*! 2159 | * @function xpc_dictionary_set_string 2160 | * 2161 | * @abstract 2162 | * Inserts a C string value into a dictionary. 2163 | * 2164 | * @param xdict 2165 | * The dictionary which is to be manipulated. 2166 | * 2167 | * @param key 2168 | * The key for which the primitive value shall be set. 2169 | * 2170 | * @param string 2171 | * The C string to insert. After calling this method, the XPC object 2172 | * corresponding to the primitive value inserted may be safely retrieved with 2173 | * {@link xpc_dictionary_get_value()}. 2174 | */ 2175 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 2176 | XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 XPC_NONNULL3 2177 | void 2178 | xpc_dictionary_set_string(xpc_object_t xdict, const char *key, 2179 | const char *string); 2180 | 2181 | /*! 2182 | * @function xpc_dictionary_set_uuid 2183 | * 2184 | * @abstract 2185 | * Inserts a uuid (primitive) value into an array. 2186 | * 2187 | * @param xdict 2188 | * The dictionary which is to be manipulated. 2189 | * 2190 | * @param key 2191 | * The key for which the primitive value shall be set. 2192 | * 2193 | * @param uuid 2194 | * The uuid_t value to insert. After calling this method, the XPC 2195 | * object corresponding to the primitive value inserted may be safely retrieved 2196 | * with {@link xpc_dictionary_get_value()}. 2197 | */ 2198 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 2199 | XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 XPC_NONNULL3 2200 | void 2201 | xpc_dictionary_set_uuid(xpc_object_t xdict, const char *key, 2202 | const uuid_t XPC_NONNULL_ARRAY uuid); 2203 | 2204 | /*! 2205 | * @function xpc_dictionary_set_fd 2206 | * 2207 | * @abstract 2208 | * Inserts a file descriptor into a dictionary. 2209 | * 2210 | * @param xdict 2211 | * The dictionary which is to be manipulated. 2212 | * 2213 | * @param key 2214 | * The key for which the primitive value shall be set. 2215 | * 2216 | * @param fd 2217 | * The file descriptor to insert. After calling this method, the XPC object 2218 | * corresponding to the primitive value inserted may be safely retrieved 2219 | * with {@link xpc_dictionary_get_value()}. 2220 | */ 2221 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 2222 | XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 2223 | void 2224 | xpc_dictionary_set_fd(xpc_object_t xdict, const char *key, int fd); 2225 | 2226 | /*! 2227 | * @function xpc_dictionary_set_connection 2228 | * 2229 | * @abstract 2230 | * Inserts a connection into a dictionary. 2231 | * 2232 | * @param xdict 2233 | * The dictionary which is to be manipulated. 2234 | * 2235 | * @param key 2236 | * The key for which the primitive value shall be set. 2237 | * 2238 | * @param connection 2239 | * The connection to insert. After calling this method, the XPC object 2240 | * corresponding to the primitive value inserted may be safely retrieved 2241 | * with {@link xpc_dictionary_get_value()}. The connection is NOT retained by 2242 | * the dictionary. 2243 | */ 2244 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 2245 | XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 XPC_NONNULL3 2246 | void 2247 | xpc_dictionary_set_connection(xpc_object_t xdict, const char *key, 2248 | xpc_connection_t connection); 2249 | 2250 | #pragma mark Dictionary Primitive Getters 2251 | /*! 2252 | * @function xpc_dictionary_get_bool 2253 | * 2254 | * @abstract 2255 | * Gets a bool primitive value from a dictionary directly. 2256 | * 2257 | * @param xdict 2258 | * The dictionary object which is to be examined. 2259 | * 2260 | * @param key 2261 | * The key whose value is to be obtained. 2262 | * 2263 | * @result 2264 | * The underlying bool value for the specified key. false if the 2265 | * the value for the specified key is not a Boolean value or if there is no 2266 | * value for the specified key. 2267 | */ 2268 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 2269 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL 2270 | bool 2271 | xpc_dictionary_get_bool(xpc_object_t xdict, const char *key); 2272 | 2273 | /*! 2274 | * @function xpc_dictionary_get_int64 2275 | * 2276 | * @abstract 2277 | * Gets an int64 primitive value from a dictionary directly. 2278 | * 2279 | * @param xdict 2280 | * The dictionary object which is to be examined. 2281 | * 2282 | * @param key 2283 | * The key whose value is to be obtained. 2284 | * 2285 | * @result 2286 | * The underlying int64_t value for the specified key. 0 if the 2287 | * value for the specified key is not a signed integer value or if there is no 2288 | * value for the specified key. 2289 | */ 2290 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 2291 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL 2292 | int64_t 2293 | xpc_dictionary_get_int64(xpc_object_t xdict, const char *key); 2294 | 2295 | /*! 2296 | * @function xpc_dictionary_get_uint64 2297 | * 2298 | * @abstract 2299 | * Gets a uint64 primitive value from a dictionary directly. 2300 | * 2301 | * @param xdict 2302 | * The dictionary object which is to be examined. 2303 | * 2304 | * @param key 2305 | * The key whose value is to be obtained. 2306 | * 2307 | * @result 2308 | * The underlying uint64_t value for the specified key. 0 if the 2309 | * value for the specified key is not an unsigned integer value or if there is 2310 | * no value for the specified key. 2311 | */ 2312 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 2313 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL 2314 | uint64_t 2315 | xpc_dictionary_get_uint64(xpc_object_t xdict, const char *key); 2316 | 2317 | /*! 2318 | * @function xpc_dictionary_get_double 2319 | * 2320 | * @abstract 2321 | * Gets a double primitive value from a dictionary directly. 2322 | * 2323 | * @param xdict 2324 | * The dictionary object which is to be examined. 2325 | * 2326 | * @param key 2327 | * The key whose value is to be obtained. 2328 | * 2329 | * @result 2330 | * The underlying double value for the specified key. NAN if the 2331 | * value for the specified key is not a floating point value or if there is no 2332 | * value for the specified key. 2333 | */ 2334 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 2335 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL 2336 | double 2337 | xpc_dictionary_get_double(xpc_object_t xdict, const char *key); 2338 | 2339 | /*! 2340 | * @function xpc_dictionary_get_date 2341 | * 2342 | * @abstract 2343 | * Gets a date value from a dictionary directly. 2344 | * 2345 | * @param xdict 2346 | * The dictionary object which is to be examined. 2347 | * 2348 | * @param key 2349 | * The key whose value is to be obtained. 2350 | * 2351 | * @result 2352 | * The underlying date interval for the specified key. 0 if the value for the 2353 | * specified key is not a date value or if there is no value for the specified 2354 | * key. 2355 | */ 2356 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 2357 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL 2358 | int64_t 2359 | xpc_dictionary_get_date(xpc_object_t xdict, const char *key); 2360 | 2361 | /*! 2362 | * @function xpc_dictionary_get_data 2363 | * 2364 | * @abstract 2365 | * Gets a raw data value from a dictionary directly. 2366 | * 2367 | * @param xdict 2368 | * The dictionary object which is to be examined. 2369 | * 2370 | * @param key 2371 | * The key whose value is to be obtained. 2372 | * 2373 | * @param length 2374 | * For the data type, the third parameter, upon output, will contain the length 2375 | * of the data corresponding to the specified key. May be NULL. 2376 | * 2377 | * @result 2378 | * The underlying raw data for the specified key. NULL if the value for the 2379 | * specified key is not a data value or if there is no value for the specified 2380 | * key. 2381 | */ 2382 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 2383 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 2384 | const void * _Nullable 2385 | xpc_dictionary_get_data(xpc_object_t xdict, const char *key, 2386 | size_t * _Nullable length); 2387 | 2388 | /*! 2389 | * @function xpc_dictionary_get_string 2390 | * 2391 | * @abstract 2392 | * Gets a C string 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 C string for the specified key. NULL if the value for the 2402 | * specified key is not a C string value or if there is no value for the 2403 | * specified key. 2404 | */ 2405 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 2406 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL 2407 | const char * _Nullable 2408 | xpc_dictionary_get_string(xpc_object_t xdict, const char *key); 2409 | 2410 | /*! 2411 | * @function xpc_dictionary_get_uuid 2412 | * 2413 | * @abstract 2414 | * Gets a uuid 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 uuid_t value for the specified key. NULL is the 2424 | * value at the specified index is not a UUID value. The returned pointer may be 2425 | * safely passed to the uuid(3) APIs. 2426 | */ 2427 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 2428 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 XPC_NONNULL2 2429 | const uint8_t * _Nullable 2430 | xpc_dictionary_get_uuid(xpc_object_t xdict, const char *key); 2431 | 2432 | /*! 2433 | * @function xpc_dictionary_dup_fd 2434 | * 2435 | * @abstract 2436 | * Creates a file descriptor 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 | * A new file descriptor created from the value for the specified key. You are 2446 | * responsible for close(2)ing this descriptor. -1 if the value for the 2447 | * specified key is not a file descriptor value or if there is no value for the 2448 | * specified key. 2449 | */ 2450 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 2451 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL 2452 | int 2453 | xpc_dictionary_dup_fd(xpc_object_t xdict, const char *key); 2454 | 2455 | /*! 2456 | * @function xpc_dictionary_create_connection 2457 | * 2458 | * @abstract 2459 | * Creates a connection from a dictionary directly. 2460 | * 2461 | * @param xdict 2462 | * The dictionary object which is to be examined. 2463 | * 2464 | * @param key 2465 | * The key whose value is to be obtained. 2466 | * 2467 | * @result 2468 | * A new connection created from the value for the specified key. You are 2469 | * responsible for calling xpc_release() on the returned connection. NULL if the 2470 | * value for the specified key is not an endpoint containing a connection or if 2471 | * there is no value for the specified key. Each call to this method for the 2472 | * same key in the same dictionary will yield a different connection. See 2473 | * {@link xpc_connection_create_from_endpoint()} for discussion as to the 2474 | * responsibilities when dealing with the returned connection. 2475 | */ 2476 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 2477 | XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL_ALL 2478 | xpc_connection_t _Nullable 2479 | xpc_dictionary_create_connection(xpc_object_t xdict, const char *key); 2480 | 2481 | /*! 2482 | * @function xpc_dictionary_get_dictionary 2483 | * 2484 | * @abstract 2485 | * Returns the dictionary value for the specified key. 2486 | * 2487 | * @param xdict 2488 | * The dictionary object which is to be examined. 2489 | * 2490 | * @param key 2491 | * The key whose value is to be obtained. 2492 | * 2493 | * @result 2494 | * The object for the specified key within the dictionary. NULL if there is no 2495 | * value associated with the specified key, if the given object was not an 2496 | * XPC dictionary, or if the object for the specified key is not a dictionary. 2497 | * 2498 | * @discussion 2499 | * This method does not grant the caller a reference to the underlying object, 2500 | * and thus the caller is not responsible for releasing the object. 2501 | */ 2502 | __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0) 2503 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL 2504 | xpc_object_t _Nullable 2505 | xpc_dictionary_get_dictionary(xpc_object_t self, const char *key); 2506 | 2507 | /*! 2508 | * @function xpc_dictionary_get_array 2509 | * 2510 | * @abstract 2511 | * Returns the array value for the specified key. 2512 | * 2513 | * @param xdict 2514 | * The dictionary object which is to be examined. 2515 | * 2516 | * @param key 2517 | * The key whose value is to be obtained. 2518 | * 2519 | * @result 2520 | * The object for the specified key within the dictionary. NULL if there is no 2521 | * value associated with the specified key, if the given object was not an 2522 | * XPC dictionary, or if the object for the specified key is not an array. 2523 | * 2524 | * @discussion 2525 | * This method does not grant the caller a reference to the underlying object, 2526 | * and thus the caller is not responsible for releasing the object. 2527 | */ 2528 | __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0) 2529 | XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL 2530 | xpc_object_t _Nullable 2531 | xpc_dictionary_get_array(xpc_object_t self, const char *key); 2532 | 2533 | #pragma mark Runtime 2534 | /*! 2535 | * @function xpc_main 2536 | * The springboard into the XPCService runtime. This function will set up your 2537 | * service bundle's listener connection and manage it automatically. After this 2538 | * initial setup, this function will, by default, call dispatch_main(). You may 2539 | * override this behavior by setting the RunLoopType key in your XPC service 2540 | * bundle's Info.plist under the XPCService dictionary. 2541 | * 2542 | * @param handler 2543 | * The handler with which to accept new connections. 2544 | */ 2545 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 2546 | XPC_EXPORT XPC_NORETURN XPC_NONNULL1 2547 | void 2548 | xpc_main(xpc_connection_handler_t handler); 2549 | 2550 | #if XPC_HOSTING_OLD_MAIN 2551 | typedef void (*xpc_service_event_handler_t)(xpc_connection_t, xpc_object_t); 2552 | 2553 | __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_7, __MAC_10_7, __IPHONE_5_0, __IPHONE_5_0) 2554 | XPC_EXPORT XPC_NORETURN XPC_NONNULL3 2555 | void 2556 | xpc_service_main(int argc, const char *argv[], 2557 | xpc_service_event_handler_t handler); 2558 | #endif // XPC_HOSTING_OLD_MAIN 2559 | 2560 | #pragma mark Transactions 2561 | /*! 2562 | * @function xpc_transaction_begin 2563 | * Informs the XPC runtime that a transaction has begun and that the service 2564 | * should not exit due to inactivity. 2565 | * 2566 | * @discussion 2567 | * A service with no outstanding transactions may automatically exit due to 2568 | * inactivity as determined by the system. 2569 | * 2570 | * This function may be used to manually manage transactions in cases where 2571 | * their automatic management (as described below) does not meet the needs of an 2572 | * XPC service. This function also updates the transaction count used for sudden 2573 | * termination, i.e. vproc_transaction_begin(), and these two interfaces may be 2574 | * used in combination. 2575 | * 2576 | * The XPC runtime will automatically begin a transaction on behalf of a service 2577 | * when a new message is received. If no reply message is expected, the 2578 | * transaction is automatically ended when the connection event handler returns. 2579 | * If a reply message is created, the transaction will end when the reply 2580 | * message is sent or released. An XPC service may use xpc_transaction_begin() 2581 | * and xpc_transaction_end() to inform the XPC runtime about activity that 2582 | * occurs outside of this common pattern. 2583 | * 2584 | * On macOS, when the XPC runtime has determined that the service should exit, 2585 | * the event handlers for all active peer connections will receive 2586 | * {@link XPC_ERROR_TERMINATION_IMMINENT} as an indication that they should 2587 | * unwind their existing transactions. After this error is delivered to a 2588 | * connection's event handler, no more messages will be delivered to the 2589 | * connection. 2590 | */ 2591 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 2592 | XPC_EXPORT 2593 | void 2594 | xpc_transaction_begin(void); 2595 | 2596 | /*! 2597 | * @function xpc_transaction_end 2598 | * Informs the XPC runtime that a transaction has ended. 2599 | * 2600 | * @discussion 2601 | * As described in {@link xpc_transaction_begin()}, this API may be used 2602 | * interchangeably with vproc_transaction_end(). 2603 | * 2604 | * See the discussion for {@link xpc_transaction_begin()} for details regarding 2605 | * the XPC runtime's idle-exit policy. 2606 | */ 2607 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 2608 | XPC_EXPORT 2609 | void 2610 | xpc_transaction_end(void); 2611 | 2612 | #pragma mark XPC Event Stream 2613 | /*! 2614 | * @function xpc_set_event_stream_handler 2615 | * Sets the event handler to invoke when streamed events are received. 2616 | * 2617 | * @param stream 2618 | * The name of the event stream for which this handler will be invoked. 2619 | * 2620 | * @param targetq 2621 | * The GCD queue to which the event handler block will be submitted. This 2622 | * parameter may be NULL, in which case the connection's target queue will be 2623 | * libdispatch's default target queue, defined as DISPATCH_TARGET_QUEUE_DEFAULT. 2624 | * 2625 | * @param handler 2626 | * The event handler block. The event which this block receives as its first 2627 | * parameter will always be a dictionary which contains the XPC_EVENT_KEY_NAME 2628 | * key. The value for this key will be a string whose value is the name assigned 2629 | * to the XPC event specified in the launchd.plist. Future keys may be added to 2630 | * this dictionary. 2631 | * 2632 | * @discussion 2633 | * Multiple calls to this function for the same event stream will result in 2634 | * undefined behavior. 2635 | */ 2636 | #if __BLOCKS__ 2637 | __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) 2638 | XPC_EXPORT XPC_NONNULL1 XPC_NONNULL3 2639 | void 2640 | xpc_set_event_stream_handler(const char *stream, 2641 | dispatch_queue_t _Nullable targetq, xpc_handler_t handler); 2642 | #endif // __BLOCKS__ 2643 | 2644 | __END_DECLS 2645 | XPC_ASSUME_NONNULL_END 2646 | 2647 | #endif // __XPC_H__ 2648 | --------------------------------------------------------------------------------