summaryrefslogtreecommitdiffstats
path: root/include
diff options
context:
space:
mode:
Diffstat (limited to 'include')
-rw-r--r--include/Makefile.am44
-rw-r--r--include/asprintf.h36
-rw-r--r--include/endianness.h123
-rw-r--r--include/libimobiledevice/afc.h384
-rw-r--r--include/libimobiledevice/bt_packet_logger.h156
-rw-r--r--include/libimobiledevice/companion_proxy.h212
-rw-r--r--include/libimobiledevice/debugserver.h272
-rw-r--r--include/libimobiledevice/diagnostics_relay.h228
-rw-r--r--include/libimobiledevice/file_relay.h141
-rw-r--r--include/libimobiledevice/heartbeat.h137
-rw-r--r--include/libimobiledevice/house_arrest.h160
-rw-r--r--include/libimobiledevice/installation_proxy.h501
-rw-r--r--include/libimobiledevice/libimobiledevice.h390
-rw-r--r--include/libimobiledevice/lockdown.h591
-rw-r--r--include/libimobiledevice/misagent.h168
-rw-r--r--include/libimobiledevice/mobile_image_mounter.h256
-rw-r--r--include/libimobiledevice/mobileactivation.h192
-rw-r--r--include/libimobiledevice/mobilebackup.h226
-rw-r--r--include/libimobiledevice/mobilebackup2.h214
-rw-r--r--include/libimobiledevice/mobilesync.h342
-rw-r--r--include/libimobiledevice/notification_proxy.h150
-rw-r--r--include/libimobiledevice/preboard.h187
-rw-r--r--include/libimobiledevice/property_list_service.h184
-rw-r--r--include/libimobiledevice/restore.h165
-rw-r--r--include/libimobiledevice/reverse_proxy.h213
-rw-r--r--include/libimobiledevice/sbservices.h155
-rw-r--r--include/libimobiledevice/screenshotr.h94
-rw-r--r--include/libimobiledevice/service.h202
-rw-r--r--include/libimobiledevice/syslog_relay.h184
-rw-r--r--include/libimobiledevice/webinspector.h137
30 files changed, 6013 insertions, 431 deletions
diff --git a/include/Makefile.am b/include/Makefile.am
index 44794c6..2abaf49 100644
--- a/include/Makefile.am
+++ b/include/Makefile.am
@@ -1,13 +1,31 @@
1nobase_include_HEADERS = libimobiledevice/libimobiledevice.h \ 1EXTRA_DIST = \
2 libimobiledevice/lockdown.h \ 2 asprintf.h \
3 libimobiledevice/afc.h \ 3 endianness.h
4 libimobiledevice/file_relay.h \ 4
5 libimobiledevice/notification_proxy.h \ 5nobase_include_HEADERS = \
6 libimobiledevice/installation_proxy.h \ 6 libimobiledevice/libimobiledevice.h \
7 libimobiledevice/sbservices.h \ 7 libimobiledevice/lockdown.h \
8 libimobiledevice/mobile_image_mounter.h \ 8 libimobiledevice/afc.h \
9 libimobiledevice/screenshotr.h \ 9 libimobiledevice/file_relay.h \
10 libimobiledevice/mobilesync.h \ 10 libimobiledevice/notification_proxy.h \
11 libimobiledevice/mobilebackup.h \ 11 libimobiledevice/installation_proxy.h \
12 libimobiledevice/house_arrest.h \ 12 libimobiledevice/sbservices.h \
13 libimobiledevice/restore.h 13 libimobiledevice/mobile_image_mounter.h \
14 libimobiledevice/screenshotr.h \
15 libimobiledevice/mobilesync.h \
16 libimobiledevice/mobilebackup.h \
17 libimobiledevice/house_arrest.h \
18 libimobiledevice/mobilebackup2.h \
19 libimobiledevice/misagent.h \
20 libimobiledevice/restore.h \
21 libimobiledevice/webinspector.h \
22 libimobiledevice/heartbeat.h \
23 libimobiledevice/diagnostics_relay.h \
24 libimobiledevice/debugserver.h \
25 libimobiledevice/syslog_relay.h \
26 libimobiledevice/mobileactivation.h \
27 libimobiledevice/preboard.h \
28 libimobiledevice/companion_proxy.h \
29 libimobiledevice/reverse_proxy.h \
30 libimobiledevice/property_list_service.h \
31 libimobiledevice/service.h
diff --git a/include/asprintf.h b/include/asprintf.h
new file mode 100644
index 0000000..3ed35be
--- /dev/null
+++ b/include/asprintf.h
@@ -0,0 +1,36 @@
1#ifndef __ASPRINTF_H
2#define __ASPRINTF_H
3
4#ifdef HAVE_CONFIG_H
5#include <config.h>
6#endif
7
8#include <stdio.h>
9
10#ifndef HAVE_VASPRINTF
11static inline int vasprintf(char **PTR, const char *TEMPLATE, va_list AP)
12{
13 int res;
14 char buf[16];
15 res = vsnprintf(buf, 16, TEMPLATE, AP);
16 if (res > 0) {
17 *PTR = (char*)malloc(res+1);
18 res = vsnprintf(*PTR, res+1, TEMPLATE, AP);
19 }
20 return res;
21}
22#endif
23
24#ifndef HAVE_ASPRINTF
25static inline int asprintf(char **PTR, const char *TEMPLATE, ...)
26{
27 int res;
28 va_list AP;
29 va_start(AP, TEMPLATE);
30 res = vasprintf(PTR, TEMPLATE, AP);
31 va_end(AP);
32 return res;
33}
34#endif
35
36#endif /* ASPRINTF_H */
diff --git a/include/endianness.h b/include/endianness.h
new file mode 100644
index 0000000..88b63db
--- /dev/null
+++ b/include/endianness.h
@@ -0,0 +1,123 @@
1#ifndef ENDIANNESS_H
2#define ENDIANNESS_H
3
4#ifndef __LITTLE_ENDIAN
5#define __LITTLE_ENDIAN 1234
6#endif
7
8#ifndef __BIG_ENDIAN
9#define __BIG_ENDIAN 4321
10#endif
11
12#ifndef __BYTE_ORDER
13#ifdef __LITTLE_ENDIAN__
14#define __BYTE_ORDER __LITTLE_ENDIAN
15#else
16#ifdef __BIG_ENDIAN__
17#define __BYTE_ORDER __BIG_ENDIAN
18#endif
19#endif
20#endif
21
22#ifndef be16toh
23#if __BYTE_ORDER == __BIG_ENDIAN
24#define be16toh(x) (x)
25#else
26#define be16toh(x) ((((x) & 0xFF00) >> 8) | (((x) & 0x00FF) << 8))
27#endif
28#endif
29
30#ifndef htobe16
31#define htobe16 be16toh
32#endif
33
34#ifndef le16toh
35#if __BYTE_ORDER == __BIG_ENDIAN
36#define le16toh(x) ((((x) & 0xFF00) >> 8) | (((x) & 0x00FF) << 8))
37#else
38#define le16toh(x) (x)
39#endif
40#endif
41
42#ifndef htole16
43#define htole16 le16toh
44#endif
45
46#ifndef __bswap_32
47#define __bswap_32(x) ((((x) & 0xFF000000) >> 24) \
48 | (((x) & 0x00FF0000) >> 8) \
49 | (((x) & 0x0000FF00) << 8) \
50 | (((x) & 0x000000FF) << 24))
51#endif
52
53#ifndef be32toh
54#if __BYTE_ORDER == __BIG_ENDIAN
55#define be32toh(x) (x)
56#else
57#define be32toh(x) __bswap_32(x)
58#endif
59#endif
60
61#ifndef htobe32
62#define htobe32 be32toh
63#endif
64
65#ifndef le32toh
66#if __BYTE_ORDER == __BIG_ENDIAN
67#define le32toh(x) __bswap_32(x)
68#else
69#define le32toh(x) (x)
70#endif
71#endif
72
73#ifndef htole32
74#define htole32 le32toh
75#endif
76
77#ifndef __bswap_64
78#define __bswap_64(x) ((((x) & 0xFF00000000000000ull) >> 56) \
79 | (((x) & 0x00FF000000000000ull) >> 40) \
80 | (((x) & 0x0000FF0000000000ull) >> 24) \
81 | (((x) & 0x000000FF00000000ull) >> 8) \
82 | (((x) & 0x00000000FF000000ull) << 8) \
83 | (((x) & 0x0000000000FF0000ull) << 24) \
84 | (((x) & 0x000000000000FF00ull) << 40) \
85 | (((x) & 0x00000000000000FFull) << 56))
86#endif
87
88#ifndef htobe64
89#if __BYTE_ORDER == __BIG_ENDIAN
90#define htobe64(x) (x)
91#else
92#define htobe64(x) __bswap_64(x)
93#endif
94#endif
95
96#ifndef be64toh
97#define be64toh htobe64
98#endif
99
100#ifndef le64toh
101#if __BYTE_ORDER == __LITTLE_ENDIAN
102#define le64toh(x) (x)
103#else
104#define le64toh(x) __bswap_64(x)
105#endif
106#endif
107
108#ifndef htole64
109#define htole64 le64toh
110#endif
111
112#if (defined(__BIG_ENDIAN__) \
113 && !defined(__FLOAT_WORD_ORDER__)) \
114 || (defined(__FLOAT_WORD_ORDER__) \
115 && __FLOAT_WORD_ORDER__ == __ORDER_BIG_ENDIAN__)
116#define float_bswap64(x) __bswap_64(x)
117#define float_bswap32(x) __bswap_32(x)
118#else
119#define float_bswap64(x) (x)
120#define float_bswap32(x) (x)
121#endif
122
123#endif /* ENDIANNESS_H */
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
27extern "C" { 28extern "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 38typedef 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
66typedef int16_t afc_error_t; 68} afc_error_t;
67 69
68/** Flags for afc_file_open */ 70/** Flags for afc_file_open */
69typedef enum { 71typedef 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
91typedef struct afc_client_private afc_client_private; 93typedef struct afc_client_private afc_client_private; /**< \private */
92typedef afc_client_private *afc_client_t; /**< The client handle. */ 94typedef afc_client_private *afc_client_t; /**< The client handle. */
93 95
94/* Interface */ 96/* Interface */
95afc_error_t afc_client_new_from_connection(idevice_connection_t connection, afc_client_t *client); 97
96afc_error_t afc_client_new(idevice_t device, uint16_t port, afc_client_t *client); 98/**
97afc_error_t afc_client_free(afc_client_t client); 99 * Makes a connection to the AFC service on the device.
98afc_error_t afc_get_device_info(afc_client_t client, char ***infos); 100 *
99afc_error_t afc_read_directory(afc_client_t client, const char *dir, char ***list); 101 * @param device The device to connect to.
100afc_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.
101afc_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
102afc_error_t afc_file_close(afc_client_t client, uint64_t handle); 104 * upon successful return.
103afc_error_t afc_file_lock(afc_client_t client, uint64_t handle, afc_lock_op_t operation); 105 *
104afc_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
105afc_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,
106afc_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.
107afc_error_t afc_file_tell(afc_client_t client, uint64_t handle, uint64_t *position); 109 */
108afc_error_t afc_file_truncate(afc_client_t client, uint64_t handle, uint64_t newsize); 110LIBIMOBILEDEVICE_API afc_error_t afc_client_new(idevice_t device, lockdownd_service_descriptor_t service, afc_client_t *client);
109afc_error_t afc_remove_path(afc_client_t client, const char *path); 111
110afc_error_t afc_rename_path(afc_client_t client, const char *from, const char *to); 112/**
111afc_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.
112afc_error_t afc_truncate(afc_client_t client, const char *path, uint64_t newsize); 114 *
113afc_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.
114afc_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 */
123LIBIMOBILEDEVICE_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 */
131LIBIMOBILEDEVICE_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 */
145LIBIMOBILEDEVICE_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 */
158LIBIMOBILEDEVICE_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 */
171LIBIMOBILEDEVICE_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 */
183LIBIMOBILEDEVICE_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 */
191LIBIMOBILEDEVICE_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 */
205LIBIMOBILEDEVICE_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 */
218LIBIMOBILEDEVICE_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 */
231LIBIMOBILEDEVICE_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 */
243LIBIMOBILEDEVICE_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 */
254LIBIMOBILEDEVICE_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 */
268LIBIMOBILEDEVICE_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 */
278LIBIMOBILEDEVICE_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 */
289LIBIMOBILEDEVICE_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 */
300LIBIMOBILEDEVICE_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 */
311LIBIMOBILEDEVICE_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 */
323LIBIMOBILEDEVICE_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 */
334LIBIMOBILEDEVICE_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 */
346LIBIMOBILEDEVICE_API afc_error_t afc_remove_path_and_contents(afc_client_t client, const char *path);
115 347
116/* Helper functions */ 348/* Helper functions */
117afc_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 */
361LIBIMOBILEDEVICE_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 */
370LIBIMOBILEDEVICE_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 */
379LIBIMOBILEDEVICE_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
27extern "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 */
37typedef 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
47typedef struct {
48 uint32_t length;
49 uint32_t ts_secs;
50 uint32_t ts_usecs;
51} bt_packet_logger_header_t;
52
53typedef struct bt_packet_logger_client_private bt_packet_logger_client_private;
54typedef bt_packet_logger_client_private *bt_packet_logger_client_t; /**< The client handle. */
55
56/** Receives each hci packet received from the device. */
57typedef 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 */
73LIBIMOBILEDEVICE_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 */
88LIBIMOBILEDEVICE_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 */
99LIBIMOBILEDEVICE_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 */
116LIBIMOBILEDEVICE_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 */
130LIBIMOBILEDEVICE_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 */
149LIBIMOBILEDEVICE_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
27extern "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 */
37typedef 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
52typedef struct companion_proxy_client_private companion_proxy_client_private; /**< \private */
53typedef companion_proxy_client_private *companion_proxy_client_t; /**< The client handle. */
54
55/** Callback for companion device events */
56typedef 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 */
70LIBIMOBILEDEVICE_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 */
85LIBIMOBILEDEVICE_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 */
96LIBIMOBILEDEVICE_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 */
107LIBIMOBILEDEVICE_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 */
118LIBIMOBILEDEVICE_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 */
132LIBIMOBILEDEVICE_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 */
148LIBIMOBILEDEVICE_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 */
158LIBIMOBILEDEVICE_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 */
176LIBIMOBILEDEVICE_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 */
193LIBIMOBILEDEVICE_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 */
206LIBIMOBILEDEVICE_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
27extern "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 */
39typedef 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
49typedef struct debugserver_client_private debugserver_client_private; /**< \private */
50typedef debugserver_client_private *debugserver_client_t; /**< The client handle. */
51
52typedef struct debugserver_command_private debugserver_command_private; /**< \private */
53typedef 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 */
69LIBIMOBILEDEVICE_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 */
84LIBIMOBILEDEVICE_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 */
95LIBIMOBILEDEVICE_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 */
110LIBIMOBILEDEVICE_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 */
128LIBIMOBILEDEVICE_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 */
142LIBIMOBILEDEVICE_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 */
155LIBIMOBILEDEVICE_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 */
167LIBIMOBILEDEVICE_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 */
181LIBIMOBILEDEVICE_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 */
200LIBIMOBILEDEVICE_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 */
213LIBIMOBILEDEVICE_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 */
225LIBIMOBILEDEVICE_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 */
238LIBIMOBILEDEVICE_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 */
248LIBIMOBILEDEVICE_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 */
257LIBIMOBILEDEVICE_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 */
266LIBIMOBILEDEVICE_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
27extern "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 */
37typedef 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 */
47typedef 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
58typedef struct diagnostics_relay_client_private diagnostics_relay_client_private; /**< \private */
59typedef 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 */
73LIBIMOBILEDEVICE_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 */
88LIBIMOBILEDEVICE_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 */
101LIBIMOBILEDEVICE_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 */
114LIBIMOBILEDEVICE_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 */
126LIBIMOBILEDEVICE_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 */
143LIBIMOBILEDEVICE_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 */
160LIBIMOBILEDEVICE_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 */
176LIBIMOBILEDEVICE_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 */
191LIBIMOBILEDEVICE_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 */
207LIBIMOBILEDEVICE_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 */
222LIBIMOBILEDEVICE_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/*@}*/ 39typedef 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. */ 50typedef struct file_relay_client_private file_relay_client_private; /**< \private */
45typedef int16_t file_relay_error_t;
46
47typedef struct file_relay_client_private file_relay_client_private;
48typedef file_relay_client_private *file_relay_client_t; /**< The client handle. */ 51typedef file_relay_client_private *file_relay_client_t; /**< The client handle. */
49 52
50file_relay_error_t file_relay_client_new(idevice_t device, uint16_t port, file_relay_client_t *client); 53/**
51file_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 */
65LIBIMOBILEDEVICE_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 */
80LIBIMOBILEDEVICE_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 */
93LIBIMOBILEDEVICE_API file_relay_error_t file_relay_client_free(file_relay_client_t client);
94
52 95
53file_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 */
126LIBIMOBILEDEVICE_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 */
160LIBIMOBILEDEVICE_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
27extern "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 */
37typedef 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
48typedef struct heartbeat_client_private heartbeat_client_private; /**< \private */
49typedef 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 */
63LIBIMOBILEDEVICE_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 */
78LIBIMOBILEDEVICE_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 */
89LIBIMOBILEDEVICE_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 */
101LIBIMOBILEDEVICE_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 */
112LIBIMOBILEDEVICE_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 */
131LIBIMOBILEDEVICE_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
27extern "C" { 28extern "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/*@}*/ 39typedef 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. */ 48typedef struct house_arrest_client_private house_arrest_client_private; /**< \private */
45typedef int16_t house_arrest_error_t;
46
47typedef struct house_arrest_client_private house_arrest_client_private;
48typedef house_arrest_client_private *house_arrest_client_t; /**< The client handle. */ 49typedef house_arrest_client_private *house_arrest_client_t; /**< The client handle. */
49 50
50/* Interface */ 51/* Interface */
51house_arrest_error_t house_arrest_client_new(idevice_t device, uint16_t port, house_arrest_client_t *client);
52house_arrest_error_t house_arrest_client_free(house_arrest_client_t client);
53 52
54house_arrest_error_t house_arrest_send_request(house_arrest_client_t client, plist_t dict); 53/**
55house_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.
56house_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 */
64LIBIMOBILEDEVICE_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 */
79LIBIMOBILEDEVICE_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 */
95LIBIMOBILEDEVICE_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 */
115LIBIMOBILEDEVICE_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 */
136LIBIMOBILEDEVICE_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 */
152LIBIMOBILEDEVICE_API house_arrest_error_t house_arrest_get_result(house_arrest_client_t client, plist_t *dict);
153
57 154
58afc_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 */
174LIBIMOBILEDEVICE_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
27extern "C" { 30extern "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/*@}*/ 40typedef 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. */ 111typedef struct instproxy_client_private instproxy_client_private; /**< \private */
46typedef int16_t instproxy_error_t;
47
48typedef struct instproxy_client_private instproxy_client_private;
49typedef instproxy_client_private *instproxy_client_t; /**< The client handle. */ 112typedef 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 */
52typedef void (*instproxy_status_cb_t) (const char *operation, plist_t status, void *user_data); 115typedef void (*instproxy_status_cb_t) (plist_t command, plist_t status, void *user_data);
53 116
54/* Interface */ 117/* Interface */
55instproxy_error_t instproxy_client_new(idevice_t device, uint16_t port, instproxy_client_t *client); 118
56instproxy_error_t instproxy_client_free(instproxy_client_t client); 119/**
57 120 * Connects to the installation_proxy service on the specified device.
58instproxy_error_t instproxy_browse(instproxy_client_t client, plist_t client_options, plist_t *result); 121 *
59instproxy_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
60instproxy_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.
61instproxy_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.
63instproxy_error_t instproxy_lookup_archives(instproxy_client_t client, plist_t client_options, plist_t *result); 126 *
64instproxy_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
65instproxy_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.
66instproxy_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 130LIBIMOBILEDEVICE_API instproxy_error_t instproxy_client_new(idevice_t device, lockdownd_service_descriptor_t service, instproxy_client_t *client);
68plist_t instproxy_client_options_new(); 131
69void instproxy_client_options_add(plist_t client_options, ...) G_GNUC_NULL_TERMINATED; 132/**
70void 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 */
145LIBIMOBILEDEVICE_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 */
156LIBIMOBILEDEVICE_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 */
174LIBIMOBILEDEVICE_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 */
193LIBIMOBILEDEVICE_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 */
209LIBIMOBILEDEVICE_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 */
235LIBIMOBILEDEVICE_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 */
263LIBIMOBILEDEVICE_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 */
284LIBIMOBILEDEVICE_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 */
300LIBIMOBILEDEVICE_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 */
326LIBIMOBILEDEVICE_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 */
350LIBIMOBILEDEVICE_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 */
373LIBIMOBILEDEVICE_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 */
389LIBIMOBILEDEVICE_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 */
399LIBIMOBILEDEVICE_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 */
407LIBIMOBILEDEVICE_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 */
423LIBIMOBILEDEVICE_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 */
438LIBIMOBILEDEVICE_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 */
448LIBIMOBILEDEVICE_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 */
455LIBIMOBILEDEVICE_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 */
467LIBIMOBILEDEVICE_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 */
477LIBIMOBILEDEVICE_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 */
485LIBIMOBILEDEVICE_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 */
499LIBIMOBILEDEVICE_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
27extern "C" { 30extern "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. */ 49typedef enum {
47typedef int16_t idevice_error_t; 50 IDEVICE_E_SUCCESS = 0,
48 51 IDEVICE_E_INVALID_ARG = -1,
49typedef 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
60typedef struct idevice_private idevice_private; /**< \private */
50typedef idevice_private *idevice_t; /**< The device handle. */ 61typedef idevice_private *idevice_t; /**< The device handle. */
51 62
52typedef struct idevice_connection_private idevice_connection_private; 63typedef struct idevice_connection_private idevice_connection_private; /**< \private */
53typedef idevice_connection_private *idevice_connection_t; /**< The connection handle. */ 64typedef idevice_connection_private *idevice_connection_t; /**< The connection handle. */
54 65
55/* generic */ 66/** Options for idevice_new_with_options() */
56void idevice_set_debug_level(int level); 67enum 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 */
74enum 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 */
80struct 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};
85typedef 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 */
60enum idevice_event_type { 89enum 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. */
67typedef struct { 97typedef 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. */
75typedef void (*idevice_event_cb_t) (const idevice_event_t *event, void *user_data); 105typedef void (*idevice_event_cb_t) (const idevice_event_t *event, void *user_data);
76 106
107/** Event subscription context type */
108typedef struct idevice_subscription_context* idevice_subscription_context_t;
109
77/* functions */ 110/* functions */
78idevice_error_t idevice_event_subscribe(idevice_event_cb_t callback, void *user_data); 111
79idevice_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 */
117LIBIMOBILEDEVICE_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 */
132LIBIMOBILEDEVICE_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 */
142LIBIMOBILEDEVICE_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 */
156LIBIMOBILEDEVICE_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 */
166LIBIMOBILEDEVICE_API idevice_error_t idevice_event_unsubscribe(void);
80 167
81/* discovery (synchronous) */ 168/* discovery (synchronous) */
82idevice_error_t idevice_get_device_list(char ***devices, int *count); 169
83idevice_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 */
183LIBIMOBILEDEVICE_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 */
192LIBIMOBILEDEVICE_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 */
203LIBIMOBILEDEVICE_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 */
212LIBIMOBILEDEVICE_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 */
86idevice_error_t idevice_new(idevice_t *device, const char *uuid); 215
87idevice_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 */
233LIBIMOBILEDEVICE_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 */
256LIBIMOBILEDEVICE_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 */
263LIBIMOBILEDEVICE_API idevice_error_t idevice_free(idevice_t device);
88 264
89/* connection/disconnection */ 265/* connection/disconnection */
90idevice_error_t idevice_connect(idevice_t device, uint16_t port, idevice_connection_t *connection); 266
91idevice_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 */
277LIBIMOBILEDEVICE_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 */
286LIBIMOBILEDEVICE_API idevice_error_t idevice_disconnect(idevice_connection_t connection);
92 287
93/* communication */ 288/* communication */
94idevice_error_t idevice_connection_send(idevice_connection_t connection, const char *data, uint32_t len, uint32_t *sent_bytes); 289
95idevice_error_t idevice_connection_receive_timeout(idevice_connection_t connection, char *data, uint32_t len, uint32_t *recv_bytes, unsigned int timeout); 290/**
96idevice_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 */
301LIBIMOBILEDEVICE_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 */
318LIBIMOBILEDEVICE_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 */
333LIBIMOBILEDEVICE_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 */
344LIBIMOBILEDEVICE_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 */
355LIBIMOBILEDEVICE_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 */
368LIBIMOBILEDEVICE_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 */
379LIBIMOBILEDEVICE_API idevice_error_t idevice_connection_get_fd(idevice_connection_t connection, int *fd);
97 380
98/* misc */ 381/* misc */
99idevice_error_t idevice_get_handle(idevice_t device, uint32_t *handle); 382
100idevice_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 */
391LIBIMOBILEDEVICE_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 */
401LIBIMOBILEDEVICE_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 */
408LIBIMOBILEDEVICE_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
28extern "C" { 30extern "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/*@{*/ 36typedef 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,
59typedef int16_t lockdownd_error_t; 61 LOCKDOWN_E_SESSION_ACTIVE = -22,
60 62 LOCKDOWN_E_SESSION_INACTIVE = -23,
61typedef 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
82typedef struct lockdownd_client_private lockdownd_client_private; /**< \private */
62typedef lockdownd_client_private *lockdownd_client_t; /**< The client handle. */ 83typedef lockdownd_client_private *lockdownd_client_t; /**< The client handle. */
63 84
64struct lockdownd_pair_record { 85struct 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 */
71typedef struct lockdownd_pair_record *lockdownd_pair_record_t; 93typedef struct lockdownd_pair_record *lockdownd_pair_record_t; /**< pair record */
94
95/** service descriptor */
96struct 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};
101typedef struct lockdownd_service_descriptor *lockdownd_service_descriptor_t;
102
103/** Callback types used in #lockdownd_cu_pairing_cb_t */
104typedef 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. */
113typedef 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 */
74lockdownd_error_t lockdownd_client_new(idevice_t device, lockdownd_client_t *client, const char *label); 117
75lockdownd_error_t lockdownd_client_new_with_handshake(idevice_t device, lockdownd_client_t *client, const char *label); 118/**
76lockdownd_error_t lockdownd_client_free(lockdownd_client_t client); 119 * Creates a new lockdownd client for the device.
77 120 *
78lockdownd_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
79lockdownd_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.
80lockdownd_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
81lockdownd_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
82lockdownd_error_t lockdownd_start_service(lockdownd_client_t client, const char *service, uint16_t *port); 125 * as the connection is no longer needed.
83lockdownd_error_t lockdownd_start_session(lockdownd_client_t client, const char *host_id, char **session_id, int *ssl_enabled); 126 *
84lockdownd_error_t lockdownd_stop_session(lockdownd_client_t client, const char *session_id); 127 * @param device The device to create a lockdownd client for
85lockdownd_error_t lockdownd_send(lockdownd_client_t client, plist_t plist); 128 * @param client The pointer to the location of the new lockdownd_client
86lockdownd_error_t lockdownd_receive(lockdownd_client_t client, plist_t *plist); 129 * @param label The label to use for communication. Usually the program name.
87lockdownd_error_t lockdownd_pair(lockdownd_client_t client, lockdownd_pair_record_t pair_record); 130 *
88lockdownd_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
89lockdownd_error_t lockdownd_unpair(lockdownd_client_t client, lockdownd_pair_record_t pair_record); 132 */
90lockdownd_error_t lockdownd_activate(lockdownd_client_t client, plist_t activation_record); 133LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_client_new(idevice_t device, lockdownd_client_t *client, const char *label);
91lockdownd_error_t lockdownd_deactivate(lockdownd_client_t client); 134
92lockdownd_error_t lockdownd_enter_recovery(lockdownd_client_t client); 135/**
93lockdownd_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 */
152LIBIMOBILEDEVICE_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 */
162LIBIMOBILEDEVICE_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 */
174LIBIMOBILEDEVICE_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 */
186LIBIMOBILEDEVICE_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 */
199LIBIMOBILEDEVICE_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 */
212LIBIMOBILEDEVICE_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 */
226LIBIMOBILEDEVICE_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 */
242LIBIMOBILEDEVICE_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 */
257LIBIMOBILEDEVICE_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 */
269LIBIMOBILEDEVICE_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 */
283LIBIMOBILEDEVICE_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 */
294LIBIMOBILEDEVICE_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 */
310LIBIMOBILEDEVICE_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 */
329LIBIMOBILEDEVICE_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 */
348LIBIMOBILEDEVICE_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 */
364LIBIMOBILEDEVICE_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 */
381LIBIMOBILEDEVICE_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 */
393LIBIMOBILEDEVICE_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 */
402LIBIMOBILEDEVICE_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 */
413LIBIMOBILEDEVICE_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 */
442LIBIMOBILEDEVICE_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 */
462LIBIMOBILEDEVICE_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 */
482LIBIMOBILEDEVICE_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 */
495LIBIMOBILEDEVICE_API lockdownd_error_t lockdownd_pair_cu(lockdownd_client_t client);
496
94 497
95/* Helper */ 498/* Helper */
96void lockdownd_client_set_label(lockdownd_client_t client, const char *label); 499
97lockdownd_error_t lockdownd_get_device_uuid(lockdownd_client_t control, char **uuid); 500/**
98lockdownd_error_t lockdownd_get_device_name(lockdownd_client_t client, char **device_name); 501 * Sets the label to send for requests to lockdownd.
99lockdownd_error_t lockdownd_get_sync_data_classes(lockdownd_client_t client, char ***classes, int *count); 502 *
100lockdownd_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 */
507LIBIMOBILEDEVICE_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 */
518LIBIMOBILEDEVICE_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 */
529LIBIMOBILEDEVICE_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 */
544LIBIMOBILEDEVICE_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 */
553LIBIMOBILEDEVICE_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 */
562LIBIMOBILEDEVICE_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 */
571LIBIMOBILEDEVICE_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
28extern "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 */
38typedef 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
47typedef struct misagent_client_private misagent_client_private; /**< \private */
48typedef 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 */
63LIBIMOBILEDEVICE_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 */
78LIBIMOBILEDEVICE_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 */
89LIBIMOBILEDEVICE_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 */
102LIBIMOBILEDEVICE_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 */
121LIBIMOBILEDEVICE_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 */
140LIBIMOBILEDEVICE_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 */
153LIBIMOBILEDEVICE_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 */
162LIBIMOBILEDEVICE_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
27extern "C" { 28extern "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/*@}*/ 38typedef 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. */ 49typedef struct mobile_image_mounter_client_private mobile_image_mounter_client_private; /**< \private */
43typedef int16_t mobile_image_mounter_error_t;
44
45typedef struct mobile_image_mounter_client_private mobile_image_mounter_client_private;
46typedef mobile_image_mounter_client_private *mobile_image_mounter_client_t; /**< The client handle. */ 50typedef mobile_image_mounter_client_private *mobile_image_mounter_client_t; /**< The client handle. */
47 51
52/** callback for image upload */
53typedef ssize_t (*mobile_image_mounter_upload_cb_t) (void* buffer, size_t length, void *user_data);
54
48/* Interface */ 55/* Interface */
49mobile_image_mounter_error_t mobile_image_mounter_new(idevice_t device, uint16_t port, mobile_image_mounter_client_t *client); 56
50mobile_image_mounter_error_t mobile_image_mounter_free(mobile_image_mounter_client_t client); 57/**
51mobile_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.
52mobile_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 *
53mobile_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 */
70LIBIMOBILEDEVICE_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 */
85LIBIMOBILEDEVICE_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 */
96LIBIMOBILEDEVICE_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 */
112LIBIMOBILEDEVICE_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 */
131LIBIMOBILEDEVICE_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 */
153LIBIMOBILEDEVICE_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 */
174LIBIMOBILEDEVICE_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 */
185LIBIMOBILEDEVICE_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 */
198LIBIMOBILEDEVICE_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 */
209LIBIMOBILEDEVICE_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 */
223LIBIMOBILEDEVICE_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 */
235LIBIMOBILEDEVICE_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 */
249LIBIMOBILEDEVICE_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 */
259LIBIMOBILEDEVICE_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 */
269LIBIMOBILEDEVICE_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
27extern "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 */
37typedef 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
47typedef struct mobileactivation_client_private mobileactivation_client_private; /**< \private */
48typedef 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 */
62LIBIMOBILEDEVICE_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 */
77LIBIMOBILEDEVICE_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 */
90LIBIMOBILEDEVICE_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 */
105LIBIMOBILEDEVICE_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 */
119LIBIMOBILEDEVICE_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 */
133LIBIMOBILEDEVICE_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 */
151LIBIMOBILEDEVICE_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 */
164LIBIMOBILEDEVICE_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 */
179LIBIMOBILEDEVICE_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 */
186LIBIMOBILEDEVICE_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/*@}*/ 38typedef enum {
43 39 MOBILEBACKUP_E_SUCCESS = 0,
44/** Represents an error code. */ 40 MOBILEBACKUP_E_INVALID_ARG = -1,
45typedef 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
47typedef struct mobilebackup_client_private mobilebackup_client_private; 50typedef struct mobilebackup_client_private mobilebackup_client_private; /**< \private */
48typedef mobilebackup_client_private *mobilebackup_client_t; /**< The client handle. */ 51typedef mobilebackup_client_private *mobilebackup_client_t; /**< The client handle. */
49 52
53/** Available flags passed to #mobilebackup_request_restore */
50typedef enum { 54typedef 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
56mobilebackup_error_t mobilebackup_client_new(idevice_t device, uint16_t port, mobilebackup_client_t * client); 60/**
57mobilebackup_error_t mobilebackup_client_free(mobilebackup_client_t client); 61 * Connects to the mobilebackup service on the specified device.
58mobilebackup_error_t mobilebackup_receive(mobilebackup_client_t client, plist_t *plist); 62 *
59mobilebackup_error_t mobilebackup_send(mobilebackup_client_t client, plist_t plist); 63 * @param device The device to connect to.
60mobilebackup_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.
61mobilebackup_error_t mobilebackup_send_backup_file_received(mobilebackup_client_t client); 65 * @param client Pointer that will be set to a newly allocated
62mobilebackup_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.
63mobilebackup_error_t mobilebackup_receive_restore_file_received(mobilebackup_client_t client, plist_t *result); 67 *
64mobilebackup_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
65mobilebackup_error_t mobilebackup_send_restore_complete(mobilebackup_client_t client); 69 * or more parameters are invalid, or DEVICE_LINK_SERVICE_E_BAD_VERSION if
66mobilebackup_error_t mobilebackup_send_error(mobilebackup_client_t client, const char *reason); 70 * the mobilebackup version on the device is newer.
71 */
72LIBIMOBILEDEVICE_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 */
87LIBIMOBILEDEVICE_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 */
98LIBIMOBILEDEVICE_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 */
109LIBIMOBILEDEVICE_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 */
122LIBIMOBILEDEVICE_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 */
141LIBIMOBILEDEVICE_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 */
152LIBIMOBILEDEVICE_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 */
175LIBIMOBILEDEVICE_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 */
195LIBIMOBILEDEVICE_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 */
215LIBIMOBILEDEVICE_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 */
228LIBIMOBILEDEVICE_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 */
240LIBIMOBILEDEVICE_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
28extern "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 */
38typedef 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
51typedef struct mobilebackup2_client_private mobilebackup2_client_private; /**< \private */
52typedef 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 */
67LIBIMOBILEDEVICE_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 */
82LIBIMOBILEDEVICE_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 */
93LIBIMOBILEDEVICE_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 */
108LIBIMOBILEDEVICE_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 */
128LIBIMOBILEDEVICE_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 */
146LIBIMOBILEDEVICE_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 */
166LIBIMOBILEDEVICE_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 */
179LIBIMOBILEDEVICE_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 */
194LIBIMOBILEDEVICE_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 */
208LIBIMOBILEDEVICE_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 41typedef 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. */
50typedef enum { 57typedef 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. */ 63typedef struct mobilesync_client_private mobilesync_client_private; /**< \private */
57typedef int16_t mobilesync_error_t;
58
59typedef struct mobilesync_client_private mobilesync_client_private;
60typedef mobilesync_client_private *mobilesync_client_t; /**< The client handle */ 64typedef mobilesync_client_private *mobilesync_client_t; /**< The client handle */
61 65
66/** Anchors used by the device and computer (structure) */
62typedef struct { 67typedef 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;
66typedef mobilesync_anchors *mobilesync_anchors_t; /**< Anchors used by the device and computer. */ 71/** Anchors used by the device and computer */
72typedef mobilesync_anchors *mobilesync_anchors_t;
67 73
68/* Interface */ 74/* Interface */
69mobilesync_error_t mobilesync_client_new(idevice_t device, uint16_t port, mobilesync_client_t * client);
70mobilesync_error_t mobilesync_client_free(mobilesync_client_t client);
71 75
72mobilesync_error_t mobilesync_receive(mobilesync_client_t client, plist_t *plist); 76/**
73mobilesync_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 */
89LIBIMOBILEDEVICE_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 */
104LIBIMOBILEDEVICE_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 */
115LIBIMOBILEDEVICE_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 */
126LIBIMOBILEDEVICE_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 */
139LIBIMOBILEDEVICE_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 */
162LIBIMOBILEDEVICE_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 */
173LIBIMOBILEDEVICE_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 */
186LIBIMOBILEDEVICE_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 */
199LIBIMOBILEDEVICE_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 */
211LIBIMOBILEDEVICE_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 */
224LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_clear_all_records_on_device(mobilesync_client_t client);
74 225
75mobilesync_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);
76mobilesync_error_t mobilesync_cancel(mobilesync_client_t client, const char* reason);
77mobilesync_error_t mobilesync_finish(mobilesync_client_t client);
78 226
79mobilesync_error_t mobilesync_get_all_records_from_device(mobilesync_client_t client); 227/**
80mobilesync_error_t mobilesync_get_changes_from_device(mobilesync_client_t client); 228 * Receives changed entitites of the currently set data class from the device
81mobilesync_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 */
240LIBIMOBILEDEVICE_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 */
250LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_acknowledge_changes_from_device(mobilesync_client_t client);
82 251
83mobilesync_error_t mobilesync_receive_changes(mobilesync_client_t client, plist_t *entities, uint8_t *is_last_record, plist_t *actions);
84mobilesync_error_t mobilesync_acknowledge_changes_from_device(mobilesync_client_t client);
85 252
86mobilesync_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 */
270LIBIMOBILEDEVICE_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 */
287LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_send_changes(mobilesync_client_t client, plist_t entities, uint8_t is_last_record, plist_t actions);
87 288
88mobilesync_error_t mobilesync_send_changes(mobilesync_client_t client, plist_t entities, uint8_t is_last_record, plist_t actions); 289/**
89mobilesync_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 */
304LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_remap_identifiers(mobilesync_client_t client, plist_t *mapping);
90 305
91/* Helper */ 306/* Helper */
92mobilesync_anchors_t mobilesync_anchors_new(const char *device_anchor, const char *computer_anchor);
93void mobilesync_anchors_free(mobilesync_anchors_t anchors);
94 307
95plist_t mobilesync_actions_new(); 308/**
96void mobilesync_actions_add(plist_t actions, ...) G_GNUC_NULL_TERMINATED; 309 * Allocates memory for a new anchors struct initialized with the passed anchors.
97void 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 */
317LIBIMOBILEDEVICE_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 */
324LIBIMOBILEDEVICE_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 */
332LIBIMOBILEDEVICE_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 */
346LIBIMOBILEDEVICE_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 */
353LIBIMOBILEDEVICE_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
27extern "C" { 28extern "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/*@}*/ 38typedef enum {
41 39 NP_E_SUCCESS = 0,
42/** Represents an error code. */ 40 NP_E_INVALID_ARG = -1,
43typedef 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
86typedef struct np_client_private np_client_private; 92typedef struct np_client_private np_client_private; /**< \private */
87typedef np_client_private *np_client_t; /**< The client handle. */ 93typedef 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. */
90typedef void (*np_notify_cb_t) (const char *notification, void *user_data); 96typedef void (*np_notify_cb_t) (const char *notification, void *user_data);
91 97
92/* Interface */ 98/* Interface */
93np_error_t np_client_new(idevice_t device, uint16_t port, np_client_t *client); 99
94np_error_t np_client_free(np_client_t client); 100/**
95np_error_t np_post_notification(np_client_t client, const char *notification); 101 * Connects to the notification_proxy on the specified device.
96np_error_t np_observe_notification(np_client_t client, const char *notification); 102 *
97np_error_t np_observe_notifications(np_client_t client, const char **notification_spec); 103 * @param device The device to connect to.
98np_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 */
112LIBIMOBILEDEVICE_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 */
127LIBIMOBILEDEVICE_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 */
137LIBIMOBILEDEVICE_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 */
148LIBIMOBILEDEVICE_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 */
159LIBIMOBILEDEVICE_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 */
172LIBIMOBILEDEVICE_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 */
196LIBIMOBILEDEVICE_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
27extern "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 */
37typedef 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
49typedef struct preboard_client_private preboard_client_private; /**< \private */
50typedef preboard_client_private *preboard_client_t; /**< The client handle. */
51
52/** Reports the status response of the given command */
53typedef 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 */
67LIBIMOBILEDEVICE_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 */
82LIBIMOBILEDEVICE_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 */
93LIBIMOBILEDEVICE_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 */
105LIBIMOBILEDEVICE_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 */
118LIBIMOBILEDEVICE_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 */
132LIBIMOBILEDEVICE_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 */
160LIBIMOBILEDEVICE_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 */
181LIBIMOBILEDEVICE_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
28extern "C" {
29#endif
30
31#include <libimobiledevice/lockdown.h>
32#include <libimobiledevice/service.h>
33
34/** Error Codes */
35typedef 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
46typedef struct property_list_service_client_private property_list_service_private; /**< \private */
47typedef 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 */
63LIBIMOBILEDEVICE_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 */
74LIBIMOBILEDEVICE_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 */
87LIBIMOBILEDEVICE_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 */
100LIBIMOBILEDEVICE_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 */
119LIBIMOBILEDEVICE_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 */
142LIBIMOBILEDEVICE_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 */
155LIBIMOBILEDEVICE_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 */
167LIBIMOBILEDEVICE_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 */
178LIBIMOBILEDEVICE_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
27extern "C" { 29extern "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/*@{*/ 35typedef 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 45typedef struct restored_client_private restored_client_private; /**< \private */
44/*@}*/
45
46/** Represents an error code. */
47typedef int16_t restored_error_t;
48
49typedef struct restored_client_private restored_client_private;
50typedef restored_client_private *restored_client_t; /**< The client handle. */ 46typedef restored_client_private *restored_client_t; /**< The client handle. */
51 47
52/* Interface */ 48/* Interface */
53restored_error_t restored_client_new(idevice_t device, restored_client_t *client, const char *label);
54restored_error_t restored_client_free(restored_client_t client);
55 49
56restored_error_t restored_query_type(restored_client_t client, char **type, uint64_t *version); 50/**
57restored_error_t restored_get_value(restored_client_t client, const char *key, plist_t *value) ; 51 * Creates a new restored client for the device.
58restored_error_t restored_send(restored_client_t client, plist_t plist); 52 *
59restored_error_t restored_receive(restored_client_t client, plist_t *plist); 53 * @param device The device to create a restored client for
60restored_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 */
59LIBIMOBILEDEVICE_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 */
69LIBIMOBILEDEVICE_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 */
82LIBIMOBILEDEVICE_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 */
93LIBIMOBILEDEVICE_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 */
104LIBIMOBILEDEVICE_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 */
118LIBIMOBILEDEVICE_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 */
129LIBIMOBILEDEVICE_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 */
139LIBIMOBILEDEVICE_API restored_error_t restored_goodbye(restored_client_t client);
61 140
62restored_error_t restored_start_restore(restored_client_t client); 141
63restored_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 */
152LIBIMOBILEDEVICE_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 */
162LIBIMOBILEDEVICE_API restored_error_t restored_reboot(restored_client_t client);
64 163
65/* Helper */ 164/* Helper */
66void 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 */
173LIBIMOBILEDEVICE_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
28extern "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 */
36typedef 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
47typedef struct reverse_proxy_client_private reverse_proxy_client_private; /**< \private */
48typedef reverse_proxy_client_private *reverse_proxy_client_t; /**< The client handle. */
49
50/** reverse proxy client type */
51typedef 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 */
57typedef 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 */
67typedef 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 */
79typedef 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 */
90typedef 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 */
100typedef 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 */
121LIBIMOBILEDEVICE_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 */
139LIBIMOBILEDEVICE_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 */
146LIBIMOBILEDEVICE_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 */
158LIBIMOBILEDEVICE_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 */
171LIBIMOBILEDEVICE_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 */
183LIBIMOBILEDEVICE_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
196LIBIMOBILEDEVICE_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 */
207LIBIMOBILEDEVICE_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
27extern "C" { 28extern "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/*@}*/ 38typedef 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 */
43typedef int16_t sbservices_error_t; 47typedef 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
45typedef struct sbservices_client_private sbservices_client_private; 55typedef struct sbservices_client_private sbservices_client_private; /**< \private */
46typedef sbservices_client_private *sbservices_client_t; /**< The client handle. */ 56typedef sbservices_client_private *sbservices_client_t; /**< The client handle. */
47 57
48/* Interface */ 58/* Interface */
49sbservices_error_t sbservices_client_new(idevice_t device, uint16_t port, sbservices_client_t *client); 59
50sbservices_error_t sbservices_client_free(sbservices_client_t client); 60/**
51sbservices_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.
52sbservices_error_t sbservices_set_icon_state(sbservices_client_t client, plist_t newstate); 62 *
53sbservices_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.
54sbservices_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 */
71LIBIMOBILEDEVICE_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 */
86LIBIMOBILEDEVICE_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 */
97LIBIMOBILEDEVICE_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 */
114LIBIMOBILEDEVICE_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 */
125LIBIMOBILEDEVICE_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 */
142LIBIMOBILEDEVICE_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 */
153LIBIMOBILEDEVICE_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 */
169LIBIMOBILEDEVICE_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/*@}*/ 39typedef 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. */ 50typedef struct screenshotr_client_private screenshotr_client_private; /**< \private */
45typedef int16_t screenshotr_error_t;
46
47typedef struct screenshotr_client_private screenshotr_client_private;
48typedef screenshotr_client_private *screenshotr_client_t; /**< The client handle. */ 51typedef screenshotr_client_private *screenshotr_client_t; /**< The client handle. */
49 52
50screenshotr_error_t screenshotr_client_new(idevice_t device, uint16_t port, screenshotr_client_t * client); 53
51screenshotr_error_t screenshotr_client_free(screenshotr_client_t client); 54/**
52screenshotr_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 */
69LIBIMOBILEDEVICE_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 */
84LIBIMOBILEDEVICE_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 */
95LIBIMOBILEDEVICE_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 */
112LIBIMOBILEDEVICE_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
27extern "C" {
28#endif
29
30#include <libimobiledevice/libimobiledevice.h>
31#include <libimobiledevice/lockdown.h>
32
33/** Error Codes */
34typedef 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
45typedef struct service_client_private service_client_private; /**< \private */
46typedef 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 */
65LIBIMOBILEDEVICE_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 */
84LIBIMOBILEDEVICE_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 */
95LIBIMOBILEDEVICE_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 */
111LIBIMOBILEDEVICE_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 */
128LIBIMOBILEDEVICE_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 */
146LIBIMOBILEDEVICE_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 */
161LIBIMOBILEDEVICE_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 */
172LIBIMOBILEDEVICE_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 */
185LIBIMOBILEDEVICE_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 */
196LIBIMOBILEDEVICE_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
28extern "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 */
38typedef 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
48typedef struct syslog_relay_client_private syslog_relay_client_private; /**< \private */
49typedef syslog_relay_client_private *syslog_relay_client_t; /**< The client handle. */
50
51/** Receives each character received from the device. */
52typedef 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 */
68LIBIMOBILEDEVICE_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 */
83LIBIMOBILEDEVICE_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 */
94LIBIMOBILEDEVICE_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 */
111LIBIMOBILEDEVICE_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 */
132LIBIMOBILEDEVICE_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 */
146LIBIMOBILEDEVICE_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 */
165LIBIMOBILEDEVICE_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 */
178LIBIMOBILEDEVICE_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
28extern "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 */
38typedef 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
49typedef struct webinspector_client_private webinspector_client_private; /**< \private */
50typedef 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 */
65LIBIMOBILEDEVICE_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 */
80LIBIMOBILEDEVICE_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 */
91LIBIMOBILEDEVICE_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 */
103LIBIMOBILEDEVICE_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 */
114LIBIMOBILEDEVICE_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 */
131LIBIMOBILEDEVICE_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
© 2009-2020 sukimashita.com - Generated by cgit - Icons from Tango - Uses Google Analytics