diff options
Diffstat (limited to 'include/libimobiledevice')
27 files changed, 5823 insertions, 418 deletions
diff --git a/include/libimobiledevice/afc.h b/include/libimobiledevice/afc.h index 8d47696..4ad3dbd 100644 --- a/include/libimobiledevice/afc.h +++ b/include/libimobiledevice/afc.h | |||
@@ -1,9 +1,10 @@ | |||
1 | /** | 1 | /** |
2 | * @file libimobiledevice/afc.h | 2 | * @file libimobiledevice/afc.h |
3 | * @brief Access the filesystem. | 3 | * @brief Access the filesystem on the device. |
4 | * \internal | 4 | * \internal |
5 | * | 5 | * |
6 | * Copyright (c) 2009 Nikias Bassen All Rights Reserved. | 6 | * Copyright (c) 2010-2014 Martin Szulecki All Rights Reserved. |
7 | * Copyright (c) 2009-2010 Nikias Bassen All Rights Reserved. | ||
7 | * | 8 | * |
8 | * This library is free software; you can redistribute it and/or | 9 | * This library is free software; you can redistribute it and/or |
9 | * modify it under the terms of the GNU Lesser General Public | 10 | * modify it under the terms of the GNU Lesser General Public |
@@ -20,50 +21,51 @@ | |||
20 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | 21 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA |
21 | */ | 22 | */ |
22 | 23 | ||
23 | #ifndef AFC_H | 24 | #ifndef IAFC_H |
24 | #define AFC_H | 25 | #define IAFC_H |
25 | 26 | ||
26 | #ifdef __cplusplus | 27 | #ifdef __cplusplus |
27 | extern "C" { | 28 | extern "C" { |
28 | #endif | 29 | #endif |
29 | 30 | ||
30 | #include <libimobiledevice/libimobiledevice.h> | 31 | #include <libimobiledevice/libimobiledevice.h> |
32 | #include <libimobiledevice/lockdown.h> | ||
31 | 33 | ||
32 | /** @name Error Codes */ | 34 | /** Service identifier passed to lockdownd_start_service() to start the AFC service */ |
33 | /*@{*/ | 35 | #define AFC_SERVICE_NAME "com.apple.afc" |
34 | #define AFC_E_SUCCESS 0 | 36 | |
35 | #define AFC_E_UNKNOWN_ERROR 1 | 37 | /** Error Codes */ |
36 | #define AFC_E_OP_HEADER_INVALID 2 | 38 | typedef enum { |
37 | #define AFC_E_NO_RESOURCES 3 | 39 | AFC_E_SUCCESS = 0, |
38 | #define AFC_E_READ_ERROR 4 | 40 | AFC_E_UNKNOWN_ERROR = 1, |
39 | #define AFC_E_WRITE_ERROR 5 | 41 | AFC_E_OP_HEADER_INVALID = 2, |
40 | #define AFC_E_UNKNOWN_PACKET_TYPE 6 | 42 | AFC_E_NO_RESOURCES = 3, |
41 | #define AFC_E_INVALID_ARG 7 | 43 | AFC_E_READ_ERROR = 4, |
42 | #define AFC_E_OBJECT_NOT_FOUND 8 | 44 | AFC_E_WRITE_ERROR = 5, |
43 | #define AFC_E_OBJECT_IS_DIR 9 | 45 | AFC_E_UNKNOWN_PACKET_TYPE = 6, |
44 | #define AFC_E_PERM_DENIED 10 | 46 | AFC_E_INVALID_ARG = 7, |
45 | #define AFC_E_SERVICE_NOT_CONNECTED 11 | 47 | AFC_E_OBJECT_NOT_FOUND = 8, |
46 | #define AFC_E_OP_TIMEOUT 12 | 48 | AFC_E_OBJECT_IS_DIR = 9, |
47 | #define AFC_E_TOO_MUCH_DATA 13 | 49 | AFC_E_PERM_DENIED = 10, |
48 | #define AFC_E_END_OF_DATA 14 | 50 | AFC_E_SERVICE_NOT_CONNECTED = 11, |
49 | #define AFC_E_OP_NOT_SUPPORTED 15 | 51 | AFC_E_OP_TIMEOUT = 12, |
50 | #define AFC_E_OBJECT_EXISTS 16 | 52 | AFC_E_TOO_MUCH_DATA = 13, |
51 | #define AFC_E_OBJECT_BUSY 17 | 53 | AFC_E_END_OF_DATA = 14, |
52 | #define AFC_E_NO_SPACE_LEFT 18 | 54 | AFC_E_OP_NOT_SUPPORTED = 15, |
53 | #define AFC_E_OP_WOULD_BLOCK 19 | 55 | AFC_E_OBJECT_EXISTS = 16, |
54 | #define AFC_E_IO_ERROR 20 | 56 | AFC_E_OBJECT_BUSY = 17, |
55 | #define AFC_E_OP_INTERRUPTED 21 | 57 | AFC_E_NO_SPACE_LEFT = 18, |
56 | #define AFC_E_OP_IN_PROGRESS 22 | 58 | AFC_E_OP_WOULD_BLOCK = 19, |
57 | #define AFC_E_INTERNAL_ERROR 23 | 59 | AFC_E_IO_ERROR = 20, |
58 | 60 | AFC_E_OP_INTERRUPTED = 21, | |
59 | #define AFC_E_MUX_ERROR 30 | 61 | AFC_E_OP_IN_PROGRESS = 22, |
60 | #define AFC_E_NO_MEM 31 | 62 | AFC_E_INTERNAL_ERROR = 23, |
61 | #define AFC_E_NOT_ENOUGH_DATA 32 | 63 | AFC_E_MUX_ERROR = 30, |
62 | #define AFC_E_DIR_NOT_EMPTY 33 | 64 | AFC_E_NO_MEM = 31, |
63 | /*@}*/ | 65 | AFC_E_NOT_ENOUGH_DATA = 32, |
64 | 66 | AFC_E_DIR_NOT_EMPTY = 33, | |
65 | /** Represents an error code. */ | 67 | AFC_E_FORCE_SIGNED_TYPE = -1 |
66 | typedef int16_t afc_error_t; | 68 | } afc_error_t; |
67 | 69 | ||
68 | /** Flags for afc_file_open */ | 70 | /** Flags for afc_file_open */ |
69 | typedef enum { | 71 | typedef enum { |
@@ -88,33 +90,293 @@ typedef enum { | |||
88 | AFC_LOCK_UN = 8 | 4 /**< unlock */ | 90 | AFC_LOCK_UN = 8 | 4 /**< unlock */ |
89 | } afc_lock_op_t; | 91 | } afc_lock_op_t; |
90 | 92 | ||
91 | typedef struct afc_client_private afc_client_private; | 93 | typedef struct afc_client_private afc_client_private; /**< \private */ |
92 | typedef afc_client_private *afc_client_t; /**< The client handle. */ | 94 | typedef afc_client_private *afc_client_t; /**< The client handle. */ |
93 | 95 | ||
94 | /* Interface */ | 96 | /* Interface */ |
95 | afc_error_t afc_client_new_from_connection(idevice_connection_t connection, afc_client_t *client); | 97 | |
96 | afc_error_t afc_client_new(idevice_t device, uint16_t port, afc_client_t *client); | 98 | /** |
97 | afc_error_t afc_client_free(afc_client_t client); | 99 | * Makes a connection to the AFC service on the device. |
98 | afc_error_t afc_get_device_info(afc_client_t client, char ***infos); | 100 | * |
99 | afc_error_t afc_read_directory(afc_client_t client, const char *dir, char ***list); | 101 | * @param device The device to connect to. |
100 | afc_error_t afc_get_file_info(afc_client_t client, const char *filename, char ***infolist); | 102 | * @param service The service descriptor returned by lockdownd_start_service. |
101 | afc_error_t afc_file_open(afc_client_t client, const char *filename, afc_file_mode_t file_mode, uint64_t *handle); | 103 | * @param client Pointer that will be set to a newly allocated afc_client_t |
102 | afc_error_t afc_file_close(afc_client_t client, uint64_t handle); | 104 | * upon successful return. |
103 | afc_error_t afc_file_lock(afc_client_t client, uint64_t handle, afc_lock_op_t operation); | 105 | * |
104 | afc_error_t afc_file_read(afc_client_t client, uint64_t handle, char *data, uint32_t length, uint32_t *bytes_read); | 106 | * @return AFC_E_SUCCESS on success, AFC_E_INVALID_ARG if device or service is |
105 | afc_error_t afc_file_write(afc_client_t client, uint64_t handle, const char *data, uint32_t length, uint32_t *bytes_written); | 107 | * invalid, AFC_E_MUX_ERROR if the connection cannot be established, |
106 | afc_error_t afc_file_seek(afc_client_t client, uint64_t handle, int64_t offset, int whence); | 108 | * or AFC_E_NO_MEM if there is a memory allocation problem. |
107 | afc_error_t afc_file_tell(afc_client_t client, uint64_t handle, uint64_t *position); | 109 | */ |
108 | afc_error_t afc_file_truncate(afc_client_t client, uint64_t handle, uint64_t newsize); | 110 | LIBIMOBILEDEVICE_API afc_error_t afc_client_new(idevice_t device, lockdownd_service_descriptor_t service, afc_client_t *client); |
109 | afc_error_t afc_remove_path(afc_client_t client, const char *path); | 111 | |
110 | afc_error_t afc_rename_path(afc_client_t client, const char *from, const char *to); | 112 | /** |
111 | afc_error_t afc_make_directory(afc_client_t client, const char *dir); | 113 | * Starts a new AFC service on the specified device and connects to it. |
112 | afc_error_t afc_truncate(afc_client_t client, const char *path, uint64_t newsize); | 114 | * |
113 | afc_error_t afc_make_link(afc_client_t client, afc_link_type_t linktype, const char *target, const char *linkname); | 115 | * @param device The device to connect to. |
114 | afc_error_t afc_set_file_time(afc_client_t client, const char *path, uint64_t mtime); | 116 | * @param client Pointer that will point to a newly allocated afc_client_t upon |
117 | * successful return. Must be freed using afc_client_free() after use. | ||
118 | * @param label The label to use for communication. Usually the program name. | ||
119 | * Pass NULL to disable sending the label in requests to lockdownd. | ||
120 | * | ||
121 | * @return AFC_E_SUCCESS on success, or an AFC_E_* error code otherwise. | ||
122 | */ | ||
123 | LIBIMOBILEDEVICE_API afc_error_t afc_client_start_service(idevice_t device, afc_client_t* client, const char* label); | ||
124 | |||
125 | /** | ||
126 | * Frees up an AFC client. If the connection was created by the client itself, | ||
127 | * the connection will be closed. | ||
128 | * | ||
129 | * @param client The client to free. | ||
130 | */ | ||
131 | LIBIMOBILEDEVICE_API afc_error_t afc_client_free(afc_client_t client); | ||
132 | |||
133 | /** | ||
134 | * Get device information for a connected client. The device information | ||
135 | * returned is the device model as well as the free space, the total capacity | ||
136 | * and blocksize on the accessed disk partition. | ||
137 | * | ||
138 | * @param client The client to get device info for. | ||
139 | * @param device_information A char list of device information terminated by an | ||
140 | * empty string or NULL if there was an error. Free with | ||
141 | * afc_dictionary_free(). | ||
142 | * | ||
143 | * @return AFC_E_SUCCESS on success or an AFC_E_* error value. | ||
144 | */ | ||
145 | LIBIMOBILEDEVICE_API afc_error_t afc_get_device_info(afc_client_t client, char ***device_information); | ||
146 | |||
147 | /** | ||
148 | * Gets a directory listing of the directory requested. | ||
149 | * | ||
150 | * @param client The client to get a directory listing from. | ||
151 | * @param path The directory for listing. (must be a fully-qualified path) | ||
152 | * @param directory_information A char list of files in the directory | ||
153 | * terminated by an empty string or NULL if there was an error. Free with | ||
154 | * afc_dictionary_free(). | ||
155 | * | ||
156 | * @return AFC_E_SUCCESS on success or an AFC_E_* error value. | ||
157 | */ | ||
158 | LIBIMOBILEDEVICE_API afc_error_t afc_read_directory(afc_client_t client, const char *path, char ***directory_information); | ||
159 | |||
160 | /** | ||
161 | * Gets information about a specific file. | ||
162 | * | ||
163 | * @param client The client to use to get the information of the file. | ||
164 | * @param path The fully-qualified path to the file. | ||
165 | * @param file_information Pointer to a buffer that will be filled with a | ||
166 | * NULL-terminated list of strings with the file information. Set to NULL | ||
167 | * before calling this function. Free with afc_dictionary_free(). | ||
168 | * | ||
169 | * @return AFC_E_SUCCESS on success or an AFC_E_* error value. | ||
170 | */ | ||
171 | LIBIMOBILEDEVICE_API afc_error_t afc_get_file_info(afc_client_t client, const char *path, char ***file_information); | ||
172 | |||
173 | /** | ||
174 | * Opens a file on the device. | ||
175 | * | ||
176 | * @param client The client to use to open the file. | ||
177 | * @param filename The file to open. (must be a fully-qualified path) | ||
178 | * @param file_mode The mode to use to open the file. | ||
179 | * @param handle Pointer to a uint64_t that will hold the handle of the file | ||
180 | * | ||
181 | * @return AFC_E_SUCCESS on success or an AFC_E_* error value. | ||
182 | */ | ||
183 | LIBIMOBILEDEVICE_API afc_error_t afc_file_open(afc_client_t client, const char *filename, afc_file_mode_t file_mode, uint64_t *handle); | ||
184 | |||
185 | /** | ||
186 | * Closes a file on the device. | ||
187 | * | ||
188 | * @param client The client to close the file with. | ||
189 | * @param handle File handle of a previously opened file. | ||
190 | */ | ||
191 | LIBIMOBILEDEVICE_API afc_error_t afc_file_close(afc_client_t client, uint64_t handle); | ||
192 | |||
193 | /** | ||
194 | * Locks or unlocks a file on the device. | ||
195 | * | ||
196 | * Makes use of flock on the device. | ||
197 | * @see http://developer.apple.com/documentation/Darwin/Reference/ManPages/man2/flock.2.html | ||
198 | * | ||
199 | * @param client The client to lock the file with. | ||
200 | * @param handle File handle of a previously opened file. | ||
201 | * @param operation the lock or unlock operation to perform, this is one of | ||
202 | * AFC_LOCK_SH (shared lock), AFC_LOCK_EX (exclusive lock), or | ||
203 | * AFC_LOCK_UN (unlock). | ||
204 | */ | ||
205 | LIBIMOBILEDEVICE_API afc_error_t afc_file_lock(afc_client_t client, uint64_t handle, afc_lock_op_t operation); | ||
206 | |||
207 | /** | ||
208 | * Attempts to the read the given number of bytes from the given file. | ||
209 | * | ||
210 | * @param client The relevant AFC client | ||
211 | * @param handle File handle of a previously opened file | ||
212 | * @param data The pointer to the memory region to store the read data | ||
213 | * @param length The number of bytes to read | ||
214 | * @param bytes_read The number of bytes actually read. | ||
215 | * | ||
216 | * @return AFC_E_SUCCESS on success or an AFC_E_* error value. | ||
217 | */ | ||
218 | LIBIMOBILEDEVICE_API afc_error_t afc_file_read(afc_client_t client, uint64_t handle, char *data, uint32_t length, uint32_t *bytes_read); | ||
219 | |||
220 | /** | ||
221 | * Writes a given number of bytes to a file. | ||
222 | * | ||
223 | * @param client The client to use to write to the file. | ||
224 | * @param handle File handle of previously opened file. | ||
225 | * @param data The data to write to the file. | ||
226 | * @param length How much data to write. | ||
227 | * @param bytes_written The number of bytes actually written to the file. | ||
228 | * | ||
229 | * @return AFC_E_SUCCESS on success or an AFC_E_* error value. | ||
230 | */ | ||
231 | LIBIMOBILEDEVICE_API afc_error_t afc_file_write(afc_client_t client, uint64_t handle, const char *data, uint32_t length, uint32_t *bytes_written); | ||
232 | |||
233 | /** | ||
234 | * Seeks to a given position of a pre-opened file on the device. | ||
235 | * | ||
236 | * @param client The client to use to seek to the position. | ||
237 | * @param handle File handle of a previously opened. | ||
238 | * @param offset Seek offset. | ||
239 | * @param whence Seeking direction, one of SEEK_SET, SEEK_CUR, or SEEK_END. | ||
240 | * | ||
241 | * @return AFC_E_SUCCESS on success or an AFC_E_* error value. | ||
242 | */ | ||
243 | LIBIMOBILEDEVICE_API afc_error_t afc_file_seek(afc_client_t client, uint64_t handle, int64_t offset, int whence); | ||
244 | |||
245 | /** | ||
246 | * Returns current position in a pre-opened file on the device. | ||
247 | * | ||
248 | * @param client The client to use. | ||
249 | * @param handle File handle of a previously opened file. | ||
250 | * @param position Position in bytes of indicator | ||
251 | * | ||
252 | * @return AFC_E_SUCCESS on success or an AFC_E_* error value. | ||
253 | */ | ||
254 | LIBIMOBILEDEVICE_API afc_error_t afc_file_tell(afc_client_t client, uint64_t handle, uint64_t *position); | ||
255 | |||
256 | /** | ||
257 | * Sets the size of a file on the device. | ||
258 | * | ||
259 | * @param client The client to use to set the file size. | ||
260 | * @param handle File handle of a previously opened file. | ||
261 | * @param newsize The size to set the file to. | ||
262 | * | ||
263 | * @return AFC_E_SUCCESS on success or an AFC_E_* error value. | ||
264 | * | ||
265 | * @note This function is more akin to ftruncate than truncate, and truncate | ||
266 | * calls would have to open the file before calling this, sadly. | ||
267 | */ | ||
268 | LIBIMOBILEDEVICE_API afc_error_t afc_file_truncate(afc_client_t client, uint64_t handle, uint64_t newsize); | ||
269 | |||
270 | /** | ||
271 | * Deletes a file or directory. | ||
272 | * | ||
273 | * @param client The client to use. | ||
274 | * @param path The path to delete. (must be a fully-qualified path) | ||
275 | * | ||
276 | * @return AFC_E_SUCCESS on success or an AFC_E_* error value. | ||
277 | */ | ||
278 | LIBIMOBILEDEVICE_API afc_error_t afc_remove_path(afc_client_t client, const char *path); | ||
279 | |||
280 | /** | ||
281 | * Renames a file or directory on the device. | ||
282 | * | ||
283 | * @param client The client to have rename. | ||
284 | * @param from The name to rename from. (must be a fully-qualified path) | ||
285 | * @param to The new name. (must also be a fully-qualified path) | ||
286 | * | ||
287 | * @return AFC_E_SUCCESS on success or an AFC_E_* error value. | ||
288 | */ | ||
289 | LIBIMOBILEDEVICE_API afc_error_t afc_rename_path(afc_client_t client, const char *from, const char *to); | ||
290 | |||
291 | /** | ||
292 | * Creates a directory on the device. | ||
293 | * | ||
294 | * @param client The client to use to make a directory. | ||
295 | * @param path The directory's path. (must be a fully-qualified path, I assume | ||
296 | * all other mkdir restrictions apply as well) | ||
297 | * | ||
298 | * @return AFC_E_SUCCESS on success or an AFC_E_* error value. | ||
299 | */ | ||
300 | LIBIMOBILEDEVICE_API afc_error_t afc_make_directory(afc_client_t client, const char *path); | ||
301 | |||
302 | /** | ||
303 | * Sets the size of a file on the device without prior opening it. | ||
304 | * | ||
305 | * @param client The client to use to set the file size. | ||
306 | * @param path The path of the file to be truncated. | ||
307 | * @param newsize The size to set the file to. | ||
308 | * | ||
309 | * @return AFC_E_SUCCESS on success or an AFC_E_* error value. | ||
310 | */ | ||
311 | LIBIMOBILEDEVICE_API afc_error_t afc_truncate(afc_client_t client, const char *path, uint64_t newsize); | ||
312 | |||
313 | /** | ||
314 | * Creates a hard link or symbolic link on the device. | ||
315 | * | ||
316 | * @param client The client to use for making a link | ||
317 | * @param linktype 1 = hard link, 2 = symlink | ||
318 | * @param target The file to be linked. | ||
319 | * @param linkname The name of link. | ||
320 | * | ||
321 | * @return AFC_E_SUCCESS on success or an AFC_E_* error value. | ||
322 | */ | ||
323 | LIBIMOBILEDEVICE_API afc_error_t afc_make_link(afc_client_t client, afc_link_type_t linktype, const char *target, const char *linkname); | ||
324 | |||
325 | /** | ||
326 | * Sets the modification time of a file on the device. | ||
327 | * | ||
328 | * @param client The client to use to set the file size. | ||
329 | * @param path Path of the file for which the modification time should be set. | ||
330 | * @param mtime The modification time to set in nanoseconds since epoch. | ||
331 | * | ||
332 | * @return AFC_E_SUCCESS on success or an AFC_E_* error value. | ||
333 | */ | ||
334 | LIBIMOBILEDEVICE_API afc_error_t afc_set_file_time(afc_client_t client, const char *path, uint64_t mtime); | ||
335 | |||
336 | /** | ||
337 | * Deletes a file or directory including possible contents. | ||
338 | * | ||
339 | * @param client The client to use. | ||
340 | * @param path The path to delete. (must be a fully-qualified path) | ||
341 | * @since libimobiledevice 1.1.7 | ||
342 | * @note Only available in iOS 6 and later. | ||
343 | * | ||
344 | * @return AFC_E_SUCCESS on success or an AFC_E_* error value. | ||
345 | */ | ||
346 | LIBIMOBILEDEVICE_API afc_error_t afc_remove_path_and_contents(afc_client_t client, const char *path); | ||
115 | 347 | ||
116 | /* Helper functions */ | 348 | /* Helper functions */ |
117 | afc_error_t afc_get_device_info_key(afc_client_t client, const char *key, char **value); | 349 | |
350 | /** | ||
351 | * Get a specific key of the device info list for a client connection. | ||
352 | * Known key values are: Model, FSTotalBytes, FSFreeBytes and FSBlockSize. | ||
353 | * This is a helper function for afc_get_device_info(). | ||
354 | * | ||
355 | * @param client The client to get device info for. | ||
356 | * @param key The key to get the value of. | ||
357 | * @param value The value for the key if successful or NULL otherwise. | ||
358 | * | ||
359 | * @return AFC_E_SUCCESS on success or an AFC_E_* error value. | ||
360 | */ | ||
361 | LIBIMOBILEDEVICE_API afc_error_t afc_get_device_info_key(afc_client_t client, const char *key, char **value); | ||
362 | |||
363 | /** | ||
364 | * Frees up a char dictionary as returned by some AFC functions. | ||
365 | * | ||
366 | * @param dictionary The char array terminated by an empty string. | ||
367 | * | ||
368 | * @return AFC_E_SUCCESS on success or an AFC_E_* error value. | ||
369 | */ | ||
370 | LIBIMOBILEDEVICE_API afc_error_t afc_dictionary_free(char **dictionary); | ||
371 | |||
372 | /** | ||
373 | * Gets a readable error string for a given AFC error code. | ||
374 | * | ||
375 | * @param err An AFC error code | ||
376 | * | ||
377 | * @returns A readable error string | ||
378 | */ | ||
379 | LIBIMOBILEDEVICE_API const char* afc_strerror(afc_error_t err); | ||
118 | 380 | ||
119 | #ifdef __cplusplus | 381 | #ifdef __cplusplus |
120 | } | 382 | } |
diff --git a/include/libimobiledevice/bt_packet_logger.h b/include/libimobiledevice/bt_packet_logger.h new file mode 100644 index 0000000..590e5c1 --- /dev/null +++ b/include/libimobiledevice/bt_packet_logger.h | |||
@@ -0,0 +1,156 @@ | |||
1 | /** | ||
2 | * @file libimobiledevice/bt_packet_logger.h | ||
3 | * @brief Capture the Bluetooth HCI trace from a device | ||
4 | * \internal | ||
5 | * | ||
6 | * Copyright (c) 2021 Geoffrey Kruse, All Rights Reserved. | ||
7 | * | ||
8 | * This library is free software; you can redistribute it and/or | ||
9 | * modify it under the terms of the GNU Lesser General Public | ||
10 | * License as published by the Free Software Foundation; either | ||
11 | * version 2.1 of the License, or (at your option) any later version. | ||
12 | * | ||
13 | * This library is distributed in the hope that it will be useful, | ||
14 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
15 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
16 | * Lesser General Public License for more details. | ||
17 | * | ||
18 | * You should have received a copy of the GNU Lesser General Public | ||
19 | * License along with this library; if not, write to the Free Software | ||
20 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | ||
21 | */ | ||
22 | |||
23 | #ifndef IBT_PACKET_LOGGER_H | ||
24 | #define IBT_PACKET_LOGGER_H | ||
25 | |||
26 | #ifdef __cplusplus | ||
27 | extern "C" { | ||
28 | #endif | ||
29 | |||
30 | #include <libimobiledevice/libimobiledevice.h> | ||
31 | #include <libimobiledevice/lockdown.h> | ||
32 | |||
33 | #define BT_PACKETLOGGER_SERVICE_NAME "com.apple.bluetooth.BTPacketLogger" | ||
34 | #define BT_MAX_PACKET_SIZE 65535 | ||
35 | |||
36 | /** Error Codes */ | ||
37 | typedef enum { | ||
38 | BT_PACKET_LOGGER_E_SUCCESS = 0, | ||
39 | BT_PACKET_LOGGER_E_INVALID_ARG = -1, | ||
40 | BT_PACKET_LOGGER_E_MUX_ERROR = -2, | ||
41 | BT_PACKET_LOGGER_E_SSL_ERROR = -3, | ||
42 | BT_PACKET_LOGGER_E_NOT_ENOUGH_DATA = -4, | ||
43 | BT_PACKET_LOGGER_E_TIMEOUT = -5, | ||
44 | BT_PACKET_LOGGER_E_UNKNOWN_ERROR = -256 | ||
45 | } bt_packet_logger_error_t; | ||
46 | |||
47 | typedef struct { | ||
48 | uint32_t length; | ||
49 | uint32_t ts_secs; | ||
50 | uint32_t ts_usecs; | ||
51 | } bt_packet_logger_header_t; | ||
52 | |||
53 | typedef struct bt_packet_logger_client_private bt_packet_logger_client_private; | ||
54 | typedef bt_packet_logger_client_private *bt_packet_logger_client_t; /**< The client handle. */ | ||
55 | |||
56 | /** Receives each hci packet received from the device. */ | ||
57 | typedef void (*bt_packet_logger_receive_cb_t)(uint8_t * data, uint16_t len, void *user_data); | ||
58 | |||
59 | /* Interface */ | ||
60 | |||
61 | /** | ||
62 | * Connects to the bt_packet_logger service on the specified device. | ||
63 | * | ||
64 | * @param device The device to connect to. | ||
65 | * @param service The service descriptor returned by lockdownd_start_service. | ||
66 | * @param client Pointer that will point to a newly allocated | ||
67 | * bt_packet_logger_client_t upon successful return. Must be freed using | ||
68 | * bt_packet_logger_client_free() after use. | ||
69 | * | ||
70 | * @return BT_PACKET_LOGGER_E_SUCCESS on success, BT_PACKET_LOGGER_E_INVALID_ARG when | ||
71 | * client is NULL, or an BT_PACKET_LOGGER_E_* error code otherwise. | ||
72 | */ | ||
73 | LIBIMOBILEDEVICE_API bt_packet_logger_error_t bt_packet_logger_client_new(idevice_t device, lockdownd_service_descriptor_t service, bt_packet_logger_client_t * client); | ||
74 | |||
75 | /** | ||
76 | * Starts a new bt_packet_logger service on the specified device and connects to it. | ||
77 | * | ||
78 | * @param device The device to connect to. | ||
79 | * @param client Pointer that will point to a newly allocated | ||
80 | * bt_packet_logger_client_t upon successful return. Must be freed using | ||
81 | * bt_packet_logger_client_free() after use. | ||
82 | * @param label The label to use for communication. Usually the program name. | ||
83 | * Pass NULL to disable sending the label in requests to lockdownd. | ||
84 | * | ||
85 | * @return BT_PACKET_LOGGER_E_SUCCESS on success, or an BT_PACKET_LOGGER_E_* error | ||
86 | * code otherwise. | ||
87 | */ | ||
88 | LIBIMOBILEDEVICE_API bt_packet_logger_error_t bt_packet_logger_client_start_service(idevice_t device, bt_packet_logger_client_t * client, const char* label); | ||
89 | |||
90 | /** | ||
91 | * Disconnects a bt_packet_logger client from the device and frees up the | ||
92 | * bt_packet_logger client data. | ||
93 | * | ||
94 | * @param client The bt_packet_logger client to disconnect and free. | ||
95 | * | ||
96 | * @return BT_PACKET_LOGGER_E_SUCCESS on success, BT_PACKET_LOGGER_E_INVALID_ARG when | ||
97 | * client is NULL, or an BT_PACKET_LOGGER_E_* error code otherwise. | ||
98 | */ | ||
99 | LIBIMOBILEDEVICE_API bt_packet_logger_error_t bt_packet_logger_client_free(bt_packet_logger_client_t client); | ||
100 | |||
101 | |||
102 | /** | ||
103 | * Starts capturing the hci interface from the device using a callback. | ||
104 | * | ||
105 | * Use bt_packet_logger_stop_capture() to stop receiving hci data. | ||
106 | * | ||
107 | * @param client The bt_packet_logger client to use | ||
108 | * @param callback Callback to receive each packet from the hci interface. | ||
109 | * @param user_data Custom pointer passed to the callback function. | ||
110 | * | ||
111 | * @return BT_PACKET_LOGGER_E_SUCCESS on success, | ||
112 | * BT_PACKET_LOGGER_E_INVALID_ARG when one or more parameters are | ||
113 | * invalid or BT_PACKET_LOGGER_E_UNKNOWN_ERROR when an unspecified | ||
114 | * error occurs or an hci capture has already been started. | ||
115 | */ | ||
116 | LIBIMOBILEDEVICE_API bt_packet_logger_error_t bt_packet_logger_start_capture(bt_packet_logger_client_t client, bt_packet_logger_receive_cb_t callback, void* user_data); | ||
117 | |||
118 | /** | ||
119 | * Stops capturing the hci interface from the device. | ||
120 | * | ||
121 | * Use bt_packet_logger_start_capture() to start receiving the hci data. | ||
122 | * | ||
123 | * @param client The bt_packet_logger client to use | ||
124 | * | ||
125 | * @return BT_PACKET_LOGGER_E_SUCCESS on success, | ||
126 | * BT_PACKET_LOGGER_E_INVALID_ARG when one or more parameters are | ||
127 | * invalid or BT_PACKET_LOGGER_E_UNKNOWN_ERROR when an unspecified | ||
128 | * error occurs or an hci capture has already been started. | ||
129 | */ | ||
130 | LIBIMOBILEDEVICE_API bt_packet_logger_error_t bt_packet_logger_stop_capture(bt_packet_logger_client_t client); | ||
131 | |||
132 | /* Receiving */ | ||
133 | |||
134 | /** | ||
135 | * Receives data using the given bt_packet_logger client with specified timeout. | ||
136 | * | ||
137 | * @param client The bt_packet_logger client to use for receiving | ||
138 | * @param data Buffer that will be filled with the data received | ||
139 | * @param size Number of bytes to receive | ||
140 | * @param received Number of bytes received (can be NULL to ignore) | ||
141 | * @param timeout Maximum time in milliseconds to wait for data. | ||
142 | * | ||
143 | * @return BT_PACKET_LOGGER_E_SUCCESS on success, | ||
144 | * BT_PACKET_LOGGER_E_INVALID_ARG when one or more parameters are | ||
145 | * invalid, BT_PACKET_LOGGER_E_MUX_ERROR when a communication error | ||
146 | * occurs, or BT_PACKET_LOGGER_E_UNKNOWN_ERROR when an unspecified | ||
147 | * error occurs. | ||
148 | */ | ||
149 | LIBIMOBILEDEVICE_API bt_packet_logger_error_t bt_packet_logger_receive_with_timeout(bt_packet_logger_client_t client, char *data, uint32_t size, uint32_t *received, unsigned int timeout); | ||
150 | |||
151 | |||
152 | #ifdef __cplusplus | ||
153 | } | ||
154 | #endif | ||
155 | |||
156 | #endif | ||
diff --git a/include/libimobiledevice/companion_proxy.h b/include/libimobiledevice/companion_proxy.h new file mode 100644 index 0000000..544322a --- /dev/null +++ b/include/libimobiledevice/companion_proxy.h | |||
@@ -0,0 +1,212 @@ | |||
1 | /** | ||
2 | * @file libimobiledevice/companion_proxy.h | ||
3 | * @brief Companion proxy support. | ||
4 | * \internal | ||
5 | * | ||
6 | * Copyright (c) 2019-2020 Nikias Bassen, All Rights Reserved. | ||
7 | * | ||
8 | * This library is free software; you can redistribute it and/or | ||
9 | * modify it under the terms of the GNU Lesser General Public | ||
10 | * License as published by the Free Software Foundation; either | ||
11 | * version 2.1 of the License, or (at your option) any later version. | ||
12 | * | ||
13 | * This library is distributed in the hope that it will be useful, | ||
14 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
15 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
16 | * Lesser General Public License for more details. | ||
17 | * | ||
18 | * You should have received a copy of the GNU Lesser General Public | ||
19 | * License along with this library; if not, write to the Free Software | ||
20 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | ||
21 | */ | ||
22 | |||
23 | #ifndef ICOMPANION_PROXY_H | ||
24 | #define ICOMPANION_PROXY_H | ||
25 | |||
26 | #ifdef __cplusplus | ||
27 | extern "C" { | ||
28 | #endif | ||
29 | |||
30 | #include <libimobiledevice/libimobiledevice.h> | ||
31 | #include <libimobiledevice/lockdown.h> | ||
32 | |||
33 | /** Service identifier passed to lockdownd_start_service() to start the companion proxy service */ | ||
34 | #define COMPANION_PROXY_SERVICE_NAME "com.apple.companion_proxy" | ||
35 | |||
36 | /** Error Codes */ | ||
37 | typedef enum { | ||
38 | COMPANION_PROXY_E_SUCCESS = 0, | ||
39 | COMPANION_PROXY_E_INVALID_ARG = -1, | ||
40 | COMPANION_PROXY_E_PLIST_ERROR = -2, | ||
41 | COMPANION_PROXY_E_MUX_ERROR = -3, | ||
42 | COMPANION_PROXY_E_SSL_ERROR = -4, | ||
43 | COMPANION_PROXY_E_NOT_ENOUGH_DATA = -5, | ||
44 | COMPANION_PROXY_E_TIMEOUT = -6, | ||
45 | COMPANION_PROXY_E_OP_IN_PROGRESS = -7, | ||
46 | COMPANION_PROXY_E_NO_DEVICES = -100, | ||
47 | COMPANION_PROXY_E_UNSUPPORTED_KEY = -101, | ||
48 | COMPANION_PROXY_E_TIMEOUT_REPLY = -102, | ||
49 | COMPANION_PROXY_E_UNKNOWN_ERROR = -256 | ||
50 | } companion_proxy_error_t; | ||
51 | |||
52 | typedef struct companion_proxy_client_private companion_proxy_client_private; /**< \private */ | ||
53 | typedef companion_proxy_client_private *companion_proxy_client_t; /**< The client handle. */ | ||
54 | |||
55 | /** Callback for companion device events */ | ||
56 | typedef void (*companion_proxy_device_event_cb_t) (plist_t event, void* userdata); | ||
57 | |||
58 | /** | ||
59 | * Connects to the companion_proxy service on the specified device. | ||
60 | * | ||
61 | * @param device The device to connect to. | ||
62 | * @param service The service descriptor returned by lockdownd_start_service. | ||
63 | * @param client Pointer that will point to a newly allocated | ||
64 | * companion_proxy_client_t upon successful return. Must be freed using | ||
65 | * companion_proxy_client_free() after use. | ||
66 | * | ||
67 | * @return COMPANION_PROXY_E_SUCCESS on success, COMPANION_PROXY_E_INVALID_ARG when | ||
68 | * the arguments are invalid, or an COMPANION_PROXY_E_* error code otherwise. | ||
69 | */ | ||
70 | LIBIMOBILEDEVICE_API companion_proxy_error_t companion_proxy_client_new(idevice_t device, lockdownd_service_descriptor_t service, companion_proxy_client_t* client); | ||
71 | |||
72 | /** | ||
73 | * Starts a new companion_proxy service on the specified device and connects to it. | ||
74 | * | ||
75 | * @param device The device to connect to. | ||
76 | * @param client Pointer that will point to a newly allocated | ||
77 | * companion_proxy_client_t upon successful return. Must be freed using | ||
78 | * companion_proxy_client_free() after use. | ||
79 | * @param label The label to use for communication. Usually the program name. | ||
80 | * Pass NULL to disable sending the label in requests to lockdownd. | ||
81 | * | ||
82 | * @return COMPANION_PROXY_E_SUCCESS on success, or an COMPANION_PROXY_E_* error | ||
83 | * code otherwise. | ||
84 | */ | ||
85 | LIBIMOBILEDEVICE_API companion_proxy_error_t companion_proxy_client_start_service(idevice_t device, companion_proxy_client_t* client, const char* label); | ||
86 | |||
87 | /** | ||
88 | * Disconnects a companion_proxy client from the device and frees up the | ||
89 | * companion_proxy client data. | ||
90 | * | ||
91 | * @param client The companion_proxy client to disconnect and free. | ||
92 | * | ||
93 | * @return COMPANION_PROXY_E_SUCCESS on success, COMPANION_PROXY_E_INVALID_ARG when | ||
94 | * client is NULL, or an COMPANION_PROXY_E_* error code otherwise. | ||
95 | */ | ||
96 | LIBIMOBILEDEVICE_API companion_proxy_error_t companion_proxy_client_free(companion_proxy_client_t client); | ||
97 | |||
98 | /** | ||
99 | * Sends a plist to the service. | ||
100 | * | ||
101 | * @param client The companion_proxy client | ||
102 | * @param plist The plist to send | ||
103 | * | ||
104 | * @return COMPANION_PROXY_E_SUCCESS on success, | ||
105 | * COMPANION_PROXY_E_INVALID_ARG when client or plist is NULL | ||
106 | */ | ||
107 | LIBIMOBILEDEVICE_API companion_proxy_error_t companion_proxy_send(companion_proxy_client_t client, plist_t plist); | ||
108 | |||
109 | /** | ||
110 | * Receives a plist from the service. | ||
111 | * | ||
112 | * @param client The companion_proxy client | ||
113 | * @param plist The plist to store the received data | ||
114 | * | ||
115 | * @return COMPANION_PROXY_E_SUCCESS on success, | ||
116 | * COMPANION_PROXY_E_INVALID_ARG when client or plist is NULL | ||
117 | */ | ||
118 | LIBIMOBILEDEVICE_API companion_proxy_error_t companion_proxy_receive(companion_proxy_client_t client, plist_t * plist); | ||
119 | |||
120 | /** | ||
121 | * Retrieves a list of paired devices. | ||
122 | * | ||
123 | * @param client The companion_proxy client | ||
124 | * @param paired_devices Point that will receive a PLIST_ARRAY with paired device UDIDs | ||
125 | * | ||
126 | * @note The device closes the connection after sending the reply. | ||
127 | * | ||
128 | * @return COMPANION_PROXY_E_SUCCESS on success, | ||
129 | * COMPANION_PROXY_E_NO_DEVICES if no devices are paired, | ||
130 | * or a COMPANION_PROXY_E_* error code otherwise. | ||
131 | */ | ||
132 | LIBIMOBILEDEVICE_API companion_proxy_error_t companion_proxy_get_device_registry(companion_proxy_client_t client, plist_t* paired_devices); | ||
133 | |||
134 | /** | ||
135 | * Starts listening for paired devices. | ||
136 | * | ||
137 | * @param client The companion_proxy client | ||
138 | * @param callback Callback function that will be called when a new device is detected | ||
139 | * @param userdata Pointer that that will be passed to the callback function | ||
140 | * | ||
141 | * @note The event parameter that gets passed to the callback function is | ||
142 | * freed internally after returning from the callback. The consumer needs | ||
143 | * to make a copy if required. | ||
144 | * | ||
145 | * @return COMPANION_PROXY_E_SUCCESS on success, | ||
146 | * or a COMPANION_PROXY_E_* error code otherwise. | ||
147 | */ | ||
148 | LIBIMOBILEDEVICE_API companion_proxy_error_t companion_proxy_start_listening_for_devices(companion_proxy_client_t client, companion_proxy_device_event_cb_t callback, void* userdata); | ||
149 | |||
150 | /** | ||
151 | * Stops listening for paired devices | ||
152 | * | ||
153 | * @param client The companion_proxy client | ||
154 | * | ||
155 | * @return COMPANION_PROXY_E_SUCCESS on success, | ||
156 | * or a COMPANION_PROXY_E_* error code otherwise. | ||
157 | */ | ||
158 | LIBIMOBILEDEVICE_API companion_proxy_error_t companion_proxy_stop_listening_for_devices(companion_proxy_client_t client); | ||
159 | |||
160 | /** | ||
161 | * Returns a value for the given key. | ||
162 | * | ||
163 | * @param client The companion_proxy client | ||
164 | * @param companion_udid UDID of the (paired) companion device | ||
165 | * @param key The key to retrieve the value for | ||
166 | * @param value A pointer to a plist_t that will receive the value for the given key. | ||
167 | * The consumer is responsible for freeing the value with plist_free() when no longer needed. | ||
168 | * | ||
169 | * @note The device closes the connection after sending the reply. | ||
170 | * | ||
171 | * @return COMPANION_PROXY_E_SUCCESS on success, | ||
172 | * COMPANION_PROXY_E_INVALID_ARG when client or paired_devices is invalid, | ||
173 | * COMPANION_PROXY_E_UNSUPPORTED_KEY if the companion device doesn't support the given key, | ||
174 | * or a COMPANION_PROXY_E_* error code otherwise. | ||
175 | */ | ||
176 | LIBIMOBILEDEVICE_API companion_proxy_error_t companion_proxy_get_value_from_registry(companion_proxy_client_t client, const char* companion_udid, const char* key, plist_t* value); | ||
177 | |||
178 | /** | ||
179 | * Start forwarding a service port on the companion device to a port on the idevice. | ||
180 | * | ||
181 | * @see companion_proxy_stop_forwarding_service_port | ||
182 | * | ||
183 | * @param client The companion_proxy client | ||
184 | * @param remote_port remote port | ||
185 | * @param service_name The name of the service that shall be forwarded | ||
186 | * @param forward_port Pointer that will receive the newly-assigned port accessible via USB/Network on the idevice | ||
187 | * @param options PLIST_DICT with additional options. Currently known are | ||
188 | * IsServiceLowPriority (boolean) and PreferWifi (boolean). | ||
189 | * | ||
190 | * @return COMPANION_PROXY_E_SUCCESS on success, | ||
191 | * or a COMPANION_PROXY_E_* error code otherwise. | ||
192 | */ | ||
193 | LIBIMOBILEDEVICE_API companion_proxy_error_t companion_proxy_start_forwarding_service_port(companion_proxy_client_t client, uint16_t remote_port, const char* service_name, uint16_t* forward_port, plist_t options); | ||
194 | |||
195 | /** | ||
196 | * Stop forwarding a service port between companion device and idevice. | ||
197 | * | ||
198 | * @see companion_proxy_start_forwarding_service_port | ||
199 | * | ||
200 | * @param client The companion_proxy client | ||
201 | * @param remote_port remote port | ||
202 | * | ||
203 | * @return COMPANION_PROXY_E_SUCCESS on success, | ||
204 | * or a COMPANION_PROXY_E_* error code otherwise. | ||
205 | */ | ||
206 | LIBIMOBILEDEVICE_API companion_proxy_error_t companion_proxy_stop_forwarding_service_port(companion_proxy_client_t client, uint16_t remote_port); | ||
207 | |||
208 | #ifdef __cplusplus | ||
209 | } | ||
210 | #endif | ||
211 | |||
212 | #endif | ||
diff --git a/include/libimobiledevice/debugserver.h b/include/libimobiledevice/debugserver.h new file mode 100644 index 0000000..809b97f --- /dev/null +++ b/include/libimobiledevice/debugserver.h | |||
@@ -0,0 +1,272 @@ | |||
1 | /** | ||
2 | * @file libimobiledevice/debugserver.h | ||
3 | * @brief Communicate with debugserver on the device. | ||
4 | * \internal | ||
5 | * | ||
6 | * Copyright (c) 2014 Martin Szulecki All Rights Reserved. | ||
7 | * | ||
8 | * This library is free software; you can redistribute it and/or | ||
9 | * modify it under the terms of the GNU Lesser General Public | ||
10 | * License as published by the Free Software Foundation; either | ||
11 | * version 2.1 of the License, or (at your option) any later version. | ||
12 | * | ||
13 | * This library is distributed in the hope that it will be useful, | ||
14 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
15 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
16 | * Lesser General Public License for more details. | ||
17 | * | ||
18 | * You should have received a copy of the GNU Lesser General Public | ||
19 | * License along with this library; if not, write to the Free Software | ||
20 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | ||
21 | */ | ||
22 | |||
23 | #ifndef IDEBUGSERVER_H | ||
24 | #define IDEBUGSERVER_H | ||
25 | |||
26 | #ifdef __cplusplus | ||
27 | extern "C" { | ||
28 | #endif | ||
29 | |||
30 | #include <libimobiledevice/libimobiledevice.h> | ||
31 | #include <libimobiledevice/lockdown.h> | ||
32 | |||
33 | /** Service identifier passed to lockdownd_start_service() to start the debugserver service */ | ||
34 | #define DEBUGSERVER_SERVICE_NAME "com.apple.debugserver" | ||
35 | /** Service identifier passed to lockdownd_start_service() to start the secure debugserver service */ | ||
36 | #define DEBUGSERVER_SECURE_SERVICE_NAME DEBUGSERVER_SERVICE_NAME ".DVTSecureSocketProxy" | ||
37 | |||
38 | /** Error Codes */ | ||
39 | typedef enum { | ||
40 | DEBUGSERVER_E_SUCCESS = 0, | ||
41 | DEBUGSERVER_E_INVALID_ARG = -1, | ||
42 | DEBUGSERVER_E_MUX_ERROR = -2, | ||
43 | DEBUGSERVER_E_SSL_ERROR = -3, | ||
44 | DEBUGSERVER_E_RESPONSE_ERROR = -4, | ||
45 | DEBUGSERVER_E_TIMEOUT = -5, | ||
46 | DEBUGSERVER_E_UNKNOWN_ERROR = -256 | ||
47 | } debugserver_error_t; | ||
48 | |||
49 | typedef struct debugserver_client_private debugserver_client_private; /**< \private */ | ||
50 | typedef debugserver_client_private *debugserver_client_t; /**< The client handle. */ | ||
51 | |||
52 | typedef struct debugserver_command_private debugserver_command_private; /**< \private */ | ||
53 | typedef debugserver_command_private *debugserver_command_t; /**< The command handle. */ | ||
54 | |||
55 | /* Interface */ | ||
56 | |||
57 | /** | ||
58 | * Connects to the debugserver service on the specified device. | ||
59 | * | ||
60 | * @param device The device to connect to. | ||
61 | * @param service The service descriptor returned by lockdownd_start_service. | ||
62 | * @param client Pointer that will point to a newly allocated | ||
63 | * debugserver_client_t upon successful return. Must be freed using | ||
64 | * debugserver_client_free() after use. | ||
65 | * | ||
66 | * @return DEBUGSERVER_E_SUCCESS on success, DEBUGSERVER_E_INVALID_ARG when | ||
67 | * client is NULL, or an DEBUGSERVER_E_* error code otherwise. | ||
68 | */ | ||
69 | LIBIMOBILEDEVICE_API debugserver_error_t debugserver_client_new(idevice_t device, lockdownd_service_descriptor_t service, debugserver_client_t * client); | ||
70 | |||
71 | /** | ||
72 | * Starts a new debugserver service on the specified device and connects to it. | ||
73 | * | ||
74 | * @param device The device to connect to. | ||
75 | * @param client Pointer that will point to a newly allocated | ||
76 | * debugserver_client_t upon successful return. Must be freed using | ||
77 | * debugserver_client_free() after use. | ||
78 | * @param label The label to use for communication. Usually the program name. | ||
79 | * Pass NULL to disable sending the label in requests to lockdownd. | ||
80 | * | ||
81 | * @return DEBUGSERVER_E_SUCCESS on success, or an DEBUGSERVER_E_* error | ||
82 | * code otherwise. | ||
83 | */ | ||
84 | LIBIMOBILEDEVICE_API debugserver_error_t debugserver_client_start_service(idevice_t device, debugserver_client_t * client, const char* label); | ||
85 | |||
86 | /** | ||
87 | * Disconnects a debugserver client from the device and frees up the | ||
88 | * debugserver client data. | ||
89 | * | ||
90 | * @param client The debugserver client to disconnect and free. | ||
91 | * | ||
92 | * @return DEBUGSERVER_E_SUCCESS on success, DEBUGSERVER_E_INVALID_ARG when | ||
93 | * client is NULL, or an DEBUGSERVER_E_* error code otherwise. | ||
94 | */ | ||
95 | LIBIMOBILEDEVICE_API debugserver_error_t debugserver_client_free(debugserver_client_t client); | ||
96 | |||
97 | /** | ||
98 | * Sends raw data using the given debugserver service client. | ||
99 | * | ||
100 | * @param client The debugserver client to use for sending | ||
101 | * @param data Data to send | ||
102 | * @param size Size of the data to send | ||
103 | * @param sent Number of bytes sent (can be NULL to ignore) | ||
104 | * | ||
105 | * @return DEBUGSERVER_E_SUCCESS on success, | ||
106 | * DEBUGSERVER_E_INVALID_ARG when one or more parameters are | ||
107 | * invalid, or DEBUGSERVER_E_UNKNOWN_ERROR when an unspecified | ||
108 | * error occurs. | ||
109 | */ | ||
110 | LIBIMOBILEDEVICE_API debugserver_error_t debugserver_client_send(debugserver_client_t client, const char* data, uint32_t size, uint32_t *sent); | ||
111 | |||
112 | /** | ||
113 | * Receives raw data using the given debugserver client with specified timeout. | ||
114 | * | ||
115 | * @param client The debugserver client to use for receiving | ||
116 | * @param data Buffer that will be filled with the data received | ||
117 | * @param size Number of bytes to receive | ||
118 | * @param received Number of bytes received (can be NULL to ignore) | ||
119 | * @param timeout Maximum time in milliseconds to wait for data. | ||
120 | * | ||
121 | * @return DEBUGSERVER_E_SUCCESS on success, | ||
122 | * DEBUGSERVER_E_INVALID_ARG when one or more parameters are | ||
123 | * invalid, DEBUGSERVER_E_MUX_ERROR when a communication error | ||
124 | * occurs, DEBUGSERVER_E_TIMEOUT when the timeout is reached, | ||
125 | * or DEBUGSERVER_E_UNKNOWN_ERROR when an unspecified | ||
126 | * error occurs. | ||
127 | */ | ||
128 | LIBIMOBILEDEVICE_API debugserver_error_t debugserver_client_receive_with_timeout(debugserver_client_t client, char *data, uint32_t size, uint32_t *received, unsigned int timeout); | ||
129 | |||
130 | /** | ||
131 | * Receives raw data from the debugserver service. | ||
132 | * | ||
133 | * @param client The debugserver client | ||
134 | * @param data Buffer that will be filled with the data received | ||
135 | * @param size Number of bytes to receive | ||
136 | * @param received Number of bytes received (can be NULL to ignore) | ||
137 | * @note The default read timeout is 10 seconds. | ||
138 | * | ||
139 | * @return DEBUGSERVER_E_SUCCESS on success, | ||
140 | * DEBUGSERVER_E_INVALID_ARG when client or plist is NULL | ||
141 | */ | ||
142 | LIBIMOBILEDEVICE_API debugserver_error_t debugserver_client_receive(debugserver_client_t client, char *data, uint32_t size, uint32_t *received); | ||
143 | |||
144 | /** | ||
145 | * Sends a command to the debugserver service. | ||
146 | * | ||
147 | * @param client The debugserver client | ||
148 | * @param command Command to process and send | ||
149 | * @param response Response received for the command (can be NULL to ignore) | ||
150 | * @param response_size Pointer to receive response size. Set to NULL to ignore. | ||
151 | * | ||
152 | * @return DEBUGSERVER_E_SUCCESS on success, | ||
153 | * DEBUGSERVER_E_INVALID_ARG when client or command is NULL | ||
154 | */ | ||
155 | LIBIMOBILEDEVICE_API debugserver_error_t debugserver_client_send_command(debugserver_client_t client, debugserver_command_t command, char** response, size_t* response_size); | ||
156 | |||
157 | /** | ||
158 | * Receives and parses response of debugserver service. | ||
159 | * | ||
160 | * @param client The debugserver client | ||
161 | * @param response Response received for last command (can be NULL to ignore) | ||
162 | * @param response_size Pointer to receive response size. Set to NULL to ignore. | ||
163 | * | ||
164 | * @return DEBUGSERVER_E_SUCCESS on success, | ||
165 | * DEBUGSERVER_E_INVALID_ARG when client is NULL | ||
166 | */ | ||
167 | LIBIMOBILEDEVICE_API debugserver_error_t debugserver_client_receive_response(debugserver_client_t client, char** response, size_t* response_size); | ||
168 | |||
169 | /** | ||
170 | * Controls status of ACK mode when sending commands or receiving responses. | ||
171 | * | ||
172 | * @see debugserver_client_send_command, debugserver_client_receive_response | ||
173 | * | ||
174 | * @param client The debugserver client | ||
175 | * @param enabled A boolean flag indicating whether the internal ACK mode | ||
176 | * handling should be enabled or disabled. | ||
177 | * | ||
178 | * @return DEBUGSERVER_E_SUCCESS on success, or an DEBUGSERVER_E_* error | ||
179 | * code otherwise. | ||
180 | */ | ||
181 | LIBIMOBILEDEVICE_API debugserver_error_t debugserver_client_set_ack_mode(debugserver_client_t client, int enabled); | ||
182 | |||
183 | /** | ||
184 | * Sets behavior when awaiting a response from the server. | ||
185 | * | ||
186 | * @see debugserver_client_send_command, debugserver_client_receive_response, | ||
187 | * debugserver_client_receive | ||
188 | * | ||
189 | * @param client The debugserver client | ||
190 | * @param cancel_receive A function pointer that will be called approximately | ||
191 | * every receive_loop_timeout milliseconds; the function should return a | ||
192 | * boolean flag specifying whether to stop waiting for a response. If NULL, | ||
193 | * behaves as if it always returns true. | ||
194 | * @param receive_loop_timeout Time in milliseconds between calls to | ||
195 | * cancel_receive. | ||
196 | * | ||
197 | * @return DEBUGSERVER_E_SUCCESS on success, or an DEBUGSERVER_E_* error | ||
198 | * code otherwise. | ||
199 | */ | ||
200 | LIBIMOBILEDEVICE_API debugserver_error_t debugserver_client_set_receive_params(debugserver_client_t client, int (*cancel_receive)(), int receive_loop_timeout); | ||
201 | |||
202 | /** | ||
203 | * Sets the argv which launches an app. | ||
204 | * | ||
205 | * @param client The debugserver client | ||
206 | * @param argc Number of arguments | ||
207 | * @param argv Array starting with the executable to be run followed by it's arguments | ||
208 | * @param response Response received for the command (can be NULL to ignore) | ||
209 | * | ||
210 | * @return DEBUGSERVER_E_SUCCESS on success, | ||
211 | * DEBUGSERVER_E_INVALID_ARG when client is NULL | ||
212 | */ | ||
213 | LIBIMOBILEDEVICE_API debugserver_error_t debugserver_client_set_argv(debugserver_client_t client, int argc, char* argv[], char** response); | ||
214 | |||
215 | /** | ||
216 | * Adds or sets an environment variable. | ||
217 | * | ||
218 | * @param client The debugserver client | ||
219 | * @param env The environment variable in "KEY=VALUE" notation | ||
220 | * @param response Response received for the command (can be NULL to ignore) | ||
221 | * | ||
222 | * @return DEBUGSERVER_E_SUCCESS on success, | ||
223 | * DEBUGSERVER_E_INVALID_ARG when client is NULL | ||
224 | */ | ||
225 | LIBIMOBILEDEVICE_API debugserver_error_t debugserver_client_set_environment_hex_encoded(debugserver_client_t client, const char* env, char** response); | ||
226 | |||
227 | /** | ||
228 | * Creates and initializes a new command object. | ||
229 | * | ||
230 | * @param name The name of the command which is sent in plain text | ||
231 | * @param argv Array of tokens for the command ment to be encoded | ||
232 | * @param argc Number of items in the token array | ||
233 | * @param command New command object | ||
234 | * | ||
235 | * @return DEBUGSERVER_E_SUCCESS on success, | ||
236 | * DEBUGSERVER_E_INVALID_ARG when name or command is NULL | ||
237 | */ | ||
238 | LIBIMOBILEDEVICE_API debugserver_error_t debugserver_command_new(const char* name, int argc, char* argv[], debugserver_command_t* command); | ||
239 | |||
240 | /** | ||
241 | * Frees memory of command object. | ||
242 | * | ||
243 | * @param command The command object | ||
244 | * | ||
245 | * @return DEBUGSERVER_E_SUCCESS on success, | ||
246 | * DEBUGSERVER_E_INVALID_ARG when command is NULL | ||
247 | */ | ||
248 | LIBIMOBILEDEVICE_API debugserver_error_t debugserver_command_free(debugserver_command_t command); | ||
249 | |||
250 | /** | ||
251 | * Encodes a string into hex notation. | ||
252 | * | ||
253 | * @param buffer String to encode into hex notiation | ||
254 | * @param encoded_buffer The buffer receives a hex encoded string | ||
255 | * @param encoded_length Length of the hex encoded string | ||
256 | */ | ||
257 | LIBIMOBILEDEVICE_API void debugserver_encode_string(const char* buffer, char** encoded_buffer, uint32_t* encoded_length); | ||
258 | |||
259 | /** | ||
260 | * Decodes a hex encoded string. | ||
261 | * | ||
262 | * @param encoded_buffer The buffer with a hex encoded string | ||
263 | * @param encoded_length Length of the encoded buffer | ||
264 | * @param buffer Decoded string to be freed by the caller | ||
265 | */ | ||
266 | LIBIMOBILEDEVICE_API void debugserver_decode_string(const char *encoded_buffer, size_t encoded_length, char** buffer); | ||
267 | |||
268 | #ifdef __cplusplus | ||
269 | } | ||
270 | #endif | ||
271 | |||
272 | #endif | ||
diff --git a/include/libimobiledevice/diagnostics_relay.h b/include/libimobiledevice/diagnostics_relay.h new file mode 100644 index 0000000..6ab47a9 --- /dev/null +++ b/include/libimobiledevice/diagnostics_relay.h | |||
@@ -0,0 +1,228 @@ | |||
1 | /** | ||
2 | * @file libimobiledevice/diagnostics_relay.h | ||
3 | * @brief Request iOS diagnostic information from device. | ||
4 | * \internal | ||
5 | * | ||
6 | * Copyright (c) 2012-2014 Martin Szulecki, All Rights Reserved. | ||
7 | * | ||
8 | * This library is free software; you can redistribute it and/or | ||
9 | * modify it under the terms of the GNU Lesser General Public | ||
10 | * License as published by the Free Software Foundation; either | ||
11 | * version 2.1 of the License, or (at your option) any later version. | ||
12 | * | ||
13 | * This library is distributed in the hope that it will be useful, | ||
14 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
15 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
16 | * Lesser General Public License for more details. | ||
17 | * | ||
18 | * You should have received a copy of the GNU Lesser General Public | ||
19 | * License along with this library; if not, write to the Free Software | ||
20 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | ||
21 | */ | ||
22 | |||
23 | #ifndef IDIAGNOSTICS_RELAY_H | ||
24 | #define IDIAGNOSTICS_RELAY_H | ||
25 | |||
26 | #ifdef __cplusplus | ||
27 | extern "C" { | ||
28 | #endif | ||
29 | |||
30 | #include <libimobiledevice/libimobiledevice.h> | ||
31 | #include <libimobiledevice/lockdown.h> | ||
32 | |||
33 | /** Service identifier passed to lockdownd_start_service() to start the diagnostics relay service */ | ||
34 | #define DIAGNOSTICS_RELAY_SERVICE_NAME "com.apple.mobile.diagnostics_relay" | ||
35 | |||
36 | /** Error Codes */ | ||
37 | typedef enum { | ||
38 | DIAGNOSTICS_RELAY_E_SUCCESS = 0, | ||
39 | DIAGNOSTICS_RELAY_E_INVALID_ARG = -1, | ||
40 | DIAGNOSTICS_RELAY_E_PLIST_ERROR = -2, | ||
41 | DIAGNOSTICS_RELAY_E_MUX_ERROR = -3, | ||
42 | DIAGNOSTICS_RELAY_E_UNKNOWN_REQUEST = -4, | ||
43 | DIAGNOSTICS_RELAY_E_UNKNOWN_ERROR = -256 | ||
44 | } diagnostics_relay_error_t; | ||
45 | |||
46 | /** Action type for #diagnostics_relay_restart and #diagnostics_relay_shutdown */ | ||
47 | typedef enum { | ||
48 | DIAGNOSTICS_RELAY_ACTION_FLAG_WAIT_FOR_DISCONNECT = 1 << 1, | ||
49 | DIAGNOSTICS_RELAY_ACTION_FLAG_DISPLAY_PASS = 1 << 2, | ||
50 | DIAGNOSTICS_RELAY_ACTION_FLAG_DISPLAY_FAIL = 1 << 3 | ||
51 | } diagnostics_relay_action_t; | ||
52 | |||
53 | #define DIAGNOSTICS_RELAY_REQUEST_TYPE_ALL "All" /**< Query all available diagnostics */ | ||
54 | #define DIAGNOSTICS_RELAY_REQUEST_TYPE_WIFI "WiFi" /**< Query WiFi diagnostics */ | ||
55 | #define DIAGNOSTICS_RELAY_REQUEST_TYPE_GAS_GAUGE "GasGauge" /**< Query GasGauge diagnostics */ | ||
56 | #define DIAGNOSTICS_RELAY_REQUEST_TYPE_NAND "NAND" /**< Query NAND diagnostics */ | ||
57 | |||
58 | typedef struct diagnostics_relay_client_private diagnostics_relay_client_private; /**< \private */ | ||
59 | typedef diagnostics_relay_client_private *diagnostics_relay_client_t; /**< The client handle. */ | ||
60 | |||
61 | /** | ||
62 | * Connects to the diagnostics_relay service on the specified device. | ||
63 | * | ||
64 | * @param device The device to connect to. | ||
65 | * @param service The service descriptor returned by lockdownd_start_service. | ||
66 | * @param client Reference that will point to a newly allocated | ||
67 | * diagnostics_relay_client_t upon successful return. | ||
68 | * | ||
69 | * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, | ||
70 | * DIAGNOSTICS_RELAY_E_INVALID_ARG when one of the parameters is invalid, | ||
71 | * or DIAGNOSTICS_RELAY_E_MUX_ERROR when the connection failed. | ||
72 | */ | ||
73 | LIBIMOBILEDEVICE_API diagnostics_relay_error_t diagnostics_relay_client_new(idevice_t device, lockdownd_service_descriptor_t service, diagnostics_relay_client_t *client); | ||
74 | |||
75 | /** | ||
76 | * Starts a new diagnostics_relay service on the specified device and connects to it. | ||
77 | * | ||
78 | * @param device The device to connect to. | ||
79 | * @param client Pointer that will point to a newly allocated | ||
80 | * diagnostics_relay_client_t upon successful return. Must be freed using | ||
81 | * diagnostics_relay_client_free() after use. | ||
82 | * @param label The label to use for communication. Usually the program name. | ||
83 | * Pass NULL to disable sending the label in requests to lockdownd. | ||
84 | * | ||
85 | * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, or an DIAGNOSTICS_RELAY_E_* error | ||
86 | * code otherwise. | ||
87 | */ | ||
88 | LIBIMOBILEDEVICE_API diagnostics_relay_error_t diagnostics_relay_client_start_service(idevice_t device, diagnostics_relay_client_t* client, const char* label); | ||
89 | |||
90 | /** | ||
91 | * Disconnects a diagnostics_relay client from the device and frees up the | ||
92 | * diagnostics_relay client data. | ||
93 | * | ||
94 | * @param client The diagnostics_relay client to disconnect and free. | ||
95 | * | ||
96 | * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, | ||
97 | * DIAGNOSTICS_RELAY_E_INVALID_ARG when one of client or client->parent | ||
98 | * is invalid, or DIAGNOSTICS_RELAY_E_UNKNOWN_ERROR when the was an | ||
99 | * error freeing the parent property_list_service client. | ||
100 | */ | ||
101 | LIBIMOBILEDEVICE_API diagnostics_relay_error_t diagnostics_relay_client_free(diagnostics_relay_client_t client); | ||
102 | |||
103 | |||
104 | /** | ||
105 | * Sends the Goodbye request signaling the end of communication. | ||
106 | * | ||
107 | * @param client The diagnostics_relay client | ||
108 | * | ||
109 | * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, | ||
110 | * DIAGNOSTICS_RELAY_E_INVALID_ARG when client is NULL, | ||
111 | * DIAGNOSTICS_RELAY_E_PLIST_ERROR if the device did not acknowledge the | ||
112 | * request | ||
113 | */ | ||
114 | LIBIMOBILEDEVICE_API diagnostics_relay_error_t diagnostics_relay_goodbye(diagnostics_relay_client_t client); | ||
115 | |||
116 | /** | ||
117 | * Puts the device into deep sleep mode and disconnects from host. | ||
118 | * | ||
119 | * @param client The diagnostics_relay client | ||
120 | * | ||
121 | * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, | ||
122 | * DIAGNOSTICS_RELAY_E_INVALID_ARG when client is NULL, | ||
123 | * DIAGNOSTICS_RELAY_E_PLIST_ERROR if the device did not acknowledge the | ||
124 | * request | ||
125 | */ | ||
126 | LIBIMOBILEDEVICE_API diagnostics_relay_error_t diagnostics_relay_sleep(diagnostics_relay_client_t client); | ||
127 | |||
128 | /** | ||
129 | * Restart the device and optionally show a user notification. | ||
130 | * | ||
131 | * @param client The diagnostics_relay client | ||
132 | * @param flags A binary flag combination of | ||
133 | * DIAGNOSTICS_RELAY_ACTION_FLAG_WAIT_FOR_DISCONNECT to wait until | ||
134 | * diagnostics_relay_client_free() disconnects before execution and | ||
135 | * DIAGNOSTICS_RELAY_ACTION_FLAG_DISPLAY_FAIL to show a "FAIL" dialog | ||
136 | * or DIAGNOSTICS_RELAY_ACTION_FLAG_DISPLAY_PASS to show an "OK" dialog | ||
137 | * | ||
138 | * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, | ||
139 | * DIAGNOSTICS_RELAY_E_INVALID_ARG when client is NULL, | ||
140 | * DIAGNOSTICS_RELAY_E_PLIST_ERROR if the device did not acknowledge the | ||
141 | * request | ||
142 | */ | ||
143 | LIBIMOBILEDEVICE_API diagnostics_relay_error_t diagnostics_relay_restart(diagnostics_relay_client_t client, diagnostics_relay_action_t flags); | ||
144 | |||
145 | /** | ||
146 | * Shutdown of the device and optionally show a user notification. | ||
147 | * | ||
148 | * @param client The diagnostics_relay client | ||
149 | * @param flags A binary flag combination of | ||
150 | * DIAGNOSTICS_RELAY_ACTION_FLAG_WAIT_FOR_DISCONNECT to wait until | ||
151 | * diagnostics_relay_client_free() disconnects before execution and | ||
152 | * DIAGNOSTICS_RELAY_ACTION_FLAG_DISPLAY_FAIL to show a "FAIL" dialog | ||
153 | * or DIAGNOSTICS_RELAY_ACTION_FLAG_DISPLAY_PASS to show an "OK" dialog | ||
154 | * | ||
155 | * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, | ||
156 | * DIAGNOSTICS_RELAY_E_INVALID_ARG when client is NULL, | ||
157 | * DIAGNOSTICS_RELAY_E_PLIST_ERROR if the device did not acknowledge the | ||
158 | * request | ||
159 | */ | ||
160 | LIBIMOBILEDEVICE_API diagnostics_relay_error_t diagnostics_relay_shutdown(diagnostics_relay_client_t client, diagnostics_relay_action_t flags); | ||
161 | |||
162 | /** | ||
163 | * Request diagnostics information for a given type. | ||
164 | * | ||
165 | * @param client The diagnostics_relay client | ||
166 | * @param type The type or domain to query for diagnostics. Some known values | ||
167 | * are "All", "WiFi", "GasGauge", and "NAND". | ||
168 | * @param diagnostics A pointer to plist_t that will receive the diagnostics information. | ||
169 | * The consumer has to free the allocated memory with plist_free() when no longer needed. | ||
170 | * | ||
171 | * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, | ||
172 | * DIAGNOSTICS_RELAY_E_INVALID_ARG when client is NULL, | ||
173 | * DIAGNOSTICS_RELAY_E_PLIST_ERROR if the device did not acknowledge the | ||
174 | * request | ||
175 | */ | ||
176 | LIBIMOBILEDEVICE_API diagnostics_relay_error_t diagnostics_relay_request_diagnostics(diagnostics_relay_client_t client, const char* type, plist_t* diagnostics); | ||
177 | |||
178 | /** | ||
179 | * Query one or multiple MobileGestalt keys. | ||
180 | * | ||
181 | * @param client The diagnostics_relay client | ||
182 | * @param keys A PLIST_ARRAY with the keys to query. | ||
183 | * @param result A pointer to plist_t that will receive the result. The consumer | ||
184 | * has to free the allocated memory with plist_free() when no longer needed. | ||
185 | * | ||
186 | * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, | ||
187 | * DIAGNOSTICS_RELAY_E_INVALID_ARG when client is NULL, | ||
188 | * DIAGNOSTICS_RELAY_E_PLIST_ERROR if the device did not acknowledge the | ||
189 | * request | ||
190 | */ | ||
191 | LIBIMOBILEDEVICE_API diagnostics_relay_error_t diagnostics_relay_query_mobilegestalt(diagnostics_relay_client_t client, plist_t keys, plist_t* result); | ||
192 | |||
193 | /** | ||
194 | * Query an IORegistry entry of a given class. | ||
195 | * | ||
196 | * @param client The diagnostics_relay client | ||
197 | * @param entry_name The IORegistry entry name to query. | ||
198 | * @param entry_class The IORegistry class to query. | ||
199 | * @param result A pointer to plist_t that will receive the result. The consumer | ||
200 | * has to free the allocated memory with plist_free() when no longer needed. | ||
201 | * | ||
202 | * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, | ||
203 | * DIAGNOSTICS_RELAY_E_INVALID_ARG when client is NULL, | ||
204 | * DIAGNOSTICS_RELAY_E_PLIST_ERROR if the device did not acknowledge the | ||
205 | * request | ||
206 | */ | ||
207 | LIBIMOBILEDEVICE_API diagnostics_relay_error_t diagnostics_relay_query_ioregistry_entry(diagnostics_relay_client_t client, const char* entry_name, const char* entry_class, plist_t* result); | ||
208 | |||
209 | /** | ||
210 | * Query an IORegistry plane. | ||
211 | * | ||
212 | * @param client The diagnostics_relay client | ||
213 | * @param plane The IORegistry plane name to query. | ||
214 | * @param result A pointer to plist_t that will receive the result. The consumer | ||
215 | * has to free the allocated memory with plist_free() when no longer needed. | ||
216 | * | ||
217 | * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, | ||
218 | * DIAGNOSTICS_RELAY_E_INVALID_ARG when client is NULL, | ||
219 | * DIAGNOSTICS_RELAY_E_PLIST_ERROR if the device did not acknowledge the | ||
220 | * request | ||
221 | */ | ||
222 | LIBIMOBILEDEVICE_API diagnostics_relay_error_t diagnostics_relay_query_ioregistry_plane(diagnostics_relay_client_t client, const char* plane, plist_t* result); | ||
223 | |||
224 | #ifdef __cplusplus | ||
225 | } | ||
226 | #endif | ||
227 | |||
228 | #endif | ||
diff --git a/include/libimobiledevice/file_relay.h b/include/libimobiledevice/file_relay.h index 52d4758..00773b8 100644 --- a/include/libimobiledevice/file_relay.h +++ b/include/libimobiledevice/file_relay.h | |||
@@ -3,6 +3,8 @@ | |||
3 | * @brief Retrieve compressed CPIO archives. | 3 | * @brief Retrieve compressed CPIO archives. |
4 | * \internal | 4 | * \internal |
5 | * | 5 | * |
6 | * Copyright (c) 2010-2014 Martin Szulecki All Rights Reserved. | ||
7 | * Copyright (c) 2014 Aaron Burghardt All Rights Reserved. | ||
6 | * Copyright (c) 2010 Nikias Bassen All Rights Reserved. | 8 | * Copyright (c) 2010 Nikias Bassen All Rights Reserved. |
7 | * | 9 | * |
8 | * This library is free software; you can redistribute it and/or | 10 | * This library is free software; you can redistribute it and/or |
@@ -28,29 +30,134 @@ extern "C" { | |||
28 | #endif | 30 | #endif |
29 | 31 | ||
30 | #include <libimobiledevice/libimobiledevice.h> | 32 | #include <libimobiledevice/libimobiledevice.h> |
33 | #include <libimobiledevice/lockdown.h> | ||
31 | 34 | ||
32 | /** @name Error Codes */ | 35 | /** Service identifier passed to lockdownd_start_service() to start the file relay service */ |
33 | /*@{*/ | 36 | #define FILE_RELAY_SERVICE_NAME "com.apple.mobile.file_relay" |
34 | #define FILE_RELAY_E_SUCCESS 0 | ||
35 | #define FILE_RELAY_E_INVALID_ARG -1 | ||
36 | #define FILE_RELAY_E_PLIST_ERROR -2 | ||
37 | #define FILE_RELAY_E_MUX_ERROR -3 | ||
38 | #define FILE_RELAY_E_INVALID_SOURCE -4 | ||
39 | #define FILE_RELAY_E_STAGING_EMPTY -5 | ||
40 | 37 | ||
41 | #define FILE_RELAY_E_UNKNOWN_ERROR -256 | 38 | /** Error Codes */ |
42 | /*@}*/ | 39 | typedef enum { |
40 | FILE_RELAY_E_SUCCESS = 0, | ||
41 | FILE_RELAY_E_INVALID_ARG = -1, | ||
42 | FILE_RELAY_E_PLIST_ERROR = -2, | ||
43 | FILE_RELAY_E_MUX_ERROR = -3, | ||
44 | FILE_RELAY_E_INVALID_SOURCE = -4, | ||
45 | FILE_RELAY_E_STAGING_EMPTY = -5, | ||
46 | FILE_RELAY_E_PERMISSION_DENIED = -6, | ||
47 | FILE_RELAY_E_UNKNOWN_ERROR = -256 | ||
48 | } file_relay_error_t; | ||
43 | 49 | ||
44 | /** Represents an error code. */ | 50 | typedef struct file_relay_client_private file_relay_client_private; /**< \private */ |
45 | typedef int16_t file_relay_error_t; | ||
46 | |||
47 | typedef struct file_relay_client_private file_relay_client_private; | ||
48 | typedef file_relay_client_private *file_relay_client_t; /**< The client handle. */ | 51 | typedef file_relay_client_private *file_relay_client_t; /**< The client handle. */ |
49 | 52 | ||
50 | file_relay_error_t file_relay_client_new(idevice_t device, uint16_t port, file_relay_client_t *client); | 53 | /** |
51 | file_relay_error_t file_relay_client_free(file_relay_client_t client); | 54 | * Connects to the file_relay service on the specified device. |
55 | * | ||
56 | * @param device The device to connect to. | ||
57 | * @param service The service descriptor returned by lockdownd_start_service. | ||
58 | * @param client Reference that will point to a newly allocated | ||
59 | * file_relay_client_t upon successful return. | ||
60 | * | ||
61 | * @return FILE_RELAY_E_SUCCESS on success, | ||
62 | * FILE_RELAY_E_INVALID_ARG when one of the parameters is invalid, | ||
63 | * or FILE_RELAY_E_MUX_ERROR when the connection failed. | ||
64 | */ | ||
65 | LIBIMOBILEDEVICE_API file_relay_error_t file_relay_client_new(idevice_t device, lockdownd_service_descriptor_t service, file_relay_client_t *client); | ||
66 | |||
67 | /** | ||
68 | * Starts a new file_relay service on the specified device and connects to it. | ||
69 | * | ||
70 | * @param device The device to connect to. | ||
71 | * @param client Pointer that will point to a newly allocated | ||
72 | * file_relay_client_t upon successful return. Must be freed using | ||
73 | * file_relay_client_free() after use. | ||
74 | * @param label The label to use for communication. Usually the program name. | ||
75 | * Pass NULL to disable sending the label in requests to lockdownd. | ||
76 | * | ||
77 | * @return FILE_RELAY_E_SUCCESS on success, or an FILE_RELAY_E_* error | ||
78 | * code otherwise. | ||
79 | */ | ||
80 | LIBIMOBILEDEVICE_API file_relay_error_t file_relay_client_start_service(idevice_t device, file_relay_client_t* client, const char* label); | ||
81 | |||
82 | /** | ||
83 | * Disconnects a file_relay client from the device and frees up the file_relay | ||
84 | * client data. | ||
85 | * | ||
86 | * @param client The file_relay client to disconnect and free. | ||
87 | * | ||
88 | * @return FILE_RELAY_E_SUCCESS on success, | ||
89 | * FILE_RELAY_E_INVALID_ARG when one of client or client->parent | ||
90 | * is invalid, or FILE_RELAY_E_UNKNOWN_ERROR when the was an error | ||
91 | * freeing the parent property_list_service client. | ||
92 | */ | ||
93 | LIBIMOBILEDEVICE_API file_relay_error_t file_relay_client_free(file_relay_client_t client); | ||
94 | |||
52 | 95 | ||
53 | file_relay_error_t file_relay_request_sources(file_relay_client_t client, const char **sources, idevice_connection_t *connection); | 96 | /** |
97 | * Request data for the given sources. | ||
98 | * | ||
99 | * @param client The connected file_relay client. | ||
100 | * @param sources A NULL-terminated list of sources to retrieve. | ||
101 | * Valid sources are: | ||
102 | * - AppleSupport | ||
103 | * - Network | ||
104 | * - VPN | ||
105 | * - WiFi | ||
106 | * - UserDatabases | ||
107 | * - CrashReporter | ||
108 | * - tmp | ||
109 | * - SystemConfiguration | ||
110 | * @param connection The connection that has to be used for receiving the | ||
111 | * data using idevice_connection_receive(). The connection will be closed | ||
112 | * automatically by the device, but use file_relay_client_free() to clean | ||
113 | * up properly. | ||
114 | * | ||
115 | * @note WARNING: Don't call this function without reading the data afterwards. | ||
116 | * A directory mobile_file_relay.XXXX used for creating the archive will | ||
117 | * remain in the /tmp directory otherwise. | ||
118 | * | ||
119 | * @return FILE_RELAY_E_SUCCESS on succes, FILE_RELAY_E_INVALID_ARG when one or | ||
120 | * more parameters are invalid, FILE_RELAY_E_MUX_ERROR if a communication | ||
121 | * error occurs, FILE_RELAY_E_PLIST_ERROR when the received result is NULL | ||
122 | * or is not a valid plist, FILE_RELAY_E_INVALID_SOURCE if one or more | ||
123 | * sources are invalid, FILE_RELAY_E_STAGING_EMPTY if no data is available | ||
124 | * for the given sources, or FILE_RELAY_E_UNKNOWN_ERROR otherwise. | ||
125 | */ | ||
126 | LIBIMOBILEDEVICE_API file_relay_error_t file_relay_request_sources(file_relay_client_t client, const char **sources, idevice_connection_t *connection); | ||
127 | |||
128 | /** | ||
129 | * Request data for the given sources. Calls file_relay_request_sources_timeout() with | ||
130 | * a timeout of 60000 milliseconds (60 seconds). | ||
131 | * | ||
132 | * @param client The connected file_relay client. | ||
133 | * @param sources A NULL-terminated list of sources to retrieve. | ||
134 | * Valid sources are: | ||
135 | * - AppleSupport | ||
136 | * - Network | ||
137 | * - VPN | ||
138 | * - WiFi | ||
139 | * - UserDatabases | ||
140 | * - CrashReporter | ||
141 | * - tmp | ||
142 | * - SystemConfiguration | ||
143 | * @param connection The connection that has to be used for receiving the | ||
144 | * data using idevice_connection_receive(). The connection will be closed | ||
145 | * automatically by the device, but use file_relay_client_free() to clean | ||
146 | * up properly. | ||
147 | * @param timeout Maximum time in milliseconds to wait for data. | ||
148 | * | ||
149 | * @note WARNING: Don't call this function without reading the data afterwards. | ||
150 | * A directory mobile_file_relay.XXXX used for creating the archive will | ||
151 | * remain in the /tmp directory otherwise. | ||
152 | * | ||
153 | * @return FILE_RELAY_E_SUCCESS on succes, FILE_RELAY_E_INVALID_ARG when one or | ||
154 | * more parameters are invalid, FILE_RELAY_E_MUX_ERROR if a communication | ||
155 | * error occurs, FILE_RELAY_E_PLIST_ERROR when the received result is NULL | ||
156 | * or is not a valid plist, FILE_RELAY_E_INVALID_SOURCE if one or more | ||
157 | * sources are invalid, FILE_RELAY_E_STAGING_EMPTY if no data is available | ||
158 | * for the given sources, or FILE_RELAY_E_UNKNOWN_ERROR otherwise. | ||
159 | */ | ||
160 | LIBIMOBILEDEVICE_API file_relay_error_t file_relay_request_sources_timeout(file_relay_client_t client, const char **sources, idevice_connection_t *connection, unsigned int timeout); | ||
54 | 161 | ||
55 | #ifdef __cplusplus | 162 | #ifdef __cplusplus |
56 | } | 163 | } |
diff --git a/include/libimobiledevice/heartbeat.h b/include/libimobiledevice/heartbeat.h new file mode 100644 index 0000000..4074b8b --- /dev/null +++ b/include/libimobiledevice/heartbeat.h | |||
@@ -0,0 +1,137 @@ | |||
1 | /** | ||
2 | * @file libimobiledevice/heartbeat.h | ||
3 | * @brief Send "heartbeat" to device to allow service connections over network. | ||
4 | * \internal | ||
5 | * | ||
6 | * Copyright (c) 2013-2014 Martin Szulecki All Rights Reserved. | ||
7 | * | ||
8 | * This library is free software; you can redistribute it and/or | ||
9 | * modify it under the terms of the GNU Lesser General Public | ||
10 | * License as published by the Free Software Foundation; either | ||
11 | * version 2.1 of the License, or (at your option) any later version. | ||
12 | * | ||
13 | * This library is distributed in the hope that it will be useful, | ||
14 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
15 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
16 | * Lesser General Public License for more details. | ||
17 | * | ||
18 | * You should have received a copy of the GNU Lesser General Public | ||
19 | * License along with this library; if not, write to the Free Software | ||
20 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | ||
21 | */ | ||
22 | |||
23 | #ifndef IHEARTBEAT_H | ||
24 | #define IHEARTBEAT_H | ||
25 | |||
26 | #ifdef __cplusplus | ||
27 | extern "C" { | ||
28 | #endif | ||
29 | |||
30 | #include <libimobiledevice/libimobiledevice.h> | ||
31 | #include <libimobiledevice/lockdown.h> | ||
32 | |||
33 | /** Service identifier passed to lockdownd_start_service() to start the heartbeat service */ | ||
34 | #define HEARTBEAT_SERVICE_NAME "com.apple.mobile.heartbeat" | ||
35 | |||
36 | /** Error Codes */ | ||
37 | typedef enum { | ||
38 | HEARTBEAT_E_SUCCESS = 0, | ||
39 | HEARTBEAT_E_INVALID_ARG = -1, | ||
40 | HEARTBEAT_E_PLIST_ERROR = -2, | ||
41 | HEARTBEAT_E_MUX_ERROR = -3, | ||
42 | HEARTBEAT_E_SSL_ERROR = -4, | ||
43 | HEARTBEAT_E_NOT_ENOUGH_DATA = -5, | ||
44 | HEARTBEAT_E_TIMEOUT = -6, | ||
45 | HEARTBEAT_E_UNKNOWN_ERROR = -256 | ||
46 | } heartbeat_error_t; | ||
47 | |||
48 | typedef struct heartbeat_client_private heartbeat_client_private; /**< \private */ | ||
49 | typedef heartbeat_client_private *heartbeat_client_t; /**< The client handle. */ | ||
50 | |||
51 | /** | ||
52 | * Connects to the heartbeat service on the specified device. | ||
53 | * | ||
54 | * @param device The device to connect to. | ||
55 | * @param service The service descriptor returned by lockdownd_start_service. | ||
56 | * @param client Pointer that will point to a newly allocated | ||
57 | * heartbeat_client_t upon successful return. Must be freed using | ||
58 | * heartbeat_client_free() after use. | ||
59 | * | ||
60 | * @return HEARTBEAT_E_SUCCESS on success, HEARTBEAT_E_INVALID_ARG when | ||
61 | * client is NULL, or an HEARTBEAT_E_* error code otherwise. | ||
62 | */ | ||
63 | LIBIMOBILEDEVICE_API heartbeat_error_t heartbeat_client_new(idevice_t device, lockdownd_service_descriptor_t service, heartbeat_client_t * client); | ||
64 | |||
65 | /** | ||
66 | * Starts a new heartbeat service on the specified device and connects to it. | ||
67 | * | ||
68 | * @param device The device to connect to. | ||
69 | * @param client Pointer that will point to a newly allocated | ||
70 | * heartbeat_client_t upon successful return. Must be freed using | ||
71 | * heartbeat_client_free() after use. | ||
72 | * @param label The label to use for communication. Usually the program name. | ||
73 | * Pass NULL to disable sending the label in requests to lockdownd. | ||
74 | * | ||
75 | * @return HEARTBEAT_E_SUCCESS on success, or an HEARTBEAT_E_* error | ||
76 | * code otherwise. | ||
77 | */ | ||
78 | LIBIMOBILEDEVICE_API heartbeat_error_t heartbeat_client_start_service(idevice_t device, heartbeat_client_t * client, const char* label); | ||
79 | |||
80 | /** | ||
81 | * Disconnects a heartbeat client from the device and frees up the | ||
82 | * heartbeat client data. | ||
83 | * | ||
84 | * @param client The heartbeat client to disconnect and free. | ||
85 | * | ||
86 | * @return HEARTBEAT_E_SUCCESS on success, HEARTBEAT_E_INVALID_ARG when | ||
87 | * client is NULL, or an HEARTBEAT_E_* error code otherwise. | ||
88 | */ | ||
89 | LIBIMOBILEDEVICE_API heartbeat_error_t heartbeat_client_free(heartbeat_client_t client); | ||
90 | |||
91 | |||
92 | /** | ||
93 | * Sends a plist to the service. | ||
94 | * | ||
95 | * @param client The heartbeat client | ||
96 | * @param plist The plist to send | ||
97 | * | ||
98 | * @return HEARTBEAT_E_SUCCESS on success, | ||
99 | * HEARTBEAT_E_INVALID_ARG when client or plist is NULL | ||
100 | */ | ||
101 | LIBIMOBILEDEVICE_API heartbeat_error_t heartbeat_send(heartbeat_client_t client, plist_t plist); | ||
102 | |||
103 | /** | ||
104 | * Receives a plist from the service. | ||
105 | * | ||
106 | * @param client The heartbeat client | ||
107 | * @param plist The plist to store the received data | ||
108 | * | ||
109 | * @return HEARTBEAT_E_SUCCESS on success, | ||
110 | * HEARTBEAT_E_INVALID_ARG when client or plist is NULL | ||
111 | */ | ||
112 | LIBIMOBILEDEVICE_API heartbeat_error_t heartbeat_receive(heartbeat_client_t client, plist_t * plist); | ||
113 | |||
114 | /** | ||
115 | * Receives a plist using the given heartbeat client. | ||
116 | * | ||
117 | * @param client The heartbeat client to use for receiving | ||
118 | * @param plist pointer to a plist_t that will point to the received plist | ||
119 | * upon successful return | ||
120 | * @param timeout_ms Maximum time in milliseconds to wait for data. | ||
121 | * | ||
122 | * @return HEARTBEAT_E_SUCCESS on success, | ||
123 | * HEARTBEAT_E_INVALID_ARG when client or *plist is NULL, | ||
124 | * HEARTBEAT_E_NOT_ENOUGH_DATA when not enough data | ||
125 | * received, HEARTBEAT_E_TIMEOUT when the connection times out, | ||
126 | * HEARTBEAT_E_PLIST_ERROR when the received data cannot be | ||
127 | * converted to a plist, HEARTBEAT_E_MUX_ERROR when a | ||
128 | * communication error occurs, or HEARTBEAT_E_UNKNOWN_ERROR | ||
129 | * when an unspecified error occurs. | ||
130 | */ | ||
131 | LIBIMOBILEDEVICE_API heartbeat_error_t heartbeat_receive_with_timeout(heartbeat_client_t client, plist_t * plist, uint32_t timeout_ms); | ||
132 | |||
133 | #ifdef __cplusplus | ||
134 | } | ||
135 | #endif | ||
136 | |||
137 | #endif | ||
diff --git a/include/libimobiledevice/house_arrest.h b/include/libimobiledevice/house_arrest.h index 04290f1..f9ba68a 100644 --- a/include/libimobiledevice/house_arrest.h +++ b/include/libimobiledevice/house_arrest.h | |||
@@ -1,8 +1,9 @@ | |||
1 | /** | 1 | /** |
2 | * @file libimobiledevice/house_arrest.h | 2 | * @file libimobiledevice/house_arrest.h |
3 | * @brief Access AppStore application folders and their contents. | 3 | * @brief Access app folders and their contents. |
4 | * \internal | 4 | * \internal |
5 | * | 5 | * |
6 | * Copyright (c) 2013-2014 Martin Szulecki All Rights Reserved. | ||
6 | * Copyright (c) 2010 Nikias Bassen, All Rights Reserved. | 7 | * Copyright (c) 2010 Nikias Bassen, All Rights Reserved. |
7 | * | 8 | * |
8 | * This library is free software; you can redistribute it and/or | 9 | * This library is free software; you can redistribute it and/or |
@@ -20,42 +21,157 @@ | |||
20 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | 21 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA |
21 | */ | 22 | */ |
22 | 23 | ||
23 | #ifndef HOUSE_ARREST_H | 24 | #ifndef IHOUSE_ARREST_H |
24 | #define HOUSE_ARREST_H | 25 | #define IHOUSE_ARREST_H |
25 | 26 | ||
26 | #ifdef __cplusplus | 27 | #ifdef __cplusplus |
27 | extern "C" { | 28 | extern "C" { |
28 | #endif | 29 | #endif |
29 | 30 | ||
30 | #include <libimobiledevice/libimobiledevice.h> | 31 | #include <libimobiledevice/libimobiledevice.h> |
32 | #include <libimobiledevice/lockdown.h> | ||
31 | #include <libimobiledevice/afc.h> | 33 | #include <libimobiledevice/afc.h> |
32 | 34 | ||
33 | /** @name Error Codes */ | 35 | /** Service identifier passed to lockdownd_start_service() to start the house arrest service */ |
34 | /*@{*/ | 36 | #define HOUSE_ARREST_SERVICE_NAME "com.apple.mobile.house_arrest" |
35 | #define HOUSE_ARREST_E_SUCCESS 0 | ||
36 | #define HOUSE_ARREST_E_INVALID_ARG -1 | ||
37 | #define HOUSE_ARREST_E_PLIST_ERROR -2 | ||
38 | #define HOUSE_ARREST_E_CONN_FAILED -3 | ||
39 | #define HOUSE_ARREST_E_INVALID_MODE -4 | ||
40 | 37 | ||
41 | #define HOUSE_ARREST_E_UNKNOWN_ERROR -256 | 38 | /** Error Codes */ |
42 | /*@}*/ | 39 | typedef enum { |
40 | HOUSE_ARREST_E_SUCCESS = 0, | ||
41 | HOUSE_ARREST_E_INVALID_ARG = -1, | ||
42 | HOUSE_ARREST_E_PLIST_ERROR = -2, | ||
43 | HOUSE_ARREST_E_CONN_FAILED = -3, | ||
44 | HOUSE_ARREST_E_INVALID_MODE = -4, | ||
45 | HOUSE_ARREST_E_UNKNOWN_ERROR = -256 | ||
46 | } house_arrest_error_t; | ||
43 | 47 | ||
44 | /** Represents an error code. */ | 48 | typedef struct house_arrest_client_private house_arrest_client_private; /**< \private */ |
45 | typedef int16_t house_arrest_error_t; | ||
46 | |||
47 | typedef struct house_arrest_client_private house_arrest_client_private; | ||
48 | typedef house_arrest_client_private *house_arrest_client_t; /**< The client handle. */ | 49 | typedef house_arrest_client_private *house_arrest_client_t; /**< The client handle. */ |
49 | 50 | ||
50 | /* Interface */ | 51 | /* Interface */ |
51 | house_arrest_error_t house_arrest_client_new(idevice_t device, uint16_t port, house_arrest_client_t *client); | ||
52 | house_arrest_error_t house_arrest_client_free(house_arrest_client_t client); | ||
53 | 52 | ||
54 | house_arrest_error_t house_arrest_send_request(house_arrest_client_t client, plist_t dict); | 53 | /** |
55 | house_arrest_error_t house_arrest_send_command(house_arrest_client_t client, const char *command, const char *appid); | 54 | * Connects to the house_arrest service on the specified device. |
56 | house_arrest_error_t house_arrest_get_result(house_arrest_client_t client, plist_t *dict); | 55 | * |
56 | * @param device The device to connect to. | ||
57 | * @param service The service descriptor returned by lockdownd_start_service. | ||
58 | * @param client Pointer that will point to a newly allocated | ||
59 | * housearrest_client_t upon successful return. | ||
60 | * | ||
61 | * @return HOUSE_ARREST_E_SUCCESS on success, HOUSE_ARREST_E_INVALID_ARG when | ||
62 | * client is NULL, or an HOUSE_ARREST_E_* error code otherwise. | ||
63 | */ | ||
64 | LIBIMOBILEDEVICE_API house_arrest_error_t house_arrest_client_new(idevice_t device, lockdownd_service_descriptor_t service, house_arrest_client_t *client); | ||
65 | |||
66 | /** | ||
67 | * Starts a new house_arrest service on the specified device and connects to it. | ||
68 | * | ||
69 | * @param device The device to connect to. | ||
70 | * @param client Pointer that will point to a newly allocated | ||
71 | * house_arrest_client_t upon successful return. Must be freed using | ||
72 | * house_arrest_client_free() after use. | ||
73 | * @param label The label to use for communication. Usually the program name. | ||
74 | * Pass NULL to disable sending the label in requests to lockdownd. | ||
75 | * | ||
76 | * @return HOUSE_ARREST_E_SUCCESS on success, or an HOUSE_ARREST_E_* error | ||
77 | * code otherwise. | ||
78 | */ | ||
79 | LIBIMOBILEDEVICE_API house_arrest_error_t house_arrest_client_start_service(idevice_t device, house_arrest_client_t* client, const char* label); | ||
80 | |||
81 | /** | ||
82 | * Disconnects an house_arrest client from the device and frees up the | ||
83 | * house_arrest client data. | ||
84 | * | ||
85 | * @note After using afc_client_new_from_house_arrest_client(), make sure | ||
86 | * you call afc_client_free() before calling this function to ensure | ||
87 | * a proper cleanup. Do not call this function if you still need to | ||
88 | * perform AFC operations since it will close the connection. | ||
89 | * | ||
90 | * @param client The house_arrest client to disconnect and free. | ||
91 | * | ||
92 | * @return HOUSE_ARREST_E_SUCCESS on success, HOUSE_ARREST_E_INVALID_ARG when | ||
93 | * client is NULL, or an HOUSE_ARREST_E_* error code otherwise. | ||
94 | */ | ||
95 | LIBIMOBILEDEVICE_API house_arrest_error_t house_arrest_client_free(house_arrest_client_t client); | ||
96 | |||
97 | |||
98 | /** | ||
99 | * Sends a generic request to the connected house_arrest service. | ||
100 | * | ||
101 | * @param client The house_arrest client to use. | ||
102 | * @param dict The request to send as a plist of type PLIST_DICT. | ||
103 | * | ||
104 | * @note If this function returns HOUSE_ARREST_E_SUCCESS it does not mean | ||
105 | * that the request was successful. To check for success or failure you | ||
106 | * need to call house_arrest_get_result(). | ||
107 | * @see house_arrest_get_result | ||
108 | * | ||
109 | * @return HOUSE_ARREST_E_SUCCESS if the request was successfully sent, | ||
110 | * HOUSE_ARREST_E_INVALID_ARG if client or dict is invalid, | ||
111 | * HOUSE_ARREST_E_PLIST_ERROR if dict is not a plist of type PLIST_DICT, | ||
112 | * HOUSE_ARREST_E_INVALID_MODE if the client is not in the correct mode, | ||
113 | * or HOUSE_ARREST_E_CONN_FAILED if a connection error occurred. | ||
114 | */ | ||
115 | LIBIMOBILEDEVICE_API house_arrest_error_t house_arrest_send_request(house_arrest_client_t client, plist_t dict); | ||
116 | |||
117 | /** | ||
118 | * Send a command to the connected house_arrest service. | ||
119 | * Calls house_arrest_send_request() internally. | ||
120 | * | ||
121 | * @param client The house_arrest client to use. | ||
122 | * @param command The command to send. Currently, only VendContainer and | ||
123 | * VendDocuments are known. | ||
124 | * @param appid The application identifier to pass along with the . | ||
125 | * | ||
126 | * @note If this function returns HOUSE_ARREST_E_SUCCESS it does not mean | ||
127 | * that the command was successful. To check for success or failure you | ||
128 | * need to call house_arrest_get_result(). | ||
129 | * @see house_arrest_get_result | ||
130 | * | ||
131 | * @return HOUSE_ARREST_E_SUCCESS if the command was successfully sent, | ||
132 | * HOUSE_ARREST_E_INVALID_ARG if client, command, or appid is invalid, | ||
133 | * HOUSE_ARREST_E_INVALID_MODE if the client is not in the correct mode, | ||
134 | * or HOUSE_ARREST_E_CONN_FAILED if a connection error occurred. | ||
135 | */ | ||
136 | LIBIMOBILEDEVICE_API house_arrest_error_t house_arrest_send_command(house_arrest_client_t client, const char *command, const char *appid); | ||
137 | |||
138 | /** | ||
139 | * Retrieves the result of a previously sent house_arrest_request_* request. | ||
140 | * | ||
141 | * @param client The house_arrest client to use | ||
142 | * @param dict Pointer that will be set to a plist containing the result to | ||
143 | * the last performed operation. It holds a key 'Status' with the value | ||
144 | * 'Complete' on success or a key 'Error' with an error description as | ||
145 | * value. The caller is responsible for freeing the returned plist. | ||
146 | * | ||
147 | * @return HOUSE_ARREST_E_SUCCESS if a result plist was retrieved, | ||
148 | * HOUSE_ARREST_E_INVALID_ARG if client is invalid, | ||
149 | * HOUSE_ARREST_E_INVALID_MODE if the client is not in the correct mode, | ||
150 | * or HOUSE_ARREST_E_CONN_FAILED if a connection error occurred. | ||
151 | */ | ||
152 | LIBIMOBILEDEVICE_API house_arrest_error_t house_arrest_get_result(house_arrest_client_t client, plist_t *dict); | ||
153 | |||
57 | 154 | ||
58 | afc_error_t afc_client_new_from_house_arrest_client(house_arrest_client_t client, afc_client_t *afc_client); | 155 | /** |
156 | * Creates an AFC client using the given house_arrest client's connection | ||
157 | * allowing file access to a specific application directory requested by | ||
158 | * functions like house_arrest_request_vendor_documents(). | ||
159 | * | ||
160 | * @param client The house_arrest client to use. | ||
161 | * @param afc_client Pointer that will be set to a newly allocated afc_client_t | ||
162 | * upon successful return. | ||
163 | * | ||
164 | * @note After calling this function the house_arrest client will go in an | ||
165 | * AFC mode that will only allow calling house_arrest_client_free(). | ||
166 | * Only call house_arrest_client_free() if all AFC operations have | ||
167 | * completed since it will close the connection. | ||
168 | * | ||
169 | * @return AFC_E_SUCCESS if the afc client was successfully created, | ||
170 | * AFC_E_INVALID_ARG if client is invalid or was already used to create | ||
171 | * an afc client, or an AFC_E_* error code returned by | ||
172 | * afc_client_new_with_service_client(). | ||
173 | */ | ||
174 | LIBIMOBILEDEVICE_API afc_error_t afc_client_new_from_house_arrest_client(house_arrest_client_t client, afc_client_t *afc_client); | ||
59 | 175 | ||
60 | #ifdef __cplusplus | 176 | #ifdef __cplusplus |
61 | } | 177 | } |
diff --git a/include/libimobiledevice/installation_proxy.h b/include/libimobiledevice/installation_proxy.h index f5f00e8..44331aa 100644 --- a/include/libimobiledevice/installation_proxy.h +++ b/include/libimobiledevice/installation_proxy.h | |||
@@ -3,7 +3,10 @@ | |||
3 | * @brief Manage applications on a device. | 3 | * @brief Manage applications on a device. |
4 | * \internal | 4 | * \internal |
5 | * | 5 | * |
6 | * Copyright (c) 2009 Nikias Bassen All Rights Reserved. | 6 | * Copyright (c) 2010-2015 Martin Szulecki All Rights Reserved. |
7 | * Copyright (c) 2014 Christophe Fergeau All Rights Reserved. | ||
8 | * Copyright (c) 2009-2012 Nikias Bassen All Rights Reserved. | ||
9 | * Copyright (c) 2010 Bryan Forbes All Rights Reserved. | ||
7 | * | 10 | * |
8 | * This library is free software; you can redistribute it and/or | 11 | * This library is free software; you can redistribute it and/or |
9 | * modify it under the terms of the GNU Lesser General Public | 12 | * modify it under the terms of the GNU Lesser General Public |
@@ -20,54 +23,480 @@ | |||
20 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | 23 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA |
21 | */ | 24 | */ |
22 | 25 | ||
23 | #ifndef INSTALLATION_PROXY_H | 26 | #ifndef IINSTALLATION_PROXY_H |
24 | #define INSTALLATION_PROXY_H | 27 | #define IINSTALLATION_PROXY_H |
25 | 28 | ||
26 | #ifdef __cplusplus | 29 | #ifdef __cplusplus |
27 | extern "C" { | 30 | extern "C" { |
28 | #endif | 31 | #endif |
29 | 32 | ||
30 | #include <libimobiledevice/libimobiledevice.h> | 33 | #include <libimobiledevice/libimobiledevice.h> |
31 | #include <glib.h> | 34 | #include <libimobiledevice/lockdown.h> |
32 | 35 | ||
33 | /** @name Error Codes */ | 36 | /** Service identifier passed to lockdownd_start_service() to start the installation proxy service */ |
34 | /*@{*/ | 37 | #define INSTPROXY_SERVICE_NAME "com.apple.mobile.installation_proxy" |
35 | #define INSTPROXY_E_SUCCESS 0 | ||
36 | #define INSTPROXY_E_INVALID_ARG -1 | ||
37 | #define INSTPROXY_E_PLIST_ERROR -2 | ||
38 | #define INSTPROXY_E_CONN_FAILED -3 | ||
39 | #define INSTPROXY_E_OP_IN_PROGRESS -4 | ||
40 | #define INSTPROXY_E_OP_FAILED -5 | ||
41 | 38 | ||
42 | #define INSTPROXY_E_UNKNOWN_ERROR -256 | 39 | /** Error Codes */ |
43 | /*@}*/ | 40 | typedef enum { |
41 | /* custom */ | ||
42 | INSTPROXY_E_SUCCESS = 0, | ||
43 | INSTPROXY_E_INVALID_ARG = -1, | ||
44 | INSTPROXY_E_PLIST_ERROR = -2, | ||
45 | INSTPROXY_E_CONN_FAILED = -3, | ||
46 | INSTPROXY_E_OP_IN_PROGRESS = -4, | ||
47 | INSTPROXY_E_OP_FAILED = -5, | ||
48 | INSTPROXY_E_RECEIVE_TIMEOUT = -6, | ||
49 | /* native */ | ||
50 | INSTPROXY_E_ALREADY_ARCHIVED = -7, | ||
51 | INSTPROXY_E_API_INTERNAL_ERROR = -8, | ||
52 | INSTPROXY_E_APPLICATION_ALREADY_INSTALLED = -9, | ||
53 | INSTPROXY_E_APPLICATION_MOVE_FAILED = -10, | ||
54 | INSTPROXY_E_APPLICATION_SINF_CAPTURE_FAILED = -11, | ||
55 | INSTPROXY_E_APPLICATION_SANDBOX_FAILED = -12, | ||
56 | INSTPROXY_E_APPLICATION_VERIFICATION_FAILED = -13, | ||
57 | INSTPROXY_E_ARCHIVE_DESTRUCTION_FAILED = -14, | ||
58 | INSTPROXY_E_BUNDLE_VERIFICATION_FAILED = -15, | ||
59 | INSTPROXY_E_CARRIER_BUNDLE_COPY_FAILED = -16, | ||
60 | INSTPROXY_E_CARRIER_BUNDLE_DIRECTORY_CREATION_FAILED = -17, | ||
61 | INSTPROXY_E_CARRIER_BUNDLE_MISSING_SUPPORTED_SIMS = -18, | ||
62 | INSTPROXY_E_COMM_CENTER_NOTIFICATION_FAILED = -19, | ||
63 | INSTPROXY_E_CONTAINER_CREATION_FAILED = -20, | ||
64 | INSTPROXY_E_CONTAINER_P0WN_FAILED = -21, | ||
65 | INSTPROXY_E_CONTAINER_REMOVAL_FAILED = -22, | ||
66 | INSTPROXY_E_EMBEDDED_PROFILE_INSTALL_FAILED = -23, | ||
67 | INSTPROXY_E_EXECUTABLE_TWIDDLE_FAILED = -24, | ||
68 | INSTPROXY_E_EXISTENCE_CHECK_FAILED = -25, | ||
69 | INSTPROXY_E_INSTALL_MAP_UPDATE_FAILED = -26, | ||
70 | INSTPROXY_E_MANIFEST_CAPTURE_FAILED = -27, | ||
71 | INSTPROXY_E_MAP_GENERATION_FAILED = -28, | ||
72 | INSTPROXY_E_MISSING_BUNDLE_EXECUTABLE = -29, | ||
73 | INSTPROXY_E_MISSING_BUNDLE_IDENTIFIER = -30, | ||
74 | INSTPROXY_E_MISSING_BUNDLE_PATH = -31, | ||
75 | INSTPROXY_E_MISSING_CONTAINER = -32, | ||
76 | INSTPROXY_E_NOTIFICATION_FAILED = -33, | ||
77 | INSTPROXY_E_PACKAGE_EXTRACTION_FAILED = -34, | ||
78 | INSTPROXY_E_PACKAGE_INSPECTION_FAILED = -35, | ||
79 | INSTPROXY_E_PACKAGE_MOVE_FAILED = -36, | ||
80 | INSTPROXY_E_PATH_CONVERSION_FAILED = -37, | ||
81 | INSTPROXY_E_RESTORE_CONTAINER_FAILED = -38, | ||
82 | INSTPROXY_E_SEATBELT_PROFILE_REMOVAL_FAILED = -39, | ||
83 | INSTPROXY_E_STAGE_CREATION_FAILED = -40, | ||
84 | INSTPROXY_E_SYMLINK_FAILED = -41, | ||
85 | INSTPROXY_E_UNKNOWN_COMMAND = -42, | ||
86 | INSTPROXY_E_ITUNES_ARTWORK_CAPTURE_FAILED = -43, | ||
87 | INSTPROXY_E_ITUNES_METADATA_CAPTURE_FAILED = -44, | ||
88 | INSTPROXY_E_DEVICE_OS_VERSION_TOO_LOW = -45, | ||
89 | INSTPROXY_E_DEVICE_FAMILY_NOT_SUPPORTED = -46, | ||
90 | INSTPROXY_E_PACKAGE_PATCH_FAILED = -47, | ||
91 | INSTPROXY_E_INCORRECT_ARCHITECTURE = -48, | ||
92 | INSTPROXY_E_PLUGIN_COPY_FAILED = -49, | ||
93 | INSTPROXY_E_BREADCRUMB_FAILED = -50, | ||
94 | INSTPROXY_E_BREADCRUMB_UNLOCK_FAILED = -51, | ||
95 | INSTPROXY_E_GEOJSON_CAPTURE_FAILED = -52, | ||
96 | INSTPROXY_E_NEWSSTAND_ARTWORK_CAPTURE_FAILED = -53, | ||
97 | INSTPROXY_E_MISSING_COMMAND = -54, | ||
98 | INSTPROXY_E_NOT_ENTITLED = -55, | ||
99 | INSTPROXY_E_MISSING_PACKAGE_PATH = -56, | ||
100 | INSTPROXY_E_MISSING_CONTAINER_PATH = -57, | ||
101 | INSTPROXY_E_MISSING_APPLICATION_IDENTIFIER = -58, | ||
102 | INSTPROXY_E_MISSING_ATTRIBUTE_VALUE = -59, | ||
103 | INSTPROXY_E_LOOKUP_FAILED = -60, | ||
104 | INSTPROXY_E_DICT_CREATION_FAILED = -61, | ||
105 | INSTPROXY_E_INSTALL_PROHIBITED = -62, | ||
106 | INSTPROXY_E_UNINSTALL_PROHIBITED = -63, | ||
107 | INSTPROXY_E_MISSING_BUNDLE_VERSION = -64, | ||
108 | INSTPROXY_E_UNKNOWN_ERROR = -256 | ||
109 | } instproxy_error_t; | ||
44 | 110 | ||
45 | /** Represents an error code. */ | 111 | typedef struct instproxy_client_private instproxy_client_private; /**< \private */ |
46 | typedef int16_t instproxy_error_t; | ||
47 | |||
48 | typedef struct instproxy_client_private instproxy_client_private; | ||
49 | typedef instproxy_client_private *instproxy_client_t; /**< The client handle. */ | 112 | typedef instproxy_client_private *instproxy_client_t; /**< The client handle. */ |
50 | 113 | ||
51 | /** Reports the status of the given operation */ | 114 | /** Reports the status response of the given command */ |
52 | typedef void (*instproxy_status_cb_t) (const char *operation, plist_t status, void *user_data); | 115 | typedef void (*instproxy_status_cb_t) (plist_t command, plist_t status, void *user_data); |
53 | 116 | ||
54 | /* Interface */ | 117 | /* Interface */ |
55 | instproxy_error_t instproxy_client_new(idevice_t device, uint16_t port, instproxy_client_t *client); | 118 | |
56 | instproxy_error_t instproxy_client_free(instproxy_client_t client); | 119 | /** |
57 | 120 | * Connects to the installation_proxy service on the specified device. | |
58 | instproxy_error_t instproxy_browse(instproxy_client_t client, plist_t client_options, plist_t *result); | 121 | * |
59 | instproxy_error_t instproxy_install(instproxy_client_t client, const char *pkg_path, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data); | 122 | * @param device The device to connect to |
60 | instproxy_error_t instproxy_upgrade(instproxy_client_t client, const char *pkg_path, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data); | 123 | * @param service The service descriptor returned by lockdownd_start_service. |
61 | instproxy_error_t instproxy_uninstall(instproxy_client_t client, const char *appid, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data); | 124 | * @param client Pointer that will be set to a newly allocated |
62 | 125 | * instproxy_client_t upon successful return. | |
63 | instproxy_error_t instproxy_lookup_archives(instproxy_client_t client, plist_t client_options, plist_t *result); | 126 | * |
64 | instproxy_error_t instproxy_archive(instproxy_client_t client, const char *appid, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data); | 127 | * @return INSTPROXY_E_SUCCESS on success, or an INSTPROXY_E_* error value |
65 | instproxy_error_t instproxy_restore(instproxy_client_t client, const char *appid, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data); | 128 | * when an error occurred. |
66 | instproxy_error_t instproxy_remove_archive(instproxy_client_t client, const char *appid, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data); | 129 | */ |
67 | 130 | LIBIMOBILEDEVICE_API instproxy_error_t instproxy_client_new(idevice_t device, lockdownd_service_descriptor_t service, instproxy_client_t *client); | |
68 | plist_t instproxy_client_options_new(); | 131 | |
69 | void instproxy_client_options_add(plist_t client_options, ...) G_GNUC_NULL_TERMINATED; | 132 | /** |
70 | void instproxy_client_options_free(plist_t client_options); | 133 | * Starts a new installation_proxy service on the specified device and connects to it. |
134 | * | ||
135 | * @param device The device to connect to. | ||
136 | * @param client Pointer that will point to a newly allocated | ||
137 | * instproxy_client_t upon successful return. Must be freed using | ||
138 | * instproxy_client_free() after use. | ||
139 | * @param label The label to use for communication. Usually the program name. | ||
140 | * Pass NULL to disable sending the label in requests to lockdownd. | ||
141 | * | ||
142 | * @return INSTPROXY_E_SUCCESS on success, or an INSTPROXY_E_* error | ||
143 | * code otherwise. | ||
144 | */ | ||
145 | LIBIMOBILEDEVICE_API instproxy_error_t instproxy_client_start_service(idevice_t device, instproxy_client_t * client, const char* label); | ||
146 | |||
147 | /** | ||
148 | * Disconnects an installation_proxy client from the device and frees up the | ||
149 | * installation_proxy client data. | ||
150 | * | ||
151 | * @param client The installation_proxy client to disconnect and free. | ||
152 | * | ||
153 | * @return INSTPROXY_E_SUCCESS on success | ||
154 | * or INSTPROXY_E_INVALID_ARG if client is NULL. | ||
155 | */ | ||
156 | LIBIMOBILEDEVICE_API instproxy_error_t instproxy_client_free(instproxy_client_t client); | ||
157 | |||
158 | /** | ||
159 | * List installed applications. This function runs synchronously. | ||
160 | * | ||
161 | * @param client The connected installation_proxy client | ||
162 | * @param client_options The client options to use, as PLIST_DICT, or NULL. | ||
163 | * Valid client options include: | ||
164 | * "ApplicationType" -> "System" | ||
165 | * "ApplicationType" -> "User" | ||
166 | * "ApplicationType" -> "Internal" | ||
167 | * "ApplicationType" -> "Any" | ||
168 | * @param result Pointer that will be set to a plist that will hold an array | ||
169 | * of PLIST_DICT holding information about the applications found. | ||
170 | * | ||
171 | * @return INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if | ||
172 | * an error occurred. | ||
173 | */ | ||
174 | LIBIMOBILEDEVICE_API instproxy_error_t instproxy_browse(instproxy_client_t client, plist_t client_options, plist_t *result); | ||
175 | |||
176 | /** | ||
177 | * List pages of installed applications in a callback. | ||
178 | * | ||
179 | * @param client The connected installation_proxy client | ||
180 | * @param client_options The client options to use, as PLIST_DICT, or NULL. | ||
181 | * Valid client options include: | ||
182 | * "ApplicationType" -> "System" | ||
183 | * "ApplicationType" -> "User" | ||
184 | * "ApplicationType" -> "Internal" | ||
185 | * "ApplicationType" -> "Any" | ||
186 | * @param status_cb Callback function to process each page of application | ||
187 | * information. Passing a callback is required. | ||
188 | * @param user_data Callback data passed to status_cb. | ||
189 | * | ||
190 | * @return INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if | ||
191 | * an error occurred. | ||
192 | */ | ||
193 | LIBIMOBILEDEVICE_API instproxy_error_t instproxy_browse_with_callback(instproxy_client_t client, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data); | ||
194 | |||
195 | /** | ||
196 | * Lookup information about specific applications from the device. | ||
197 | * | ||
198 | * @param client The connected installation_proxy client | ||
199 | * @param appids An array of bundle identifiers that MUST have a terminating | ||
200 | * NULL entry or NULL to lookup all. | ||
201 | * @param client_options The client options to use, as PLIST_DICT, or NULL. | ||
202 | * Currently there are no known client options, so pass NULL here. | ||
203 | * @param result Pointer that will be set to a plist containing a PLIST_DICT | ||
204 | * holding requested information about the application or NULL on errors. | ||
205 | * | ||
206 | * @return INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if | ||
207 | * an error occurred. | ||
208 | */ | ||
209 | LIBIMOBILEDEVICE_API instproxy_error_t instproxy_lookup(instproxy_client_t client, const char** appids, plist_t client_options, plist_t *result); | ||
210 | |||
211 | /** | ||
212 | * Install an application on the device. | ||
213 | * | ||
214 | * @param client The connected installation_proxy client | ||
215 | * @param pkg_path Path of the installation package (inside the AFC jail) | ||
216 | * @param client_options The client options to use, as PLIST_DICT, or NULL. | ||
217 | * Valid options include: | ||
218 | * "iTunesMetadata" -> PLIST_DATA | ||
219 | * "ApplicationSINF" -> PLIST_DATA | ||
220 | * "PackageType" -> "Developer" | ||
221 | * If PackageType -> Developer is specified, then pkg_path points to | ||
222 | * an .app directory instead of an install package. | ||
223 | * @param status_cb Callback function for progress and status information. If | ||
224 | * NULL is passed, this function will run synchronously. | ||
225 | * @param user_data Callback data passed to status_cb. | ||
226 | * | ||
227 | * @return INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if | ||
228 | * an error occurred. | ||
229 | * | ||
230 | * @note If a callback function is given (async mode), this function returns | ||
231 | * INSTPROXY_E_SUCCESS immediately if the status updater thread has been | ||
232 | * created successfully; any error occurring during the command has to be | ||
233 | * handled inside the specified callback function. | ||
234 | */ | ||
235 | LIBIMOBILEDEVICE_API instproxy_error_t instproxy_install(instproxy_client_t client, const char *pkg_path, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data); | ||
236 | |||
237 | /** | ||
238 | * Upgrade an application on the device. This function is nearly the same as | ||
239 | * instproxy_install; the difference is that the installation progress on the | ||
240 | * device is faster if the application is already installed. | ||
241 | * | ||
242 | * @param client The connected installation_proxy client | ||
243 | * @param pkg_path Path of the installation package (inside the AFC jail) | ||
244 | * @param client_options The client options to use, as PLIST_DICT, or NULL. | ||
245 | * Valid options include: | ||
246 | * "iTunesMetadata" -> PLIST_DATA | ||
247 | * "ApplicationSINF" -> PLIST_DATA | ||
248 | * "PackageType" -> "Developer" | ||
249 | * If PackageType -> Developer is specified, then pkg_path points to | ||
250 | * an .app directory instead of an install package. | ||
251 | * @param status_cb Callback function for progress and status information. If | ||
252 | * NULL is passed, this function will run synchronously. | ||
253 | * @param user_data Callback data passed to status_cb. | ||
254 | * | ||
255 | * @return INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if | ||
256 | * an error occurred. | ||
257 | * | ||
258 | * @note If a callback function is given (async mode), this function returns | ||
259 | * INSTPROXY_E_SUCCESS immediately if the status updater thread has been | ||
260 | * created successfully; any error occurring during the command has to be | ||
261 | * handled inside the specified callback function. | ||
262 | */ | ||
263 | LIBIMOBILEDEVICE_API instproxy_error_t instproxy_upgrade(instproxy_client_t client, const char *pkg_path, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data); | ||
264 | |||
265 | /** | ||
266 | * Uninstall an application from the device. | ||
267 | * | ||
268 | * @param client The connected installation proxy client | ||
269 | * @param appid ApplicationIdentifier of the app to uninstall | ||
270 | * @param client_options The client options to use, as PLIST_DICT, or NULL. | ||
271 | * Currently there are no known client options, so pass NULL here. | ||
272 | * @param status_cb Callback function for progress and status information. If | ||
273 | * NULL is passed, this function will run synchronously. | ||
274 | * @param user_data Callback data passed to status_cb. | ||
275 | * | ||
276 | * @return INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if | ||
277 | * an error occurred. | ||
278 | * | ||
279 | * @note If a callback function is given (async mode), this function returns | ||
280 | * INSTPROXY_E_SUCCESS immediately if the status updater thread has been | ||
281 | * created successfully; any error occurring during the command has to be | ||
282 | * handled inside the specified callback function. | ||
283 | */ | ||
284 | LIBIMOBILEDEVICE_API instproxy_error_t instproxy_uninstall(instproxy_client_t client, const char *appid, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data); | ||
285 | |||
286 | /** | ||
287 | * List archived applications. This function runs synchronously. | ||
288 | * | ||
289 | * @see instproxy_archive | ||
290 | * | ||
291 | * @param client The connected installation_proxy client | ||
292 | * @param client_options The client options to use, as PLIST_DICT, or NULL. | ||
293 | * Currently there are no known client options, so pass NULL here. | ||
294 | * @param result Pointer that will be set to a plist containing a PLIST_DICT | ||
295 | * holding information about the archived applications found. | ||
296 | * | ||
297 | * @return INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if | ||
298 | * an error occurred. | ||
299 | */ | ||
300 | LIBIMOBILEDEVICE_API instproxy_error_t instproxy_lookup_archives(instproxy_client_t client, plist_t client_options, plist_t *result); | ||
301 | |||
302 | /** | ||
303 | * Archive an application on the device. | ||
304 | * This function tells the device to make an archive of the specified | ||
305 | * application. This results in the device creating a ZIP archive in the | ||
306 | * 'ApplicationArchives' directory and uninstalling the application. | ||
307 | * | ||
308 | * @param client The connected installation proxy client | ||
309 | * @param appid ApplicationIdentifier of the app to archive. | ||
310 | * @param client_options The client options to use, as PLIST_DICT, or NULL. | ||
311 | * Valid options include: | ||
312 | * "SkipUninstall" -> Boolean | ||
313 | * "ArchiveType" -> "ApplicationOnly" | ||
314 | * @param status_cb Callback function for progress and status information. If | ||
315 | * NULL is passed, this function will run synchronously. | ||
316 | * @param user_data Callback data passed to status_cb. | ||
317 | * | ||
318 | * @return INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if | ||
319 | * an error occurred. | ||
320 | * | ||
321 | * @note If a callback function is given (async mode), this function returns | ||
322 | * INSTPROXY_E_SUCCESS immediately if the status updater thread has been | ||
323 | * created successfully; any error occurring during the command has to be | ||
324 | * handled inside the specified callback function. | ||
325 | */ | ||
326 | LIBIMOBILEDEVICE_API instproxy_error_t instproxy_archive(instproxy_client_t client, const char *appid, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data); | ||
327 | |||
328 | /** | ||
329 | * Restore a previously archived application on the device. | ||
330 | * This function is the counterpart to instproxy_archive. | ||
331 | * @see instproxy_archive | ||
332 | * | ||
333 | * @param client The connected installation proxy client | ||
334 | * @param appid ApplicationIdentifier of the app to restore. | ||
335 | * @param client_options The client options to use, as PLIST_DICT, or NULL. | ||
336 | * Valid options include: | ||
337 | * "ArchiveType" -> "DocumentsOnly" | ||
338 | * @param status_cb Callback function for progress and status information. If | ||
339 | * NULL is passed, this function will run synchronously. | ||
340 | * @param user_data Callback data passed to status_cb. | ||
341 | * | ||
342 | * @return INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if | ||
343 | * an error occurred. | ||
344 | * | ||
345 | * @note If a callback function is given (async mode), this function returns | ||
346 | * INSTPROXY_E_SUCCESS immediately if the status updater thread has been | ||
347 | * created successfully; any error occurring during the command has to be | ||
348 | * handled inside the specified callback function. | ||
349 | */ | ||
350 | LIBIMOBILEDEVICE_API instproxy_error_t instproxy_restore(instproxy_client_t client, const char *appid, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data); | ||
351 | |||
352 | /** | ||
353 | * Removes a previously archived application from the device. | ||
354 | * This function removes the ZIP archive from the 'ApplicationArchives' | ||
355 | * directory. | ||
356 | * | ||
357 | * @param client The connected installation proxy client | ||
358 | * @param appid ApplicationIdentifier of the archived app to remove. | ||
359 | * @param client_options The client options to use, as PLIST_DICT, or NULL. | ||
360 | * Currently there are no known client options, so passing NULL is fine. | ||
361 | * @param status_cb Callback function for progress and status information. If | ||
362 | * NULL is passed, this function will run synchronously. | ||
363 | * @param user_data Callback data passed to status_cb. | ||
364 | * | ||
365 | * @return INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if | ||
366 | * an error occurred. | ||
367 | * | ||
368 | * @note If a callback function is given (async mode), this function returns | ||
369 | * INSTPROXY_E_SUCCESS immediately if the status updater thread has been | ||
370 | * created successfully; any error occurring during the command has to be | ||
371 | * handled inside the specified callback function. | ||
372 | */ | ||
373 | LIBIMOBILEDEVICE_API instproxy_error_t instproxy_remove_archive(instproxy_client_t client, const char *appid, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data); | ||
374 | |||
375 | /** | ||
376 | * Checks a device for certain capabilities. | ||
377 | * | ||
378 | * @param client The connected installation_proxy client | ||
379 | * @param capabilities An array of char* with capability names that MUST have a | ||
380 | * terminating NULL entry. | ||
381 | * @param client_options The client options to use, as PLIST_DICT, or NULL. | ||
382 | * Currently there are no known client options, so pass NULL here. | ||
383 | * @param result Pointer that will be set to a plist containing a PLIST_DICT | ||
384 | * holding information if the capabilities matched or NULL on errors. | ||
385 | * | ||
386 | * @return INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if | ||
387 | * an error occurred. | ||
388 | */ | ||
389 | LIBIMOBILEDEVICE_API instproxy_error_t instproxy_check_capabilities_match(instproxy_client_t client, const char** capabilities, plist_t client_options, plist_t *result); | ||
390 | |||
391 | /* Helper */ | ||
392 | |||
393 | /** | ||
394 | * Gets the name from a command dictionary. | ||
395 | * | ||
396 | * @param command The dictionary describing the command. | ||
397 | * @param name Pointer to store the name of the command. | ||
398 | */ | ||
399 | LIBIMOBILEDEVICE_API void instproxy_command_get_name(plist_t command, char** name); | ||
400 | |||
401 | /** | ||
402 | * Gets the name of a status. | ||
403 | * | ||
404 | * @param status The dictionary status response to use. | ||
405 | * @param name Pointer to store the name of the status. | ||
406 | */ | ||
407 | LIBIMOBILEDEVICE_API void instproxy_status_get_name(plist_t status, char **name); | ||
408 | |||
409 | /** | ||
410 | * Gets error name, code and description from a response if available. | ||
411 | * | ||
412 | * @param status The dictionary status response to use. | ||
413 | * @param name Pointer to store the name of an error. | ||
414 | * @param description Pointer to store error description text if available. | ||
415 | * The caller is reponsible for freeing the allocated buffer after use. | ||
416 | * If NULL is passed no description will be returned. | ||
417 | * @param code Pointer to store the returned error code if available. | ||
418 | * If NULL is passed no error code will be returned. | ||
419 | * | ||
420 | * @return INSTPROXY_E_SUCCESS if no error is found or an INSTPROXY_E_* error | ||
421 | * value matching the error that ẃas found in the status. | ||
422 | */ | ||
423 | LIBIMOBILEDEVICE_API instproxy_error_t instproxy_status_get_error(plist_t status, char **name, char** description, uint64_t* code); | ||
424 | |||
425 | /** | ||
426 | * Gets total and current item information from a browse response if available. | ||
427 | * | ||
428 | * @param status The dictionary status response to use. | ||
429 | * @param total Pointer to store the total number of items. | ||
430 | * @param current_index Pointer to store the current index of all browsed items. | ||
431 | * @param current_amount Pointer to store the amount of items in the | ||
432 | * current list. | ||
433 | * @param list Pointer to store a newly allocated plist with items. | ||
434 | * The caller is reponsible for freeing the list after use. | ||
435 | * If NULL is passed no list will be returned. If NULL is returned no | ||
436 | * list was found in the status. | ||
437 | */ | ||
438 | LIBIMOBILEDEVICE_API void instproxy_status_get_current_list(plist_t status, uint64_t* total, uint64_t* current_index, uint64_t* current_amount, plist_t* list); | ||
439 | |||
440 | |||
441 | /** | ||
442 | * Gets progress in percentage from a status if available. | ||
443 | * | ||
444 | * @param status The dictionary status response to use. | ||
445 | * @param percent Pointer to an int to store the progress in percent (0-100) | ||
446 | * or -1 if no progress was found in the status. | ||
447 | */ | ||
448 | LIBIMOBILEDEVICE_API void instproxy_status_get_percent_complete(plist_t status, int *percent); | ||
449 | |||
450 | /** | ||
451 | * Creates a new client_options plist. | ||
452 | * | ||
453 | * @return A new plist_t of type PLIST_DICT. | ||
454 | */ | ||
455 | LIBIMOBILEDEVICE_API plist_t instproxy_client_options_new(void); | ||
456 | |||
457 | /** | ||
458 | * Adds one or more new key:value pairs to the given client_options. | ||
459 | * | ||
460 | * @param client_options The client options to modify. | ||
461 | * @param ... KEY, VALUE, [KEY, VALUE], NULL | ||
462 | * | ||
463 | * @note The keys and values passed are expected to be strings, except for the | ||
464 | * keys "ApplicationSINF", "iTunesMetadata", "ReturnAttributes" which are | ||
465 | * expecting a plist_t node as value and "SkipUninstall" expects int. | ||
466 | */ | ||
467 | LIBIMOBILEDEVICE_API void instproxy_client_options_add(plist_t client_options, ...); | ||
468 | |||
469 | /** | ||
470 | * Adds attributes to the given client_options to filter browse results. | ||
471 | * | ||
472 | * @param client_options The client options to modify. | ||
473 | * @param ... VALUE, VALUE, [VALUE], NULL | ||
474 | * | ||
475 | * @note The values passed are expected to be strings. | ||
476 | */ | ||
477 | LIBIMOBILEDEVICE_API void instproxy_client_options_set_return_attributes(plist_t client_options, ...); | ||
478 | |||
479 | /** | ||
480 | * Frees client_options plist. | ||
481 | * | ||
482 | * @param client_options The client options plist to free. Does nothing if NULL | ||
483 | * is passed. | ||
484 | */ | ||
485 | LIBIMOBILEDEVICE_API void instproxy_client_options_free(plist_t client_options); | ||
486 | |||
487 | /** | ||
488 | * Queries the device for the path of an application. | ||
489 | * | ||
490 | * @param client The connected installation proxy client. | ||
491 | * @param bundle_id ApplicationIdentifier of app to retrieve the path for. | ||
492 | * @param path Pointer to store the device path for the application | ||
493 | * which is set to NULL if it could not be determined. | ||
494 | * | ||
495 | * @return INSTPROXY_E_SUCCESS on success, INSTPROXY_E_OP_FAILED if | ||
496 | * the path could not be determined or an INSTPROXY_E_* error | ||
497 | * value if an error occurred. | ||
498 | */ | ||
499 | LIBIMOBILEDEVICE_API instproxy_error_t instproxy_client_get_path_for_bundle_identifier(instproxy_client_t client, const char* bundle_id, char** path); | ||
71 | 500 | ||
72 | #ifdef __cplusplus | 501 | #ifdef __cplusplus |
73 | } | 502 | } |
diff --git a/include/libimobiledevice/libimobiledevice.h b/include/libimobiledevice/libimobiledevice.h index d0923d6..a9d270b 100644 --- a/include/libimobiledevice/libimobiledevice.h +++ b/include/libimobiledevice/libimobiledevice.h | |||
@@ -3,25 +3,28 @@ | |||
3 | * @brief Device/Connection handling and communication | 3 | * @brief Device/Connection handling and communication |
4 | * \internal | 4 | * \internal |
5 | * | 5 | * |
6 | * Copyright (c) 2010-2019 Nikias Bassen All Rights Reserved. | ||
7 | * Copyright (c) 2010-2014 Martin Szulecki All Rights Reserved. | ||
8 | * Copyright (c) 2014 Christophe Fergeau All Rights Reserved. | ||
6 | * Copyright (c) 2008 Jonathan Beck All Rights Reserved. | 9 | * Copyright (c) 2008 Jonathan Beck All Rights Reserved. |
7 | * | 10 | * |
8 | * This library is free software; you can redistribute it and/or | 11 | * This library is free software; you can redistribute it and/or |
9 | * modify it under the terms of the GNU Lesser General Public | 12 | * modify it under the terms of the GNU Lesser General Public |
10 | * License as published by the Free Software Foundation; either | 13 | * License as published by the Free Software Foundation; either |
11 | * version 2.1 of the License, or (at your option) any later version. | 14 | * version 2.1 of the License, or (at your option) any later version. |
12 | * | 15 | * |
13 | * This library is distributed in the hope that it will be useful, | 16 | * This library is distributed in the hope that it will be useful, |
14 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | 17 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
15 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | 18 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
16 | * Lesser General Public License for more details. | 19 | * Lesser General Public License for more details. |
17 | * | 20 | * |
18 | * You should have received a copy of the GNU Lesser General Public | 21 | * You should have received a copy of the GNU Lesser General Public |
19 | * License along with this library; if not, write to the Free Software | 22 | * License along with this library; if not, write to the Free Software |
20 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | 23 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA |
21 | */ | 24 | */ |
22 | 25 | ||
23 | #ifndef LIBIMOBILEDEVICE_H | 26 | #ifndef IMOBILEDEVICE_H |
24 | #define LIBIMOBILEDEVICE_H | 27 | #define IMOBILEDEVICE_H |
25 | 28 | ||
26 | #ifdef __cplusplus | 29 | #ifdef __cplusplus |
27 | extern "C" { | 30 | extern "C" { |
@@ -32,72 +35,377 @@ extern "C" { | |||
32 | #include <sys/stat.h> | 35 | #include <sys/stat.h> |
33 | #include <plist/plist.h> | 36 | #include <plist/plist.h> |
34 | 37 | ||
35 | /** @name Error Codes */ | 38 | #ifndef LIBIMOBILEDEVICE_API |
36 | /*@{*/ | 39 | #ifdef LIBIMOBILEDEVICE_STATIC |
37 | #define IDEVICE_E_SUCCESS 0 | 40 | #define LIBIMOBILEDEVICE_API |
38 | #define IDEVICE_E_INVALID_ARG -1 | 41 | #elif defined(_WIN32) |
39 | #define IDEVICE_E_UNKNOWN_ERROR -2 | 42 | #define LIBIMOBILEDEVICE_API __declspec(dllimport) |
40 | #define IDEVICE_E_NO_DEVICE -3 | 43 | #else |
41 | #define IDEVICE_E_NOT_ENOUGH_DATA -4 | 44 | #define LIBIMOBILEDEVICE_API |
42 | #define IDEVICE_E_BAD_HEADER -5 | 45 | #endif |
43 | #define IDEVICE_E_SSL_ERROR -6 | 46 | #endif |
44 | /*@}*/ | 47 | |
45 | 48 | /** Error Codes */ | |
46 | /** Represents an error code. */ | 49 | typedef enum { |
47 | typedef int16_t idevice_error_t; | 50 | IDEVICE_E_SUCCESS = 0, |
48 | 51 | IDEVICE_E_INVALID_ARG = -1, | |
49 | typedef struct idevice_private idevice_private; | 52 | IDEVICE_E_UNKNOWN_ERROR = -2, |
53 | IDEVICE_E_NO_DEVICE = -3, | ||
54 | IDEVICE_E_NOT_ENOUGH_DATA = -4, | ||
55 | IDEVICE_E_CONNREFUSED = -5, | ||
56 | IDEVICE_E_SSL_ERROR = -6, | ||
57 | IDEVICE_E_TIMEOUT = -7 | ||
58 | } idevice_error_t; | ||
59 | |||
60 | typedef struct idevice_private idevice_private; /**< \private */ | ||
50 | typedef idevice_private *idevice_t; /**< The device handle. */ | 61 | typedef idevice_private *idevice_t; /**< The device handle. */ |
51 | 62 | ||
52 | typedef struct idevice_connection_private idevice_connection_private; | 63 | typedef struct idevice_connection_private idevice_connection_private; /**< \private */ |
53 | typedef idevice_connection_private *idevice_connection_t; /**< The connection handle. */ | 64 | typedef idevice_connection_private *idevice_connection_t; /**< The connection handle. */ |
54 | 65 | ||
55 | /* generic */ | 66 | /** Options for idevice_new_with_options() */ |
56 | void idevice_set_debug_level(int level); | 67 | enum idevice_options { |
68 | IDEVICE_LOOKUP_USBMUX = 1 << 1, /**< include USBMUX devices during lookup */ | ||
69 | IDEVICE_LOOKUP_NETWORK = 1 << 2, /**< include network devices during lookup */ | ||
70 | IDEVICE_LOOKUP_PREFER_NETWORK = 1 << 3 /**< prefer network connection if device is available via USBMUX *and* network */ | ||
71 | }; | ||
72 | |||
73 | /** Type of connection a device is available on */ | ||
74 | enum idevice_connection_type { | ||
75 | CONNECTION_USBMUXD = 1, /**< device is available via USBMUX */ | ||
76 | CONNECTION_NETWORK /**< device is available via network */ | ||
77 | }; | ||
78 | |||
79 | /** Device information returned by #idevice_get_device_list_extended API */ | ||
80 | struct idevice_info { | ||
81 | char *udid; /**< UDID of the device */ | ||
82 | enum idevice_connection_type conn_type; /**< Type of connection the device is available on */ | ||
83 | void* conn_data; /**< Connection data, depending on the connection type */ | ||
84 | }; | ||
85 | typedef struct idevice_info* idevice_info_t; | ||
57 | 86 | ||
58 | /* discovery (events/asynchronous) */ | 87 | /* discovery (events/asynchronous) */ |
59 | /** The event type for device add or removal */ | 88 | /** The event type for device add or removal */ |
60 | enum idevice_event_type { | 89 | enum idevice_event_type { |
61 | IDEVICE_DEVICE_ADD = 1, | 90 | IDEVICE_DEVICE_ADD = 1, /**< device was added */ |
62 | IDEVICE_DEVICE_REMOVE | 91 | IDEVICE_DEVICE_REMOVE, /**< device was removed */ |
92 | IDEVICE_DEVICE_PAIRED /**< device completed pairing process */ | ||
63 | }; | 93 | }; |
64 | 94 | ||
65 | /* event data structure */ | 95 | /* event data structure */ |
66 | /** Provides information about the occured event. */ | 96 | /** Provides information about the occurred event. */ |
67 | typedef struct { | 97 | typedef struct { |
68 | enum idevice_event_type event; /**< The event type. */ | 98 | enum idevice_event_type event; /**< The event type. */ |
69 | const char *uuid; /**< The device unique id. */ | 99 | const char *udid; /**< The device unique id. */ |
70 | int conn_type; /**< The connection type. Currently only 1 for usbmuxd. */ | 100 | enum idevice_connection_type conn_type; /**< The connection type. */ |
71 | } idevice_event_t; | 101 | } idevice_event_t; |
72 | 102 | ||
73 | /* event callback function prototype */ | 103 | /* event callback function prototype */ |
74 | /** Callback to notifiy if a device was added or removed. */ | 104 | /** Callback to notifiy if a device was added or removed. */ |
75 | typedef void (*idevice_event_cb_t) (const idevice_event_t *event, void *user_data); | 105 | typedef void (*idevice_event_cb_t) (const idevice_event_t *event, void *user_data); |
76 | 106 | ||
107 | /** Event subscription context type */ | ||
108 | typedef struct idevice_subscription_context* idevice_subscription_context_t; | ||
109 | |||
77 | /* functions */ | 110 | /* functions */ |
78 | idevice_error_t idevice_event_subscribe(idevice_event_cb_t callback, void *user_data); | 111 | |
79 | idevice_error_t idevice_event_unsubscribe(); | 112 | /** |
113 | * Set the level of debugging. | ||
114 | * | ||
115 | * @param level Set to 0 for no debug output or 1 to enable debug output. | ||
116 | */ | ||
117 | LIBIMOBILEDEVICE_API void idevice_set_debug_level(int level); | ||
118 | |||
119 | /** | ||
120 | * Subscribe a callback function that will be called when device add/remove | ||
121 | * events occur. | ||
122 | * | ||
123 | * @param context A pointer to a idevice_subscription_context_t that will be | ||
124 | * set upon creation of the subscription. The returned context must be | ||
125 | * passed to idevice_events_unsubscribe() to unsubscribe the callback. | ||
126 | * @param callback Callback function to call. | ||
127 | * @param user_data Application-specific data passed as parameter | ||
128 | * to the registered callback function. | ||
129 | * | ||
130 | * @return IDEVICE_E_SUCCESS on success or an error value when an error occurred. | ||
131 | */ | ||
132 | LIBIMOBILEDEVICE_API idevice_error_t idevice_events_subscribe(idevice_subscription_context_t *context, idevice_event_cb_t callback, void *user_data); | ||
133 | |||
134 | /** | ||
135 | * Unsubscribe the event callback function that has been registered with | ||
136 | * idevice_events_subscribe(). | ||
137 | * | ||
138 | * @param context A valid context as returned from idevice_events_subscribe(). | ||
139 | * | ||
140 | * @return IDEVICE_E_SUCCESS on success or an error value when an error occurred. | ||
141 | */ | ||
142 | LIBIMOBILEDEVICE_API idevice_error_t idevice_events_unsubscribe(idevice_subscription_context_t context); | ||
143 | |||
144 | /** | ||
145 | * (DEPRECATED) Register a callback function that will be called when device add/remove | ||
146 | * events occur. | ||
147 | * | ||
148 | * @deprecated Use idevice_events_subscribe() instead. | ||
149 | * | ||
150 | * @param callback Callback function to call. | ||
151 | * @param user_data Application-specific data passed as parameter | ||
152 | * to the registered callback function. | ||
153 | * | ||
154 | * @return IDEVICE_E_SUCCESS on success or an error value when an error occurred. | ||
155 | */ | ||
156 | LIBIMOBILEDEVICE_API idevice_error_t idevice_event_subscribe(idevice_event_cb_t callback, void *user_data); | ||
157 | |||
158 | /** | ||
159 | * (DEPRECATED) Release the event callback function that has been registered with | ||
160 | * idevice_event_subscribe(). | ||
161 | * | ||
162 | * @deprecated Use idevice_events_unsubscribe() instead. | ||
163 | * | ||
164 | * @return IDEVICE_E_SUCCESS on success or an error value when an error occurred. | ||
165 | */ | ||
166 | LIBIMOBILEDEVICE_API idevice_error_t idevice_event_unsubscribe(void); | ||
80 | 167 | ||
81 | /* discovery (synchronous) */ | 168 | /* discovery (synchronous) */ |
82 | idevice_error_t idevice_get_device_list(char ***devices, int *count); | 169 | |
83 | idevice_error_t idevice_device_list_free(char **devices); | 170 | /** |
171 | * Get a list of UDIDs of currently available devices (USBMUX devices only). | ||
172 | * | ||
173 | * @param devices List of UDIDs of devices that are currently available. | ||
174 | * This list is terminated by a NULL pointer. | ||
175 | * @param count Number of devices found. | ||
176 | * | ||
177 | * @return IDEVICE_E_SUCCESS on success or an error value when an error occurred. | ||
178 | * | ||
179 | * @note This function only returns the UDIDs of USBMUX devices. To also include | ||
180 | * network devices in the list, use idevice_get_device_list_extended(). | ||
181 | * @see idevice_get_device_list_extended | ||
182 | */ | ||
183 | LIBIMOBILEDEVICE_API idevice_error_t idevice_get_device_list(char ***devices, int *count); | ||
184 | |||
185 | /** | ||
186 | * Free a list of device UDIDs. | ||
187 | * | ||
188 | * @param devices List of UDIDs to free. | ||
189 | * | ||
190 | * @return Always returnes IDEVICE_E_SUCCESS. | ||
191 | */ | ||
192 | LIBIMOBILEDEVICE_API idevice_error_t idevice_device_list_free(char **devices); | ||
193 | |||
194 | /** | ||
195 | * Get a list of currently available devices | ||
196 | * | ||
197 | * @param devices List of idevice_info_t records with device information. | ||
198 | * This list is terminated by a NULL pointer. | ||
199 | * @param count Number of devices included in the list. | ||
200 | * | ||
201 | * @return IDEVICE_E_SUCCESS on success or an error value when an error occurred. | ||
202 | */ | ||
203 | LIBIMOBILEDEVICE_API idevice_error_t idevice_get_device_list_extended(idevice_info_t **devices, int *count); | ||
204 | |||
205 | /** | ||
206 | * Free an extended device list retrieved through idevice_get_device_list_extended(). | ||
207 | * | ||
208 | * @param devices Device list to free. | ||
209 | * | ||
210 | * @return IDEVICE_E_SUCCESS on success or an error value when an error occurred. | ||
211 | */ | ||
212 | LIBIMOBILEDEVICE_API idevice_error_t idevice_device_list_extended_free(idevice_info_t *devices); | ||
84 | 213 | ||
85 | /* device structure creation and destruction */ | 214 | /* device structure creation and destruction */ |
86 | idevice_error_t idevice_new(idevice_t *device, const char *uuid); | 215 | |
87 | idevice_error_t idevice_free(idevice_t device); | 216 | /** |
217 | * Creates an idevice_t structure for the device specified by UDID, | ||
218 | * if the device is available (USBMUX devices only). | ||
219 | * | ||
220 | * @note The resulting idevice_t structure has to be freed with | ||
221 | * idevice_free() if it is no longer used. | ||
222 | * If you need to connect to a device available via network, use | ||
223 | * idevice_new_with_options() and include IDEVICE_LOOKUP_NETWORK in options. | ||
224 | * | ||
225 | * @see idevice_new_with_options | ||
226 | * | ||
227 | * @param device Upon calling this function, a pointer to a location of type | ||
228 | * idevice_t. On successful return, this location will be populated. | ||
229 | * @param udid The UDID to match. | ||
230 | * | ||
231 | * @return IDEVICE_E_SUCCESS if ok, otherwise an error code. | ||
232 | */ | ||
233 | LIBIMOBILEDEVICE_API idevice_error_t idevice_new(idevice_t *device, const char *udid); | ||
234 | |||
235 | /** | ||
236 | * Creates an idevice_t structure for the device specified by UDID, | ||
237 | * if the device is available, with the given lookup options. | ||
238 | * | ||
239 | * @note The resulting idevice_t structure has to be freed with | ||
240 | * idevice_free() if it is no longer used. | ||
241 | * | ||
242 | * @param device Upon calling this function, a pointer to a location of type | ||
243 | * idevice_t. On successful return, this location will be populated. | ||
244 | * @param udid The UDID to match. | ||
245 | * @param options Specifies what connection types should be considered | ||
246 | * when looking up devices. Accepts bitwise or'ed values of idevice_options. | ||
247 | * If 0 (no option) is specified it will default to IDEVICE_LOOKUP_USBMUX. | ||
248 | * To lookup both USB and network-connected devices, pass | ||
249 | * IDEVICE_LOOKUP_USBMUX | IDEVICE_LOOKUP_NETWORK. If a device is available | ||
250 | * both via USBMUX *and* network, it will select the USB connection. | ||
251 | * This behavior can be changed by adding IDEVICE_LOOKUP_PREFER_NETWORK | ||
252 | * to the options in which case it will select the network connection. | ||
253 | * | ||
254 | * @return IDEVICE_E_SUCCESS if ok, otherwise an error code. | ||
255 | */ | ||
256 | LIBIMOBILEDEVICE_API idevice_error_t idevice_new_with_options(idevice_t *device, const char *udid, enum idevice_options options); | ||
257 | |||
258 | /** | ||
259 | * Cleans up an idevice structure, then frees the structure itself. | ||
260 | * | ||
261 | * @param device idevice_t to free. | ||
262 | */ | ||
263 | LIBIMOBILEDEVICE_API idevice_error_t idevice_free(idevice_t device); | ||
88 | 264 | ||
89 | /* connection/disconnection */ | 265 | /* connection/disconnection */ |
90 | idevice_error_t idevice_connect(idevice_t device, uint16_t port, idevice_connection_t *connection); | 266 | |
91 | idevice_error_t idevice_disconnect(idevice_connection_t connection); | 267 | /** |
268 | * Set up a connection to the given device. | ||
269 | * | ||
270 | * @param device The device to connect to. | ||
271 | * @param port The destination port to connect to. | ||
272 | * @param connection Pointer to an idevice_connection_t that will be filled | ||
273 | * with the necessary data of the connection. | ||
274 | * | ||
275 | * @return IDEVICE_E_SUCCESS if ok, otherwise an error code. | ||
276 | */ | ||
277 | LIBIMOBILEDEVICE_API idevice_error_t idevice_connect(idevice_t device, uint16_t port, idevice_connection_t *connection); | ||
278 | |||
279 | /** | ||
280 | * Disconnect from the device and clean up the connection structure. | ||
281 | * | ||
282 | * @param connection The connection to close. | ||
283 | * | ||
284 | * @return IDEVICE_E_SUCCESS if ok, otherwise an error code. | ||
285 | */ | ||
286 | LIBIMOBILEDEVICE_API idevice_error_t idevice_disconnect(idevice_connection_t connection); | ||
92 | 287 | ||
93 | /* communication */ | 288 | /* communication */ |
94 | idevice_error_t idevice_connection_send(idevice_connection_t connection, const char *data, uint32_t len, uint32_t *sent_bytes); | 289 | |
95 | idevice_error_t idevice_connection_receive_timeout(idevice_connection_t connection, char *data, uint32_t len, uint32_t *recv_bytes, unsigned int timeout); | 290 | /** |
96 | idevice_error_t idevice_connection_receive(idevice_connection_t connection, char *data, uint32_t len, uint32_t *recv_bytes); | 291 | * Send data to a device via the given connection. |
292 | * | ||
293 | * @param connection The connection to send data over. | ||
294 | * @param data Buffer with data to send. | ||
295 | * @param len Size of the buffer to send. | ||
296 | * @param sent_bytes Pointer to an uint32_t that will be filled | ||
297 | * with the number of bytes actually sent. | ||
298 | * | ||
299 | * @return IDEVICE_E_SUCCESS if ok, otherwise an error code. | ||
300 | */ | ||
301 | LIBIMOBILEDEVICE_API idevice_error_t idevice_connection_send(idevice_connection_t connection, const char *data, uint32_t len, uint32_t *sent_bytes); | ||
302 | |||
303 | /** | ||
304 | * Receive data from a device via the given connection. | ||
305 | * This function will return after the given timeout even if no data has been | ||
306 | * received. | ||
307 | * | ||
308 | * @param connection The connection to receive data from. | ||
309 | * @param data Buffer that will be filled with the received data. | ||
310 | * This buffer has to be large enough to hold len bytes. | ||
311 | * @param len Buffer size or number of bytes to receive. | ||
312 | * @param recv_bytes Number of bytes actually received. | ||
313 | * @param timeout Timeout in milliseconds after which this function should | ||
314 | * return even if no data has been received. | ||
315 | * | ||
316 | * @return IDEVICE_E_SUCCESS if ok, otherwise an error code. | ||
317 | */ | ||
318 | LIBIMOBILEDEVICE_API idevice_error_t idevice_connection_receive_timeout(idevice_connection_t connection, char *data, uint32_t len, uint32_t *recv_bytes, unsigned int timeout); | ||
319 | |||
320 | /** | ||
321 | * Receive data from a device via the given connection. | ||
322 | * This function is like idevice_connection_receive_timeout, but with a | ||
323 | * predefined reasonable timeout. | ||
324 | * | ||
325 | * @param connection The connection to receive data from. | ||
326 | * @param data Buffer that will be filled with the received data. | ||
327 | * This buffer has to be large enough to hold len bytes. | ||
328 | * @param len Buffer size or number of bytes to receive. | ||
329 | * @param recv_bytes Number of bytes actually received. | ||
330 | * | ||
331 | * @return IDEVICE_E_SUCCESS if ok, otherwise an error code. | ||
332 | */ | ||
333 | LIBIMOBILEDEVICE_API idevice_error_t idevice_connection_receive(idevice_connection_t connection, char *data, uint32_t len, uint32_t *recv_bytes); | ||
334 | |||
335 | /** | ||
336 | * Enables SSL for the given connection. | ||
337 | * | ||
338 | * @param connection The connection to enable SSL for. | ||
339 | * | ||
340 | * @return IDEVICE_E_SUCCESS on success, IDEVICE_E_INVALID_ARG when connection | ||
341 | * is NULL or connection->ssl_data is non-NULL, or IDEVICE_E_SSL_ERROR when | ||
342 | * SSL initialization, setup, or handshake fails. | ||
343 | */ | ||
344 | LIBIMOBILEDEVICE_API idevice_error_t idevice_connection_enable_ssl(idevice_connection_t connection); | ||
345 | |||
346 | /** | ||
347 | * Disable SSL for the given connection. | ||
348 | * | ||
349 | * @param connection The connection to disable SSL for. | ||
350 | * | ||
351 | * @return IDEVICE_E_SUCCESS on success, IDEVICE_E_INVALID_ARG when connection | ||
352 | * is NULL. This function also returns IDEVICE_E_SUCCESS when SSL is not | ||
353 | * enabled and does no further error checking on cleanup. | ||
354 | */ | ||
355 | LIBIMOBILEDEVICE_API idevice_error_t idevice_connection_disable_ssl(idevice_connection_t connection); | ||
356 | |||
357 | /** | ||
358 | * Disable bypass SSL for the given connection without sending out terminate messages. | ||
359 | * | ||
360 | * @param connection The connection to disable SSL for. | ||
361 | * @param sslBypass if true ssl connection will not be terminated but just cleaned up, allowing | ||
362 | * plain text data going on underlying connection | ||
363 | * | ||
364 | * @return IDEVICE_E_SUCCESS on success, IDEVICE_E_INVALID_ARG when connection | ||
365 | * is NULL. This function also returns IDEVICE_E_SUCCESS when SSL is not | ||
366 | * enabled and does no further error checking on cleanup. | ||
367 | */ | ||
368 | LIBIMOBILEDEVICE_API idevice_error_t idevice_connection_disable_bypass_ssl(idevice_connection_t connection, uint8_t sslBypass); | ||
369 | |||
370 | |||
371 | /** | ||
372 | * Get the underlying file descriptor for a connection | ||
373 | * | ||
374 | * @param connection The connection to get fd of | ||
375 | * @param fd Pointer to an int where the fd is stored | ||
376 | * | ||
377 | * @return IDEVICE_E_SUCCESS if ok, otherwise an error code. | ||
378 | */ | ||
379 | LIBIMOBILEDEVICE_API idevice_error_t idevice_connection_get_fd(idevice_connection_t connection, int *fd); | ||
97 | 380 | ||
98 | /* misc */ | 381 | /* misc */ |
99 | idevice_error_t idevice_get_handle(idevice_t device, uint32_t *handle); | 382 | |
100 | idevice_error_t idevice_get_uuid(idevice_t device, char **uuid); | 383 | /** |
384 | * Gets the handle or (USBMUX device id) of the device. | ||
385 | * | ||
386 | * @param device The device to get the USBMUX device id for. | ||
387 | * @param handle Pointer to a uint32_t that will be set to the USBMUX handle value. | ||
388 | * | ||
389 | * @return IDEVICE_E_SUCCESS on success, otherwise an error code. | ||
390 | */ | ||
391 | LIBIMOBILEDEVICE_API idevice_error_t idevice_get_handle(idevice_t device, uint32_t *handle); | ||
392 | |||
393 | /** | ||
394 | * Gets the Unique Device ID for the device. | ||
395 | * | ||
396 | * @param device The device to get the Unique Device ID for. | ||
397 | * @param udid Pointer that will be set to an allocated buffer with the device UDID. The consumer is responsible for releasing the allocated memory. | ||
398 | * | ||
399 | * @return IDEVICE_E_SUCCESS on success, otherwise an error code. | ||
400 | */ | ||
401 | LIBIMOBILEDEVICE_API idevice_error_t idevice_get_udid(idevice_t device, char **udid); | ||
402 | |||
403 | /** | ||
404 | * Returns a static string of the libimobiledevice version. | ||
405 | * | ||
406 | * @return The libimobiledevice version as static ascii string | ||
407 | */ | ||
408 | LIBIMOBILEDEVICE_API const char* libimobiledevice_version(); | ||
101 | 409 | ||
102 | #ifdef __cplusplus | 410 | #ifdef __cplusplus |
103 | } | 411 | } |
diff --git a/include/libimobiledevice/lockdown.h b/include/libimobiledevice/lockdown.h index 97df6b0..21669ef 100644 --- a/include/libimobiledevice/lockdown.h +++ b/include/libimobiledevice/lockdown.h | |||
@@ -3,8 +3,10 @@ | |||
3 | * @brief Manage device preferences, start services, pairing and activation. | 3 | * @brief Manage device preferences, start services, pairing and activation. |
4 | * \internal | 4 | * \internal |
5 | * | 5 | * |
6 | * Copyright (c) 2009-2014 Martin S. All Rights Reserved. | ||
7 | * Copyright (c) 2014 Koby Boyango All Rights Reserved. | ||
8 | * Copyright (c) 2010 Bryan Forbes All Rights Reserved. | ||
6 | * Copyright (c) 2008 Zach C. All Rights Reserved. | 9 | * Copyright (c) 2008 Zach C. All Rights Reserved. |
7 | * Copyright (c) 2009 Martin S. All Rights Reserved. | ||
8 | * | 10 | * |
9 | * This library is free software; you can redistribute it and/or | 11 | * This library is free software; you can redistribute it and/or |
10 | * modify it under the terms of the GNU Lesser General Public | 12 | * modify it under the terms of the GNU Lesser General Public |
@@ -21,8 +23,8 @@ | |||
21 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | 23 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA |
22 | */ | 24 | */ |
23 | 25 | ||
24 | #ifndef LOCKDOWN_H | 26 | #ifndef ILOCKDOWN_H |
25 | #define LOCKDOWN_H | 27 | #define ILOCKDOWN_H |
26 | 28 | ||
27 | #ifdef __cplusplus | 29 | #ifdef __cplusplus |
28 | extern "C" { | 30 | extern "C" { |
@@ -30,74 +32,543 @@ extern "C" { | |||
30 | 32 | ||
31 | #include <libimobiledevice/libimobiledevice.h> | 33 | #include <libimobiledevice/libimobiledevice.h> |
32 | 34 | ||
33 | /** @name Error Codes */ | 35 | /** Error Codes */ |
34 | /*@{*/ | 36 | typedef enum { |
35 | #define LOCKDOWN_E_SUCCESS 0 | 37 | /* custom */ |
36 | #define LOCKDOWN_E_INVALID_ARG -1 | 38 | LOCKDOWN_E_SUCCESS = 0, |
37 | #define LOCKDOWN_E_INVALID_CONF -2 | 39 | LOCKDOWN_E_INVALID_ARG = -1, |
38 | #define LOCKDOWN_E_PLIST_ERROR -3 | 40 | LOCKDOWN_E_INVALID_CONF = -2, |
39 | #define LOCKDOWN_E_PAIRING_FAILED -4 | 41 | LOCKDOWN_E_PLIST_ERROR = -3, |
40 | #define LOCKDOWN_E_SSL_ERROR -5 | 42 | LOCKDOWN_E_PAIRING_FAILED = -4, |
41 | #define LOCKDOWN_E_DICT_ERROR -6 | 43 | LOCKDOWN_E_SSL_ERROR = -5, |
42 | #define LOCKDOWN_E_START_SERVICE_FAILED -7 | 44 | LOCKDOWN_E_DICT_ERROR = -6, |
43 | #define LOCKDOWN_E_NOT_ENOUGH_DATA -8 | 45 | LOCKDOWN_E_RECEIVE_TIMEOUT = -7, |
44 | #define LOCKDOWN_E_SET_VALUE_PROHIBITED -9 | 46 | LOCKDOWN_E_MUX_ERROR = -8, |
45 | #define LOCKDOWN_E_GET_VALUE_PROHIBITED -10 | 47 | LOCKDOWN_E_NO_RUNNING_SESSION = -9, |
46 | #define LOCKDOWN_E_REMOVE_VALUE_PROHIBITED -11 | 48 | /* native */ |
47 | #define LOCKDOWN_E_MUX_ERROR -12 | 49 | LOCKDOWN_E_INVALID_RESPONSE = -10, |
48 | #define LOCKDOWN_E_ACTIVATION_FAILED -13 | 50 | LOCKDOWN_E_MISSING_KEY = -11, |
49 | #define LOCKDOWN_E_PASSWORD_PROTECTED -14 | 51 | LOCKDOWN_E_MISSING_VALUE = -12, |
50 | #define LOCKDOWN_E_NO_RUNNING_SESSION -15 | 52 | LOCKDOWN_E_GET_PROHIBITED = -13, |
51 | #define LOCKDOWN_E_INVALID_HOST_ID -16 | 53 | LOCKDOWN_E_SET_PROHIBITED = -14, |
52 | #define LOCKDOWN_E_INVALID_SERVICE -17 | 54 | LOCKDOWN_E_REMOVE_PROHIBITED = -15, |
53 | #define LOCKDOWN_E_INVALID_ACTIVATION_RECORD -18 | 55 | LOCKDOWN_E_IMMUTABLE_VALUE = -16, |
54 | 56 | LOCKDOWN_E_PASSWORD_PROTECTED = -17, | |
55 | #define LOCKDOWN_E_UNKNOWN_ERROR -256 | 57 | LOCKDOWN_E_USER_DENIED_PAIRING = -18, |
56 | /*@}*/ | 58 | LOCKDOWN_E_PAIRING_DIALOG_RESPONSE_PENDING = -19, |
57 | 59 | LOCKDOWN_E_MISSING_HOST_ID = -20, | |
58 | /** Represents an error code. */ | 60 | LOCKDOWN_E_INVALID_HOST_ID = -21, |
59 | typedef int16_t lockdownd_error_t; | 61 | LOCKDOWN_E_SESSION_ACTIVE = -22, |
60 | 62 | LOCKDOWN_E_SESSION_INACTIVE = -23, | |
61 | typedef struct lockdownd_client_private lockdownd_client_private; | 63 | LOCKDOWN_E_MISSING_SESSION_ID = -24, |
64 | LOCKDOWN_E_INVALID_SESSION_ID = -25, | ||
65 | LOCKDOWN_E_MISSING_SERVICE = -26, | ||
66 | LOCKDOWN_E_INVALID_SERVICE = -27, | ||
67 | LOCKDOWN_E_SERVICE_LIMIT = -28, | ||
68 | LOCKDOWN_E_MISSING_PAIR_RECORD = -29, | ||
69 | LOCKDOWN_E_SAVE_PAIR_RECORD_FAILED = -30, | ||
70 | LOCKDOWN_E_INVALID_PAIR_RECORD = -31, | ||
71 | LOCKDOWN_E_INVALID_ACTIVATION_RECORD = -32, | ||
72 | LOCKDOWN_E_MISSING_ACTIVATION_RECORD = -33, | ||
73 | LOCKDOWN_E_SERVICE_PROHIBITED = -34, | ||
74 | LOCKDOWN_E_ESCROW_LOCKED = -35, | ||
75 | LOCKDOWN_E_PAIRING_PROHIBITED_OVER_THIS_CONNECTION = -36, | ||
76 | LOCKDOWN_E_FMIP_PROTECTED = -37, | ||
77 | LOCKDOWN_E_MC_PROTECTED = -38, | ||
78 | LOCKDOWN_E_MC_CHALLENGE_REQUIRED = -39, | ||
79 | LOCKDOWN_E_UNKNOWN_ERROR = -256 | ||
80 | } lockdownd_error_t; | ||
81 | |||
82 | typedef struct lockdownd_client_private lockdownd_client_private; /**< \private */ | ||
62 | typedef lockdownd_client_private *lockdownd_client_t; /**< The client handle. */ | 83 | typedef lockdownd_client_private *lockdownd_client_t; /**< The client handle. */ |
63 | 84 | ||
64 | struct lockdownd_pair_record { | 85 | struct lockdownd_pair_record { |
65 | char *device_certificate; /**< The device certificate */ | 86 | char *device_certificate; /**< The device certificate */ |
66 | char *host_certificate; /**< The host certificate */ | 87 | char *host_certificate; /**< The host certificate */ |
67 | char *host_id; /**< A unique HostID for the host computer */ | ||
68 | char *root_certificate; /**< The root certificate */ | 88 | char *root_certificate; /**< The root certificate */ |
89 | char *host_id; /**< A unique HostID for the host computer */ | ||
90 | char *system_buid; /**< A unique system id */ | ||
69 | }; | 91 | }; |
70 | /** A pair record holding device, host and root certificates along the host_id */ | 92 | /** pair record holding device, host and root certificates along the host_id */ |
71 | typedef struct lockdownd_pair_record *lockdownd_pair_record_t; | 93 | typedef struct lockdownd_pair_record *lockdownd_pair_record_t; /**< pair record */ |
94 | |||
95 | /** service descriptor */ | ||
96 | struct lockdownd_service_descriptor { | ||
97 | uint16_t port; /**< port number the service was started on */ | ||
98 | uint8_t ssl_enabled; /**< an indicator if the service requires SSL */ | ||
99 | char* identifier; /**< identifier of the service */ | ||
100 | }; | ||
101 | typedef struct lockdownd_service_descriptor *lockdownd_service_descriptor_t; | ||
102 | |||
103 | /** Callback types used in #lockdownd_cu_pairing_cb_t */ | ||
104 | typedef enum { | ||
105 | LOCKDOWN_CU_PAIRING_PIN_REQUESTED, /**< PIN requested: data_ptr is a char* buffer, and data_size points to the size of this buffer that must not be exceeded and has to be updated to the actual number of characters filled into the buffer. */ | ||
106 | LOCKDOWN_CU_PAIRING_DEVICE_INFO, /**< device information available: data_ptr is a plist_t, and data_size is ignored. The plist_t has to be copied if required, since it is freed when the callback function returns. */ | ||
107 | LOCKDOWN_CU_PAIRING_ERROR /**< pairing error message available: data_ptr is a NULL-terminated char* buffer containing the error message, and data_size is ignored. Buffer needs to be copied if it shall persist outside the callback. */ | ||
108 | } lockdownd_cu_pairing_cb_type_t; | ||
109 | |||
110 | /* CU pairing callback function prototype */ | ||
111 | /** Callback used to supply the pairing PIN during a CU pairing session, | ||
112 | * and to report device information and pairing error messages. */ | ||
113 | typedef void (*lockdownd_cu_pairing_cb_t) (lockdownd_cu_pairing_cb_type_t cb_type, void *user_data, void* data_ptr, unsigned int* data_size); | ||
114 | |||
72 | 115 | ||
73 | /* Interface */ | 116 | /* Interface */ |
74 | lockdownd_error_t lockdownd_client_new(idevice_t device, lockdownd_client_t *client, const char *label); | 117 | |
75 | lockdownd_error_t lockdownd_client_new_with_handshake(idevice_t device, lockdownd_client_t *client, const char *label); | 118 | /** |
76 | lockdownd_error_t lockdownd_client_free(lockdownd_client_t client); | 119 | * Creates a new lockdownd client for the device. |
77 | 120 | * | |
78 | lockdownd_error_t lockdownd_query_type(lockdownd_client_t client, char **type); | 121 | * @note This function does not pair with the device or start a session. This |
79 | lockdownd_error_t lockdownd_get_value(lockdownd_client_t client, const char *domain, const char *key, plist_t *value); | 122 | * has to be done manually by the caller after the client is created. |
80 | lockdownd_error_t lockdownd_set_value(lockdownd_client_t client, const char *domain, const char *key, plist_t value); | 123 | * The device disconnects automatically if the lockdown connection idles |
81 | lockdownd_error_t lockdownd_remove_value(lockdownd_client_t client, const char *domain, const char *key); | 124 | * for more than 10 seconds. Make sure to call lockdownd_client_free() as soon |
82 | lockdownd_error_t lockdownd_start_service(lockdownd_client_t client, const char *service, uint16_t *port); | 125 | * as the connection is no longer needed. |
83 | lockdownd_error_t lockdownd_start_session(lockdownd_client_t client, const char *host_id, char **session_id, int *ssl_enabled); | 126 | * |
84 | lockdownd_error_t lockdownd_stop_session(lockdownd_client_t client, const char *session_id); | 127 | * @param device The device to create a lockdownd client for |
85 | lockdownd_error_t lockdownd_send(lockdownd_client_t client, plist_t plist); | 128 | * @param client The pointer to the location of the new lockdownd_client |
86 | lockdownd_error_t lockdownd_receive(lockdownd_client_t client, plist_t *plist); | 129 | * @param label The label to use for communication. Usually the program name. |
87 | lockdownd_error_t lockdownd_pair(lockdownd_client_t client, lockdownd_pair_record_t pair_record); | 130 | * |
88 | lockdownd_error_t lockdownd_validate_pair(lockdownd_client_t client, lockdownd_pair_record_t pair_record); | 131 | * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL |
89 | lockdownd_error_t lockdownd_unpair(lockdownd_client_t client, lockdownd_pair_record_t pair_record); | 132 | */ |
90 | lockdownd_error_t lockdownd_activate(lockdownd_client_t client, plist_t activation_record); | 133 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_client_new(idevice_t device, lockdownd_client_t *client, const char *label); |
91 | lockdownd_error_t lockdownd_deactivate(lockdownd_client_t client); | 134 | |
92 | lockdownd_error_t lockdownd_enter_recovery(lockdownd_client_t client); | 135 | /** |
93 | lockdownd_error_t lockdownd_goodbye(lockdownd_client_t client); | 136 | * Creates a new lockdownd client for the device and starts initial handshake. |
137 | * The handshake consists out of query_type, validate_pair, pair and | ||
138 | * start_session calls. It uses the internal pairing record management. | ||
139 | * | ||
140 | * @note The device disconnects automatically if the lockdown connection idles | ||
141 | * for more than 10 seconds. Make sure to call lockdownd_client_free() as soon | ||
142 | * as the connection is no longer needed. | ||
143 | * | ||
144 | * @param device The device to create a lockdownd client for | ||
145 | * @param client The pointer to the location of the new lockdownd_client | ||
146 | * @param label The label to use for communication. Usually the program name. | ||
147 | * Pass NULL to disable sending the label in requests to lockdownd. | ||
148 | * | ||
149 | * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL, | ||
150 | * LOCKDOWN_E_INVALID_CONF if configuration data is wrong | ||
151 | */ | ||
152 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_client_new_with_handshake(idevice_t device, lockdownd_client_t *client, const char *label); | ||
153 | |||
154 | /** | ||
155 | * Closes the lockdownd client session if one is running and frees up the | ||
156 | * lockdownd_client struct. | ||
157 | * | ||
158 | * @param client The lockdown client | ||
159 | * | ||
160 | * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL | ||
161 | */ | ||
162 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_client_free(lockdownd_client_t client); | ||
163 | |||
164 | |||
165 | /** | ||
166 | * Query the type of the service daemon. Depending on whether the device is | ||
167 | * queried in normal mode or restore mode, different types will be returned. | ||
168 | * | ||
169 | * @param client The lockdownd client | ||
170 | * @param type The type returned by the service daemon. Pass NULL to ignore. | ||
171 | * | ||
172 | * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL | ||
173 | */ | ||
174 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_query_type(lockdownd_client_t client, char **type); | ||
175 | |||
176 | /** | ||
177 | * Retrieves a preferences plist using an optional domain and/or key name. | ||
178 | * | ||
179 | * @param client An initialized lockdownd client. | ||
180 | * @param domain The domain to query on or NULL for global domain | ||
181 | * @param key The key name to request or NULL to query for all keys | ||
182 | * @param value A plist node representing the result value node | ||
183 | * | ||
184 | * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL | ||
185 | */ | ||
186 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_get_value(lockdownd_client_t client, const char *domain, const char *key, plist_t *value); | ||
187 | |||
188 | /** | ||
189 | * Sets a preferences value using a plist and optional by domain and/or key name. | ||
190 | * | ||
191 | * @param client an initialized lockdownd client. | ||
192 | * @param domain the domain to query on or NULL for global domain | ||
193 | * @param key the key name to set the value or NULL to set a value dict plist | ||
194 | * @param value a plist node of any node type representing the value to set | ||
195 | * | ||
196 | * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client or | ||
197 | * value is NULL | ||
198 | */ | ||
199 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_set_value(lockdownd_client_t client, const char *domain, const char *key, plist_t value); | ||
200 | |||
201 | /** | ||
202 | * Removes a preference node by domain and/or key name. | ||
203 | * | ||
204 | * @note: Use with caution as this could remove vital information on the device | ||
205 | * | ||
206 | * @param client An initialized lockdownd client. | ||
207 | * @param domain The domain to query on or NULL for global domain | ||
208 | * @param key The key name to remove or NULL remove all keys for the current domain | ||
209 | * | ||
210 | * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL | ||
211 | */ | ||
212 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_remove_value(lockdownd_client_t client, const char *domain, const char *key); | ||
213 | |||
214 | /** | ||
215 | * Requests to start a service and retrieve it's port on success. | ||
216 | * | ||
217 | * @param client The lockdownd client | ||
218 | * @param identifier The identifier of the service to start | ||
219 | * @param service The service descriptor on success or NULL on failure | ||
220 | * | ||
221 | * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG if a parameter | ||
222 | * is NULL, LOCKDOWN_E_INVALID_SERVICE if the requested service is not known | ||
223 | * by the device, LOCKDOWN_E_START_SERVICE_FAILED if the service could not be | ||
224 | * started by the device | ||
225 | */ | ||
226 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_start_service(lockdownd_client_t client, const char *identifier, lockdownd_service_descriptor_t *service); | ||
227 | |||
228 | /** | ||
229 | * Requests to start a service and retrieve it's port on success. | ||
230 | * Sends the escrow bag from the device's pair record. | ||
231 | * | ||
232 | * @param client The lockdownd client | ||
233 | * @param identifier The identifier of the service to start | ||
234 | * @param service The service descriptor on success or NULL on failure | ||
235 | * | ||
236 | * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG if a parameter | ||
237 | * is NULL, LOCKDOWN_E_INVALID_SERVICE if the requested service is not known | ||
238 | * by the device, LOCKDOWN_E_START_SERVICE_FAILED if the service could not because | ||
239 | * started by the device, LOCKDOWN_E_INVALID_CONF if the host id or escrow bag are | ||
240 | * missing from the device record. | ||
241 | */ | ||
242 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_start_service_with_escrow_bag(lockdownd_client_t client, const char *identifier, lockdownd_service_descriptor_t *service); | ||
243 | |||
244 | /** | ||
245 | * Opens a session with lockdownd and switches to SSL mode if device wants it. | ||
246 | * | ||
247 | * @param client The lockdownd client | ||
248 | * @param host_id The HostID of the computer | ||
249 | * @param session_id The new session_id of the created session | ||
250 | * @param ssl_enabled Whether SSL communication is used in the session | ||
251 | * | ||
252 | * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when a client | ||
253 | * or host_id is NULL, LOCKDOWN_E_PLIST_ERROR if the response plist had errors, | ||
254 | * LOCKDOWN_E_INVALID_HOST_ID if the device does not know the supplied HostID, | ||
255 | * LOCKDOWN_E_SSL_ERROR if enabling SSL communication failed | ||
256 | */ | ||
257 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_start_session(lockdownd_client_t client, const char *host_id, char **session_id, int *ssl_enabled); | ||
258 | |||
259 | /** | ||
260 | * Closes the lockdownd session by sending the StopSession request. | ||
261 | * | ||
262 | * @see lockdownd_start_session | ||
263 | * | ||
264 | * @param client The lockdown client | ||
265 | * @param session_id The id of a running session | ||
266 | * | ||
267 | * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL | ||
268 | */ | ||
269 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_stop_session(lockdownd_client_t client, const char *session_id); | ||
270 | |||
271 | /** | ||
272 | * Sends a plist to lockdownd. | ||
273 | * | ||
274 | * @note This function is low-level and should only be used if you need to send | ||
275 | * a new type of message. | ||
276 | * | ||
277 | * @param client The lockdownd client | ||
278 | * @param plist The plist to send | ||
279 | * | ||
280 | * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client or | ||
281 | * plist is NULL | ||
282 | */ | ||
283 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_send(lockdownd_client_t client, plist_t plist); | ||
284 | |||
285 | /** | ||
286 | * Receives a plist from lockdownd. | ||
287 | * | ||
288 | * @param client The lockdownd client | ||
289 | * @param plist The plist to store the received data | ||
290 | * | ||
291 | * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client or | ||
292 | * plist is NULL | ||
293 | */ | ||
294 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_receive(lockdownd_client_t client, plist_t *plist); | ||
295 | |||
296 | /** | ||
297 | * Pairs the device using the supplied pair record. | ||
298 | * | ||
299 | * @param client The lockdown client | ||
300 | * @param pair_record The pair record to use for pairing. If NULL is passed, then | ||
301 | * the pair records from the current machine are used. New records will be | ||
302 | * generated automatically when pairing is done for the first time. | ||
303 | * | ||
304 | * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL, | ||
305 | * LOCKDOWN_E_PLIST_ERROR if the pair_record certificates are wrong, | ||
306 | * LOCKDOWN_E_PAIRING_FAILED if the pairing failed, | ||
307 | * LOCKDOWN_E_PASSWORD_PROTECTED if the device is password protected, | ||
308 | * LOCKDOWN_E_INVALID_HOST_ID if the device does not know the caller's host id | ||
309 | */ | ||
310 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_pair(lockdownd_client_t client, lockdownd_pair_record_t pair_record); | ||
311 | |||
312 | /** | ||
313 | * Pairs the device using the supplied pair record and passing the given options. | ||
314 | * | ||
315 | * @param client The lockdown client | ||
316 | * @param pair_record The pair record to use for pairing. If NULL is passed, then | ||
317 | * the pair records from the current machine are used. New records will be | ||
318 | * generated automatically when pairing is done for the first time. | ||
319 | * @param options The pairing options to pass. Can be NULL for no options. | ||
320 | * @param response If non-NULL a pointer to lockdownd's response dictionary is returned. | ||
321 | * The caller is responsible to free the response dictionary with plist_free(). | ||
322 | * | ||
323 | * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL, | ||
324 | * LOCKDOWN_E_PLIST_ERROR if the pair_record certificates are wrong, | ||
325 | * LOCKDOWN_E_PAIRING_FAILED if the pairing failed, | ||
326 | * LOCKDOWN_E_PASSWORD_PROTECTED if the device is password protected, | ||
327 | * LOCKDOWN_E_INVALID_HOST_ID if the device does not know the caller's host id | ||
328 | */ | ||
329 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_pair_with_options(lockdownd_client_t client, lockdownd_pair_record_t pair_record, plist_t options, plist_t *response); | ||
330 | |||
331 | /** | ||
332 | * Validates if the device is paired with the given HostID. If successful the | ||
333 | * specified host will become trusted host of the device indicated by the | ||
334 | * lockdownd preference named TrustedHostAttached. Otherwise the host must be | ||
335 | * paired using lockdownd_pair() first. | ||
336 | * | ||
337 | * @param client The lockdown client | ||
338 | * @param pair_record The pair record to validate pairing with. If NULL is | ||
339 | * passed, then the pair record is read from the internal pairing record | ||
340 | * management. | ||
341 | * | ||
342 | * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL, | ||
343 | * LOCKDOWN_E_PLIST_ERROR if the pair_record certificates are wrong, | ||
344 | * LOCKDOWN_E_PAIRING_FAILED if the pairing failed, | ||
345 | * LOCKDOWN_E_PASSWORD_PROTECTED if the device is password protected, | ||
346 | * LOCKDOWN_E_INVALID_HOST_ID if the device does not know the caller's host id | ||
347 | */ | ||
348 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_validate_pair(lockdownd_client_t client, lockdownd_pair_record_t pair_record); | ||
349 | |||
350 | /** | ||
351 | * Unpairs the device with the given HostID and removes the pairing records | ||
352 | * from the device and host if the internal pairing record management is used. | ||
353 | * | ||
354 | * @param client The lockdown client | ||
355 | * @param pair_record The pair record to use for unpair. If NULL is passed, then | ||
356 | * the pair records from the current machine are used. | ||
357 | * | ||
358 | * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL, | ||
359 | * LOCKDOWN_E_PLIST_ERROR if the pair_record certificates are wrong, | ||
360 | * LOCKDOWN_E_PAIRING_FAILED if the pairing failed, | ||
361 | * LOCKDOWN_E_PASSWORD_PROTECTED if the device is password protected, | ||
362 | * LOCKDOWN_E_INVALID_HOST_ID if the device does not know the caller's host id | ||
363 | */ | ||
364 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_unpair(lockdownd_client_t client, lockdownd_pair_record_t pair_record); | ||
365 | |||
366 | /** | ||
367 | * Activates the device. Only works within an open session. | ||
368 | * The ActivationRecord plist dictionary must be obtained using the | ||
369 | * activation protocol requesting from Apple's https webservice. | ||
370 | * | ||
371 | * @param client The lockdown client | ||
372 | * @param activation_record The activation record plist dictionary | ||
373 | * | ||
374 | * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client or | ||
375 | * activation_record is NULL, LOCKDOWN_E_NO_RUNNING_SESSION if no session is | ||
376 | * open, LOCKDOWN_E_PLIST_ERROR if the received plist is broken, | ||
377 | * LOCKDOWN_E_ACTIVATION_FAILED if the activation failed, | ||
378 | * LOCKDOWN_E_INVALID_ACTIVATION_RECORD if the device reports that the | ||
379 | * activation_record is invalid | ||
380 | */ | ||
381 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_activate(lockdownd_client_t client, plist_t activation_record); | ||
382 | |||
383 | /** | ||
384 | * Deactivates the device, returning it to the locked “Activate with iTunes” | ||
385 | * screen. | ||
386 | * | ||
387 | * @param client The lockdown client | ||
388 | * | ||
389 | * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL, | ||
390 | * LOCKDOWN_E_NO_RUNNING_SESSION if no session is open, | ||
391 | * LOCKDOWN_E_PLIST_ERROR if the received plist is broken | ||
392 | */ | ||
393 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_deactivate(lockdownd_client_t client); | ||
394 | |||
395 | /** | ||
396 | * Tells the device to immediately enter recovery mode. | ||
397 | * | ||
398 | * @param client The lockdown client | ||
399 | * | ||
400 | * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL | ||
401 | */ | ||
402 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_enter_recovery(lockdownd_client_t client); | ||
403 | |||
404 | /** | ||
405 | * Sends the Goodbye request to lockdownd signaling the end of communication. | ||
406 | * | ||
407 | * @param client The lockdown client | ||
408 | * | ||
409 | * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client | ||
410 | * is NULL, LOCKDOWN_E_PLIST_ERROR if the device did not acknowledge the | ||
411 | * request | ||
412 | */ | ||
413 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_goodbye(lockdownd_client_t client); | ||
414 | |||
415 | /** | ||
416 | * Creates a CU pairing session for the current lockdown client. | ||
417 | * This is required to allow lockdownd_cu_send_request_and_get_reply(), | ||
418 | * lockdownd_get_value_cu() and lockdonwd_pair_cu() requests, and eventually | ||
419 | * allows to perform an actual wireless pairing. | ||
420 | * | ||
421 | * Through the callback function, the PIN displayed on the device has to be | ||
422 | * supplied during the process. Currently, only AppleTV devices have this | ||
423 | * capability. | ||
424 | * | ||
425 | * @param client The lockdown client to perform the CU pairing for | ||
426 | * @param pairing_callback Callback function that is used to supply the PIN | ||
427 | * for the pairing process, but also to receive device information or | ||
428 | * pairing error messages. | ||
429 | * @param cb_user_data User data that will be passed as additional argument | ||
430 | * to the callback function. | ||
431 | * @param host_info (Optional) A dictionary containing host information to | ||
432 | * send to the device when finalizing the CU pairing. The supplied | ||
433 | * values will override the default values gathered for the current host. | ||
434 | * @param acl (Optional) A dictionary containing ACL information. Currently | ||
435 | * only com.apple.ScreenCapture:true and com.apple.developer:true are known | ||
436 | * valid ACL values, which are used as default when NULL is passed. | ||
437 | * | ||
438 | * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG if one of the | ||
439 | * parameters is invalid, LOCKDOWN_E_PAIRING_FAILED if the pairing failed, | ||
440 | * or a LOCKDOWN_E_* error code otherwise. | ||
441 | */ | ||
442 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_cu_pairing_create(lockdownd_client_t client, lockdownd_cu_pairing_cb_t pairing_callback, void* cb_user_data, plist_t host_info, plist_t acl); | ||
443 | |||
444 | /** | ||
445 | * Sends a request via lockdown client with established CU pairing session | ||
446 | * and attempts to retrieve a reply. This function is used internally | ||
447 | * by lockdownd_get_value_cu() and lockdownd_pair_cu(), but exposed here to | ||
448 | * allow custom requests being sent and their replies being received. | ||
449 | * | ||
450 | * @param client A lockdown client with an established CU pairing. | ||
451 | * @param request The request to perform. | ||
452 | * @param request_payload The payload for the request. | ||
453 | * @param reply (Optional) If not NULL, the plist_t will be set to the reply | ||
454 | * dictionary that has been received. Consumer is responsible to free it | ||
455 | * using plist_free() when no longer required. | ||
456 | * | ||
457 | * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG if one of the | ||
458 | * parameters is invalid, LOCKDOWN_E_NO_RUNNING_SESSION if the current | ||
459 | * lockdown client does not have an established CU pairing session, | ||
460 | * or a LOCKDOWN_E_* error code otherwise. | ||
461 | */ | ||
462 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_cu_send_request_and_get_reply(lockdownd_client_t client, const char* request, plist_t request_payload, plist_t* reply); | ||
463 | |||
464 | /** | ||
465 | * Retrieves a value using an optional domain and/or key name from a lockdown | ||
466 | * client with established CU pairing session. | ||
467 | * | ||
468 | * This is used to retrieve values that are only accessible after a CU pairing | ||
469 | * has been established, and would otherwise only be accessible with a valid | ||
470 | * device pairing. | ||
471 | * | ||
472 | * @param client A lockdown client with an established CU pairing. | ||
473 | * @param domain The domain to query on or NULL for global domain | ||
474 | * @param key The key name to request or NULL to query for all keys | ||
475 | * @param value A plist node representing the result value node | ||
476 | * | ||
477 | * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG if one of the | ||
478 | * parameters is invalid, LOCKDOWN_E_NO_RUNNING_SESSION if the current | ||
479 | * lockdown client does not have an established CU pairing session, | ||
480 | * or a LOCKDOWN_E_* error code otherwise. | ||
481 | */ | ||
482 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_get_value_cu(lockdownd_client_t client, const char* domain, const char* key, plist_t* value); | ||
483 | |||
484 | /** | ||
485 | * Perform a device pairing with a lockdown client that has an established | ||
486 | * CU pairing session. | ||
487 | * | ||
488 | * @param client A lockdown client with an established CU pairing. | ||
489 | * | ||
490 | * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client | ||
491 | * is NULL, LOCKDOWN_E_NO_RUNNING_SESSION if the current lockdown client | ||
492 | * does not have an established CU pairing session, or a LOCKDOWN_E_* error | ||
493 | * code otherwise. | ||
494 | */ | ||
495 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_pair_cu(lockdownd_client_t client); | ||
496 | |||
94 | 497 | ||
95 | /* Helper */ | 498 | /* Helper */ |
96 | void lockdownd_client_set_label(lockdownd_client_t client, const char *label); | 499 | |
97 | lockdownd_error_t lockdownd_get_device_uuid(lockdownd_client_t control, char **uuid); | 500 | /** |
98 | lockdownd_error_t lockdownd_get_device_name(lockdownd_client_t client, char **device_name); | 501 | * Sets the label to send for requests to lockdownd. |
99 | lockdownd_error_t lockdownd_get_sync_data_classes(lockdownd_client_t client, char ***classes, int *count); | 502 | * |
100 | lockdownd_error_t lockdownd_data_classes_free(char **classes); | 503 | * @param client The lockdown client |
504 | * @param label The label to set or NULL to disable sending a label | ||
505 | * | ||
506 | */ | ||
507 | LIBIMOBILEDEVICE_API void lockdownd_client_set_label(lockdownd_client_t client, const char *label); | ||
508 | |||
509 | /** | ||
510 | * Returns the unique id of the device from lockdownd. | ||
511 | * | ||
512 | * @param client An initialized lockdownd client. | ||
513 | * @param udid Holds the unique id of the device. The caller is responsible | ||
514 | * for freeing the memory. | ||
515 | * | ||
516 | * @return LOCKDOWN_E_SUCCESS on success | ||
517 | */ | ||
518 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_get_device_udid(lockdownd_client_t client, char **udid); | ||
519 | |||
520 | /** | ||
521 | * Retrieves the name of the device from lockdownd set by the user. | ||
522 | * | ||
523 | * @param client An initialized lockdownd client. | ||
524 | * @param device_name Holds the name of the device. The caller is | ||
525 | * responsible for freeing the memory. | ||
526 | * | ||
527 | * @return LOCKDOWN_E_SUCCESS on success | ||
528 | */ | ||
529 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_get_device_name(lockdownd_client_t client, char **device_name); | ||
530 | |||
531 | /** | ||
532 | * Calculates and returns the data classes the device supports from lockdownd. | ||
533 | * | ||
534 | * @param client An initialized lockdownd client. | ||
535 | * @param classes A pointer to store an array of class names. The caller is responsible | ||
536 | * for freeing the memory which can be done using mobilesync_data_classes_free(). | ||
537 | * @param count The number of items in the classes array. | ||
538 | * | ||
539 | * @return LOCKDOWN_E_SUCCESS on success, | ||
540 | * LOCKDOWN_E_INVALID_ARG when client is NULL, | ||
541 | * LOCKDOWN_E_NO_RUNNING_SESSION if no session is open, | ||
542 | * LOCKDOWN_E_PLIST_ERROR if the received plist is broken | ||
543 | */ | ||
544 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_get_sync_data_classes(lockdownd_client_t client, char ***classes, int *count); | ||
545 | |||
546 | /** | ||
547 | * Frees memory of an allocated array of data classes as returned by lockdownd_get_sync_data_classes() | ||
548 | * | ||
549 | * @param classes An array of class names to free. | ||
550 | * | ||
551 | * @return LOCKDOWN_E_SUCCESS on success | ||
552 | */ | ||
553 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_data_classes_free(char **classes); | ||
554 | |||
555 | /** | ||
556 | * Frees memory of a service descriptor as returned by lockdownd_start_service() | ||
557 | * | ||
558 | * @param service A service descriptor instance to free. | ||
559 | * | ||
560 | * @return LOCKDOWN_E_SUCCESS on success | ||
561 | */ | ||
562 | LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_service_descriptor_free(lockdownd_service_descriptor_t service); | ||
563 | |||
564 | /** | ||
565 | * Gets a readable error string for a given lockdown error code. | ||
566 | * | ||
567 | * @param err A lockdownd error code | ||
568 | * | ||
569 | * @returns A readable error string | ||
570 | */ | ||
571 | LIBIMOBILEDEVICE_API const char* lockdownd_strerror(lockdownd_error_t err); | ||
101 | 572 | ||
102 | #ifdef __cplusplus | 573 | #ifdef __cplusplus |
103 | } | 574 | } |
diff --git a/include/libimobiledevice/misagent.h b/include/libimobiledevice/misagent.h new file mode 100644 index 0000000..7981a8b --- /dev/null +++ b/include/libimobiledevice/misagent.h | |||
@@ -0,0 +1,168 @@ | |||
1 | /** | ||
2 | * @file libimobiledevice/misagent.h | ||
3 | * @brief Manage provisioning profiles. | ||
4 | * \internal | ||
5 | * | ||
6 | * Copyright (c) 2013-2014 Martin Szulecki All Rights Reserved. | ||
7 | * Copyright (c) 2012 Nikias Bassen All Rights Reserved. | ||
8 | * | ||
9 | * This library is free software; you can redistribute it and/or | ||
10 | * modify it under the terms of the GNU Lesser General Public | ||
11 | * License as published by the Free Software Foundation; either | ||
12 | * version 2.1 of the License, or (at your option) any later version. | ||
13 | * | ||
14 | * This library is distributed in the hope that it will be useful, | ||
15 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
16 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
17 | * Lesser General Public License for more details. | ||
18 | * | ||
19 | * You should have received a copy of the GNU Lesser General Public | ||
20 | * License along with this library; if not, write to the Free Software | ||
21 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | ||
22 | */ | ||
23 | |||
24 | #ifndef IMISAGENT_H | ||
25 | #define IMISAGENT_H | ||
26 | |||
27 | #ifdef __cplusplus | ||
28 | extern "C" { | ||
29 | #endif | ||
30 | |||
31 | #include <libimobiledevice/libimobiledevice.h> | ||
32 | #include <libimobiledevice/lockdown.h> | ||
33 | |||
34 | /** Service identifier passed to lockdownd_start_service() to start the misagent service */ | ||
35 | #define MISAGENT_SERVICE_NAME "com.apple.misagent" | ||
36 | |||
37 | /** Error Codes */ | ||
38 | typedef enum { | ||
39 | MISAGENT_E_SUCCESS = 0, | ||
40 | MISAGENT_E_INVALID_ARG = -1, | ||
41 | MISAGENT_E_PLIST_ERROR = -2, | ||
42 | MISAGENT_E_CONN_FAILED = -3, | ||
43 | MISAGENT_E_REQUEST_FAILED = -4, | ||
44 | MISAGENT_E_UNKNOWN_ERROR = -256 | ||
45 | } misagent_error_t; | ||
46 | |||
47 | typedef struct misagent_client_private misagent_client_private; /**< \private */ | ||
48 | typedef misagent_client_private *misagent_client_t; /**< The client handle. */ | ||
49 | |||
50 | /* Interface */ | ||
51 | |||
52 | /** | ||
53 | * Connects to the misagent service on the specified device. | ||
54 | * | ||
55 | * @param device The device to connect to. | ||
56 | * @param service The service descriptor returned by lockdownd_start_service. | ||
57 | * @param client Pointer that will point to a newly allocated | ||
58 | * misagent_client_t upon successful return. | ||
59 | * | ||
60 | * @return MISAGENT_E_SUCCESS on success, MISAGENT_E_INVALID_ARG when | ||
61 | * client is NULL, or an MISAGENT_E_* error code otherwise. | ||
62 | */ | ||
63 | LIBIMOBILEDEVICE_API misagent_error_t misagent_client_new(idevice_t device, lockdownd_service_descriptor_t service, misagent_client_t *client); | ||
64 | |||
65 | /** | ||
66 | * Starts a new misagent service on the specified device and connects to it. | ||
67 | * | ||
68 | * @param device The device to connect to. | ||
69 | * @param client Pointer that will point to a newly allocated | ||
70 | * misagent_client_t upon successful return. Must be freed using | ||
71 | * misagent_client_free() after use. | ||
72 | * @param label The label to use for communication. Usually the program name. | ||
73 | * Pass NULL to disable sending the label in requests to lockdownd. | ||
74 | * | ||
75 | * @return MISAGENT_E_SUCCESS on success, or an MISAGENT_E_* error | ||
76 | * code otherwise. | ||
77 | */ | ||
78 | LIBIMOBILEDEVICE_API misagent_error_t misagent_client_start_service(idevice_t device, misagent_client_t* client, const char* label); | ||
79 | |||
80 | /** | ||
81 | * Disconnects an misagent client from the device and frees up the | ||
82 | * misagent client data. | ||
83 | * | ||
84 | * @param client The misagent client to disconnect and free. | ||
85 | * | ||
86 | * @return MISAGENT_E_SUCCESS on success, MISAGENT_E_INVALID_ARG when | ||
87 | * client is NULL, or an MISAGENT_E_* error code otherwise. | ||
88 | */ | ||
89 | LIBIMOBILEDEVICE_API misagent_error_t misagent_client_free(misagent_client_t client); | ||
90 | |||
91 | |||
92 | /** | ||
93 | * Installs the given provisioning profile. Only works with valid profiles. | ||
94 | * | ||
95 | * @param client The connected misagent to use for installation | ||
96 | * @param profile The valid provisioning profile to install. This has to be | ||
97 | * passed as a PLIST_DATA, otherwise the function will fail. | ||
98 | * | ||
99 | * @return MISAGENT_E_SUCCESS on success, MISAGENT_E_INVALID_ARG when | ||
100 | * client is invalid, or an MISAGENT_E_* error code otherwise. | ||
101 | */ | ||
102 | LIBIMOBILEDEVICE_API misagent_error_t misagent_install(misagent_client_t client, plist_t profile); | ||
103 | |||
104 | /** | ||
105 | * Retrieves all installed provisioning profiles (iOS 9.2.1 or below). | ||
106 | * | ||
107 | * @param client The connected misagent to use. | ||
108 | * @param profiles Pointer to a plist_t that will be set to a PLIST_ARRAY | ||
109 | * if the function is successful. | ||
110 | * | ||
111 | * @return MISAGENT_E_SUCCESS on success, MISAGENT_E_INVALID_ARG when | ||
112 | * client is invalid, or an MISAGENT_E_* error code otherwise. | ||
113 | * | ||
114 | * @note This API call only works with iOS 9.2.1 or below. | ||
115 | * For newer iOS versions use misagent_copy_all() instead. | ||
116 | * | ||
117 | * @note If no provisioning profiles are installed on the device, this function | ||
118 | * still returns MISAGENT_E_SUCCESS and profiles will just point to an | ||
119 | * empty array. | ||
120 | */ | ||
121 | LIBIMOBILEDEVICE_API misagent_error_t misagent_copy(misagent_client_t client, plist_t* profiles); | ||
122 | |||
123 | /** | ||
124 | * Retrieves all installed provisioning profiles (iOS 9.3 or higher). | ||
125 | * | ||
126 | * @param client The connected misagent to use. | ||
127 | * @param profiles Pointer to a plist_t that will be set to a PLIST_ARRAY | ||
128 | * if the function is successful. | ||
129 | * | ||
130 | * @return MISAGENT_E_SUCCESS on success, MISAGENT_E_INVALID_ARG when | ||
131 | * client is invalid, or an MISAGENT_E_* error code otherwise. | ||
132 | * | ||
133 | * @note This API call only works with iOS 9.3 or higher. | ||
134 | * For older iOS versions use misagent_copy() instead. | ||
135 | * | ||
136 | * @note If no provisioning profiles are installed on the device, this function | ||
137 | * still returns MISAGENT_E_SUCCESS and profiles will just point to an | ||
138 | * empty array. | ||
139 | */ | ||
140 | LIBIMOBILEDEVICE_API misagent_error_t misagent_copy_all(misagent_client_t client, plist_t* profiles); | ||
141 | |||
142 | /** | ||
143 | * Removes a given provisioning profile. | ||
144 | * | ||
145 | * @param client The connected misagent to use. | ||
146 | * @param profileID Identifier of the provisioning profile to remove. | ||
147 | * This is a UUID that can be obtained from the provisioning profile data. | ||
148 | * @see misagent_copy | ||
149 | * | ||
150 | * @return MISAGENT_E_SUCCESS on success, MISAGENT_E_INVALID_ARG when | ||
151 | * client is invalid, or an MISAGENT_E_* error code otherwise. | ||
152 | */ | ||
153 | LIBIMOBILEDEVICE_API misagent_error_t misagent_remove(misagent_client_t client, const char* profileID); | ||
154 | |||
155 | /** | ||
156 | * Retrieves the status code from the last operation. | ||
157 | * | ||
158 | * @param client The misagent to use. | ||
159 | * | ||
160 | * @return -1 if client is invalid, or the status code from the last operation | ||
161 | */ | ||
162 | LIBIMOBILEDEVICE_API int misagent_get_status_code(misagent_client_t client); | ||
163 | |||
164 | #ifdef __cplusplus | ||
165 | } | ||
166 | #endif | ||
167 | |||
168 | #endif | ||
diff --git a/include/libimobiledevice/mobile_image_mounter.h b/include/libimobiledevice/mobile_image_mounter.h index 04c65d5..76bb61a 100644 --- a/include/libimobiledevice/mobile_image_mounter.h +++ b/include/libimobiledevice/mobile_image_mounter.h | |||
@@ -3,7 +3,8 @@ | |||
3 | * @brief Mount developer/debug disk images on the device. | 3 | * @brief Mount developer/debug disk images on the device. |
4 | * \internal | 4 | * \internal |
5 | * | 5 | * |
6 | * Copyright (c) 2010 Nikias Bassen All Rights Reserved. | 6 | * Copyright (c) 2010-2014 Martin Szulecki All Rights Reserved. |
7 | * Copyright (c) 2010-2014 Nikias Bassen All Rights Reserved. | ||
7 | * | 8 | * |
8 | * This library is free software; you can redistribute it and/or | 9 | * This library is free software; you can redistribute it and/or |
9 | * modify it under the terms of the GNU Lesser General Public | 10 | * modify it under the terms of the GNU Lesser General Public |
@@ -20,37 +21,252 @@ | |||
20 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | 21 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA |
21 | */ | 22 | */ |
22 | 23 | ||
23 | #ifndef MOBILE_IMAGE_MOUNTER_H | 24 | #ifndef IMOBILE_IMAGE_MOUNTER_H |
24 | #define MOBILE_IMAGE_MOUNTER_H | 25 | #define IMOBILE_IMAGE_MOUNTER_H |
25 | 26 | ||
26 | #ifdef __cplusplus | 27 | #ifdef __cplusplus |
27 | extern "C" { | 28 | extern "C" { |
28 | #endif | 29 | #endif |
29 | 30 | ||
30 | #include <libimobiledevice/libimobiledevice.h> | 31 | #include <libimobiledevice/libimobiledevice.h> |
32 | #include <libimobiledevice/lockdown.h> | ||
31 | 33 | ||
32 | /** @name Error Codes */ | 34 | /** Service identifier passed to lockdownd_start_service() to start the mobile image mounter service */ |
33 | /*@{*/ | 35 | #define MOBILE_IMAGE_MOUNTER_SERVICE_NAME "com.apple.mobile.mobile_image_mounter" |
34 | #define MOBILE_IMAGE_MOUNTER_E_SUCCESS 0 | ||
35 | #define MOBILE_IMAGE_MOUNTER_E_INVALID_ARG -1 | ||
36 | #define MOBILE_IMAGE_MOUNTER_E_PLIST_ERROR -2 | ||
37 | #define MOBILE_IMAGE_MOUNTER_E_CONN_FAILED -3 | ||
38 | 36 | ||
39 | #define MOBILE_IMAGE_MOUNTER_E_UNKNOWN_ERROR -256 | 37 | /** Error Codes */ |
40 | /*@}*/ | 38 | typedef enum { |
39 | MOBILE_IMAGE_MOUNTER_E_SUCCESS = 0, | ||
40 | MOBILE_IMAGE_MOUNTER_E_INVALID_ARG = -1, | ||
41 | MOBILE_IMAGE_MOUNTER_E_PLIST_ERROR = -2, | ||
42 | MOBILE_IMAGE_MOUNTER_E_CONN_FAILED = -3, | ||
43 | MOBILE_IMAGE_MOUNTER_E_COMMAND_FAILED = -4, | ||
44 | MOBILE_IMAGE_MOUNTER_E_DEVICE_LOCKED = -5, | ||
45 | MOBILE_IMAGE_MOUNTER_E_NOT_SUPPORTED = -6, | ||
46 | MOBILE_IMAGE_MOUNTER_E_UNKNOWN_ERROR = -256 | ||
47 | } mobile_image_mounter_error_t; | ||
41 | 48 | ||
42 | /** Represents an error code. */ | 49 | typedef struct mobile_image_mounter_client_private mobile_image_mounter_client_private; /**< \private */ |
43 | typedef int16_t mobile_image_mounter_error_t; | ||
44 | |||
45 | typedef struct mobile_image_mounter_client_private mobile_image_mounter_client_private; | ||
46 | typedef mobile_image_mounter_client_private *mobile_image_mounter_client_t; /**< The client handle. */ | 50 | typedef mobile_image_mounter_client_private *mobile_image_mounter_client_t; /**< The client handle. */ |
47 | 51 | ||
52 | /** callback for image upload */ | ||
53 | typedef ssize_t (*mobile_image_mounter_upload_cb_t) (void* buffer, size_t length, void *user_data); | ||
54 | |||
48 | /* Interface */ | 55 | /* Interface */ |
49 | mobile_image_mounter_error_t mobile_image_mounter_new(idevice_t device, uint16_t port, mobile_image_mounter_client_t *client); | 56 | |
50 | mobile_image_mounter_error_t mobile_image_mounter_free(mobile_image_mounter_client_t client); | 57 | /** |
51 | mobile_image_mounter_error_t mobile_image_mounter_lookup_image(mobile_image_mounter_client_t client, const char *image_type, plist_t *result); | 58 | * Connects to the mobile_image_mounter service on the specified device. |
52 | mobile_image_mounter_error_t mobile_image_mounter_mount_image(mobile_image_mounter_client_t client, const char *image_path, const char *image_signature, uint16_t signature_length, const char *image_type, plist_t *result); | 59 | * |
53 | mobile_image_mounter_error_t mobile_image_mounter_hangup(mobile_image_mounter_client_t client); | 60 | * @param device The device to connect to. |
61 | * @param service The service descriptor returned by lockdownd_start_service. | ||
62 | * @param client Pointer that will be set to a newly allocated | ||
63 | * mobile_image_mounter_client_t upon successful return. | ||
64 | * | ||
65 | * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, | ||
66 | * MOBILE_IMAGE_MOUNTER_E_INVALID_ARG if device is NULL, | ||
67 | * or MOBILE_IMAGE_MOUNTER_E_CONN_FAILED if the connection to the | ||
68 | * device could not be established. | ||
69 | */ | ||
70 | LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_new(idevice_t device, lockdownd_service_descriptor_t service, mobile_image_mounter_client_t *client); | ||
71 | |||
72 | /** | ||
73 | * Starts a new mobile_image_mounter service on the specified device and connects to it. | ||
74 | * | ||
75 | * @param device The device to connect to. | ||
76 | * @param client Pointer that will point to a newly allocated | ||
77 | * mobile_image_mounter_t upon successful return. Must be freed using | ||
78 | * mobile_image_mounter_free() after use. | ||
79 | * @param label The label to use for communication. Usually the program name. | ||
80 | * Pass NULL to disable sending the label in requests to lockdownd. | ||
81 | * | ||
82 | * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, or an MOBILE_IMAGE_MOUNTER_E_* error | ||
83 | * code otherwise. | ||
84 | */ | ||
85 | LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_start_service(idevice_t device, mobile_image_mounter_client_t* client, const char* label); | ||
86 | |||
87 | /** | ||
88 | * Disconnects a mobile_image_mounter client from the device and frees up the | ||
89 | * mobile_image_mounter client data. | ||
90 | * | ||
91 | * @param client The mobile_image_mounter client to disconnect and free. | ||
92 | * | ||
93 | * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, | ||
94 | * or MOBILE_IMAGE_MOUNTER_E_INVALID_ARG if client is NULL. | ||
95 | */ | ||
96 | LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_free(mobile_image_mounter_client_t client); | ||
97 | |||
98 | |||
99 | /** | ||
100 | * Tells if the image of ImageType is already mounted. | ||
101 | * | ||
102 | * @param client The client use | ||
103 | * @param image_type The type of the image to look up | ||
104 | * @param result Pointer to a plist that will receive the result of the | ||
105 | * operation. | ||
106 | * | ||
107 | * @note This function may return MOBILE_IMAGE_MOUNTER_E_SUCCESS even if the | ||
108 | * operation has failed. Check the resulting plist for further information. | ||
109 | * | ||
110 | * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, or an error code on error | ||
111 | */ | ||
112 | LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_lookup_image(mobile_image_mounter_client_t client, const char *image_type, plist_t *result); | ||
113 | |||
114 | /** | ||
115 | * Uploads an image with an optional signature to the device. | ||
116 | * | ||
117 | * @param client The connected mobile_image_mounter client. | ||
118 | * @param image_type Type of image that is being uploaded. | ||
119 | * @param image_size Total size of the image. | ||
120 | * @param signature Buffer with a signature of the image being uploaded. If | ||
121 | * NULL, no signature will be used. | ||
122 | * @param signature_size Total size of the image signature buffer. If 0, no | ||
123 | * signature will be used. | ||
124 | * @param upload_cb Callback function that gets the data chunks for uploading | ||
125 | * the image. | ||
126 | * @param userdata User defined data for the upload callback function. | ||
127 | * | ||
128 | * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on succes, or a | ||
129 | * MOBILE_IMAGE_MOUNTER_E_* error code otherwise. | ||
130 | */ | ||
131 | LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_upload_image(mobile_image_mounter_client_t client, const char *image_type, size_t image_size, const unsigned char *signature, unsigned int signature_size, mobile_image_mounter_upload_cb_t upload_cb, void* userdata); | ||
132 | |||
133 | /** | ||
134 | * Mounts an image on the device. | ||
135 | * | ||
136 | * @param client The connected mobile_image_mounter client. | ||
137 | * @param image_path The absolute path of the image to mount. The image must | ||
138 | * be present before calling this function. | ||
139 | * @param signature Pointer to a buffer holding the images' signature | ||
140 | * @param signature_size Length of the signature image_signature points to | ||
141 | * @param image_type Type of image to mount | ||
142 | * @param options A dictionary containing additional key/value pairs to add | ||
143 | * @param result Pointer to a plist that will receive the result of the | ||
144 | * operation. | ||
145 | * | ||
146 | * @note This function may return MOBILE_IMAGE_MOUNTER_E_SUCCESS even if the | ||
147 | * operation has failed. Check the resulting plist for further information. | ||
148 | * | ||
149 | * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, | ||
150 | * MOBILE_IMAGE_MOUNTER_E_INVALID_ARG if on ore more parameters are | ||
151 | * invalid, or another error code otherwise. | ||
152 | */ | ||
153 | LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_mount_image_with_options(mobile_image_mounter_client_t client, const char *image_path, const unsigned char *signature, unsigned int signature_size, const char *image_type, plist_t options, plist_t *result); | ||
154 | |||
155 | /** | ||
156 | * Mounts an image on the device. | ||
157 | * | ||
158 | * @param client The connected mobile_image_mounter client. | ||
159 | * @param image_path The absolute path of the image to mount. The image must | ||
160 | * be present before calling this function. | ||
161 | * @param signature Pointer to a buffer holding the images' signature | ||
162 | * @param signature_size Length of the signature image_signature points to | ||
163 | * @param image_type Type of image to mount | ||
164 | * @param result Pointer to a plist that will receive the result of the | ||
165 | * operation. | ||
166 | * | ||
167 | * @note This function may return MOBILE_IMAGE_MOUNTER_E_SUCCESS even if the | ||
168 | * operation has failed. Check the resulting plist for further information. | ||
169 | * | ||
170 | * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, | ||
171 | * MOBILE_IMAGE_MOUNTER_E_INVALID_ARG if on ore more parameters are | ||
172 | * invalid, or another error code otherwise. | ||
173 | */ | ||
174 | LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_mount_image(mobile_image_mounter_client_t client, const char *image_path, const unsigned char *signature, unsigned int signature_size, const char *image_type, plist_t *result); | ||
175 | |||
176 | /** | ||
177 | * Unmount a mounted image at given path on the device. | ||
178 | * | ||
179 | * @param client The connected mobile_image_mounter client. | ||
180 | * @param mount_path The mount path of the mounted image on the device. | ||
181 | * | ||
182 | * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, | ||
183 | * or a MOBILE_IMAGE_MOUNTER_E_* error code on error. | ||
184 | */ | ||
185 | LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_unmount_image(mobile_image_mounter_client_t client, const char *mount_path); | ||
186 | |||
187 | /** | ||
188 | * Hangs up the connection to the mobile_image_mounter service. | ||
189 | * This functions has to be called before freeing up a mobile_image_mounter | ||
190 | * instance. If not, errors appear in the device's syslog. | ||
191 | * | ||
192 | * @param client The client to hang up | ||
193 | * | ||
194 | * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, | ||
195 | * MOBILE_IMAGE_MOUNTER_E_INVALID_ARG if client is invalid, | ||
196 | * or another error code otherwise. | ||
197 | */ | ||
198 | LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_hangup(mobile_image_mounter_client_t client); | ||
199 | |||
200 | /** | ||
201 | * Query the developer mode status of the given device. | ||
202 | * | ||
203 | * @param client The connected mobile_image_mounter client. | ||
204 | * @param result A pointer to a plist_t that will be set to the resulting developer mode status dictionary. | ||
205 | * | ||
206 | * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, | ||
207 | * or a MOBILE_IMAGE_MOUNTER_E_* error code on error. | ||
208 | */ | ||
209 | LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_query_developer_mode_status(mobile_image_mounter_client_t client, plist_t *result); | ||
210 | |||
211 | /** | ||
212 | * Query a personalization nonce for the given image type, used for personalized disk images (iOS 17+). | ||
213 | * This nonce is supposed to be added to the TSS request for the corresponding image. | ||
214 | * | ||
215 | * @param client The connected mobile_image_mounter client. | ||
216 | * @param image_type The image_type to get the personalization nonce for, usually `DeveloperDiskImage`. | ||
217 | * @param nonce Pointer that will be set to an allocated buffer with the nonce value. | ||
218 | * @param nonce_size Pointer to an unsigned int that will receive the size of the nonce value. | ||
219 | * | ||
220 | * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, | ||
221 | * or a MOBILE_IMAGE_MOUNTER_E_* error code on error. | ||
222 | */ | ||
223 | LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_query_nonce(mobile_image_mounter_client_t client, const char* image_type, unsigned char** nonce, unsigned int* nonce_size); | ||
224 | |||
225 | /** | ||
226 | * Query personalization identitifers for the given image_type. | ||
227 | * | ||
228 | * @param client The connected mobile_image_mounter client. | ||
229 | * @param image_type The image_type to get the personalization identifiers for. Can be NULL. | ||
230 | * @param result A pointer to a plist_t that will be set to the resulting identifier dictionary. | ||
231 | * | ||
232 | * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, | ||
233 | * or a MOBILE_IMAGE_MOUNTER_E_* error code on error. | ||
234 | */ | ||
235 | LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_query_personalization_identifiers(mobile_image_mounter_client_t client, const char* image_type, plist_t *result); | ||
236 | |||
237 | /** | ||
238 | * | ||
239 | * @param client The connected mobile_image_mounter client. | ||
240 | * @param image_type The image_type to get the personalization identifiers for. Can be NULL. | ||
241 | * @param signature The signature of the corresponding personalized image. | ||
242 | * @param signature_size The size of signature. | ||
243 | * @param manifest Pointer that will be set to an allocated buffer with the manifest data. | ||
244 | * @param manifest_size Pointer to an unsigned int that will be set to the size of the manifest data. | ||
245 | * | ||
246 | * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, | ||
247 | * or a MOBILE_IMAGE_MOUNTER_E_* error code on error. | ||
248 | */ | ||
249 | LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_query_personalization_manifest(mobile_image_mounter_client_t client, const char* image_type, const unsigned char* signature, unsigned int signature_size, unsigned char** manifest, unsigned int* manifest_size); | ||
250 | |||
251 | /** | ||
252 | * Roll the personalization nonce. | ||
253 | * | ||
254 | * @param client The connected mobile_image_mounter client. | ||
255 | * | ||
256 | * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, | ||
257 | * or a MOBILE_IMAGE_MOUNTER_E_* error code on error. | ||
258 | */ | ||
259 | LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_roll_personalization_nonce(mobile_image_mounter_client_t client); | ||
260 | |||
261 | /** | ||
262 | * Roll the Cryptex nonce. | ||
263 | * | ||
264 | * @param client The connected mobile_image_mounter client. | ||
265 | * | ||
266 | * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, | ||
267 | * or a MOBILE_IMAGE_MOUNTER_E_* error code on error. | ||
268 | */ | ||
269 | LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_roll_cryptex_nonce(mobile_image_mounter_client_t client); | ||
54 | 270 | ||
55 | #ifdef __cplusplus | 271 | #ifdef __cplusplus |
56 | } | 272 | } |
diff --git a/include/libimobiledevice/mobileactivation.h b/include/libimobiledevice/mobileactivation.h new file mode 100644 index 0000000..8e036a8 --- /dev/null +++ b/include/libimobiledevice/mobileactivation.h | |||
@@ -0,0 +1,192 @@ | |||
1 | /** | ||
2 | * @file libimobiledevice/mobileactivation.h | ||
3 | * @brief Handle device activation and deactivation. | ||
4 | * \internal | ||
5 | * | ||
6 | * Copyright (c) 2016-2017 Nikias Bassen, All Rights Reserved. | ||
7 | * | ||
8 | * This library is free software; you can redistribute it and/or | ||
9 | * modify it under the terms of the GNU Lesser General Public | ||
10 | * License as published by the Free Software Foundation; either | ||
11 | * version 2.1 of the License, or (at your option) any later version. | ||
12 | * | ||
13 | * This library is distributed in the hope that it will be useful, | ||
14 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
15 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
16 | * Lesser General Public License for more details. | ||
17 | * | ||
18 | * You should have received a copy of the GNU Lesser General Public | ||
19 | * License along with this library; if not, write to the Free Software | ||
20 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | ||
21 | */ | ||
22 | |||
23 | #ifndef IMOBILEACTIVATION_H | ||
24 | #define IMOBILEACTIVATION_H | ||
25 | |||
26 | #ifdef __cplusplus | ||
27 | extern "C" { | ||
28 | #endif | ||
29 | |||
30 | #include <libimobiledevice/libimobiledevice.h> | ||
31 | #include <libimobiledevice/lockdown.h> | ||
32 | |||
33 | /** Service identifier passed to lockdownd_start_service() to start the mobile activation service */ | ||
34 | #define MOBILEACTIVATION_SERVICE_NAME "com.apple.mobileactivationd" | ||
35 | |||
36 | /** Error Codes */ | ||
37 | typedef enum { | ||
38 | MOBILEACTIVATION_E_SUCCESS = 0, | ||
39 | MOBILEACTIVATION_E_INVALID_ARG = -1, | ||
40 | MOBILEACTIVATION_E_PLIST_ERROR = -2, | ||
41 | MOBILEACTIVATION_E_MUX_ERROR = -3, | ||
42 | MOBILEACTIVATION_E_UNKNOWN_REQUEST = -4, | ||
43 | MOBILEACTIVATION_E_REQUEST_FAILED = -5, | ||
44 | MOBILEACTIVATION_E_UNKNOWN_ERROR = -256 | ||
45 | } mobileactivation_error_t; | ||
46 | |||
47 | typedef struct mobileactivation_client_private mobileactivation_client_private; /**< \private */ | ||
48 | typedef mobileactivation_client_private *mobileactivation_client_t; /**< The client handle. */ | ||
49 | |||
50 | /** | ||
51 | * Connects to the mobileactivation service on the specified device. | ||
52 | * | ||
53 | * @param device The device to connect to. | ||
54 | * @param service The service descriptor returned by lockdownd_start_service. | ||
55 | * @param client Reference that will point to a newly allocated | ||
56 | * mobileactivation_client_t upon successful return. | ||
57 | * | ||
58 | * @return MOBILEACTIVATION_E_SUCCESS on success, | ||
59 | * MOBILEACTIVATION_E_INVALID_ARG when one of the parameters is invalid, | ||
60 | * or MOBILEACTIVATION_E_MUX_ERROR when the connection failed. | ||
61 | */ | ||
62 | LIBIMOBILEDEVICE_API mobileactivation_error_t mobileactivation_client_new(idevice_t device, lockdownd_service_descriptor_t service, mobileactivation_client_t *client); | ||
63 | |||
64 | /** | ||
65 | * Starts a new mobileactivation service on the specified device and connects to it. | ||
66 | * | ||
67 | * @param device The device to connect to. | ||
68 | * @param client Pointer that will point to a newly allocated | ||
69 | * mobileactivation_client_t upon successful return. Must be freed using | ||
70 | * mobileactivation_client_free() after use. | ||
71 | * @param label The label to use for communication. Usually the program name. | ||
72 | * Pass NULL to disable sending the label in requests to lockdownd. | ||
73 | * | ||
74 | * @return MOBILEACTIVATION_E_SUCCESS on success, or an MOBILEACTIVATION_E_* | ||
75 | * error code otherwise. | ||
76 | */ | ||
77 | LIBIMOBILEDEVICE_API mobileactivation_error_t mobileactivation_client_start_service(idevice_t device, mobileactivation_client_t* client, const char* label); | ||
78 | |||
79 | /** | ||
80 | * Disconnects a mobileactivation client from the device and frees up the | ||
81 | * mobileactivation client data. | ||
82 | * | ||
83 | * @param client The mobileactivation client to disconnect and free. | ||
84 | * | ||
85 | * @return MOBILEACTIVATION_E_SUCCESS on success, | ||
86 | * MOBILEACTIVATION_E_INVALID_ARG when one of client or client->parent | ||
87 | * is invalid, or MOBILEACTIVATION_E_UNKNOWN_ERROR when the was an | ||
88 | * error freeing the parent property_list_service client. | ||
89 | */ | ||
90 | LIBIMOBILEDEVICE_API mobileactivation_error_t mobileactivation_client_free(mobileactivation_client_t client); | ||
91 | |||
92 | |||
93 | /** | ||
94 | * Retrieves the device's activation state. | ||
95 | * | ||
96 | * @param client The mobileactivation client. | ||
97 | * @param state Pointer to a plist_t variable that will be set to the | ||
98 | * activation state reported by the mobileactivation service. The | ||
99 | * consumer is responsible for freeing the returned object using | ||
100 | * plist_free(). | ||
101 | * | ||
102 | * @return MOBILEACTIVATION_E_SUCCESS on success, or an MOBILEACTIVATION_E_* | ||
103 | * error code otherwise. | ||
104 | */ | ||
105 | LIBIMOBILEDEVICE_API mobileactivation_error_t mobileactivation_get_activation_state(mobileactivation_client_t client, plist_t *state); | ||
106 | |||
107 | /** | ||
108 | * Retrieves a session blob required for 'drmHandshake' via albert.apple.com. | ||
109 | * | ||
110 | * @param client The mobileactivation client | ||
111 | * @param blob Pointer to a plist_t variable that will be set to the | ||
112 | * session blob created by the mobielactivation service. The | ||
113 | * consumer is responsible for freeing the returned object using | ||
114 | * plist_free(). | ||
115 | * | ||
116 | * @return MOBILEACTIVATION_E_SUCCESS on success, or an MOBILEACTIVATION_E_* | ||
117 | * error code otherwise. | ||
118 | */ | ||
119 | LIBIMOBILEDEVICE_API mobileactivation_error_t mobileactivation_create_activation_session_info(mobileactivation_client_t client, plist_t *blob); | ||
120 | |||
121 | /** | ||
122 | * Retrieves the activation info required for device activation. | ||
123 | * | ||
124 | * @param client The mobileactivation client | ||
125 | * @param info Pointer to a plist_t variable that will be set to the | ||
126 | * activation info created by the mobileactivation service. The | ||
127 | * consumer is responsible for freeing the returned object using | ||
128 | * plist_free(). | ||
129 | * | ||
130 | * @return MOBILEACTIVATION_E_SUCCESS on success, or an MOBILEACTIVATION_E_* | ||
131 | * error code otherwise. | ||
132 | */ | ||
133 | LIBIMOBILEDEVICE_API mobileactivation_error_t mobileactivation_create_activation_info(mobileactivation_client_t client, plist_t *info); | ||
134 | |||
135 | /** | ||
136 | * Retrieves the activation info required for device activation in 'session' | ||
137 | * mode. This function expects a handshake result retrieved from | ||
138 | * https://albert.apple.com/deviceservies/drmHandshake with a blob | ||
139 | * provided by mobileactivation_create_activation_session_info(). | ||
140 | * | ||
141 | * @param client The mobileactivation client | ||
142 | * @param handshake_response The handshake response returned from drmHandshake | ||
143 | * @param info Pointer to a plist_t variable that will be set to the | ||
144 | * activation info created by the mobileactivation service. The | ||
145 | * consumer is responsible for freeing the returned object using | ||
146 | * plist_free(). | ||
147 | * | ||
148 | * @return MOBILEACTIVATION_E_SUCCESS on success, or an MOBILEACTIVATION_E_* | ||
149 | * error code otherwise. | ||
150 | */ | ||
151 | LIBIMOBILEDEVICE_API mobileactivation_error_t mobileactivation_create_activation_info_with_session(mobileactivation_client_t client, plist_t handshake_response, plist_t *info); | ||
152 | |||
153 | /** | ||
154 | * Activates the device with the given activation record. | ||
155 | * The activation record plist dictionary must be obtained using the | ||
156 | * activation protocol requesting from Apple's https webservice. | ||
157 | * | ||
158 | * @param client The mobileactivation client | ||
159 | * @param activation_record The activation record plist dictionary | ||
160 | * | ||
161 | * @return MOBILEACTIVATION_E_SUCCESS on success, or an MOBILEACTIVATION_E_* | ||
162 | * error code otherwise. | ||
163 | */ | ||
164 | LIBIMOBILEDEVICE_API mobileactivation_error_t mobileactivation_activate(mobileactivation_client_t client, plist_t activation_record); | ||
165 | |||
166 | /** | ||
167 | * Activates the device with the given activation record in 'session' mode. | ||
168 | * The activation record plist must be obtained using the | ||
169 | * activation protocol requesting from Apple's https webservice. | ||
170 | * | ||
171 | * @param client The mobileactivation client | ||
172 | * @param activation_record The activation record in plist format | ||
173 | * @param headers A plist dictionary with the activation response headers | ||
174 | * as returned from Apple's https webservice with the activation record | ||
175 | * | ||
176 | * @return MOBILEACTIVATION_E_SUCCESS on success, or an MOBILEACTIVATION_E_* | ||
177 | * error code otherwise. | ||
178 | */ | ||
179 | LIBIMOBILEDEVICE_API mobileactivation_error_t mobileactivation_activate_with_session(mobileactivation_client_t client, plist_t activation_record, plist_t headers); | ||
180 | |||
181 | /** | ||
182 | * Deactivates the device. | ||
183 | * | ||
184 | * @param client The mobileactivation client | ||
185 | */ | ||
186 | LIBIMOBILEDEVICE_API mobileactivation_error_t mobileactivation_deactivate(mobileactivation_client_t client); | ||
187 | |||
188 | #ifdef __cplusplus | ||
189 | } | ||
190 | #endif | ||
191 | |||
192 | #endif | ||
diff --git a/include/libimobiledevice/mobilebackup.h b/include/libimobiledevice/mobilebackup.h index 8f31cc4..2ecb60c 100644 --- a/include/libimobiledevice/mobilebackup.h +++ b/include/libimobiledevice/mobilebackup.h | |||
@@ -3,7 +3,8 @@ | |||
3 | * @brief Backup and restore of all device data. | 3 | * @brief Backup and restore of all device data. |
4 | * \internal | 4 | * \internal |
5 | * | 5 | * |
6 | * Copyright (c) 2009 Martin Szulecki All Rights Reserved. | 6 | * Copyright (c) 2010-2019 Nikias Bassen, All Rights Reserved. |
7 | * Copyright (c) 2009-2014 Martin Szulecki, All Rights Reserved. | ||
7 | * | 8 | * |
8 | * This library is free software; you can redistribute it and/or | 9 | * This library is free software; you can redistribute it and/or |
9 | * modify it under the terms of the GNU Lesser General Public | 10 | * modify it under the terms of the GNU Lesser General Public |
@@ -28,42 +29,215 @@ extern "C" { | |||
28 | #endif | 29 | #endif |
29 | 30 | ||
30 | #include <libimobiledevice/libimobiledevice.h> | 31 | #include <libimobiledevice/libimobiledevice.h> |
32 | #include <libimobiledevice/lockdown.h> | ||
31 | 33 | ||
32 | /** @name Error Codes */ | 34 | /** Service identifier passed to lockdownd_start_service() to start the mobilebackup service */ |
33 | /*@{*/ | 35 | #define MOBILEBACKUP_SERVICE_NAME "com.apple.mobilebackup" |
34 | #define MOBILEBACKUP_E_SUCCESS 0 | ||
35 | #define MOBILEBACKUP_E_INVALID_ARG -1 | ||
36 | #define MOBILEBACKUP_E_PLIST_ERROR -2 | ||
37 | #define MOBILEBACKUP_E_MUX_ERROR -3 | ||
38 | #define MOBILEBACKUP_E_BAD_VERSION -4 | ||
39 | #define MOBILEBACKUP_E_REPLY_NOT_OK -5 | ||
40 | 36 | ||
41 | #define MOBILEBACKUP_E_UNKNOWN_ERROR -256 | 37 | /** Error Codes */ |
42 | /*@}*/ | 38 | typedef enum { |
43 | 39 | MOBILEBACKUP_E_SUCCESS = 0, | |
44 | /** Represents an error code. */ | 40 | MOBILEBACKUP_E_INVALID_ARG = -1, |
45 | typedef int16_t mobilebackup_error_t; | 41 | MOBILEBACKUP_E_PLIST_ERROR = -2, |
42 | MOBILEBACKUP_E_MUX_ERROR = -3, | ||
43 | MOBILEBACKUP_E_SSL_ERROR = -4, | ||
44 | MOBILEBACKUP_E_RECEIVE_TIMEOUT = -5, | ||
45 | MOBILEBACKUP_E_BAD_VERSION = -6, | ||
46 | MOBILEBACKUP_E_REPLY_NOT_OK = -7, | ||
47 | MOBILEBACKUP_E_UNKNOWN_ERROR = -256 | ||
48 | } mobilebackup_error_t; | ||
46 | 49 | ||
47 | typedef struct mobilebackup_client_private mobilebackup_client_private; | 50 | typedef struct mobilebackup_client_private mobilebackup_client_private; /**< \private */ |
48 | typedef mobilebackup_client_private *mobilebackup_client_t; /**< The client handle. */ | 51 | typedef mobilebackup_client_private *mobilebackup_client_t; /**< The client handle. */ |
49 | 52 | ||
53 | /** Available flags passed to #mobilebackup_request_restore */ | ||
50 | typedef enum { | 54 | typedef enum { |
51 | MB_RESTORE_NOTIFY_SPRINGBOARD = 1 << 0, | 55 | MB_RESTORE_NOTIFY_SPRINGBOARD = 1 << 0, |
52 | MB_RESTORE_PRESERVE_SETTINGS = 1 << 1, | 56 | MB_RESTORE_PRESERVE_SETTINGS = 1 << 1, |
53 | MB_RESTORE_PRESERVE_CAMERA_ROLL = 1 << 2 | 57 | MB_RESTORE_PRESERVE_CAMERA_ROLL = 1 << 2 |
54 | } mobilebackup_flags_t; | 58 | } mobilebackup_flags_t; |
55 | 59 | ||
56 | mobilebackup_error_t mobilebackup_client_new(idevice_t device, uint16_t port, mobilebackup_client_t * client); | 60 | /** |
57 | mobilebackup_error_t mobilebackup_client_free(mobilebackup_client_t client); | 61 | * Connects to the mobilebackup service on the specified device. |
58 | mobilebackup_error_t mobilebackup_receive(mobilebackup_client_t client, plist_t *plist); | 62 | * |
59 | mobilebackup_error_t mobilebackup_send(mobilebackup_client_t client, plist_t plist); | 63 | * @param device The device to connect to. |
60 | mobilebackup_error_t mobilebackup_request_backup(mobilebackup_client_t client, plist_t backup_manifest, const char *base_path, const char *proto_version); | 64 | * @param service The service descriptor returned by lockdownd_start_service. |
61 | mobilebackup_error_t mobilebackup_send_backup_file_received(mobilebackup_client_t client); | 65 | * @param client Pointer that will be set to a newly allocated |
62 | mobilebackup_error_t mobilebackup_request_restore(mobilebackup_client_t client, plist_t backup_manifest, mobilebackup_flags_t flags, const char *proto_version); | 66 | * mobilebackup_client_t upon successful return. |
63 | mobilebackup_error_t mobilebackup_receive_restore_file_received(mobilebackup_client_t client, plist_t *result); | 67 | * |
64 | mobilebackup_error_t mobilebackup_receive_restore_application_received(mobilebackup_client_t client, plist_t *result); | 68 | * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID ARG if one |
65 | mobilebackup_error_t mobilebackup_send_restore_complete(mobilebackup_client_t client); | 69 | * or more parameters are invalid, or DEVICE_LINK_SERVICE_E_BAD_VERSION if |
66 | mobilebackup_error_t mobilebackup_send_error(mobilebackup_client_t client, const char *reason); | 70 | * the mobilebackup version on the device is newer. |
71 | */ | ||
72 | LIBIMOBILEDEVICE_API mobilebackup_error_t mobilebackup_client_new(idevice_t device, lockdownd_service_descriptor_t service, mobilebackup_client_t * client); | ||
73 | |||
74 | /** | ||
75 | * Starts a new mobilebackup service on the specified device and connects to it. | ||
76 | * | ||
77 | * @param device The device to connect to. | ||
78 | * @param client Pointer that will point to a newly allocated | ||
79 | * mobilebackup_client_t upon successful return. Must be freed using | ||
80 | * mobilebackup_client_free() after use. | ||
81 | * @param label The label to use for communication. Usually the program name. | ||
82 | * Pass NULL to disable sending the label in requests to lockdownd. | ||
83 | * | ||
84 | * @return MOBILEBACKUP_E_SUCCESS on success, or an MOBILEBACKUP_E_* error | ||
85 | * code otherwise. | ||
86 | */ | ||
87 | LIBIMOBILEDEVICE_API mobilebackup_error_t mobilebackup_client_start_service(idevice_t device, mobilebackup_client_t* client, const char* label); | ||
88 | |||
89 | /** | ||
90 | * Disconnects a mobilebackup client from the device and frees up the | ||
91 | * mobilebackup client data. | ||
92 | * | ||
93 | * @param client The mobilebackup client to disconnect and free. | ||
94 | * | ||
95 | * @return MOBILEBACKUP_E_SUCCESS on success, or MOBILEBACKUP_E_INVALID_ARG | ||
96 | * if client is NULL. | ||
97 | */ | ||
98 | LIBIMOBILEDEVICE_API mobilebackup_error_t mobilebackup_client_free(mobilebackup_client_t client); | ||
99 | |||
100 | |||
101 | /** | ||
102 | * Polls the device for mobilebackup data. | ||
103 | * | ||
104 | * @param client The mobilebackup client | ||
105 | * @param plist A pointer to the location where the plist should be stored | ||
106 | * | ||
107 | * @return an error code | ||
108 | */ | ||
109 | LIBIMOBILEDEVICE_API mobilebackup_error_t mobilebackup_receive(mobilebackup_client_t client, plist_t *plist); | ||
110 | |||
111 | /** | ||
112 | * Sends mobilebackup data to the device | ||
113 | * | ||
114 | * @note This function is low-level and should only be used if you need to send | ||
115 | * a new type of message. | ||
116 | * | ||
117 | * @param client The mobilebackup client | ||
118 | * @param plist The location of the plist to send | ||
119 | * | ||
120 | * @return an error code | ||
121 | */ | ||
122 | LIBIMOBILEDEVICE_API mobilebackup_error_t mobilebackup_send(mobilebackup_client_t client, plist_t plist); | ||
123 | |||
124 | /** | ||
125 | * Request a backup from the connected device. | ||
126 | * | ||
127 | * @param client The connected MobileBackup client to use. | ||
128 | * @param backup_manifest The backup manifest, a plist_t of type PLIST_DICT | ||
129 | * containing the backup state of the last backup. For a first-time backup | ||
130 | * set this parameter to NULL. | ||
131 | * @param base_path The base path on the device to use for the backup | ||
132 | * operation, usually "/". | ||
133 | * @param proto_version A string denoting the version of the backup protocol | ||
134 | * to use. Latest known version is "1.6" | ||
135 | * | ||
136 | * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID_ARG if | ||
137 | * one of the parameters is invalid, MOBILEBACKUP_E_PLIST_ERROR if | ||
138 | * backup_manifest is not of type PLIST_DICT, MOBILEBACKUP_E_MUX_ERROR | ||
139 | * if a communication error occurs, MOBILEBACKUP_E_REPLY_NOT_OK | ||
140 | */ | ||
141 | LIBIMOBILEDEVICE_API mobilebackup_error_t mobilebackup_request_backup(mobilebackup_client_t client, plist_t backup_manifest, const char *base_path, const char *proto_version); | ||
142 | |||
143 | /** | ||
144 | * Sends a confirmation to the device that a backup file has been received. | ||
145 | * | ||
146 | * @param client The connected MobileBackup client to use. | ||
147 | * | ||
148 | * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID_ARG if | ||
149 | * client is invalid, or MOBILEBACKUP_E_MUX_ERROR if a communication error | ||
150 | * occurs. | ||
151 | */ | ||
152 | LIBIMOBILEDEVICE_API mobilebackup_error_t mobilebackup_send_backup_file_received(mobilebackup_client_t client); | ||
153 | |||
154 | /** | ||
155 | * Request that a backup should be restored to the connected device. | ||
156 | * | ||
157 | * @param client The connected MobileBackup client to use. | ||
158 | * @param backup_manifest The backup manifest, a plist_t of type PLIST_DICT | ||
159 | * containing the backup state to be restored. | ||
160 | * @param flags Flags to send with the request. Currently this is a combination | ||
161 | * of the following mobilebackup_flags_t: | ||
162 | * MB_RESTORE_NOTIFY_SPRINGBOARD - let SpringBoard show a 'Restore' screen | ||
163 | * MB_RESTORE_PRESERVE_SETTINGS - do not overwrite any settings | ||
164 | * MB_RESTORE_PRESERVE_CAMERA_ROLL - preserve the photos of the camera roll | ||
165 | * @param proto_version A string denoting the version of the backup protocol | ||
166 | * to use. Latest known version is "1.6". Ideally this value should be | ||
167 | * extracted from the given manifest plist. | ||
168 | * | ||
169 | * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID_ARG if | ||
170 | * one of the parameters is invalid, MOBILEBACKUP_E_PLIST_ERROR if | ||
171 | * backup_manifest is not of type PLIST_DICT, MOBILEBACKUP_E_MUX_ERROR | ||
172 | * if a communication error occurs, or MOBILEBACKUP_E_REPLY_NOT_OK | ||
173 | * if the device did not accept the request. | ||
174 | */ | ||
175 | LIBIMOBILEDEVICE_API mobilebackup_error_t mobilebackup_request_restore(mobilebackup_client_t client, plist_t backup_manifest, mobilebackup_flags_t flags, const char *proto_version); | ||
176 | |||
177 | /** | ||
178 | * Receive a confirmation from the device that it successfully received | ||
179 | * a restore file. | ||
180 | * | ||
181 | * @param client The connected MobileBackup client to use. | ||
182 | * @param result Pointer to a plist_t that will be set to the received plist | ||
183 | * for further processing. The caller has to free it using plist_free(). | ||
184 | * Note that it will be set to NULL if the operation itself fails due to | ||
185 | * a communication or plist error. | ||
186 | * If this parameter is NULL, it will be ignored. | ||
187 | * | ||
188 | * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID_ARG if | ||
189 | * client is invalid, MOBILEBACKUP_E_REPLY_NOT_OK if the expected | ||
190 | * 'BackupMessageRestoreFileReceived' message could not be received, | ||
191 | * MOBILEBACKUP_E_PLIST_ERROR if the received message is not a valid backup | ||
192 | * message plist, or MOBILEBACKUP_E_MUX_ERROR if a communication error | ||
193 | * occurs. | ||
194 | */ | ||
195 | LIBIMOBILEDEVICE_API mobilebackup_error_t mobilebackup_receive_restore_file_received(mobilebackup_client_t client, plist_t *result); | ||
196 | |||
197 | /** | ||
198 | * Receive a confirmation from the device that it successfully received | ||
199 | * application data file. | ||
200 | * | ||
201 | * @param client The connected MobileBackup client to use. | ||
202 | * @param result Pointer to a plist_t that will be set to the received plist | ||
203 | * for further processing. The caller has to free it using plist_free(). | ||
204 | * Note that it will be set to NULL if the operation itself fails due to | ||
205 | * a communication or plist error. | ||
206 | * If this parameter is NULL, it will be ignored. | ||
207 | * | ||
208 | * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID_ARG if | ||
209 | * client is invalid, MOBILEBACKUP_E_REPLY_NOT_OK if the expected | ||
210 | * 'BackupMessageRestoreApplicationReceived' message could not be received, | ||
211 | * MOBILEBACKUP_E_PLIST_ERROR if the received message is not a valid backup | ||
212 | * message plist, or MOBILEBACKUP_E_MUX_ERROR if a communication error | ||
213 | * occurs. | ||
214 | */ | ||
215 | LIBIMOBILEDEVICE_API mobilebackup_error_t mobilebackup_receive_restore_application_received(mobilebackup_client_t client, plist_t *result); | ||
216 | |||
217 | /** | ||
218 | * Tells the device that the restore process is complete and waits for the | ||
219 | * device to close the connection. After that, the device should reboot. | ||
220 | * | ||
221 | * @param client The connected MobileBackup client to use. | ||
222 | * | ||
223 | * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID_ARG if | ||
224 | * client is invalid, MOBILEBACKUP_E_PLIST_ERROR if the received disconnect | ||
225 | * message plist is invalid, or MOBILEBACKUP_E_MUX_ERROR if a communication | ||
226 | * error occurs. | ||
227 | */ | ||
228 | LIBIMOBILEDEVICE_API mobilebackup_error_t mobilebackup_send_restore_complete(mobilebackup_client_t client); | ||
229 | |||
230 | /** | ||
231 | * Sends a backup error message to the device. | ||
232 | * | ||
233 | * @param client The connected MobileBackup client to use. | ||
234 | * @param reason A string describing the reason for the error message. | ||
235 | * | ||
236 | * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID_ARG if | ||
237 | * one of the parameters is invalid, or MOBILEBACKUP_E_MUX_ERROR if a | ||
238 | * communication error occurs. | ||
239 | */ | ||
240 | LIBIMOBILEDEVICE_API mobilebackup_error_t mobilebackup_send_error(mobilebackup_client_t client, const char *reason); | ||
67 | 241 | ||
68 | #ifdef __cplusplus | 242 | #ifdef __cplusplus |
69 | } | 243 | } |
diff --git a/include/libimobiledevice/mobilebackup2.h b/include/libimobiledevice/mobilebackup2.h new file mode 100644 index 0000000..2e9222d --- /dev/null +++ b/include/libimobiledevice/mobilebackup2.h | |||
@@ -0,0 +1,214 @@ | |||
1 | /** | ||
2 | * @file libimobiledevice/mobilebackup2.h | ||
3 | * @brief Backup and restore of all device data (mobilebackup2, iOS4+ only) | ||
4 | * \internal | ||
5 | * | ||
6 | * Copyright (c) 2010-2019 Nikias Bassen, All Rights Reserved. | ||
7 | * Copyright (c) 2011-2014 Martin Szulecki, All Rights Reserved. | ||
8 | * | ||
9 | * This library is free software; you can redistribute it and/or | ||
10 | * modify it under the terms of the GNU Lesser General Public | ||
11 | * License as published by the Free Software Foundation; either | ||
12 | * version 2.1 of the License, or (at your option) any later version. | ||
13 | * | ||
14 | * This library is distributed in the hope that it will be useful, | ||
15 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
16 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
17 | * Lesser General Public License for more details. | ||
18 | * | ||
19 | * You should have received a copy of the GNU Lesser General Public | ||
20 | * License along with this library; if not, write to the Free Software | ||
21 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | ||
22 | */ | ||
23 | |||
24 | #ifndef IMOBILEBACKUP2_H | ||
25 | #define IMOBILEBACKUP2_H | ||
26 | |||
27 | #ifdef __cplusplus | ||
28 | extern "C" { | ||
29 | #endif | ||
30 | |||
31 | #include <libimobiledevice/libimobiledevice.h> | ||
32 | #include <libimobiledevice/lockdown.h> | ||
33 | |||
34 | /** Service identifier passed to lockdownd_start_service() to start the mobilebackup2 service */ | ||
35 | #define MOBILEBACKUP2_SERVICE_NAME "com.apple.mobilebackup2" | ||
36 | |||
37 | /** Error Codes */ | ||
38 | typedef enum { | ||
39 | MOBILEBACKUP2_E_SUCCESS = 0, | ||
40 | MOBILEBACKUP2_E_INVALID_ARG = -1, | ||
41 | MOBILEBACKUP2_E_PLIST_ERROR = -2, | ||
42 | MOBILEBACKUP2_E_MUX_ERROR = -3, | ||
43 | MOBILEBACKUP2_E_SSL_ERROR = -4, | ||
44 | MOBILEBACKUP2_E_RECEIVE_TIMEOUT = -5, | ||
45 | MOBILEBACKUP2_E_BAD_VERSION = -6, | ||
46 | MOBILEBACKUP2_E_REPLY_NOT_OK = -7, | ||
47 | MOBILEBACKUP2_E_NO_COMMON_VERSION = -8, | ||
48 | MOBILEBACKUP2_E_UNKNOWN_ERROR = -256 | ||
49 | } mobilebackup2_error_t; | ||
50 | |||
51 | typedef struct mobilebackup2_client_private mobilebackup2_client_private; /**< \private */ | ||
52 | typedef mobilebackup2_client_private *mobilebackup2_client_t; /**< The client handle. */ | ||
53 | |||
54 | |||
55 | /** | ||
56 | * Connects to the mobilebackup2 service on the specified device. | ||
57 | * | ||
58 | * @param device The device to connect to. | ||
59 | * @param service The service descriptor returned by lockdownd_start_service. | ||
60 | * @param client Pointer that will be set to a newly allocated | ||
61 | * mobilebackup2_client_t upon successful return. | ||
62 | * | ||
63 | * @return MOBILEBACKUP2_E_SUCCESS on success, MOBILEBACKUP2_E_INVALID ARG | ||
64 | * if one or more parameter is invalid, or MOBILEBACKUP2_E_BAD_VERSION | ||
65 | * if the mobilebackup2 version on the device is newer. | ||
66 | */ | ||
67 | LIBIMOBILEDEVICE_API mobilebackup2_error_t mobilebackup2_client_new(idevice_t device, lockdownd_service_descriptor_t service, mobilebackup2_client_t * client); | ||
68 | |||
69 | /** | ||
70 | * Starts a new mobilebackup2 service on the specified device and connects to it. | ||
71 | * | ||
72 | * @param device The device to connect to. | ||
73 | * @param client Pointer that will point to a newly allocated | ||
74 | * mobilebackup2_client_t upon successful return. Must be freed using | ||
75 | * mobilebackup2_client_free() after use. | ||
76 | * @param label The label to use for communication. Usually the program name. | ||
77 | * Pass NULL to disable sending the label in requests to lockdownd. | ||
78 | * | ||
79 | * @return MOBILEBACKUP2_E_SUCCESS on success, or an MOBILEBACKUP2_E_* error | ||
80 | * code otherwise. | ||
81 | */ | ||
82 | LIBIMOBILEDEVICE_API mobilebackup2_error_t mobilebackup2_client_start_service(idevice_t device, mobilebackup2_client_t* client, const char* label); | ||
83 | |||
84 | /** | ||
85 | * Disconnects a mobilebackup2 client from the device and frees up the | ||
86 | * mobilebackup2 client data. | ||
87 | * | ||
88 | * @param client The mobilebackup2 client to disconnect and free. | ||
89 | * | ||
90 | * @return MOBILEBACKUP2_E_SUCCESS on success, or MOBILEBACKUP2_E_INVALID_ARG | ||
91 | * if client is NULL. | ||
92 | */ | ||
93 | LIBIMOBILEDEVICE_API mobilebackup2_error_t mobilebackup2_client_free(mobilebackup2_client_t client); | ||
94 | |||
95 | |||
96 | /** | ||
97 | * Sends a backup message plist. | ||
98 | * | ||
99 | * @param client The connected MobileBackup client to use. | ||
100 | * @param message The message to send. This will be inserted into the request | ||
101 | * plist as value for MessageName. If this parameter is NULL, | ||
102 | * the plist passed in the options parameter will be sent directly. | ||
103 | * @param options Additional options as PLIST_DICT to add to the request. | ||
104 | * The MessageName key with the value passed in the message parameter | ||
105 | * will be inserted into this plist before sending it. This parameter | ||
106 | * can be NULL if message is not NULL. | ||
107 | */ | ||
108 | LIBIMOBILEDEVICE_API mobilebackup2_error_t mobilebackup2_send_message(mobilebackup2_client_t client, const char *message, plist_t options); | ||
109 | |||
110 | /** | ||
111 | * Receives a DL* message plist from the device. | ||
112 | * This function is a wrapper around device_link_service_receive_message. | ||
113 | * | ||
114 | * @param client The connected MobileBackup client to use. | ||
115 | * @param msg_plist Pointer to a plist that will be set to the contents of the | ||
116 | * message plist upon successful return. | ||
117 | * @param dlmessage A pointer that will be set to a newly allocated char* | ||
118 | * containing the DL* string from the given plist. It is up to the caller | ||
119 | * to free the allocated memory. If this parameter is NULL | ||
120 | * it will be ignored. | ||
121 | * | ||
122 | * @return MOBILEBACKUP2_E_SUCCESS if a DL* message was received, | ||
123 | * MOBILEBACKUP2_E_INVALID_ARG if client or message is invalid, | ||
124 | * MOBILEBACKUP2_E_PLIST_ERROR if the received plist is invalid | ||
125 | * or is not a DL* message plist, or MOBILEBACKUP2_E_MUX_ERROR if | ||
126 | * receiving from the device failed. | ||
127 | */ | ||
128 | LIBIMOBILEDEVICE_API mobilebackup2_error_t mobilebackup2_receive_message(mobilebackup2_client_t client, plist_t *msg_plist, char **dlmessage); | ||
129 | |||
130 | /** | ||
131 | * Send binary data to the device. | ||
132 | * | ||
133 | * @note This function returns MOBILEBACKUP2_E_SUCCESS even if less than the | ||
134 | * requested length has been sent. The fourth parameter is required and | ||
135 | * must be checked to ensure if the whole data has been sent. | ||
136 | * | ||
137 | * @param client The MobileBackup client to send to. | ||
138 | * @param data Pointer to the data to send | ||
139 | * @param length Number of bytes to send | ||
140 | * @param bytes Number of bytes actually sent | ||
141 | * | ||
142 | * @return MOBILEBACKUP2_E_SUCCESS if any data was successfully sent, | ||
143 | * MOBILEBACKUP2_E_INVALID_ARG if one of the parameters is invalid, | ||
144 | * or MOBILEBACKUP2_E_MUX_ERROR if sending of the data failed. | ||
145 | */ | ||
146 | LIBIMOBILEDEVICE_API mobilebackup2_error_t mobilebackup2_send_raw(mobilebackup2_client_t client, const char *data, uint32_t length, uint32_t *bytes); | ||
147 | |||
148 | /** | ||
149 | * Receive binary from the device. | ||
150 | * | ||
151 | * @note This function returns MOBILEBACKUP2_E_SUCCESS even if no data | ||
152 | * has been received (unless a communication error occurred). | ||
153 | * The fourth parameter is required and must be checked to know how | ||
154 | * many bytes were actually received. | ||
155 | * | ||
156 | * @param client The MobileBackup client to receive from. | ||
157 | * @param data Pointer to a buffer that will be filled with the received data. | ||
158 | * @param length Number of bytes to receive. The data buffer needs to be large | ||
159 | * enough to store this amount of data. | ||
160 | * @param bytes Number of bytes actually received. | ||
161 | * | ||
162 | * @return MOBILEBACKUP2_E_SUCCESS if any or no data was received, | ||
163 | * MOBILEBACKUP2_E_INVALID_ARG if one of the parameters is invalid, | ||
164 | * or MOBILEBACKUP2_E_MUX_ERROR if receiving the data failed. | ||
165 | */ | ||
166 | LIBIMOBILEDEVICE_API mobilebackup2_error_t mobilebackup2_receive_raw(mobilebackup2_client_t client, char *data, uint32_t length, uint32_t *bytes); | ||
167 | |||
168 | /** | ||
169 | * Performs the mobilebackup2 protocol version exchange. | ||
170 | * | ||
171 | * @param client The MobileBackup client to use. | ||
172 | * @param local_versions An array of supported versions to send to the remote. | ||
173 | * @param count The number of items in local_versions. | ||
174 | * @param remote_version Holds the protocol version of the remote on success. | ||
175 | * | ||
176 | * @return MOBILEBACKUP2_E_SUCCESS on success, or a MOBILEBACKUP2_E_* error | ||
177 | * code otherwise. | ||
178 | */ | ||
179 | LIBIMOBILEDEVICE_API mobilebackup2_error_t mobilebackup2_version_exchange(mobilebackup2_client_t client, double local_versions[], char count, double *remote_version); | ||
180 | |||
181 | /** | ||
182 | * Send a request to the connected mobilebackup2 service. | ||
183 | * | ||
184 | * @param client | ||
185 | * @param request The request to send to the backup service. | ||
186 | * Currently, this is one of "Backup", "Restore", "Info", or "List". | ||
187 | * @param target_identifier UDID of the target device. | ||
188 | * @param source_identifier UDID of backup data? | ||
189 | * @param options Additional options in a plist of type PLIST_DICT. | ||
190 | * | ||
191 | * @return MOBILEBACKUP2_E_SUCCESS if the request was successfully sent, | ||
192 | * or a MOBILEBACKUP2_E_* error value otherwise. | ||
193 | */ | ||
194 | LIBIMOBILEDEVICE_API mobilebackup2_error_t mobilebackup2_send_request(mobilebackup2_client_t client, const char *request, const char *target_identifier, const char *source_identifier, plist_t options); | ||
195 | |||
196 | /** | ||
197 | * Sends a DLMessageStatusResponse to the device. | ||
198 | * | ||
199 | * @param client The MobileBackup client to use. | ||
200 | * @param status_code The status code to send. | ||
201 | * @param status1 A status message to send. Can be NULL if not required. | ||
202 | * @param status2 An additional status plist to attach to the response. | ||
203 | * Can be NULL if not required. | ||
204 | * | ||
205 | * @return MOBILEBACKUP2_E_SUCCESS on success, MOBILEBACKUP2_E_INVALID_ARG | ||
206 | * if client is invalid, or another MOBILEBACKUP2_E_* otherwise. | ||
207 | */ | ||
208 | LIBIMOBILEDEVICE_API mobilebackup2_error_t mobilebackup2_send_status_response(mobilebackup2_client_t client, int status_code, const char *status1, plist_t status2); | ||
209 | |||
210 | #ifdef __cplusplus | ||
211 | } | ||
212 | #endif | ||
213 | |||
214 | #endif | ||
diff --git a/include/libimobiledevice/mobilesync.h b/include/libimobiledevice/mobilesync.h index 7658b7d..c3bc53d 100644 --- a/include/libimobiledevice/mobilesync.h +++ b/include/libimobiledevice/mobilesync.h | |||
@@ -3,6 +3,9 @@ | |||
3 | * @brief Synchronize data classes with a device and computer. | 3 | * @brief Synchronize data classes with a device and computer. |
4 | * \internal | 4 | * \internal |
5 | * | 5 | * |
6 | * Copyright (c) 2010-2019 Nikias Bassen, All Rights Reserved. | ||
7 | * Copyright (c) 2010-2014 Martin Szulecki All Rights Reserved. | ||
8 | * Copyright (c) 2014 Christophe Fergeau All Rights Reserved. | ||
6 | * Copyright (c) 2010 Bryan Forbes All Rights Reserved. | 9 | * Copyright (c) 2010 Bryan Forbes All Rights Reserved. |
7 | * Copyright (c) 2009 Jonathan Beck All Rights Reserved. | 10 | * Copyright (c) 2009 Jonathan Beck All Rights Reserved. |
8 | * | 11 | * |
@@ -29,22 +32,26 @@ extern "C" { | |||
29 | #endif | 32 | #endif |
30 | 33 | ||
31 | #include <libimobiledevice/libimobiledevice.h> | 34 | #include <libimobiledevice/libimobiledevice.h> |
32 | #include <glib.h> | 35 | #include <libimobiledevice/lockdown.h> |
33 | 36 | ||
34 | /** @name Error Codes */ | 37 | /** Service identifier passed to lockdownd_start_service() to start the mobilesync service */ |
35 | /*@{*/ | 38 | #define MOBILESYNC_SERVICE_NAME "com.apple.mobilesync" |
36 | #define MOBILESYNC_E_SUCCESS 0 | 39 | |
37 | #define MOBILESYNC_E_INVALID_ARG -1 | 40 | /** Error Codes */ |
38 | #define MOBILESYNC_E_PLIST_ERROR -2 | 41 | typedef enum { |
39 | #define MOBILESYNC_E_MUX_ERROR -3 | 42 | MOBILESYNC_E_SUCCESS = 0, |
40 | #define MOBILESYNC_E_BAD_VERSION -4 | 43 | MOBILESYNC_E_INVALID_ARG = -1, |
41 | #define MOBILESYNC_E_SYNC_REFUSED -5 | 44 | MOBILESYNC_E_PLIST_ERROR = -2, |
42 | #define MOBILESYNC_E_CANCELLED -6 | 45 | MOBILESYNC_E_MUX_ERROR = -3, |
43 | #define MOBILESYNC_E_WRONG_DIRECTION -7 | 46 | MOBILESYNC_E_SSL_ERROR = -4, |
44 | #define MOBILESYNC_E_NOT_READY -8 | 47 | MOBILESYNC_E_RECEIVE_TIMEOUT = -5, |
45 | 48 | MOBILESYNC_E_BAD_VERSION = -6, | |
46 | #define MOBILESYNC_E_UNKNOWN_ERROR -256 | 49 | MOBILESYNC_E_SYNC_REFUSED = -7, |
47 | /*@}*/ | 50 | MOBILESYNC_E_CANCELLED = -8, |
51 | MOBILESYNC_E_WRONG_DIRECTION = -9, | ||
52 | MOBILESYNC_E_NOT_READY = -10, | ||
53 | MOBILESYNC_E_UNKNOWN_ERROR = -256 | ||
54 | } mobilesync_error_t; | ||
48 | 55 | ||
49 | /** The sync type of the current sync session. */ | 56 | /** The sync type of the current sync session. */ |
50 | typedef enum { | 57 | typedef enum { |
@@ -53,48 +60,297 @@ typedef enum { | |||
53 | MOBILESYNC_SYNC_TYPE_RESET /**< Reset-sync signals that the computer should send all data again. */ | 60 | MOBILESYNC_SYNC_TYPE_RESET /**< Reset-sync signals that the computer should send all data again. */ |
54 | } mobilesync_sync_type_t; | 61 | } mobilesync_sync_type_t; |
55 | 62 | ||
56 | /** Represents an error code. */ | 63 | typedef struct mobilesync_client_private mobilesync_client_private; /**< \private */ |
57 | typedef int16_t mobilesync_error_t; | ||
58 | |||
59 | typedef struct mobilesync_client_private mobilesync_client_private; | ||
60 | typedef mobilesync_client_private *mobilesync_client_t; /**< The client handle */ | 64 | typedef mobilesync_client_private *mobilesync_client_t; /**< The client handle */ |
61 | 65 | ||
66 | /** Anchors used by the device and computer (structure) */ | ||
62 | typedef struct { | 67 | typedef struct { |
63 | char *device_anchor; | 68 | char *device_anchor; /**< device anchor */ |
64 | char *computer_anchor; | 69 | char *computer_anchor; /**< computer anchor */ |
65 | } mobilesync_anchors; | 70 | } mobilesync_anchors; |
66 | typedef mobilesync_anchors *mobilesync_anchors_t; /**< Anchors used by the device and computer. */ | 71 | /** Anchors used by the device and computer */ |
72 | typedef mobilesync_anchors *mobilesync_anchors_t; | ||
67 | 73 | ||
68 | /* Interface */ | 74 | /* Interface */ |
69 | mobilesync_error_t mobilesync_client_new(idevice_t device, uint16_t port, mobilesync_client_t * client); | ||
70 | mobilesync_error_t mobilesync_client_free(mobilesync_client_t client); | ||
71 | 75 | ||
72 | mobilesync_error_t mobilesync_receive(mobilesync_client_t client, plist_t *plist); | 76 | /** |
73 | mobilesync_error_t mobilesync_send(mobilesync_client_t client, plist_t plist); | 77 | * Connects to the mobilesync service on the specified device. |
78 | * | ||
79 | * @param device The device to connect to. | ||
80 | * @param service The service descriptor returned by lockdownd_start_service. | ||
81 | * @param client Pointer that will be set to a newly allocated | ||
82 | * #mobilesync_client_t upon successful return. | ||
83 | * | ||
84 | * @retval MOBILESYNC_E_SUCCESS on success | ||
85 | * @retval MOBILESYNC_E_INVALID_ARG if one or more parameters are invalid | ||
86 | * @retval DEVICE_LINK_SERVICE_E_BAD_VERSION if the mobilesync version on | ||
87 | * the device is newer. | ||
88 | */ | ||
89 | LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_client_new(idevice_t device, lockdownd_service_descriptor_t service, mobilesync_client_t * client); | ||
90 | |||
91 | /** | ||
92 | * Starts a new mobilesync service on the specified device and connects to it. | ||
93 | * | ||
94 | * @param device The device to connect to. | ||
95 | * @param client Pointer that will point to a newly allocated | ||
96 | * mobilesync_client_t upon successful return. Must be freed using | ||
97 | * mobilesync_client_free() after use. | ||
98 | * @param label The label to use for communication. Usually the program name. | ||
99 | * Pass NULL to disable sending the label in requests to lockdownd. | ||
100 | * | ||
101 | * @return MOBILESYNC_E_SUCCESS on success, or an MOBILESYNC_E_* error | ||
102 | * code otherwise. | ||
103 | */ | ||
104 | LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_client_start_service(idevice_t device, mobilesync_client_t* client, const char* label); | ||
105 | |||
106 | /** | ||
107 | * Disconnects a mobilesync client from the device and frees up the | ||
108 | * mobilesync client data. | ||
109 | * | ||
110 | * @param client The mobilesync client to disconnect and free. | ||
111 | * | ||
112 | * @retval MOBILESYNC_E_SUCCESS on success | ||
113 | * @retval MOBILESYNC_E_INVALID_ARG if \a client is NULL. | ||
114 | */ | ||
115 | LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_client_free(mobilesync_client_t client); | ||
116 | |||
117 | |||
118 | /** | ||
119 | * Polls the device for mobilesync data. | ||
120 | * | ||
121 | * @param client The mobilesync client | ||
122 | * @param plist A pointer to the location where the plist should be stored | ||
123 | * | ||
124 | * @return an error code | ||
125 | */ | ||
126 | LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_receive(mobilesync_client_t client, plist_t *plist); | ||
127 | |||
128 | /** | ||
129 | * Sends mobilesync data to the device | ||
130 | * | ||
131 | * @note This function is low-level and should only be used if you need to send | ||
132 | * a new type of message. | ||
133 | * | ||
134 | * @param client The mobilesync client | ||
135 | * @param plist The location of the plist to send | ||
136 | * | ||
137 | * @return an error code | ||
138 | */ | ||
139 | LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_send(mobilesync_client_t client, plist_t plist); | ||
140 | |||
141 | |||
142 | /** | ||
143 | * Requests starting synchronization of a data class with the device | ||
144 | * | ||
145 | * @param client The mobilesync client | ||
146 | * @param data_class The data class identifier to sync | ||
147 | * @param anchors The anchors required to exchange with the device. The anchors | ||
148 | * allow the device to tell if the synchronization information on the computer | ||
149 | * and device are consistent to determine what sync type is required. | ||
150 | * @param computer_data_class_version The version of the data class storage on the computer | ||
151 | * @param sync_type A pointer to store the sync type reported by the device_anchor | ||
152 | * @param device_data_class_version The version of the data class storage on the device | ||
153 | * @param error_description A pointer to store an error message if reported by the device | ||
154 | * | ||
155 | * @retval MOBILESYNC_E_SUCCESS on success | ||
156 | * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid | ||
157 | * @retval MOBILESYNC_E_PLIST_ERROR if the received plist is not of valid form | ||
158 | * @retval MOBILESYNC_E_SYNC_REFUSED if the device refused to sync | ||
159 | * @retval MOBILESYNC_E_CANCELLED if the device explicitly cancelled the | ||
160 | * sync request | ||
161 | */ | ||
162 | LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_start(mobilesync_client_t client, const char *data_class, mobilesync_anchors_t anchors, uint64_t computer_data_class_version, mobilesync_sync_type_t *sync_type, uint64_t *device_data_class_version, char** error_description); | ||
163 | |||
164 | /** | ||
165 | * Cancels a running synchronization session with a device at any time. | ||
166 | * | ||
167 | * @param client The mobilesync client | ||
168 | * @param reason The reason to supply to the device for cancelling | ||
169 | * | ||
170 | * @retval MOBILESYNC_E_SUCCESS on success | ||
171 | * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid | ||
172 | */ | ||
173 | LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_cancel(mobilesync_client_t client, const char* reason); | ||
174 | |||
175 | /** | ||
176 | * Finish a synchronization session of a data class on the device. | ||
177 | * A session must have previously been started using mobilesync_start(). | ||
178 | * | ||
179 | * @param client The mobilesync client | ||
180 | * | ||
181 | * @retval MOBILESYNC_E_SUCCESS on success | ||
182 | * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid | ||
183 | * @retval MOBILESYNC_E_PLIST_ERROR if the received plist is not of valid | ||
184 | * form | ||
185 | */ | ||
186 | LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_finish(mobilesync_client_t client); | ||
187 | |||
188 | |||
189 | /** | ||
190 | * Requests to receive all records of the currently set data class from the device. | ||
191 | * The actually changes are retrieved using mobilesync_receive_changes() after this | ||
192 | * request has been successful. | ||
193 | * | ||
194 | * @param client The mobilesync client | ||
195 | * | ||
196 | * @retval MOBILESYNC_E_SUCCESS on success | ||
197 | * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid | ||
198 | */ | ||
199 | LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_get_all_records_from_device(mobilesync_client_t client); | ||
200 | |||
201 | /** | ||
202 | * Requests to receive only changed records of the currently set data class from the device. | ||
203 | * The actually changes are retrieved using mobilesync_receive_changes() after this | ||
204 | * request has been successful. | ||
205 | * | ||
206 | * @param client The mobilesync client | ||
207 | * | ||
208 | * @retval MOBILESYNC_E_SUCCESS on success | ||
209 | * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid | ||
210 | */ | ||
211 | LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_get_changes_from_device(mobilesync_client_t client); | ||
212 | |||
213 | /** | ||
214 | * Requests the device to delete all records of the current data class | ||
215 | * | ||
216 | * @note The operation must be called after starting synchronization. | ||
217 | * | ||
218 | * @param client The mobilesync client | ||
219 | * | ||
220 | * @retval MOBILESYNC_E_SUCCESS on success | ||
221 | * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid | ||
222 | * @retval MOBILESYNC_E_PLIST_ERROR if the received plist is not of valid form | ||
223 | */ | ||
224 | LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_clear_all_records_on_device(mobilesync_client_t client); | ||
74 | 225 | ||
75 | mobilesync_error_t mobilesync_start(mobilesync_client_t client, const char *data_class, mobilesync_anchors_t anchors, uint64_t computer_data_class_version, mobilesync_sync_type_t *sync_type, uint64_t *device_data_class_version); | ||
76 | mobilesync_error_t mobilesync_cancel(mobilesync_client_t client, const char* reason); | ||
77 | mobilesync_error_t mobilesync_finish(mobilesync_client_t client); | ||
78 | 226 | ||
79 | mobilesync_error_t mobilesync_get_all_records_from_device(mobilesync_client_t client); | 227 | /** |
80 | mobilesync_error_t mobilesync_get_changes_from_device(mobilesync_client_t client); | 228 | * Receives changed entitites of the currently set data class from the device |
81 | mobilesync_error_t mobilesync_clear_all_records_on_device(mobilesync_client_t client); | 229 | * |
230 | * @param client The mobilesync client | ||
231 | * @param entities A pointer to store the changed entity records as a PLIST_DICT | ||
232 | * @param is_last_record A pointer to store a flag indicating if this submission is the last one | ||
233 | * @param actions A pointer to additional flags the device is sending or NULL to ignore | ||
234 | * | ||
235 | * @retval MOBILESYNC_E_SUCCESS on success | ||
236 | * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid | ||
237 | * @retval MOBILESYNC_E_CANCELLED if the device explicitly cancelled the | ||
238 | * session | ||
239 | */ | ||
240 | LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_receive_changes(mobilesync_client_t client, plist_t *entities, uint8_t *is_last_record, plist_t *actions); | ||
241 | |||
242 | /** | ||
243 | * Acknowledges to the device that the changes have been merged on the computer | ||
244 | * | ||
245 | * @param client The mobilesync client | ||
246 | * | ||
247 | * @retval MOBILESYNC_E_SUCCESS on success | ||
248 | * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid | ||
249 | */ | ||
250 | LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_acknowledge_changes_from_device(mobilesync_client_t client); | ||
82 | 251 | ||
83 | mobilesync_error_t mobilesync_receive_changes(mobilesync_client_t client, plist_t *entities, uint8_t *is_last_record, plist_t *actions); | ||
84 | mobilesync_error_t mobilesync_acknowledge_changes_from_device(mobilesync_client_t client); | ||
85 | 252 | ||
86 | mobilesync_error_t mobilesync_ready_to_send_changes_from_computer(mobilesync_client_t client); | 253 | /** |
254 | * Verifies if the device is ready to receive changes from the computer. | ||
255 | * This call changes the synchronization direction so that mobilesync_send_changes() | ||
256 | * can be used to send changes to the device. | ||
257 | * | ||
258 | * @param client The mobilesync client | ||
259 | * | ||
260 | * @retval MOBILESYNC_E_SUCCESS on success | ||
261 | * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid | ||
262 | * @retval MOBILESYNC_E_PLIST_ERROR if the received plist is not of valid form | ||
263 | * @retval MOBILESYNC_E_WRONG_DIRECTION if the current sync direction does | ||
264 | * not permit this call | ||
265 | * @retval MOBILESYNC_E_CANCELLED if the device explicitly cancelled the | ||
266 | * session | ||
267 | * @retval MOBILESYNC_E_NOT_READY if the device is not ready to start | ||
268 | * receiving any changes | ||
269 | */ | ||
270 | LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_ready_to_send_changes_from_computer(mobilesync_client_t client); | ||
271 | |||
272 | |||
273 | /** | ||
274 | * Sends changed entities of the currently set data class to the device | ||
275 | * | ||
276 | * @param client The mobilesync client | ||
277 | * @param entities The changed entity records as a PLIST_DICT | ||
278 | * @param is_last_record A flag indicating if this submission is the last one | ||
279 | * @param actions Additional actions for the device created with mobilesync_actions_new() | ||
280 | * or NULL if no actions should be passed | ||
281 | * | ||
282 | * @retval MOBILESYNC_E_SUCCESS on success | ||
283 | * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid, | ||
284 | * @retval MOBILESYNC_E_WRONG_DIRECTION if the current sync direction does | ||
285 | * not permit this call | ||
286 | */ | ||
287 | LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_send_changes(mobilesync_client_t client, plist_t entities, uint8_t is_last_record, plist_t actions); | ||
87 | 288 | ||
88 | mobilesync_error_t mobilesync_send_changes(mobilesync_client_t client, plist_t entities, uint8_t is_last_record, plist_t actions); | 289 | /** |
89 | mobilesync_error_t mobilesync_remap_identifiers(mobilesync_client_t client, plist_t *mapping); | 290 | * Receives any remapped identifiers reported after the device merged submitted changes. |
291 | * | ||
292 | * @param client The mobilesync client | ||
293 | * @param mapping A pointer to an array plist containing a dict of identifier remappings | ||
294 | * | ||
295 | * @retval MOBILESYNC_E_SUCCESS on success | ||
296 | * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid | ||
297 | * @retval MOBILESYNC_E_PLIST_ERROR if the received plist is not of valid | ||
298 | * form | ||
299 | * @retval MOBILESYNC_E_WRONG_DIRECTION if the current sync direction does | ||
300 | * not permit this call | ||
301 | * @retval MOBILESYNC_E_CANCELLED if the device explicitly cancelled the | ||
302 | * session | ||
303 | */ | ||
304 | LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_remap_identifiers(mobilesync_client_t client, plist_t *mapping); | ||
90 | 305 | ||
91 | /* Helper */ | 306 | /* Helper */ |
92 | mobilesync_anchors_t mobilesync_anchors_new(const char *device_anchor, const char *computer_anchor); | ||
93 | void mobilesync_anchors_free(mobilesync_anchors_t anchors); | ||
94 | 307 | ||
95 | plist_t mobilesync_actions_new(); | 308 | /** |
96 | void mobilesync_actions_add(plist_t actions, ...) G_GNUC_NULL_TERMINATED; | 309 | * Allocates memory for a new anchors struct initialized with the passed anchors. |
97 | void mobilesync_actions_free(plist_t actions); | 310 | * |
311 | * @param device_anchor An anchor the device reported the last time or NULL | ||
312 | * if none is known yet which for instance is true on first synchronization. | ||
313 | * @param computer_anchor An arbitrary string to use as anchor for the computer. | ||
314 | * | ||
315 | * @return A new #mobilesync_anchors_t struct. Must be freed using mobilesync_anchors_free(). | ||
316 | */ | ||
317 | LIBIMOBILEDEVICE_API mobilesync_anchors_t mobilesync_anchors_new(const char *device_anchor, const char *computer_anchor); | ||
318 | |||
319 | /** | ||
320 | * Free memory used by anchors. | ||
321 | * | ||
322 | * @param anchors The anchors to free. | ||
323 | */ | ||
324 | LIBIMOBILEDEVICE_API void mobilesync_anchors_free(mobilesync_anchors_t anchors); | ||
325 | |||
326 | |||
327 | /** | ||
328 | * Create a new actions plist to use in mobilesync_send_changes(). | ||
329 | * | ||
330 | * @return A new plist_t of type PLIST_DICT. | ||
331 | */ | ||
332 | LIBIMOBILEDEVICE_API plist_t mobilesync_actions_new(void); | ||
333 | |||
334 | /** | ||
335 | * Add one or more new key:value pairs to the given actions plist. | ||
336 | * | ||
337 | * @param actions The actions to modify. | ||
338 | * @param ... KEY, VALUE, [KEY, VALUE], NULL | ||
339 | * | ||
340 | * @note The known keys so far are "SyncDeviceLinkEntityNamesKey" which expects | ||
341 | * an array of entity names, followed by a count paramter as well as | ||
342 | * "SyncDeviceLinkAllRecordsOfPulledEntityTypeSentKey" which expects an | ||
343 | * integer to use as a boolean value indicating that the device should | ||
344 | * link submitted changes and report remapped identifiers. | ||
345 | */ | ||
346 | LIBIMOBILEDEVICE_API void mobilesync_actions_add(plist_t actions, ...); | ||
347 | |||
348 | /** | ||
349 | * Free actions plist. | ||
350 | * | ||
351 | * @param actions The actions plist to free. Does nothing if NULL is passed. | ||
352 | */ | ||
353 | LIBIMOBILEDEVICE_API void mobilesync_actions_free(plist_t actions); | ||
98 | 354 | ||
99 | #ifdef __cplusplus | 355 | #ifdef __cplusplus |
100 | } | 356 | } |
diff --git a/include/libimobiledevice/notification_proxy.h b/include/libimobiledevice/notification_proxy.h index 43c479d..f4f090b 100644 --- a/include/libimobiledevice/notification_proxy.h +++ b/include/libimobiledevice/notification_proxy.h | |||
@@ -3,7 +3,8 @@ | |||
3 | * @brief Observe and post notifications. | 3 | * @brief Observe and post notifications. |
4 | * \internal | 4 | * \internal |
5 | * | 5 | * |
6 | * Copyright (c) 2009 Nikias Bassen All Rights Reserved. | 6 | * Copyright (c) 2010-2014 Martin Szulecki All Rights Reserved. |
7 | * Copyright (c) 2009-2010 Nikias Bassen All Rights Reserved. | ||
7 | * | 8 | * |
8 | * This library is free software; you can redistribute it and/or | 9 | * This library is free software; you can redistribute it and/or |
9 | * modify it under the terms of the GNU Lesser General Public | 10 | * modify it under the terms of the GNU Lesser General Public |
@@ -20,45 +21,49 @@ | |||
20 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | 21 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA |
21 | */ | 22 | */ |
22 | 23 | ||
23 | #ifndef NOTIFICATION_PROXY_H | 24 | #ifndef INOTIFICATION_PROXY_H |
24 | #define NOTIFICATION_PROXY_H | 25 | #define INOTIFICATION_PROXY_H |
25 | 26 | ||
26 | #ifdef __cplusplus | 27 | #ifdef __cplusplus |
27 | extern "C" { | 28 | extern "C" { |
28 | #endif | 29 | #endif |
29 | 30 | ||
30 | #include <libimobiledevice/libimobiledevice.h> | 31 | #include <libimobiledevice/libimobiledevice.h> |
32 | #include <libimobiledevice/lockdown.h> | ||
31 | 33 | ||
32 | /** @name Error Codes */ | 34 | /** Service identifier passed to lockdownd_start_service() to start the notification proxy service */ |
33 | /*@{*/ | 35 | #define NP_SERVICE_NAME "com.apple.mobile.notification_proxy" |
34 | #define NP_E_SUCCESS 0 | ||
35 | #define NP_E_INVALID_ARG -1 | ||
36 | #define NP_E_PLIST_ERROR -2 | ||
37 | #define NP_E_CONN_FAILED -3 | ||
38 | 36 | ||
39 | #define NP_E_UNKNOWN_ERROR -256 | 37 | /** Error Codes */ |
40 | /*@}*/ | 38 | typedef enum { |
41 | 39 | NP_E_SUCCESS = 0, | |
42 | /** Represents an error code. */ | 40 | NP_E_INVALID_ARG = -1, |
43 | typedef int16_t np_error_t; | 41 | NP_E_PLIST_ERROR = -2, |
42 | NP_E_CONN_FAILED = -3, | ||
43 | NP_E_UNKNOWN_ERROR = -256 | ||
44 | } np_error_t; | ||
44 | 45 | ||
45 | /** | 46 | /** |
46 | * @name Notifications that can be send | 47 | * @name Notifications that can be sent |
47 | * | 48 | * |
48 | * For use with np_post_notification() (client --> device) | 49 | * For use with np_post_notification() (client --> device) |
49 | */ | 50 | */ |
51 | /**@{*/ | ||
52 | //! @cond | ||
50 | #define NP_SYNC_WILL_START "com.apple.itunes-mobdev.syncWillStart" | 53 | #define NP_SYNC_WILL_START "com.apple.itunes-mobdev.syncWillStart" |
51 | #define NP_SYNC_DID_START "com.apple.itunes-mobdev.syncDidStart" | 54 | #define NP_SYNC_DID_START "com.apple.itunes-mobdev.syncDidStart" |
52 | #define NP_SYNC_DID_FINISH "com.apple.itunes-mobdev.syncDidFinish" | 55 | #define NP_SYNC_DID_FINISH "com.apple.itunes-mobdev.syncDidFinish" |
53 | #define NP_SYNC_LOCK_REQUEST "com.apple.itunes-mobdev.syncLockRequest" | 56 | #define NP_SYNC_LOCK_REQUEST "com.apple.itunes-mobdev.syncLockRequest" |
54 | /*@}*/ | 57 | //! @endcond |
58 | /**@}*/ | ||
55 | 59 | ||
56 | /** | 60 | /** |
57 | * @name Notifications that can be received | 61 | * @name Notifications that can be received |
58 | * | 62 | * |
59 | * For use with np_observe_notification() (device --> client) | 63 | * For use with np_observe_notification() (device --> client) |
60 | */ | 64 | */ |
61 | /*@{*/ | 65 | /**@{*/ |
66 | //! @cond | ||
62 | #define NP_SYNC_CANCEL_REQUEST "com.apple.itunes-client.syncCancelRequest" | 67 | #define NP_SYNC_CANCEL_REQUEST "com.apple.itunes-client.syncCancelRequest" |
63 | #define NP_SYNC_SUSPEND_REQUEST "com.apple.itunes-client.syncSuspendRequest" | 68 | #define NP_SYNC_SUSPEND_REQUEST "com.apple.itunes-client.syncSuspendRequest" |
64 | #define NP_SYNC_RESUME_REQUEST "com.apple.itunes-client.syncResumeRequest" | 69 | #define NP_SYNC_RESUME_REQUEST "com.apple.itunes-client.syncResumeRequest" |
@@ -81,21 +86,114 @@ typedef int16_t np_error_t; | |||
81 | #define NP_ITDBPREP_DID_END "com.apple.itdbprep.notification.didEnd" | 86 | #define NP_ITDBPREP_DID_END "com.apple.itdbprep.notification.didEnd" |
82 | #define NP_LANGUAGE_CHANGED "com.apple.language.changed" | 87 | #define NP_LANGUAGE_CHANGED "com.apple.language.changed" |
83 | #define NP_ADDRESS_BOOK_PREF_CHANGED "com.apple.AddressBook.PreferenceChanged" | 88 | #define NP_ADDRESS_BOOK_PREF_CHANGED "com.apple.AddressBook.PreferenceChanged" |
84 | /*@}*/ | 89 | //! @endcond |
90 | /**@}*/ | ||
85 | 91 | ||
86 | typedef struct np_client_private np_client_private; | 92 | typedef struct np_client_private np_client_private; /**< \private */ |
87 | typedef np_client_private *np_client_t; /**< The client handle. */ | 93 | typedef np_client_private *np_client_t; /**< The client handle. */ |
88 | 94 | ||
89 | /** Reports which notification was received. */ | 95 | /** Callback function that reports which notification was received. */ |
90 | typedef void (*np_notify_cb_t) (const char *notification, void *user_data); | 96 | typedef void (*np_notify_cb_t) (const char *notification, void *user_data); |
91 | 97 | ||
92 | /* Interface */ | 98 | /* Interface */ |
93 | np_error_t np_client_new(idevice_t device, uint16_t port, np_client_t *client); | 99 | |
94 | np_error_t np_client_free(np_client_t client); | 100 | /** |
95 | np_error_t np_post_notification(np_client_t client, const char *notification); | 101 | * Connects to the notification_proxy on the specified device. |
96 | np_error_t np_observe_notification(np_client_t client, const char *notification); | 102 | * |
97 | np_error_t np_observe_notifications(np_client_t client, const char **notification_spec); | 103 | * @param device The device to connect to. |
98 | np_error_t np_set_notify_callback(np_client_t client, np_notify_cb_t notify_cb, void *userdata); | 104 | * @param service The service descriptor returned by lockdownd_start_service. |
105 | * @param client Pointer that will be set to a newly allocated np_client_t | ||
106 | * upon successful return. | ||
107 | * | ||
108 | * @return NP_E_SUCCESS on success, NP_E_INVALID_ARG when device is NULL, | ||
109 | * or NP_E_CONN_FAILED when the connection to the device could not be | ||
110 | * established. | ||
111 | */ | ||
112 | LIBIMOBILEDEVICE_API np_error_t np_client_new(idevice_t device, lockdownd_service_descriptor_t service, np_client_t *client); | ||
113 | |||
114 | /** | ||
115 | * Starts a new notification proxy service on the specified device and connects to it. | ||
116 | * | ||
117 | * @param device The device to connect to. | ||
118 | * @param client Pointer that will point to a newly allocated | ||
119 | * np_client_t upon successful return. Must be freed using | ||
120 | * np_client_free() after use. | ||
121 | * @param label The label to use for communication. Usually the program name. | ||
122 | * Pass NULL to disable sending the label in requests to lockdownd. | ||
123 | * | ||
124 | * @return NP_E_SUCCESS on success, or an NP_E_* error | ||
125 | * code otherwise. | ||
126 | */ | ||
127 | LIBIMOBILEDEVICE_API np_error_t np_client_start_service(idevice_t device, np_client_t* client, const char* label); | ||
128 | |||
129 | /** | ||
130 | * Disconnects a notification_proxy client from the device and frees up the | ||
131 | * notification_proxy client data. | ||
132 | * | ||
133 | * @param client The notification_proxy client to disconnect and free. | ||
134 | * | ||
135 | * @return NP_E_SUCCESS on success, or NP_E_INVALID_ARG when client is NULL. | ||
136 | */ | ||
137 | LIBIMOBILEDEVICE_API np_error_t np_client_free(np_client_t client); | ||
138 | |||
139 | |||
140 | /** | ||
141 | * Sends a notification to the device's notification_proxy. | ||
142 | * | ||
143 | * @param client The client to send to | ||
144 | * @param notification The notification message to send | ||
145 | * | ||
146 | * @return NP_E_SUCCESS on success, or an error returned by np_plist_send | ||
147 | */ | ||
148 | LIBIMOBILEDEVICE_API np_error_t np_post_notification(np_client_t client, const char *notification); | ||
149 | |||
150 | /** | ||
151 | * Tells the device to send a notification on the specified event. | ||
152 | * | ||
153 | * @param client The client to send to | ||
154 | * @param notification The notifications that should be observed. | ||
155 | * | ||
156 | * @return NP_E_SUCCESS on success, NP_E_INVALID_ARG when client or | ||
157 | * notification are NULL, or an error returned by np_plist_send. | ||
158 | */ | ||
159 | LIBIMOBILEDEVICE_API np_error_t np_observe_notification(np_client_t client, const char *notification); | ||
160 | |||
161 | /** | ||
162 | * Tells the device to send a notification on specified events. | ||
163 | * | ||
164 | * @param client The client to send to | ||
165 | * @param notification_spec Specification of the notifications that should be | ||
166 | * observed. This is expected to be an array of const char* that MUST have a | ||
167 | * terminating NULL entry. | ||
168 | * | ||
169 | * @return NP_E_SUCCESS on success, NP_E_INVALID_ARG when client is null, | ||
170 | * or an error returned by np_observe_notification. | ||
171 | */ | ||
172 | LIBIMOBILEDEVICE_API np_error_t np_observe_notifications(np_client_t client, const char **notification_spec); | ||
173 | |||
174 | /** | ||
175 | * This function allows an application to define a callback function that will | ||
176 | * be called when a notification has been received. | ||
177 | * It will start a thread that polls for notifications and calls the callback | ||
178 | * function if a notification has been received. | ||
179 | * In case of an error condition when polling for notifications - e.g. device | ||
180 | * disconnect - the thread will call the callback function with an empty | ||
181 | * notification "" and terminate itself. | ||
182 | * | ||
183 | * @param client the NP client | ||
184 | * @param notify_cb pointer to a callback function or NULL to de-register a | ||
185 | * previously set callback function. | ||
186 | * @param user_data Pointer that will be passed to the callback function as | ||
187 | * user data. If notify_cb is NULL, this parameter is ignored. | ||
188 | * | ||
189 | * @note Only one callback function can be registered at the same time; | ||
190 | * any previously set callback function will be removed automatically. | ||
191 | * | ||
192 | * @return NP_E_SUCCESS when the callback was successfully registered, | ||
193 | * NP_E_INVALID_ARG when client is NULL, or NP_E_UNKNOWN_ERROR when | ||
194 | * the callback thread could no be created. | ||
195 | */ | ||
196 | LIBIMOBILEDEVICE_API np_error_t np_set_notify_callback(np_client_t client, np_notify_cb_t notify_cb, void *user_data); | ||
99 | 197 | ||
100 | #ifdef __cplusplus | 198 | #ifdef __cplusplus |
101 | } | 199 | } |
diff --git a/include/libimobiledevice/preboard.h b/include/libimobiledevice/preboard.h new file mode 100644 index 0000000..0d89eb4 --- /dev/null +++ b/include/libimobiledevice/preboard.h | |||
@@ -0,0 +1,187 @@ | |||
1 | /** | ||
2 | * @file libimobiledevice/preboard.h | ||
3 | * @brief Service to 'preboard' a device, which allows to ask for passcode during firmware updates. | ||
4 | * \internal | ||
5 | * | ||
6 | * Copyright (c) 2019 Nikias Bassen, All Rights Reserved. | ||
7 | * | ||
8 | * This library is free software; you can redistribute it and/or | ||
9 | * modify it under the terms of the GNU Lesser General Public | ||
10 | * License as published by the Free Software Foundation; either | ||
11 | * version 2.1 of the License, or (at your option) any later version. | ||
12 | * | ||
13 | * This library is distributed in the hope that it will be useful, | ||
14 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
15 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
16 | * Lesser General Public License for more details. | ||
17 | * | ||
18 | * You should have received a copy of the GNU Lesser General Public | ||
19 | * License along with this library; if not, write to the Free Software | ||
20 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | ||
21 | */ | ||
22 | |||
23 | #ifndef IPREBOARD_H | ||
24 | #define IPREBOARD_H | ||
25 | |||
26 | #ifdef __cplusplus | ||
27 | extern "C" { | ||
28 | #endif | ||
29 | |||
30 | #include <libimobiledevice/libimobiledevice.h> | ||
31 | #include <libimobiledevice/lockdown.h> | ||
32 | |||
33 | /** Service identifier passed to lockdownd_start_service() to start the preboard service */ | ||
34 | #define PREBOARD_SERVICE_NAME "com.apple.preboardservice_v2" | ||
35 | |||
36 | /** Error Codes */ | ||
37 | typedef enum { | ||
38 | PREBOARD_E_SUCCESS = 0, | ||
39 | PREBOARD_E_INVALID_ARG = -1, | ||
40 | PREBOARD_E_PLIST_ERROR = -2, | ||
41 | PREBOARD_E_MUX_ERROR = -3, | ||
42 | PREBOARD_E_SSL_ERROR = -4, | ||
43 | PREBOARD_E_NOT_ENOUGH_DATA = -5, | ||
44 | PREBOARD_E_TIMEOUT = -6, | ||
45 | PREBOARD_E_OP_IN_PROGRESS = -10, | ||
46 | PREBOARD_E_UNKNOWN_ERROR = -256 | ||
47 | } preboard_error_t; | ||
48 | |||
49 | typedef struct preboard_client_private preboard_client_private; /**< \private */ | ||
50 | typedef preboard_client_private *preboard_client_t; /**< The client handle. */ | ||
51 | |||
52 | /** Reports the status response of the given command */ | ||
53 | typedef void (*preboard_status_cb_t) (plist_t message, void *user_data); | ||
54 | |||
55 | /** | ||
56 | * Connects to the preboard service on the specified device. | ||
57 | * | ||
58 | * @param device The device to connect to. | ||
59 | * @param service The service descriptor returned by lockdownd_start_service. | ||
60 | * @param client Pointer that will point to a newly allocated | ||
61 | * preboard_client_t upon successful return. Must be freed using | ||
62 | * preboard_client_free() after use. | ||
63 | * | ||
64 | * @return PREBOARD_E_SUCCESS on success, PREBOARD_E_INVALID_ARG when | ||
65 | * client is NULL, or an PREBOARD_E_* error code otherwise. | ||
66 | */ | ||
67 | LIBIMOBILEDEVICE_API preboard_error_t preboard_client_new(idevice_t device, lockdownd_service_descriptor_t service, preboard_client_t * client); | ||
68 | |||
69 | /** | ||
70 | * Starts a new preboard service on the specified device and connects to it. | ||
71 | * | ||
72 | * @param device The device to connect to. | ||
73 | * @param client Pointer that will point to a newly allocated | ||
74 | * preboard_client_t upon successful return. Must be freed using | ||
75 | * preboard_client_free() after use. | ||
76 | * @param label The label to use for communication. Usually the program name. | ||
77 | * Pass NULL to disable sending the label in requests to lockdownd. | ||
78 | * | ||
79 | * @return PREBOARD_E_SUCCESS on success, or a PREBOARD_E_* error | ||
80 | * code otherwise. | ||
81 | */ | ||
82 | LIBIMOBILEDEVICE_API preboard_error_t preboard_client_start_service(idevice_t device, preboard_client_t * client, const char* label); | ||
83 | |||
84 | /** | ||
85 | * Disconnects a preboard client from the device and frees up the | ||
86 | * preboard client data. | ||
87 | * | ||
88 | * @param client The preboard client to disconnect and free. | ||
89 | * | ||
90 | * @return PREBOARD_E_SUCCESS on success, PREBOARD_E_INVALID_ARG when | ||
91 | * client is NULL, or a PREBOARD_E_* error code otherwise. | ||
92 | */ | ||
93 | LIBIMOBILEDEVICE_API preboard_error_t preboard_client_free(preboard_client_t client); | ||
94 | |||
95 | /** | ||
96 | * Sends a plist to the service. | ||
97 | * | ||
98 | * @param client The preboard client | ||
99 | * @param plist The plist to send | ||
100 | * | ||
101 | * @return PREBOARD_E_SUCCESS on success, | ||
102 | * PREBOARD_E_INVALID_ARG when client or plist is NULL, | ||
103 | * or a PREBOARD_E_* error code on error | ||
104 | */ | ||
105 | LIBIMOBILEDEVICE_API preboard_error_t preboard_send(preboard_client_t client, plist_t plist); | ||
106 | |||
107 | /** | ||
108 | * Receives a plist from the service. | ||
109 | * | ||
110 | * @param client The preboard client | ||
111 | * @param plist Pointer to a plist_t what will be set to the received plist | ||
112 | * | ||
113 | * @return PREBOARD_E_SUCCESS on success, | ||
114 | * PREBOARD_E_INVALID_ARG when client or plist is NULL, | ||
115 | * PREBOARD_E_TIMEOUT when no data was received after 5 seconds, | ||
116 | * or a PREBOARD_E_* error code on error | ||
117 | */ | ||
118 | LIBIMOBILEDEVICE_API preboard_error_t preboard_receive(preboard_client_t client, plist_t * plist); | ||
119 | |||
120 | /** | ||
121 | * Receives a plist from the service with the specified timeout. | ||
122 | * | ||
123 | * @param client The preboard client | ||
124 | * @param plist Pointer to a plist_t what will be set to the received plist | ||
125 | * @param timeout_ms Timeout in milliseconds | ||
126 | * | ||
127 | * @return PREBOARD_E_SUCCESS on success, | ||
128 | * PREBOARD_E_INVALID_ARG when client or plist is NULL, | ||
129 | * PREBOARD_E_TIMEOUT when no data was received after the given timeout, | ||
130 | * or a PREBOARD_E_* error code on error. | ||
131 | */ | ||
132 | LIBIMOBILEDEVICE_API preboard_error_t preboard_receive_with_timeout(preboard_client_t client, plist_t * plist, uint32_t timeout_ms); | ||
133 | |||
134 | /** | ||
135 | * Tells the preboard service to create a stashbag. This will make the device | ||
136 | * show a passcode entry so it can generate and store a token that is later | ||
137 | * used during restore. | ||
138 | * | ||
139 | * @param client The preboard client | ||
140 | * @param manifest An optional manifest | ||
141 | * @param status_cb Callback function that will receive status and error messages. | ||
142 | * Can be NULL if you want to handle receiving messages in your own code. | ||
143 | * @param user_data User data for callback function or NULL. | ||
144 | * | ||
145 | * The callback or following preboard_receive* invocations will usually | ||
146 | * receive a dictionary with: | ||
147 | * { ShowDialog: true } | ||
148 | * If the user does not enter a passcode, after 2 minutes a timeout is reached | ||
149 | * and the device sends a dictionary with: | ||
150 | * { Timeout: true } | ||
151 | * followed by { HideDialog: true } | ||
152 | * If the user aborts the passcode entry, the device sends a dictionary: | ||
153 | * { Error: 1, ErrorString: \<error string\> } | ||
154 | * followed by { HideDialog: true } | ||
155 | * | ||
156 | * @return PREBOARD_E_SUCCESS if the command was successfully submitted, | ||
157 | * PREBOARD_E_INVALID_ARG when client is invalid, | ||
158 | * or a PREBOARD_E_* error code on error. | ||
159 | */ | ||
160 | LIBIMOBILEDEVICE_API preboard_error_t preboard_create_stashbag(preboard_client_t client, plist_t manifest, preboard_status_cb_t status_cb, void *user_data); | ||
161 | |||
162 | /** | ||
163 | * Instructs the preboard service to commit a previously created stashbag. | ||
164 | * | ||
165 | * @param client The preboard client to use for receiving | ||
166 | * @param manifest An optional manifest | ||
167 | * @param status_cb Callback function that will receive status and error messages | ||
168 | * Can be NULL if you want to handle receiving messages in your own code. | ||
169 | * @param user_data User data for callback function or NULL. | ||
170 | * | ||
171 | * The callback or following preboard_receive* invocations will usually | ||
172 | * receive a dictionary with: | ||
173 | * { StashbagCommitComplete: true } | ||
174 | * or in case of an error: | ||
175 | * { StashbagCommitComplete: 0, Error: 1, \<optional\> ErrorString: \<error string\> } | ||
176 | * | ||
177 | * @return PREBOARD_E_SUCCESS if the command was successfully submitted, | ||
178 | * PREBOARD_E_INVALID_ARG when client is invalid, | ||
179 | * or a PREBOARD_E_* error code on error. | ||
180 | */ | ||
181 | LIBIMOBILEDEVICE_API preboard_error_t preboard_commit_stashbag(preboard_client_t client, plist_t manifest, preboard_status_cb_t status_cb, void *user_data); | ||
182 | |||
183 | #ifdef __cplusplus | ||
184 | } | ||
185 | #endif | ||
186 | |||
187 | #endif | ||
diff --git a/include/libimobiledevice/property_list_service.h b/include/libimobiledevice/property_list_service.h new file mode 100644 index 0000000..e6b26a3 --- /dev/null +++ b/include/libimobiledevice/property_list_service.h | |||
@@ -0,0 +1,184 @@ | |||
1 | /** | ||
2 | * @file libimobiledevice/property_list_service.h | ||
3 | * @brief Definitions for the PropertyList service | ||
4 | * \internal | ||
5 | * | ||
6 | * Copyright (c) 2010-2014 Martin Szulecki All Rights Reserved. | ||
7 | * Copyright (c) 2010-2014 Nikias Bassen, All Rights Reserved. | ||
8 | * | ||
9 | * This library is free software; you can redistribute it and/or | ||
10 | * modify it under the terms of the GNU Lesser General Public | ||
11 | * License as published by the Free Software Foundation; either | ||
12 | * version 2.1 of the License, or (at your option) any later version. | ||
13 | * | ||
14 | * This library is distributed in the hope that it will be useful, | ||
15 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
16 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
17 | * Lesser General Public License for more details. | ||
18 | * | ||
19 | * You should have received a copy of the GNU Lesser General Public | ||
20 | * License along with this library; if not, write to the Free Software | ||
21 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | ||
22 | */ | ||
23 | |||
24 | #ifndef IPROPERTY_LIST_SERVICE_H | ||
25 | #define IPROPERTY_LIST_SERVICE_H | ||
26 | |||
27 | #ifdef __cplusplus | ||
28 | extern "C" { | ||
29 | #endif | ||
30 | |||
31 | #include <libimobiledevice/lockdown.h> | ||
32 | #include <libimobiledevice/service.h> | ||
33 | |||
34 | /** Error Codes */ | ||
35 | typedef enum { | ||
36 | PROPERTY_LIST_SERVICE_E_SUCCESS = 0, | ||
37 | PROPERTY_LIST_SERVICE_E_INVALID_ARG = -1, | ||
38 | PROPERTY_LIST_SERVICE_E_PLIST_ERROR = -2, | ||
39 | PROPERTY_LIST_SERVICE_E_MUX_ERROR = -3, | ||
40 | PROPERTY_LIST_SERVICE_E_SSL_ERROR = -4, | ||
41 | PROPERTY_LIST_SERVICE_E_RECEIVE_TIMEOUT = -5, | ||
42 | PROPERTY_LIST_SERVICE_E_NOT_ENOUGH_DATA = -6, | ||
43 | PROPERTY_LIST_SERVICE_E_UNKNOWN_ERROR = -256 | ||
44 | } property_list_service_error_t; | ||
45 | |||
46 | typedef struct property_list_service_client_private property_list_service_private; /**< \private */ | ||
47 | typedef property_list_service_private* property_list_service_client_t; /**< The client handle. */ | ||
48 | |||
49 | /* Interface */ | ||
50 | |||
51 | /** | ||
52 | * Creates a new property list service for the specified port. | ||
53 | * | ||
54 | * @param device The device to connect to. | ||
55 | * @param service The service descriptor returned by lockdownd_start_service. | ||
56 | * @param client Pointer that will be set to a newly allocated | ||
57 | * property_list_service_client_t upon successful return. | ||
58 | * | ||
59 | * @return PROPERTY_LIST_SERVICE_E_SUCCESS on success, | ||
60 | * PROPERTY_LIST_SERVICE_E_INVALID_ARG when one of the arguments is invalid, | ||
61 | * or PROPERTY_LIST_SERVICE_E_MUX_ERROR when connecting to the device failed. | ||
62 | */ | ||
63 | LIBIMOBILEDEVICE_API property_list_service_error_t property_list_service_client_new(idevice_t device, lockdownd_service_descriptor_t service, property_list_service_client_t *client); | ||
64 | |||
65 | /** | ||
66 | * Frees a PropertyList service. | ||
67 | * | ||
68 | * @param client The property list service to free. | ||
69 | * | ||
70 | * @return PROPERTY_LIST_SERVICE_E_SUCCESS on success, | ||
71 | * PROPERTY_LIST_SERVICE_E_INVALID_ARG when client is invalid, or a | ||
72 | * PROPERTY_LIST_SERVICE_E_UNKNOWN_ERROR when another error occurred. | ||
73 | */ | ||
74 | LIBIMOBILEDEVICE_API property_list_service_error_t property_list_service_client_free(property_list_service_client_t client); | ||
75 | |||
76 | /** | ||
77 | * Sends an XML plist. | ||
78 | * | ||
79 | * @param client The property list service client to use for sending. | ||
80 | * @param plist plist to send | ||
81 | * | ||
82 | * @return PROPERTY_LIST_SERVICE_E_SUCCESS on success, | ||
83 | * PROPERTY_LIST_SERVICE_E_INVALID_ARG when client or plist is NULL, | ||
84 | * PROPERTY_LIST_SERVICE_E_PLIST_ERROR when dict is not a valid plist, | ||
85 | * or PROPERTY_LIST_SERVICE_E_UNKNOWN_ERROR when an unspecified error occurs. | ||
86 | */ | ||
87 | LIBIMOBILEDEVICE_API property_list_service_error_t property_list_service_send_xml_plist(property_list_service_client_t client, plist_t plist); | ||
88 | |||
89 | /** | ||
90 | * Sends a binary plist. | ||
91 | * | ||
92 | * @param client The property list service client to use for sending. | ||
93 | * @param plist plist to send | ||
94 | * | ||
95 | * @return PROPERTY_LIST_SERVICE_E_SUCCESS on success, | ||
96 | * PROPERTY_LIST_SERVICE_E_INVALID_ARG when client or plist is NULL, | ||
97 | * PROPERTY_LIST_SERVICE_E_PLIST_ERROR when dict is not a valid plist, | ||
98 | * or PROPERTY_LIST_SERVICE_E_UNKNOWN_ERROR when an unspecified error occurs. | ||
99 | */ | ||
100 | LIBIMOBILEDEVICE_API property_list_service_error_t property_list_service_send_binary_plist(property_list_service_client_t client, plist_t plist); | ||
101 | |||
102 | /** | ||
103 | * Receives a plist using the given property list service client with specified | ||
104 | * timeout. | ||
105 | * Binary or XML plists are automatically handled. | ||
106 | * | ||
107 | * @param client The property list service client to use for receiving | ||
108 | * @param plist pointer to a plist_t that will point to the received plist | ||
109 | * upon successful return | ||
110 | * @param timeout Maximum time in milliseconds to wait for data. | ||
111 | * | ||
112 | * @return PROPERTY_LIST_SERVICE_E_SUCCESS on success, | ||
113 | * PROPERTY_LIST_SERVICE_E_INVALID_ARG when connection or *plist is NULL, | ||
114 | * PROPERTY_LIST_SERVICE_E_PLIST_ERROR when the received data cannot be | ||
115 | * converted to a plist, PROPERTY_LIST_SERVICE_E_MUX_ERROR when a | ||
116 | * communication error occurs, or PROPERTY_LIST_SERVICE_E_UNKNOWN_ERROR when | ||
117 | * an unspecified error occurs. | ||
118 | */ | ||
119 | LIBIMOBILEDEVICE_API property_list_service_error_t property_list_service_receive_plist_with_timeout(property_list_service_client_t client, plist_t *plist, unsigned int timeout); | ||
120 | |||
121 | /** | ||
122 | * Receives a plist using the given property list service client. | ||
123 | * Binary or XML plists are automatically handled. | ||
124 | * | ||
125 | * This function is like property_list_service_receive_plist_with_timeout | ||
126 | * using a timeout of 10 seconds. | ||
127 | * @see property_list_service_receive_plist_with_timeout | ||
128 | * | ||
129 | * @param client The property list service client to use for receiving | ||
130 | * @param plist pointer to a plist_t that will point to the received plist | ||
131 | * upon successful return | ||
132 | * | ||
133 | * @return PROPERTY_LIST_SERVICE_E_SUCCESS on success, | ||
134 | * PROPERTY_LIST_SERVICE_E_INVALID_ARG when client or *plist is NULL, | ||
135 | * PROPERTY_LIST_SERVICE_E_NOT_ENOUGH_DATA when not enough data | ||
136 | * received, PROPERTY_LIST_SERVICE_E_RECEIVE_TIMEOUT when the connection times out, | ||
137 | * PROPERTY_LIST_SERVICE_E_PLIST_ERROR when the received data cannot be | ||
138 | * converted to a plist, PROPERTY_LIST_SERVICE_E_MUX_ERROR when a | ||
139 | * communication error occurs, or PROPERTY_LIST_SERVICE_E_UNKNOWN_ERROR when | ||
140 | * an unspecified error occurs. | ||
141 | */ | ||
142 | LIBIMOBILEDEVICE_API property_list_service_error_t property_list_service_receive_plist(property_list_service_client_t client, plist_t *plist); | ||
143 | |||
144 | /** | ||
145 | * Enable SSL for the given property list service client. | ||
146 | * | ||
147 | * @param client The connected property list service client for which SSL | ||
148 | * should be enabled. | ||
149 | * | ||
150 | * @return PROPERTY_LIST_SERVICE_E_SUCCESS on success, | ||
151 | * PROPERTY_LIST_SERVICE_E_INVALID_ARG if one or more of the arguments are invalid, | ||
152 | * PROPERTY_LIST_SERVICE_E_SSL_ERROR when SSL could not be enabled, | ||
153 | * or PROPERTY_LIST_SERVICE_E_UNKNOWN_ERROR otherwise. | ||
154 | */ | ||
155 | LIBIMOBILEDEVICE_API property_list_service_error_t property_list_service_enable_ssl(property_list_service_client_t client); | ||
156 | |||
157 | /** | ||
158 | * Disable SSL for the given property list service client. | ||
159 | * | ||
160 | * @param client The connected property list service client for which SSL | ||
161 | * should be disabled. | ||
162 | * | ||
163 | * @return PROPERTY_LIST_SERVICE_E_SUCCESS on success, | ||
164 | * PROPERTY_LIST_SERVICE_E_INVALID_ARG if one or more of the arguments are invalid, | ||
165 | * or PROPERTY_LIST_SERVICE_E_UNKNOWN_ERROR otherwise. | ||
166 | */ | ||
167 | LIBIMOBILEDEVICE_API property_list_service_error_t property_list_service_disable_ssl(property_list_service_client_t client); | ||
168 | |||
169 | /** | ||
170 | * Return a handle to the parent #service_client_t of the given property list service client. | ||
171 | * | ||
172 | * @param client The property list service client | ||
173 | * @param service_client Pointer to be assigned to the parent #service_client_t | ||
174 | * | ||
175 | * @return PROPERTY_LIST_SERVICE_E_SUCCESS on success, | ||
176 | * PROPERTY_LIST_SERVICE_E_INVALID_ARG if one or more of the arguments are invalid. | ||
177 | */ | ||
178 | LIBIMOBILEDEVICE_API property_list_service_error_t property_list_service_get_service_client(property_list_service_client_t client, service_client_t *service_client); | ||
179 | |||
180 | #ifdef __cplusplus | ||
181 | } | ||
182 | #endif | ||
183 | |||
184 | #endif | ||
diff --git a/include/libimobiledevice/restore.h b/include/libimobiledevice/restore.h index 9c30b03..859dc98 100644 --- a/include/libimobiledevice/restore.h +++ b/include/libimobiledevice/restore.h | |||
@@ -1,8 +1,10 @@ | |||
1 | /** | 1 | /** |
2 | * @file libimobiledevice/restore.h | 2 | * @file libimobiledevice/restore.h |
3 | * @brief Initiate restore process or reboot device. | 3 | * @brief Initiate restore process or reboot device. |
4 | * @note This service is only available if the device is in restore mode. | ||
4 | * \internal | 5 | * \internal |
5 | * | 6 | * |
7 | * Copyright (c) 2010-2014 Martin Szulecki All Rights Reserved. | ||
6 | * Copyright (c) 2010 Joshua Hill. All Rights Reserved. | 8 | * Copyright (c) 2010 Joshua Hill. All Rights Reserved. |
7 | * | 9 | * |
8 | * This library is free software; you can redistribute it and/or | 10 | * This library is free software; you can redistribute it and/or |
@@ -20,8 +22,8 @@ | |||
20 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | 22 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA |
21 | */ | 23 | */ |
22 | 24 | ||
23 | #ifndef RESTORE_H | 25 | #ifndef IRESTORE_H |
24 | #define RESTORE_H | 26 | #define IRESTORE_H |
25 | 27 | ||
26 | #ifdef __cplusplus | 28 | #ifdef __cplusplus |
27 | extern "C" { | 29 | extern "C" { |
@@ -29,41 +31,146 @@ extern "C" { | |||
29 | 31 | ||
30 | #include <libimobiledevice/libimobiledevice.h> | 32 | #include <libimobiledevice/libimobiledevice.h> |
31 | 33 | ||
32 | /** @name Error Codes */ | 34 | /** Error Codes */ |
33 | /*@{*/ | 35 | typedef enum { |
34 | #define RESTORE_E_SUCCESS 0 | 36 | RESTORE_E_SUCCESS = 0, |
35 | #define RESTORE_E_INVALID_ARG -1 | 37 | RESTORE_E_INVALID_ARG = -1, |
36 | #define RESTORE_E_INVALID_CONF -2 | 38 | RESTORE_E_PLIST_ERROR = -2, |
37 | #define RESTORE_E_PLIST_ERROR -3 | 39 | RESTORE_E_MUX_ERROR = -3, |
38 | #define RESTORE_E_DICT_ERROR -4 | 40 | RESTORE_E_NOT_ENOUGH_DATA = -4, |
39 | #define RESTORE_E_NOT_ENOUGH_DATA -5 | 41 | RESTORE_E_RECEIVE_TIMEOUT = -5, |
40 | #define RESTORE_E_MUX_ERROR -6 | 42 | RESTORE_E_UNKNOWN_ERROR = -256 |
41 | #define RESTORE_E_START_RESTORE_FAILED -7 | 43 | } restored_error_t; |
42 | 44 | ||
43 | #define RESTORE_E_UNKNOWN_ERROR -256 | 45 | typedef struct restored_client_private restored_client_private; /**< \private */ |
44 | /*@}*/ | ||
45 | |||
46 | /** Represents an error code. */ | ||
47 | typedef int16_t restored_error_t; | ||
48 | |||
49 | typedef struct restored_client_private restored_client_private; | ||
50 | typedef restored_client_private *restored_client_t; /**< The client handle. */ | 46 | typedef restored_client_private *restored_client_t; /**< The client handle. */ |
51 | 47 | ||
52 | /* Interface */ | 48 | /* Interface */ |
53 | restored_error_t restored_client_new(idevice_t device, restored_client_t *client, const char *label); | ||
54 | restored_error_t restored_client_free(restored_client_t client); | ||
55 | 49 | ||
56 | restored_error_t restored_query_type(restored_client_t client, char **type, uint64_t *version); | 50 | /** |
57 | restored_error_t restored_get_value(restored_client_t client, const char *key, plist_t *value) ; | 51 | * Creates a new restored client for the device. |
58 | restored_error_t restored_send(restored_client_t client, plist_t plist); | 52 | * |
59 | restored_error_t restored_receive(restored_client_t client, plist_t *plist); | 53 | * @param device The device to create a restored client for |
60 | restored_error_t restored_goodbye(restored_client_t client); | 54 | * @param client The pointer to the location of the new restored_client |
55 | * @param label The label to use for communication. Usually the program name. | ||
56 | * | ||
57 | * @return RESTORE_E_SUCCESS on success, RESTORE_E_INVALID_ARG when client is NULL | ||
58 | */ | ||
59 | LIBIMOBILEDEVICE_API restored_error_t restored_client_new(idevice_t device, restored_client_t *client, const char *label); | ||
60 | |||
61 | /** | ||
62 | * Closes the restored client session if one is running and frees up the | ||
63 | * restored_client struct. | ||
64 | * | ||
65 | * @param client The restore client | ||
66 | * | ||
67 | * @return RESTORE_E_SUCCESS on success, RESTORE_E_INVALID_ARG when client is NULL | ||
68 | */ | ||
69 | LIBIMOBILEDEVICE_API restored_error_t restored_client_free(restored_client_t client); | ||
70 | |||
71 | |||
72 | /** | ||
73 | * Query the type of the service daemon. Depending on whether the device is | ||
74 | * queried in normal mode or restore mode, different types will be returned. | ||
75 | * | ||
76 | * @param client The restored client | ||
77 | * @param type The type returned by the service daemon. Pass NULL to ignore. | ||
78 | * @param version The restore protocol version. Pass NULL to ignore. | ||
79 | * | ||
80 | * @return RESTORE_E_SUCCESS on success, RESTORE_E_INVALID_ARG when client is NULL | ||
81 | */ | ||
82 | LIBIMOBILEDEVICE_API restored_error_t restored_query_type(restored_client_t client, char **type, uint64_t *version); | ||
83 | |||
84 | /** | ||
85 | * Queries a value from the device specified by a key. | ||
86 | * | ||
87 | * @param client An initialized restored client. | ||
88 | * @param key The key name to request | ||
89 | * @param value A plist node representing the result value node | ||
90 | * | ||
91 | * @return RESTORE_E_SUCCESS on success, RESTORE_E_INVALID_ARG when client is NULL, RESTORE_E_PLIST_ERROR if value for key can't be found | ||
92 | */ | ||
93 | LIBIMOBILEDEVICE_API restored_error_t restored_query_value(restored_client_t client, const char *key, plist_t *value); | ||
94 | |||
95 | /** | ||
96 | * Retrieves a value from information plist specified by a key. | ||
97 | * | ||
98 | * @param client An initialized restored client. | ||
99 | * @param key The key name to request or NULL to query for all keys | ||
100 | * @param value A plist node representing the result value node | ||
101 | * | ||
102 | * @return RESTORE_E_SUCCESS on success, RESTORE_E_INVALID_ARG when client is NULL, RESTORE_E_PLIST_ERROR if value for key can't be found | ||
103 | */ | ||
104 | LIBIMOBILEDEVICE_API restored_error_t restored_get_value(restored_client_t client, const char *key, plist_t *value) ; | ||
105 | |||
106 | /** | ||
107 | * Sends a plist to restored. | ||
108 | * | ||
109 | * @note This function is low-level and should only be used if you need to send | ||
110 | * a new type of message. | ||
111 | * | ||
112 | * @param client The restored client | ||
113 | * @param plist The plist to send | ||
114 | * | ||
115 | * @return RESTORE_E_SUCCESS on success, RESTORE_E_INVALID_ARG when client or | ||
116 | * plist is NULL | ||
117 | */ | ||
118 | LIBIMOBILEDEVICE_API restored_error_t restored_send(restored_client_t client, plist_t plist); | ||
119 | |||
120 | /** | ||
121 | * Receives a plist from restored. | ||
122 | * | ||
123 | * @param client The restored client | ||
124 | * @param plist The plist to store the received data | ||
125 | * | ||
126 | * @return RESTORE_E_SUCCESS on success, RESTORE_E_INVALID_ARG when client or | ||
127 | * plist is NULL | ||
128 | */ | ||
129 | LIBIMOBILEDEVICE_API restored_error_t restored_receive(restored_client_t client, plist_t *plist); | ||
130 | |||
131 | /** | ||
132 | * Sends the Goodbye request to restored signaling the end of communication. | ||
133 | * | ||
134 | * @param client The restore client | ||
135 | * | ||
136 | * @return RESTORE_E_SUCCESS on success, RESTORE_E_INVALID_ARG when client is NULL, | ||
137 | * RESTORE_E_PLIST_ERROR if the device did not acknowledge the request | ||
138 | */ | ||
139 | LIBIMOBILEDEVICE_API restored_error_t restored_goodbye(restored_client_t client); | ||
61 | 140 | ||
62 | restored_error_t restored_start_restore(restored_client_t client); | 141 | |
63 | restored_error_t restored_reboot(restored_client_t client); | 142 | /** |
143 | * Requests to start a restore and retrieve it's port on success. | ||
144 | * | ||
145 | * @param client The restored client | ||
146 | * @param options PLIST_DICT with options for the restore process or NULL | ||
147 | * @param version the restore protocol version, see restored_query_type() | ||
148 | * | ||
149 | * @return RESTORE_E_SUCCESS on success, RESTORE_E_INVALID_ARG if a parameter | ||
150 | * is NULL, RESTORE_E_START_RESTORE_FAILED if the request fails | ||
151 | */ | ||
152 | LIBIMOBILEDEVICE_API restored_error_t restored_start_restore(restored_client_t client, plist_t options, uint64_t version); | ||
153 | |||
154 | /** | ||
155 | * Requests device to reboot. | ||
156 | * | ||
157 | * @param client The restored client | ||
158 | * | ||
159 | * @return RESTORE_E_SUCCESS on success, RESTORE_E_INVALID_ARG if a parameter | ||
160 | * is NULL | ||
161 | */ | ||
162 | LIBIMOBILEDEVICE_API restored_error_t restored_reboot(restored_client_t client); | ||
64 | 163 | ||
65 | /* Helper */ | 164 | /* Helper */ |
66 | void restored_client_set_label(restored_client_t client, const char *label); | 165 | |
166 | /** | ||
167 | * Sets the label to send for requests to restored. | ||
168 | * | ||
169 | * @param client The restore client | ||
170 | * @param label The label to set or NULL to disable sending a label | ||
171 | * | ||
172 | */ | ||
173 | LIBIMOBILEDEVICE_API void restored_client_set_label(restored_client_t client, const char *label); | ||
67 | 174 | ||
68 | #ifdef __cplusplus | 175 | #ifdef __cplusplus |
69 | } | 176 | } |
diff --git a/include/libimobiledevice/reverse_proxy.h b/include/libimobiledevice/reverse_proxy.h new file mode 100644 index 0000000..5e2f54b --- /dev/null +++ b/include/libimobiledevice/reverse_proxy.h | |||
@@ -0,0 +1,213 @@ | |||
1 | /** | ||
2 | * @file libimobiledevice/reverse_proxy.h | ||
3 | * @brief Provide a reverse proxy to allow the device to communicate through, | ||
4 | * which is used during firmware restore. | ||
5 | * \internal | ||
6 | * | ||
7 | * Copyright (c) 2021 Nikias Bassen, All Rights Reserved. | ||
8 | * | ||
9 | * This library is free software; you can redistribute it and/or | ||
10 | * modify it under the terms of the GNU Lesser General Public | ||
11 | * License as published by the Free Software Foundation; either | ||
12 | * version 2.1 of the License, or (at your option) any later version. | ||
13 | * | ||
14 | * This library is distributed in the hope that it will be useful, | ||
15 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
16 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
17 | * Lesser General Public License for more details. | ||
18 | * | ||
19 | * You should have received a copy of the GNU Lesser General Public | ||
20 | * License along with this library; if not, write to the Free Software | ||
21 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | ||
22 | */ | ||
23 | |||
24 | #ifndef IREVERSE_PROXY_H | ||
25 | #define IREVERSE_PROXY_H | ||
26 | |||
27 | #ifdef __cplusplus | ||
28 | extern "C" { | ||
29 | #endif | ||
30 | |||
31 | #include <libimobiledevice/libimobiledevice.h> | ||
32 | |||
33 | #define REVERSE_PROXY_DEFAULT_PORT 1082 /**< default port the reverse proxy is listening on */ | ||
34 | |||
35 | /** Error Codes */ | ||
36 | typedef enum { | ||
37 | REVERSE_PROXY_E_SUCCESS = 0, | ||
38 | REVERSE_PROXY_E_INVALID_ARG = -1, | ||
39 | REVERSE_PROXY_E_PLIST_ERROR = -2, | ||
40 | REVERSE_PROXY_E_MUX_ERROR = -3, | ||
41 | REVERSE_PROXY_E_SSL_ERROR = -4, | ||
42 | REVERSE_PROXY_E_NOT_ENOUGH_DATA = -5, | ||
43 | REVERSE_PROXY_E_TIMEOUT = -6, | ||
44 | REVERSE_PROXY_E_UNKNOWN_ERROR = -256 | ||
45 | } reverse_proxy_error_t; | ||
46 | |||
47 | typedef struct reverse_proxy_client_private reverse_proxy_client_private; /**< \private */ | ||
48 | typedef reverse_proxy_client_private *reverse_proxy_client_t; /**< The client handle. */ | ||
49 | |||
50 | /** reverse proxy client type */ | ||
51 | typedef enum { | ||
52 | RP_TYPE_CTRL = 1, /**< control connection */ | ||
53 | RP_TYPE_CONN /**< proxy connection */ | ||
54 | } reverse_proxy_client_type_t; | ||
55 | |||
56 | /** reverse proxy status for reverse_proxy_status_cb_t callback */ | ||
57 | typedef enum { | ||
58 | RP_STATUS_READY = 1, /**< proxy is ready */ | ||
59 | RP_STATUS_TERMINATE, /**< proxy terminated */ | ||
60 | RP_STATUS_CONNECT_REQ, /**< connection request received (only RP_TYPE_CTRL) */ | ||
61 | RP_STATUS_SHUTDOWN_REQ, /**< shutdown request received (only RP_TYPE_CTRL) */ | ||
62 | RP_STATUS_CONNECTED, /**< connection established (only RP_TYPE_CONN) */ | ||
63 | RP_STATUS_DISCONNECTED, /**< connection closed (only RP_TYPE_CONN) */ | ||
64 | } reverse_proxy_status_t; | ||
65 | |||
66 | /** reverse proxy data direction passed to reverse_proxy_data_cb_t callback */ | ||
67 | typedef enum { | ||
68 | RP_DATA_DIRECTION_OUT = 1, /**< data going out to remote host */ | ||
69 | RP_DATA_DIRECTION_IN /**< data coming in from remote host */ | ||
70 | } reverse_proxy_data_direction_t; | ||
71 | |||
72 | /** | ||
73 | * Log callback function prototype. | ||
74 | * | ||
75 | * @param client The client that called the callback function | ||
76 | * @param log_msg The log message | ||
77 | * @param user_data The user_data pointer that was set when registering the callback | ||
78 | */ | ||
79 | typedef void (*reverse_proxy_log_cb_t) (reverse_proxy_client_t client, const char* log_msg, void* user_data); | ||
80 | |||
81 | /** | ||
82 | * Data callback function prototype. | ||
83 | * | ||
84 | * @param client The client that called the callback function | ||
85 | * @param direction The direction of the data, either RP_DATA_DIRECTION_OUT or RP_DATA_DIRECTION_IN | ||
86 | * @param buffer The data buffer | ||
87 | * @param length The length of the data buffer | ||
88 | * @param user_data The user_data pointer that was set when registering the callback | ||
89 | */ | ||
90 | typedef void (*reverse_proxy_data_cb_t) (reverse_proxy_client_t client, reverse_proxy_data_direction_t direction, const char* buffer, uint32_t length, void* user_data); | ||
91 | |||
92 | /** | ||
93 | * Status callback function prototype. | ||
94 | * | ||
95 | * @param client The client that called the callback function | ||
96 | * @param status The status the client is reporting | ||
97 | * @param status_msg A status message the client reports along with the status | ||
98 | * @param user_data The user_data pointer that was set when registering the callback | ||
99 | */ | ||
100 | typedef void (*reverse_proxy_status_cb_t) (reverse_proxy_client_t client, reverse_proxy_status_t status, const char* status_msg, void* user_data); | ||
101 | |||
102 | /** | ||
103 | * Create a reverse proxy client using com.apple.PurpleReverseProxy.Ctrl and | ||
104 | * com.apple.PurpleReverseProxy.Conn lockdown services. This will open a port | ||
105 | * 1083 on the device that iOS apps could connect to; \b however that is | ||
106 | * only allowed if an app has the com.apple.private.PurpleReverseProxy.allowed | ||
107 | * entitlement, which currently only \c /usr/libexec/fdrhelper holds. | ||
108 | * | ||
109 | * @note This function only creates and initializes the reverse proxy; | ||
110 | * to make it operational, call reverse_proxy_client_start_proxy(). | ||
111 | * | ||
112 | * @param device The device to connect to. | ||
113 | * @param client Pointer that will be set to a newly allocated #reverse_proxy_client_t | ||
114 | * upon successful return. | ||
115 | * @param label A label to pass to lockdownd when creating the service | ||
116 | * connections, usually the program name. | ||
117 | * | ||
118 | * @return REVERSE_PROXY_E_SUCCESS on success, | ||
119 | * or a REVERSE_PROXY_E_* error code otherwise. | ||
120 | */ | ||
121 | LIBIMOBILEDEVICE_API reverse_proxy_error_t reverse_proxy_client_create_with_service(idevice_t device, reverse_proxy_client_t* client, const char* label); | ||
122 | |||
123 | /** | ||
124 | * Create a reverse proxy client using an open port on the device. This is | ||
125 | * used during firmware restores with the default port REVERSE_PROXY_DEFAULT_PORT (1082). | ||
126 | * | ||
127 | * @note This function only creates and initializes the reverse proxy; | ||
128 | * to make it operational, call reverse_proxy_client_start_proxy(). | ||
129 | * | ||
130 | * @param device The device to connect to. | ||
131 | * @param client Pointer that will be set to a newly allocated reverse_proxy_client_t | ||
132 | * upon successful return. | ||
133 | * @param device_port An open port on the device. Unless it's being used for | ||
134 | * a custom implementation, pass REVERSE_PROXY_DEFAULT_PORT here. | ||
135 | * | ||
136 | * @return REVERSE_PROXY_E_SUCCESS on success, | ||
137 | * or a REVERSE_PROXY_E_* error code otherwise. | ||
138 | */ | ||
139 | LIBIMOBILEDEVICE_API reverse_proxy_error_t reverse_proxy_client_create_with_port(idevice_t device, reverse_proxy_client_t* client, uint16_t device_port); | ||
140 | |||
141 | /** | ||
142 | * Disconnects a reverse proxy client and frees up the client data. | ||
143 | * | ||
144 | * @param client The reverse proxy client to disconnect and free. | ||
145 | */ | ||
146 | LIBIMOBILEDEVICE_API reverse_proxy_error_t reverse_proxy_client_free(reverse_proxy_client_t client); | ||
147 | |||
148 | /** | ||
149 | * Make an initialized reverse proxy client operational, i.e. start the actual proxy. | ||
150 | * | ||
151 | * @param client The reverse proxy client to start. | ||
152 | * @param control_protocol_version The control protocol version to use. | ||
153 | * This is either 1 or 2. Recent devices use 2. | ||
154 | * | ||
155 | * @return REVERSE_PROXY_E_SUCCESS on success, | ||
156 | * or a REVERSE_PROXY_E_* error code otherwise. | ||
157 | */ | ||
158 | LIBIMOBILEDEVICE_API reverse_proxy_error_t reverse_proxy_client_start_proxy(reverse_proxy_client_t client, int control_protocol_version); | ||
159 | |||
160 | /** | ||
161 | * Set a status callback function. This allows to report the status of the | ||
162 | * reverse proxy, like Ready, Connect Request, Connected, etc. | ||
163 | * | ||
164 | * @note Set the callback before calling reverse_proxy_client_start_proxy(). | ||
165 | * | ||
166 | * @param client The reverse proxy client | ||
167 | * @param callback The status callback function that will be called | ||
168 | * when the status of the reverse proxy changes. | ||
169 | * @param user_data A pointer that will be passed to the callback function. | ||
170 | */ | ||
171 | LIBIMOBILEDEVICE_API void reverse_proxy_client_set_status_callback(reverse_proxy_client_t client, reverse_proxy_status_cb_t callback, void* user_data); | ||
172 | |||
173 | /** | ||
174 | * Set a log callback function. Useful for debugging or verbosity. | ||
175 | * | ||
176 | * @note Set the callback before calling reverse_proxy_client_start_proxy(). | ||
177 | * | ||
178 | * @param client The reverse proxy client | ||
179 | * @param callback The log callback function that will be called | ||
180 | * when the reverse proxy logs something. | ||
181 | * @param user_data A pointer that will be passed to the callback function. | ||
182 | */ | ||
183 | LIBIMOBILEDEVICE_API void reverse_proxy_client_set_log_callback(reverse_proxy_client_t client, reverse_proxy_log_cb_t callback, void* user_data); | ||
184 | |||
185 | /** | ||
186 | * Set a data callback function. Useful for debugging or extra verbosity. | ||
187 | * | ||
188 | * @note Set the callback before calling reverse_proxy_client_start_proxy(). | ||
189 | * | ||
190 | * @param client The reverse proxy client | ||
191 | * @param callback The status callback function that will be called | ||
192 | * when the status of the reverse proxy changes. | ||
193 | * @param user_data A pointer that will be passed to the callback function. | ||
194 | */ | ||
195 | |||
196 | LIBIMOBILEDEVICE_API void reverse_proxy_client_set_data_callback(reverse_proxy_client_t client, reverse_proxy_data_cb_t callback, void* user_data); | ||
197 | |||
198 | /** | ||
199 | * Helper function to return the type of a given reverse proxy client, which | ||
200 | * is either RP_TYPE_CTRL or RP_TYPE_CONN. Useful for callback functions. | ||
201 | * @see reverse_proxy_client_type_t | ||
202 | * | ||
203 | * @param client The reverse proxy client | ||
204 | * | ||
205 | * @return The type of the rerverse proxy client | ||
206 | */ | ||
207 | LIBIMOBILEDEVICE_API reverse_proxy_client_type_t reverse_proxy_get_type(reverse_proxy_client_t client); | ||
208 | |||
209 | #ifdef __cplusplus | ||
210 | } | ||
211 | #endif | ||
212 | |||
213 | #endif | ||
diff --git a/include/libimobiledevice/sbservices.h b/include/libimobiledevice/sbservices.h index 616168e..7435947 100644 --- a/include/libimobiledevice/sbservices.h +++ b/include/libimobiledevice/sbservices.h | |||
@@ -3,7 +3,8 @@ | |||
3 | * @brief Manage SpringBoard icons and retrieve icon images. | 3 | * @brief Manage SpringBoard icons and retrieve icon images. |
4 | * \internal | 4 | * \internal |
5 | * | 5 | * |
6 | * Copyright (c) 2009 Nikias Bassen All Rights Reserved. | 6 | * Copyright (c) 2010-2014 Martin Szulecki All Rights Reserved. |
7 | * Copyright (c) 2009-2010 Nikias Bassen All Rights Reserved. | ||
7 | * | 8 | * |
8 | * This library is free software; you can redistribute it and/or | 9 | * This library is free software; you can redistribute it and/or |
9 | * modify it under the terms of the GNU Lesser General Public | 10 | * modify it under the terms of the GNU Lesser General Public |
@@ -20,38 +21,152 @@ | |||
20 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | 21 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA |
21 | */ | 22 | */ |
22 | 23 | ||
23 | #ifndef SB_SERVICES_H | 24 | #ifndef ISB_SERVICES_H |
24 | #define SB_SERVICES_H | 25 | #define ISB_SERVICES_H |
25 | 26 | ||
26 | #ifdef __cplusplus | 27 | #ifdef __cplusplus |
27 | extern "C" { | 28 | extern "C" { |
28 | #endif | 29 | #endif |
29 | 30 | ||
30 | #include <libimobiledevice/libimobiledevice.h> | 31 | #include <libimobiledevice/libimobiledevice.h> |
32 | #include <libimobiledevice/lockdown.h> | ||
31 | 33 | ||
32 | /** @name Error Codes */ | 34 | /** Service identifier passed to lockdownd_start_service() to start the springboardservices service */ |
33 | /*@{*/ | 35 | #define SBSERVICES_SERVICE_NAME "com.apple.springboardservices" |
34 | #define SBSERVICES_E_SUCCESS 0 | ||
35 | #define SBSERVICES_E_INVALID_ARG -1 | ||
36 | #define SBSERVICES_E_PLIST_ERROR -2 | ||
37 | #define SBSERVICES_E_CONN_FAILED -3 | ||
38 | 36 | ||
39 | #define SBSERVICES_E_UNKNOWN_ERROR -256 | 37 | /** Error Codes */ |
40 | /*@}*/ | 38 | typedef enum { |
39 | SBSERVICES_E_SUCCESS = 0, | ||
40 | SBSERVICES_E_INVALID_ARG = -1, | ||
41 | SBSERVICES_E_PLIST_ERROR = -2, | ||
42 | SBSERVICES_E_CONN_FAILED = -3, | ||
43 | SBSERVICES_E_UNKNOWN_ERROR = -256 | ||
44 | } sbservices_error_t; | ||
41 | 45 | ||
42 | /** Represents an error code. */ | 46 | /** Orientation of the user interface on the device */ |
43 | typedef int16_t sbservices_error_t; | 47 | typedef enum { |
48 | SBSERVICES_INTERFACE_ORIENTATION_UNKNOWN = 0, | ||
49 | SBSERVICES_INTERFACE_ORIENTATION_PORTRAIT = 1, | ||
50 | SBSERVICES_INTERFACE_ORIENTATION_PORTRAIT_UPSIDE_DOWN = 2, | ||
51 | SBSERVICES_INTERFACE_ORIENTATION_LANDSCAPE_RIGHT = 3, | ||
52 | SBSERVICES_INTERFACE_ORIENTATION_LANDSCAPE_LEFT = 4 | ||
53 | } sbservices_interface_orientation_t; | ||
44 | 54 | ||
45 | typedef struct sbservices_client_private sbservices_client_private; | 55 | typedef struct sbservices_client_private sbservices_client_private; /**< \private */ |
46 | typedef sbservices_client_private *sbservices_client_t; /**< The client handle. */ | 56 | typedef sbservices_client_private *sbservices_client_t; /**< The client handle. */ |
47 | 57 | ||
48 | /* Interface */ | 58 | /* Interface */ |
49 | sbservices_error_t sbservices_client_new(idevice_t device, uint16_t port, sbservices_client_t *client); | 59 | |
50 | sbservices_error_t sbservices_client_free(sbservices_client_t client); | 60 | /** |
51 | sbservices_error_t sbservices_get_icon_state(sbservices_client_t client, plist_t *state, const char *format_version); | 61 | * Connects to the springboardservices service on the specified device. |
52 | sbservices_error_t sbservices_set_icon_state(sbservices_client_t client, plist_t newstate); | 62 | * |
53 | sbservices_error_t sbservices_get_icon_pngdata(sbservices_client_t client, const char *bundleId, char **pngdata, uint64_t *pngsize); | 63 | * @param device The device to connect to. |
54 | sbservices_error_t sbservices_get_home_screen_wallpaper_pngdata(sbservices_client_t client, char **pngdata, uint64_t *pngsize); | 64 | * @param service The service descriptor returned by lockdownd_start_service. |
65 | * @param client Pointer that will point to a newly allocated | ||
66 | * sbservices_client_t upon successful return. | ||
67 | * | ||
68 | * @return SBSERVICES_E_SUCCESS on success, SBSERVICES_E_INVALID_ARG when | ||
69 | * client is NULL, or an SBSERVICES_E_* error code otherwise. | ||
70 | */ | ||
71 | LIBIMOBILEDEVICE_API sbservices_error_t sbservices_client_new(idevice_t device, lockdownd_service_descriptor_t service, sbservices_client_t *client); | ||
72 | |||
73 | /** | ||
74 | * Starts a new sbservices service on the specified device and connects to it. | ||
75 | * | ||
76 | * @param device The device to connect to. | ||
77 | * @param client Pointer that will point to a newly allocated | ||
78 | * sbservices_client_t upon successful return. Must be freed using | ||
79 | * sbservices_client_free() after use. | ||
80 | * @param label The label to use for communication. Usually the program name. | ||
81 | * Pass NULL to disable sending the label in requests to lockdownd. | ||
82 | * | ||
83 | * @return SBSERVICES_E_SUCCESS on success, or an SBSERVICES_E_* error | ||
84 | * code otherwise. | ||
85 | */ | ||
86 | LIBIMOBILEDEVICE_API sbservices_error_t sbservices_client_start_service(idevice_t device, sbservices_client_t* client, const char* label); | ||
87 | |||
88 | /** | ||
89 | * Disconnects an sbservices client from the device and frees up the | ||
90 | * sbservices client data. | ||
91 | * | ||
92 | * @param client The sbservices client to disconnect and free. | ||
93 | * | ||
94 | * @return SBSERVICES_E_SUCCESS on success, SBSERVICES_E_INVALID_ARG when | ||
95 | * client is NULL, or an SBSERVICES_E_* error code otherwise. | ||
96 | */ | ||
97 | LIBIMOBILEDEVICE_API sbservices_error_t sbservices_client_free(sbservices_client_t client); | ||
98 | |||
99 | |||
100 | /** | ||
101 | * Gets the icon state of the connected device. | ||
102 | * | ||
103 | * @param client The connected sbservices client to use. | ||
104 | * @param state Pointer that will point to a newly allocated plist containing | ||
105 | * the current icon state. It is up to the caller to free the memory. | ||
106 | * @param format_version A string to be passed as formatVersion along with | ||
107 | * the request, or NULL if no formatVersion should be passed. This is only | ||
108 | * supported since iOS 4.0 so for older firmware versions this must be set | ||
109 | * to NULL. | ||
110 | * | ||
111 | * @return SBSERVICES_E_SUCCESS on success, SBSERVICES_E_INVALID_ARG when | ||
112 | * client or state is invalid, or an SBSERVICES_E_* error code otherwise. | ||
113 | */ | ||
114 | LIBIMOBILEDEVICE_API sbservices_error_t sbservices_get_icon_state(sbservices_client_t client, plist_t *state, const char *format_version); | ||
115 | |||
116 | /** | ||
117 | * Sets the icon state of the connected device. | ||
118 | * | ||
119 | * @param client The connected sbservices client to use. | ||
120 | * @param newstate A plist containing the new iconstate. | ||
121 | * | ||
122 | * @return SBSERVICES_E_SUCCESS on success, SBSERVICES_E_INVALID_ARG when | ||
123 | * client or newstate is NULL, or an SBSERVICES_E_* error code otherwise. | ||
124 | */ | ||
125 | LIBIMOBILEDEVICE_API sbservices_error_t sbservices_set_icon_state(sbservices_client_t client, plist_t newstate); | ||
126 | |||
127 | /** | ||
128 | * Get the icon of the specified app as PNG data. | ||
129 | * | ||
130 | * @param client The connected sbservices client to use. | ||
131 | * @param bundleId The bundle identifier of the app to retrieve the icon for. | ||
132 | * @param pngdata Pointer that will point to a newly allocated buffer | ||
133 | * containing the PNG data upon successful return. It is up to the caller | ||
134 | * to free the memory. | ||
135 | * @param pngsize Pointer to a uint64_t that will be set to the size of the | ||
136 | * buffer pngdata points to upon successful return. | ||
137 | * | ||
138 | * @return SBSERVICES_E_SUCCESS on success, SBSERVICES_E_INVALID_ARG when | ||
139 | * client, bundleId, or pngdata are invalid, or an SBSERVICES_E_* error | ||
140 | * code otherwise. | ||
141 | */ | ||
142 | LIBIMOBILEDEVICE_API sbservices_error_t sbservices_get_icon_pngdata(sbservices_client_t client, const char *bundleId, char **pngdata, uint64_t *pngsize); | ||
143 | |||
144 | /** | ||
145 | * Gets the interface orientation of the device. | ||
146 | * | ||
147 | * @param client The connected sbservices client to use. | ||
148 | * @param interface_orientation The interface orientation upon successful return. | ||
149 | * | ||
150 | * @return SBSERVICES_E_SUCCESS on success, SBSERVICES_E_INVALID_ARG when | ||
151 | * client or state is invalid, or an SBSERVICES_E_* error code otherwise. | ||
152 | */ | ||
153 | LIBIMOBILEDEVICE_API sbservices_error_t sbservices_get_interface_orientation(sbservices_client_t client, sbservices_interface_orientation_t* interface_orientation); | ||
154 | |||
155 | /** | ||
156 | * Get the home screen wallpaper as PNG data. | ||
157 | * | ||
158 | * @param client The connected sbservices client to use. | ||
159 | * @param pngdata Pointer that will point to a newly allocated buffer | ||
160 | * containing the PNG data upon successful return. It is up to the caller | ||
161 | * to free the memory. | ||
162 | * @param pngsize Pointer to a uint64_t that will be set to the size of the | ||
163 | * buffer pngdata points to upon successful return. | ||
164 | * | ||
165 | * @return SBSERVICES_E_SUCCESS on success, SBSERVICES_E_INVALID_ARG when | ||
166 | * client or pngdata are invalid, or an SBSERVICES_E_* error | ||
167 | * code otherwise. | ||
168 | */ | ||
169 | LIBIMOBILEDEVICE_API sbservices_error_t sbservices_get_home_screen_wallpaper_pngdata(sbservices_client_t client, char **pngdata, uint64_t *pngsize); | ||
55 | 170 | ||
56 | #ifdef __cplusplus | 171 | #ifdef __cplusplus |
57 | } | 172 | } |
diff --git a/include/libimobiledevice/screenshotr.h b/include/libimobiledevice/screenshotr.h index b3669ee..db3c969 100644 --- a/include/libimobiledevice/screenshotr.h +++ b/include/libimobiledevice/screenshotr.h | |||
@@ -4,7 +4,8 @@ | |||
4 | * @note Requires a mounted developer image. | 4 | * @note Requires a mounted developer image. |
5 | * \internal | 5 | * \internal |
6 | * | 6 | * |
7 | * Copyright (c) 2010 Nikias Bassen All Rights Reserved. | 7 | * Copyright (c) 2010-2019 Nikias Bassen, All Rights Reserved. |
8 | * Copyright (c) 2010-2014 Martin Szulecki, All Rights Reserved. | ||
8 | * | 9 | * |
9 | * This library is free software; you can redistribute it and/or | 10 | * This library is free software; you can redistribute it and/or |
10 | * modify it under the terms of the GNU Lesser General Public | 11 | * modify it under the terms of the GNU Lesser General Public |
@@ -29,27 +30,86 @@ extern "C" { | |||
29 | #endif | 30 | #endif |
30 | 31 | ||
31 | #include <libimobiledevice/libimobiledevice.h> | 32 | #include <libimobiledevice/libimobiledevice.h> |
33 | #include <libimobiledevice/lockdown.h> | ||
32 | 34 | ||
33 | /** @name Error Codes */ | 35 | /** Service identifier passed to lockdownd_start_service() to start the screenshotr service */ |
34 | /*@{*/ | 36 | #define SCREENSHOTR_SERVICE_NAME "com.apple.mobile.screenshotr" |
35 | #define SCREENSHOTR_E_SUCCESS 0 | ||
36 | #define SCREENSHOTR_E_INVALID_ARG -1 | ||
37 | #define SCREENSHOTR_E_PLIST_ERROR -2 | ||
38 | #define SCREENSHOTR_E_MUX_ERROR -3 | ||
39 | #define SCREENSHOTR_E_BAD_VERSION -4 | ||
40 | 37 | ||
41 | #define SCREENSHOTR_E_UNKNOWN_ERROR -256 | 38 | /** Error Codes */ |
42 | /*@}*/ | 39 | typedef enum { |
40 | SCREENSHOTR_E_SUCCESS = 0, | ||
41 | SCREENSHOTR_E_INVALID_ARG = -1, | ||
42 | SCREENSHOTR_E_PLIST_ERROR = -2, | ||
43 | SCREENSHOTR_E_MUX_ERROR = -3, | ||
44 | SCREENSHOTR_E_SSL_ERROR = -4, | ||
45 | SCREENSHOTR_E_RECEIVE_TIMEOUT = -5, | ||
46 | SCREENSHOTR_E_BAD_VERSION = -6, | ||
47 | SCREENSHOTR_E_UNKNOWN_ERROR = -256 | ||
48 | } screenshotr_error_t; | ||
43 | 49 | ||
44 | /** Represents an error code. */ | 50 | typedef struct screenshotr_client_private screenshotr_client_private; /**< \private */ |
45 | typedef int16_t screenshotr_error_t; | ||
46 | |||
47 | typedef struct screenshotr_client_private screenshotr_client_private; | ||
48 | typedef screenshotr_client_private *screenshotr_client_t; /**< The client handle. */ | 51 | typedef screenshotr_client_private *screenshotr_client_t; /**< The client handle. */ |
49 | 52 | ||
50 | screenshotr_error_t screenshotr_client_new(idevice_t device, uint16_t port, screenshotr_client_t * client); | 53 | |
51 | screenshotr_error_t screenshotr_client_free(screenshotr_client_t client); | 54 | /** |
52 | screenshotr_error_t screenshotr_take_screenshot(screenshotr_client_t client, char **imgdata, uint64_t *imgsize); | 55 | * Connects to the screenshotr service on the specified device. |
56 | * | ||
57 | * @param device The device to connect to. | ||
58 | * @param service The service descriptor returned by lockdownd_start_service. | ||
59 | * @param client Pointer that will be set to a newly allocated | ||
60 | * screenshotr_client_t upon successful return. | ||
61 | * | ||
62 | * @note This service is only available if a developer disk image has been | ||
63 | * mounted. | ||
64 | * | ||
65 | * @return SCREENSHOTR_E_SUCCESS on success, SCREENSHOTR_E_INVALID ARG if one | ||
66 | * or more parameters are invalid, or SCREENSHOTR_E_CONN_FAILED if the | ||
67 | * connection to the device could not be established. | ||
68 | */ | ||
69 | LIBIMOBILEDEVICE_API screenshotr_error_t screenshotr_client_new(idevice_t device, lockdownd_service_descriptor_t service, screenshotr_client_t * client); | ||
70 | |||
71 | /** | ||
72 | * Starts a new screenshotr service on the specified device and connects to it. | ||
73 | * | ||
74 | * @param device The device to connect to. | ||
75 | * @param client Pointer that will point to a newly allocated | ||
76 | * screenshotr_client_t upon successful return. Must be freed using | ||
77 | * screenshotr_client_free() after use. | ||
78 | * @param label The label to use for communication. Usually the program name. | ||
79 | * Pass NULL to disable sending the label in requests to lockdownd. | ||
80 | * | ||
81 | * @return SCREENSHOTR_E_SUCCESS on success, or an SCREENSHOTR_E_* error | ||
82 | * code otherwise. | ||
83 | */ | ||
84 | LIBIMOBILEDEVICE_API screenshotr_error_t screenshotr_client_start_service(idevice_t device, screenshotr_client_t* client, const char* label); | ||
85 | |||
86 | /** | ||
87 | * Disconnects a screenshotr client from the device and frees up the | ||
88 | * screenshotr client data. | ||
89 | * | ||
90 | * @param client The screenshotr client to disconnect and free. | ||
91 | * | ||
92 | * @return SCREENSHOTR_E_SUCCESS on success, or SCREENSHOTR_E_INVALID_ARG | ||
93 | * if client is NULL. | ||
94 | */ | ||
95 | LIBIMOBILEDEVICE_API screenshotr_error_t screenshotr_client_free(screenshotr_client_t client); | ||
96 | |||
97 | |||
98 | /** | ||
99 | * Get a screen shot from the connected device. | ||
100 | * | ||
101 | * @param client The connection screenshotr service client. | ||
102 | * @param imgdata Pointer that will point to a newly allocated buffer | ||
103 | * containing TIFF image data upon successful return. It is up to the | ||
104 | * caller to free the memory. | ||
105 | * @param imgsize Pointer to a uint64_t that will be set to the size of the | ||
106 | * buffer imgdata points to upon successful return. | ||
107 | * | ||
108 | * @return SCREENSHOTR_E_SUCCESS on success, SCREENSHOTR_E_INVALID_ARG if | ||
109 | * one or more parameters are invalid, or another error code if an | ||
110 | * error occurred. | ||
111 | */ | ||
112 | LIBIMOBILEDEVICE_API screenshotr_error_t screenshotr_take_screenshot(screenshotr_client_t client, char **imgdata, uint64_t *imgsize); | ||
53 | 113 | ||
54 | #ifdef __cplusplus | 114 | #ifdef __cplusplus |
55 | } | 115 | } |
diff --git a/include/libimobiledevice/service.h b/include/libimobiledevice/service.h new file mode 100644 index 0000000..f31ada4 --- /dev/null +++ b/include/libimobiledevice/service.h | |||
@@ -0,0 +1,202 @@ | |||
1 | /** | ||
2 | * @file libimobiledevice/service.h | ||
3 | * @brief Generic basic service implementation to inherit. | ||
4 | * \internal | ||
5 | * | ||
6 | * Copyright (c) 2013-2014 Martin Szulecki All Rights Reserved. | ||
7 | * | ||
8 | * This library is free software; you can redistribute it and/or | ||
9 | * modify it under the terms of the GNU Lesser General Public | ||
10 | * License as published by the Free Software Foundation; either | ||
11 | * version 2.1 of the License, or (at your option) any later version. | ||
12 | * | ||
13 | * This library is distributed in the hope that it will be useful, | ||
14 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
15 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
16 | * Lesser General Public License for more details. | ||
17 | * | ||
18 | * You should have received a copy of the GNU Lesser General Public | ||
19 | * License along with this library; if not, write to the Free Software | ||
20 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | ||
21 | */ | ||
22 | |||
23 | #ifndef ISERVICE_H | ||
24 | #define ISERVICE_H | ||
25 | |||
26 | #ifdef __cplusplus | ||
27 | extern "C" { | ||
28 | #endif | ||
29 | |||
30 | #include <libimobiledevice/libimobiledevice.h> | ||
31 | #include <libimobiledevice/lockdown.h> | ||
32 | |||
33 | /** Error Codes */ | ||
34 | typedef enum { | ||
35 | SERVICE_E_SUCCESS = 0, | ||
36 | SERVICE_E_INVALID_ARG = -1, | ||
37 | SERVICE_E_MUX_ERROR = -3, | ||
38 | SERVICE_E_SSL_ERROR = -4, | ||
39 | SERVICE_E_START_SERVICE_ERROR = -5, | ||
40 | SERVICE_E_NOT_ENOUGH_DATA = -6, | ||
41 | SERVICE_E_TIMEOUT = -7, | ||
42 | SERVICE_E_UNKNOWN_ERROR = -256 | ||
43 | } service_error_t; | ||
44 | |||
45 | typedef struct service_client_private service_client_private; /**< \private */ | ||
46 | typedef service_client_private* service_client_t; /**< The client handle. */ | ||
47 | |||
48 | /** service constructor cast */ | ||
49 | #define SERVICE_CONSTRUCTOR(x) (int32_t (*)(idevice_t, lockdownd_service_descriptor_t, void**))(x) | ||
50 | |||
51 | /* Interface */ | ||
52 | |||
53 | /** | ||
54 | * Creates a new service for the specified service descriptor. | ||
55 | * | ||
56 | * @param device The device to connect to. | ||
57 | * @param service The service descriptor returned by lockdownd_start_service. | ||
58 | * @param client Pointer that will be set to a newly allocated | ||
59 | * service_client_t upon successful return. | ||
60 | * | ||
61 | * @return SERVICE_E_SUCCESS on success, | ||
62 | * SERVICE_E_INVALID_ARG when one of the arguments is invalid, | ||
63 | * or SERVICE_E_MUX_ERROR when connecting to the device failed. | ||
64 | */ | ||
65 | LIBIMOBILEDEVICE_API service_error_t service_client_new(idevice_t device, lockdownd_service_descriptor_t service, service_client_t *client); | ||
66 | |||
67 | /** | ||
68 | * Starts a new service on the specified device with given name and | ||
69 | * connects to it. | ||
70 | * | ||
71 | * @param device The device to connect to. | ||
72 | * @param service_name The name of the service to start. | ||
73 | * @param client Pointer that will point to a newly allocated service_client_t | ||
74 | * upon successful return. Must be freed using service_client_free() after | ||
75 | * use. | ||
76 | * @param label The label to use for communication. Usually the program name. | ||
77 | * Pass NULL to disable sending the label in requests to lockdownd. | ||
78 | * @param constructor_func Constructor function for the service client to create (e.g. afc_client_new()) | ||
79 | * @param error_code Pointer to an int32_t that will receive the service start error code. | ||
80 | * | ||
81 | * @return SERVICE_E_SUCCESS on success, or a SERVICE_E_* error code | ||
82 | * otherwise. | ||
83 | */ | ||
84 | LIBIMOBILEDEVICE_API service_error_t service_client_factory_start_service(idevice_t device, const char* service_name, void **client, const char* label, int32_t (*constructor_func)(idevice_t, lockdownd_service_descriptor_t, void**), int32_t *error_code); | ||
85 | |||
86 | /** | ||
87 | * Frees a service instance. | ||
88 | * | ||
89 | * @param client The service instance to free. | ||
90 | * | ||
91 | * @return SERVICE_E_SUCCESS on success, | ||
92 | * SERVICE_E_INVALID_ARG when client is invalid, or a | ||
93 | * SERVICE_E_UNKNOWN_ERROR when another error occurred. | ||
94 | */ | ||
95 | LIBIMOBILEDEVICE_API service_error_t service_client_free(service_client_t client); | ||
96 | |||
97 | |||
98 | /** | ||
99 | * Sends data using the given service client. | ||
100 | * | ||
101 | * @param client The service client to use for sending. | ||
102 | * @param data Data to send | ||
103 | * @param size Size of the data to send | ||
104 | * @param sent Number of bytes sent (can be NULL to ignore) | ||
105 | * | ||
106 | * @return SERVICE_E_SUCCESS on success, | ||
107 | * SERVICE_E_INVALID_ARG when one or more parameters are | ||
108 | * invalid, or SERVICE_E_UNKNOWN_ERROR when an unspecified | ||
109 | * error occurs. | ||
110 | */ | ||
111 | LIBIMOBILEDEVICE_API service_error_t service_send(service_client_t client, const char *data, uint32_t size, uint32_t *sent); | ||
112 | |||
113 | /** | ||
114 | * Receives data using the given service client with specified timeout. | ||
115 | * | ||
116 | * @param client The service client to use for receiving | ||
117 | * @param data Buffer that will be filled with the data received | ||
118 | * @param size Number of bytes to receive | ||
119 | * @param received Number of bytes received (can be NULL to ignore) | ||
120 | * @param timeout Maximum time in milliseconds to wait for data. | ||
121 | * | ||
122 | * @return SERVICE_E_SUCCESS on success, | ||
123 | * SERVICE_E_INVALID_ARG when one or more parameters are | ||
124 | * invalid, SERVICE_E_MUX_ERROR when a communication error | ||
125 | * occurs, or SERVICE_E_UNKNOWN_ERROR when an unspecified | ||
126 | * error occurs. | ||
127 | */ | ||
128 | LIBIMOBILEDEVICE_API service_error_t service_receive_with_timeout(service_client_t client, char *data, uint32_t size, uint32_t *received, unsigned int timeout); | ||
129 | |||
130 | /** | ||
131 | * Receives data using the given service client. | ||
132 | * | ||
133 | * @param client The service client to use for receiving | ||
134 | * @param data Buffer that will be filled with the data received | ||
135 | * @param size Number of bytes to receive | ||
136 | * @param received Number of bytes received (can be NULL to ignore) | ||
137 | * | ||
138 | * @return SERVICE_E_SUCCESS on success, | ||
139 | * SERVICE_E_INVALID_ARG when one or more parameters are | ||
140 | * invalid, SERVICE_E_NOT_ENOUGH_DATA when not enough data | ||
141 | * received, SERVICE_E_TIMEOUT when the connection times out, | ||
142 | * SERVICE_E_MUX_ERROR when a communication error | ||
143 | * occurs, or SERVICE_E_UNKNOWN_ERROR when an unspecified | ||
144 | * error occurs. | ||
145 | */ | ||
146 | LIBIMOBILEDEVICE_API service_error_t service_receive(service_client_t client, char *data, uint32_t size, uint32_t *received); | ||
147 | |||
148 | |||
149 | /** | ||
150 | * Enable SSL for the given service client. | ||
151 | * | ||
152 | * @param client The connected service client for that SSL should be enabled. | ||
153 | * | ||
154 | * @return SERVICE_E_SUCCESS on success, | ||
155 | * SERVICE_E_INVALID_ARG if client or client->connection is | ||
156 | * NULL, SERVICE_E_NOT_ENOUGH_DATA when not enough data | ||
157 | * received, SERVICE_E_TIMEOUT when the connection times out, | ||
158 | * SERVICE_E_SSL_ERROR when SSL could not be enabled, | ||
159 | * or SERVICE_E_UNKNOWN_ERROR otherwise. | ||
160 | */ | ||
161 | LIBIMOBILEDEVICE_API service_error_t service_enable_ssl(service_client_t client); | ||
162 | |||
163 | /** | ||
164 | * Disable SSL for the given service client. | ||
165 | * | ||
166 | * @param client The connected service client for which SSL should be disabled. | ||
167 | * | ||
168 | * @return SERVICE_E_SUCCESS on success, | ||
169 | * SERVICE_E_INVALID_ARG if client or client->connection is | ||
170 | * NULL, or SERVICE_E_UNKNOWN_ERROR otherwise. | ||
171 | */ | ||
172 | LIBIMOBILEDEVICE_API service_error_t service_disable_ssl(service_client_t client); | ||
173 | |||
174 | /** | ||
175 | * Disable SSL for the given service client, optionally without sending SSL terminate messages. | ||
176 | * | ||
177 | * @param client The connected service client for which SSL should be disabled. | ||
178 | * @param sslBypass A boolean value indicating wether to disable SSL with a proper | ||
179 | * SSL shutdown (0), or bypass the shutdown (1). | ||
180 | * | ||
181 | * @return SERVICE_E_SUCCESS on success, | ||
182 | * SERVICE_E_INVALID_ARG if client or client->connection is | ||
183 | * NULL, or SERVICE_E_UNKNOWN_ERROR otherwise. | ||
184 | */ | ||
185 | LIBIMOBILEDEVICE_API service_error_t service_disable_bypass_ssl(service_client_t client, uint8_t sslBypass); | ||
186 | |||
187 | /** | ||
188 | * Return a handle to the parent #idevice_connection_t of the given service client. | ||
189 | * | ||
190 | * @param client The service client | ||
191 | * @param connection Pointer to be assigned to the #idevice_connection_t. | ||
192 | * | ||
193 | * @return SERVICE_E_SUCCESS on success, | ||
194 | * SERVICE_E_INVALID_ARG if one or more of the arguments are invalid. | ||
195 | */ | ||
196 | LIBIMOBILEDEVICE_API service_error_t service_get_connection(service_client_t client, idevice_connection_t *connection); | ||
197 | |||
198 | #ifdef __cplusplus | ||
199 | } | ||
200 | #endif | ||
201 | |||
202 | #endif | ||
diff --git a/include/libimobiledevice/syslog_relay.h b/include/libimobiledevice/syslog_relay.h new file mode 100644 index 0000000..0f6487a --- /dev/null +++ b/include/libimobiledevice/syslog_relay.h | |||
@@ -0,0 +1,184 @@ | |||
1 | /** | ||
2 | * @file libimobiledevice/syslog_relay.h | ||
3 | * @brief Capture the syslog output from a device. | ||
4 | * \internal | ||
5 | * | ||
6 | * Copyright (c) 2019-2020 Nikias Bassen, All Rights Reserved. | ||
7 | * Copyright (c) 2013-2014 Martin Szulecki, All Rights Reserved. | ||
8 | * | ||
9 | * This library is free software; you can redistribute it and/or | ||
10 | * modify it under the terms of the GNU Lesser General Public | ||
11 | * License as published by the Free Software Foundation; either | ||
12 | * version 2.1 of the License, or (at your option) any later version. | ||
13 | * | ||
14 | * This library is distributed in the hope that it will be useful, | ||
15 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
16 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
17 | * Lesser General Public License for more details. | ||
18 | * | ||
19 | * You should have received a copy of the GNU Lesser General Public | ||
20 | * License along with this library; if not, write to the Free Software | ||
21 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | ||
22 | */ | ||
23 | |||
24 | #ifndef ISYSLOG_RELAY_H | ||
25 | #define ISYSLOG_RELAY_H | ||
26 | |||
27 | #ifdef __cplusplus | ||
28 | extern "C" { | ||
29 | #endif | ||
30 | |||
31 | #include <libimobiledevice/libimobiledevice.h> | ||
32 | #include <libimobiledevice/lockdown.h> | ||
33 | |||
34 | /** Service identifier passed to lockdownd_start_service() to start the syslog relay service */ | ||
35 | #define SYSLOG_RELAY_SERVICE_NAME "com.apple.syslog_relay" | ||
36 | |||
37 | /** Error Codes */ | ||
38 | typedef enum { | ||
39 | SYSLOG_RELAY_E_SUCCESS = 0, | ||
40 | SYSLOG_RELAY_E_INVALID_ARG = -1, | ||
41 | SYSLOG_RELAY_E_MUX_ERROR = -2, | ||
42 | SYSLOG_RELAY_E_SSL_ERROR = -3, | ||
43 | SYSLOG_RELAY_E_NOT_ENOUGH_DATA = -4, | ||
44 | SYSLOG_RELAY_E_TIMEOUT = -5, | ||
45 | SYSLOG_RELAY_E_UNKNOWN_ERROR = -256 | ||
46 | } syslog_relay_error_t; | ||
47 | |||
48 | typedef struct syslog_relay_client_private syslog_relay_client_private; /**< \private */ | ||
49 | typedef syslog_relay_client_private *syslog_relay_client_t; /**< The client handle. */ | ||
50 | |||
51 | /** Receives each character received from the device. */ | ||
52 | typedef void (*syslog_relay_receive_cb_t)(char c, void *user_data); | ||
53 | |||
54 | /* Interface */ | ||
55 | |||
56 | /** | ||
57 | * Connects to the syslog_relay service on the specified device. | ||
58 | * | ||
59 | * @param device The device to connect to. | ||
60 | * @param service The service descriptor returned by lockdownd_start_service. | ||
61 | * @param client Pointer that will point to a newly allocated | ||
62 | * syslog_relay_client_t upon successful return. Must be freed using | ||
63 | * syslog_relay_client_free() after use. | ||
64 | * | ||
65 | * @return SYSLOG_RELAY_E_SUCCESS on success, SYSLOG_RELAY_E_INVALID_ARG when | ||
66 | * client is NULL, or an SYSLOG_RELAY_E_* error code otherwise. | ||
67 | */ | ||
68 | LIBIMOBILEDEVICE_API syslog_relay_error_t syslog_relay_client_new(idevice_t device, lockdownd_service_descriptor_t service, syslog_relay_client_t * client); | ||
69 | |||
70 | /** | ||
71 | * Starts a new syslog_relay service on the specified device and connects to it. | ||
72 | * | ||
73 | * @param device The device to connect to. | ||
74 | * @param client Pointer that will point to a newly allocated | ||
75 | * syslog_relay_client_t upon successful return. Must be freed using | ||
76 | * syslog_relay_client_free() after use. | ||
77 | * @param label The label to use for communication. Usually the program name. | ||
78 | * Pass NULL to disable sending the label in requests to lockdownd. | ||
79 | * | ||
80 | * @return SYSLOG_RELAY_E_SUCCESS on success, or an SYSLOG_RELAY_E_* error | ||
81 | * code otherwise. | ||
82 | */ | ||
83 | LIBIMOBILEDEVICE_API syslog_relay_error_t syslog_relay_client_start_service(idevice_t device, syslog_relay_client_t * client, const char* label); | ||
84 | |||
85 | /** | ||
86 | * Disconnects a syslog_relay client from the device and frees up the | ||
87 | * syslog_relay client data. | ||
88 | * | ||
89 | * @param client The syslog_relay client to disconnect and free. | ||
90 | * | ||
91 | * @return SYSLOG_RELAY_E_SUCCESS on success, SYSLOG_RELAY_E_INVALID_ARG when | ||
92 | * client is NULL, or an SYSLOG_RELAY_E_* error code otherwise. | ||
93 | */ | ||
94 | LIBIMOBILEDEVICE_API syslog_relay_error_t syslog_relay_client_free(syslog_relay_client_t client); | ||
95 | |||
96 | |||
97 | /** | ||
98 | * Starts capturing the syslog of the device using a callback. | ||
99 | * | ||
100 | * Use syslog_relay_stop_capture() to stop receiving the syslog. | ||
101 | * | ||
102 | * @param client The syslog_relay client to use | ||
103 | * @param callback Callback to receive each character from the syslog. | ||
104 | * @param user_data Custom pointer passed to the callback function. | ||
105 | * | ||
106 | * @return SYSLOG_RELAY_E_SUCCESS on success, | ||
107 | * SYSLOG_RELAY_E_INVALID_ARG when one or more parameters are | ||
108 | * invalid or SYSLOG_RELAY_E_UNKNOWN_ERROR when an unspecified | ||
109 | * error occurs or a syslog capture has already been started. | ||
110 | */ | ||
111 | LIBIMOBILEDEVICE_API syslog_relay_error_t syslog_relay_start_capture(syslog_relay_client_t client, syslog_relay_receive_cb_t callback, void* user_data); | ||
112 | |||
113 | /** | ||
114 | * Starts capturing the *raw* syslog of the device using a callback. | ||
115 | * This function is like syslog_relay_start_capture with the difference that | ||
116 | * it will neither check nor process the received data before passing it to | ||
117 | * the callback function. | ||
118 | * | ||
119 | * Use syslog_relay_stop_capture() to stop receiving the syslog. | ||
120 | * | ||
121 | * @note Use syslog_relay_start_capture for a safer implementation. | ||
122 | * | ||
123 | * @param client The syslog_relay client to use | ||
124 | * @param callback Callback to receive each character from the syslog. | ||
125 | * @param user_data Custom pointer passed to the callback function. | ||
126 | * | ||
127 | * @return SYSLOG_RELAY_E_SUCCESS on success, | ||
128 | * SYSLOG_RELAY_E_INVALID_ARG when one or more parameters are | ||
129 | * invalid or SYSLOG_RELAY_E_UNKNOWN_ERROR when an unspecified | ||
130 | * error occurs or a syslog capture has already been started. | ||
131 | */ | ||
132 | LIBIMOBILEDEVICE_API syslog_relay_error_t syslog_relay_start_capture_raw(syslog_relay_client_t client, syslog_relay_receive_cb_t callback, void* user_data); | ||
133 | |||
134 | /** | ||
135 | * Stops capturing the syslog of the device. | ||
136 | * | ||
137 | * Use syslog_relay_start_capture() to start receiving the syslog. | ||
138 | * | ||
139 | * @param client The syslog_relay client to use | ||
140 | * | ||
141 | * @return SYSLOG_RELAY_E_SUCCESS on success, | ||
142 | * SYSLOG_RELAY_E_INVALID_ARG when one or more parameters are | ||
143 | * invalid or SYSLOG_RELAY_E_UNKNOWN_ERROR when an unspecified | ||
144 | * error occurs or a syslog capture has already been started. | ||
145 | */ | ||
146 | LIBIMOBILEDEVICE_API syslog_relay_error_t syslog_relay_stop_capture(syslog_relay_client_t client); | ||
147 | |||
148 | /* Receiving */ | ||
149 | |||
150 | /** | ||
151 | * Receives data using the given syslog_relay client with specified timeout. | ||
152 | * | ||
153 | * @param client The syslog_relay client to use for receiving | ||
154 | * @param data Buffer that will be filled with the data received | ||
155 | * @param size Number of bytes to receive | ||
156 | * @param received Number of bytes received (can be NULL to ignore) | ||
157 | * @param timeout Maximum time in milliseconds to wait for data. | ||
158 | * | ||
159 | * @return SYSLOG_RELAY_E_SUCCESS on success, | ||
160 | * SYSLOG_RELAY_E_INVALID_ARG when one or more parameters are | ||
161 | * invalid, SYSLOG_RELAY_E_MUX_ERROR when a communication error | ||
162 | * occurs, or SYSLOG_RELAY_E_UNKNOWN_ERROR when an unspecified | ||
163 | * error occurs. | ||
164 | */ | ||
165 | LIBIMOBILEDEVICE_API syslog_relay_error_t syslog_relay_receive_with_timeout(syslog_relay_client_t client, char *data, uint32_t size, uint32_t *received, unsigned int timeout); | ||
166 | |||
167 | /** | ||
168 | * Receives data from the service. | ||
169 | * | ||
170 | * @param client The syslog_relay client | ||
171 | * @param data Buffer that will be filled with the data received | ||
172 | * @param size Number of bytes to receive | ||
173 | * @param received Number of bytes received (can be NULL to ignore) | ||
174 | * | ||
175 | * @return SYSLOG_RELAY_E_SUCCESS on success, | ||
176 | * SYSLOG_RELAY_E_INVALID_ARG when client or plist is NULL | ||
177 | */ | ||
178 | LIBIMOBILEDEVICE_API syslog_relay_error_t syslog_relay_receive(syslog_relay_client_t client, char *data, uint32_t size, uint32_t *received); | ||
179 | |||
180 | #ifdef __cplusplus | ||
181 | } | ||
182 | #endif | ||
183 | |||
184 | #endif | ||
diff --git a/include/libimobiledevice/webinspector.h b/include/libimobiledevice/webinspector.h new file mode 100644 index 0000000..16d2ca2 --- /dev/null +++ b/include/libimobiledevice/webinspector.h | |||
@@ -0,0 +1,137 @@ | |||
1 | /** | ||
2 | * @file libimobiledevice/webinspector.h | ||
3 | * @brief WebKit Remote Debugging. | ||
4 | * \internal | ||
5 | * | ||
6 | * Copyright (c) 2013-2014 Martin Szulecki All Rights Reserved. | ||
7 | * Copyright (c) 2013 Yury Melnichek All Rights Reserved. | ||
8 | * | ||
9 | * This library is free software; you can redistribute it and/or | ||
10 | * modify it under the terms of the GNU Lesser General Public | ||
11 | * License as published by the Free Software Foundation; either | ||
12 | * version 2.1 of the License, or (at your option) any later version. | ||
13 | * | ||
14 | * This library is distributed in the hope that it will be useful, | ||
15 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
16 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
17 | * Lesser General Public License for more details. | ||
18 | * | ||
19 | * You should have received a copy of the GNU Lesser General Public | ||
20 | * License along with this library; if not, write to the Free Software | ||
21 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | ||
22 | */ | ||
23 | |||
24 | #ifndef IWEBINSPECTOR_H | ||
25 | #define IWEBINSPECTOR_H | ||
26 | |||
27 | #ifdef __cplusplus | ||
28 | extern "C" { | ||
29 | #endif | ||
30 | |||
31 | #include <libimobiledevice/libimobiledevice.h> | ||
32 | #include <libimobiledevice/lockdown.h> | ||
33 | |||
34 | /** Service identifier passed to lockdownd_start_service() to start the webinspector service */ | ||
35 | #define WEBINSPECTOR_SERVICE_NAME "com.apple.webinspector" | ||
36 | |||
37 | /** Error Codes */ | ||
38 | typedef enum { | ||
39 | WEBINSPECTOR_E_SUCCESS = 0, | ||
40 | WEBINSPECTOR_E_INVALID_ARG = -1, | ||
41 | WEBINSPECTOR_E_PLIST_ERROR = -2, | ||
42 | WEBINSPECTOR_E_MUX_ERROR = -3, | ||
43 | WEBINSPECTOR_E_SSL_ERROR = -4, | ||
44 | WEBINSPECTOR_E_RECEIVE_TIMEOUT = -5, | ||
45 | WEBINSPECTOR_E_NOT_ENOUGH_DATA = -6, | ||
46 | WEBINSPECTOR_E_UNKNOWN_ERROR = -256 | ||
47 | } webinspector_error_t; | ||
48 | |||
49 | typedef struct webinspector_client_private webinspector_client_private; /**< \private */ | ||
50 | typedef webinspector_client_private *webinspector_client_t; /**< The client handle. */ | ||
51 | |||
52 | |||
53 | /** | ||
54 | * Connects to the webinspector service on the specified device. | ||
55 | * | ||
56 | * @param device The device to connect to. | ||
57 | * @param service The service descriptor returned by lockdownd_start_service. | ||
58 | * @param client Pointer that will point to a newly allocated | ||
59 | * webinspector_client_t upon successful return. Must be freed using | ||
60 | * webinspector_client_free() after use. | ||
61 | * | ||
62 | * @return WEBINSPECTOR_E_SUCCESS on success, WEBINSPECTOR_E_INVALID_ARG when | ||
63 | * client is NULL, or an WEBINSPECTOR_E_* error code otherwise. | ||
64 | */ | ||
65 | LIBIMOBILEDEVICE_API webinspector_error_t webinspector_client_new(idevice_t device, lockdownd_service_descriptor_t service, webinspector_client_t * client); | ||
66 | |||
67 | /** | ||
68 | * Starts a new webinspector service on the specified device and connects to it. | ||
69 | * | ||
70 | * @param device The device to connect to. | ||
71 | * @param client Pointer that will point to a newly allocated | ||
72 | * webinspector_client_t upon successful return. Must be freed using | ||
73 | * webinspector_client_free() after use. | ||
74 | * @param label The label to use for communication. Usually the program name. | ||
75 | * Pass NULL to disable sending the label in requests to lockdownd. | ||
76 | * | ||
77 | * @return WEBINSPECTOR_E_SUCCESS on success, or an WEBINSPECTOR_E_* error | ||
78 | * code otherwise. | ||
79 | */ | ||
80 | LIBIMOBILEDEVICE_API webinspector_error_t webinspector_client_start_service(idevice_t device, webinspector_client_t * client, const char* label); | ||
81 | |||
82 | /** | ||
83 | * Disconnects a webinspector client from the device and frees up the | ||
84 | * webinspector client data. | ||
85 | * | ||
86 | * @param client The webinspector client to disconnect and free. | ||
87 | * | ||
88 | * @return WEBINSPECTOR_E_SUCCESS on success, WEBINSPECTOR_E_INVALID_ARG when | ||
89 | * client is NULL, or an WEBINSPECTOR_E_* error code otherwise. | ||
90 | */ | ||
91 | LIBIMOBILEDEVICE_API webinspector_error_t webinspector_client_free(webinspector_client_t client); | ||
92 | |||
93 | |||
94 | /** | ||
95 | * Sends a plist to the service. | ||
96 | * | ||
97 | * @param client The webinspector client | ||
98 | * @param plist The plist to send | ||
99 | * | ||
100 | * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, | ||
101 | * DIAGNOSTICS_RELAY_E_INVALID_ARG when client or plist is NULL | ||
102 | */ | ||
103 | LIBIMOBILEDEVICE_API webinspector_error_t webinspector_send(webinspector_client_t client, plist_t plist); | ||
104 | |||
105 | /** | ||
106 | * Receives a plist from the service. | ||
107 | * | ||
108 | * @param client The webinspector client | ||
109 | * @param plist The plist to store the received data | ||
110 | * | ||
111 | * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, | ||
112 | * DIAGNOSTICS_RELAY_E_INVALID_ARG when client or plist is NULL | ||
113 | */ | ||
114 | LIBIMOBILEDEVICE_API webinspector_error_t webinspector_receive(webinspector_client_t client, plist_t * plist); | ||
115 | |||
116 | /** | ||
117 | * Receives a plist using the given webinspector client. | ||
118 | * | ||
119 | * @param client The webinspector client to use for receiving | ||
120 | * @param plist pointer to a plist_t that will point to the received plist | ||
121 | * upon successful return | ||
122 | * @param timeout_ms Maximum time in milliseconds to wait for data. | ||
123 | * | ||
124 | * @return WEBINSPECTOR_E_SUCCESS on success, | ||
125 | * WEBINSPECTOR_E_INVALID_ARG when client or *plist is NULL, | ||
126 | * WEBINSPECTOR_E_PLIST_ERROR when the received data cannot be | ||
127 | * converted to a plist, WEBINSPECTOR_E_MUX_ERROR when a | ||
128 | * communication error occurs, or WEBINSPECTOR_E_UNKNOWN_ERROR | ||
129 | * when an unspecified error occurs. | ||
130 | */ | ||
131 | LIBIMOBILEDEVICE_API webinspector_error_t webinspector_receive_with_timeout(webinspector_client_t client, plist_t * plist, uint32_t timeout_ms); | ||
132 | |||
133 | #ifdef __cplusplus | ||
134 | } | ||
135 | #endif | ||
136 | |||
137 | #endif | ||