Debian Codegraph @

include/usbmuxd.h

raw
1 /*
2 * usbmuxd.h - A client library to talk to the usbmuxd daemon.
3 *
4 * Copyright (C) 2009-2018 Nikias Bassen <[email protected]>
5 * Copyright (C) 2014 Martin Szulecki <[email protected]>
6 * Copyright (C) 2009 Paul Sladen <[email protected]>
7 *
8 * This library is free software; you can redistribute it and/or modify
9 * it under the terms of the GNU Lesser General Public License as
10 * published by the Free Software Foundation, either version 2.1 of the
11 * 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
16 * GNU 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 program; if not, write to the Free Software
20 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
21 */
22
23 #ifndef USBMUXD_H
24 #define USBMUXD_H
25 #include <stdint.h>
26
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30
31 #ifndef USBMUXD_API
32 #ifdef LIBUSBMUXD_STATIC
33 #define USBMUXD_API
34 #elif defined(_WIN32)
35 #define USBMUXD_API __declspec(dllimport)
36 #else
37 #define USBMUXD_API
38 #endif
39 #endif
40
41 /** Device lookup options for usbmuxd_get_device. */
42 enum usbmux_lookup_options {
43 DEVICE_LOOKUP_USBMUX = 1 << 1, /**< include USBMUX devices during lookup */
44 DEVICE_LOOKUP_NETWORK = 1 << 2, /**< include network devices during lookup */
45 DEVICE_LOOKUP_PREFER_NETWORK = 1 << 3 /**< prefer network connection if device is available via USBMUX *and* network */
46 };
47
48 /** Type of connection a device is available on */
49 enum usbmux_connection_type {
50 CONNECTION_TYPE_USB = 1,
51 CONNECTION_TYPE_NETWORK
52 };
53
54 /**
55 * Device information structure holding data to identify the device.
56 * The relevant 'handle' should be passed to 'usbmuxd_connect()', to
57 * start a proxy connection. The value 'handle' should be considered
58 * opaque and no presumption made about the meaning of its value.
59 */
60 typedef struct {
61 uint32_t handle;
62 uint32_t product_id;
63 char udid[44];
64 enum usbmux_connection_type conn_type;
65 uint8_t conn_data[200];
66 } usbmuxd_device_info_t;
67
68 /**
69 * event types for event callback function
70 */
71 enum usbmuxd_event_type {
72 UE_DEVICE_ADD = 1,
73 UE_DEVICE_REMOVE,
74 UE_DEVICE_PAIRED
75 };
76
77 /**
78 * Event structure that will be passed to the callback function.
79 * 'event' will contains the type of the event, and 'device' will contains
80 * information about the device.
81 */
82 typedef struct {
83 int event;
84 usbmuxd_device_info_t device;
85 } usbmuxd_event_t;
86
87 /**
88 * Callback function prototype.
89 */
90 typedef void (*usbmuxd_event_cb_t) (const usbmuxd_event_t *event, void *user_data);
91
92 /**
93 * Subscription context type.
94 */
95 typedef struct usbmuxd_subscription_context* usbmuxd_subscription_context_t;
96
97 /**
98 * Subscribe a callback function to be called upon device add/remove events.
99 * This method can be called multiple times to register multiple callbacks
100 * since every subscription will have its own context (returned in the
101 * first parameter).
102 *
103 * @param context A pointer to a usbmuxd_subscription_context_t that will be
104 * set upon creation of the subscription. The returned context must be
105 * passed to usbmuxd_events_unsubscribe() to unsubscribe the callback.
106 * @param callback A callback function that is executed when an event occurs.
107 * @param user_data Custom data passed on to the callback function. The data
108 * needs to be kept available until the callback function is unsubscribed.
109 *
110 * @return 0 on success or a negative errno value.
111 */
112 USBMUXD_API int usbmuxd_events_subscribe(usbmuxd_subscription_context_t *context, usbmuxd_event_cb_t callback, void *user_data);
113
114 /**
115 * Unsubscribe callback function
116 *
117 * @param context A valid context as returned from usbmuxd_events_subscribe().
118 *
119 * @return 0 on success or a negative errno value.
120 */
121 USBMUXD_API int usbmuxd_events_unsubscribe(usbmuxd_subscription_context_t context);
122
123 /**
124 * Subscribe a callback (deprecated)
125 *
126 * @param callback A callback function that is executed when an event occurs.
127 * @param user_data Custom data passed on to the callback function. The data
128 * needs to be kept available until the callback function is unsubscribed.
129 *
130 * @return 0 on success or negative on error.
131 *
132 * @note Deprecated. Use usbmuxd_events_subscribe and usbmuxd_events_unsubscribe instead.
133 * @see usbmuxd_events_subscribe
134 */
135 USBMUXD_API int usbmuxd_subscribe(usbmuxd_event_cb_t callback, void *user_data);
136
137 /**
138 * Unsubscribe callback (deprecated)
139 *
140 * @return 0 on success or negative on error.
141 *
142 * @note Deprecated. Use usbmuxd_events_subscribe and usbmuxd_events_unsubscribe instead.
143 * @see usbmuxd_events_unsubscribe
144 */
145 USBMUXD_API int usbmuxd_unsubscribe(void);
146
147 /**
148 * Contacts usbmuxd and retrieves a list of connected devices.
149 *
150 * @param device_list A pointer to an array of usbmuxd_device_info_t
151 * that will hold records of the connected devices. The last record
152 * is a null-terminated record with all fields set to 0/NULL.
153 * @note The user has to free the list returned.
154 *
155 * @return number of attached devices, zero on no devices, or negative
156 * if an error occured.
157 */
158 USBMUXD_API int usbmuxd_get_device_list(usbmuxd_device_info_t **device_list);
159
160 /**
161 * Frees the device list returned by an usbmuxd_get_device_list call
162 *
163 * @param device_list A pointer to an array of usbmuxd_device_info_t to free.
164 *
165 * @return 0 on success, -1 on error.
166 */
167 USBMUXD_API int usbmuxd_device_list_free(usbmuxd_device_info_t **device_list);
168
169 /**
170 * Looks up the device specified by UDID and returns device information.
171 *
172 * @note This function only considers devices connected through USB. To
173 * query devices available via network, use usbmuxd_get_device().
174 *
175 * @see usbmuxd_get_device
176 *
177 * @param udid A device UDID of the device to look for. If udid is NULL,
178 * This function will return the first device found.
179 * @param device Pointer to a previously allocated (or static)
180 * usbmuxd_device_info_t that will be filled with the device info.
181 *
182 * @return 0 if no matching device is connected, 1 if the device was found,
183 * or a negative value on error.
184 */
185 USBMUXD_API int usbmuxd_get_device_by_udid(const char *udid, usbmuxd_device_info_t *device);
186
187 /**
188 * Looks up the device specified by UDID with given options and returns
189 * device information.
190 *
191 * @param udid A device UDID of the device to look for. If udid is NULL,
192 * this function will return the first device found.
193 * @param device Pointer to a previously allocated (or static)
194 * usbmuxd_device_info_t that will be filled with the device info.
195 * @param options Specifying what device connection types should be
196 * considered during lookup. Accepts bitwise or'ed values of
197 * usbmux_lookup_options.
198 * If 0 (no option) is specified it will default to DEVICE_LOOKUP_USBMUX.
199 * To lookup both USB and network-connected devices, pass
200 * DEVICE_LOOKUP_USBMUX | DEVICE_LOOKUP_NETWORK. If a device is available
201 * both via USBMUX *and* network, it will select the USB connection.
202 * This behavior can be changed by adding DEVICE_LOOKUP_PREFER_NETWORK
203 * to the options in which case it will select the network connection.
204 *
205 * @see enum usbmux_lookup_options
206 *
207 * @return 0 if no matching device is connected, 1 if the device was found,
208 * or a negative value on error.
209 */
210 USBMUXD_API int usbmuxd_get_device(const char *udid, usbmuxd_device_info_t *device, enum usbmux_lookup_options options);
211
212 /**
213 * Request proxy connection to the specified device and port.
214 *
215 * @param handle returned in the usbmux_device_info_t structure via
216 * usbmuxd_get_device() or usbmuxd_get_device_list().
217 *
218 * @param tcp_port TCP port number on device, in range 0-65535.
219 * common values are 62078 for lockdown, and 22 for SSH.
220 *
221 * @return socket file descriptor of the connection, or a negative errno
222 * value on error.
223 */
224 USBMUXD_API int usbmuxd_connect(const uint32_t handle, const unsigned short tcp_port);
225
226 /**
227 * Disconnect. For now, this just closes the socket file descriptor.
228 *
229 * @param sfd socket file descriptor returned by usbmuxd_connect()
230 *
231 * @return 0 on success, -1 on error.
232 */
233 USBMUXD_API int usbmuxd_disconnect(int sfd);
234
235 /**
236 * Send data to the specified socket.
237 *
238 * @param sfd socket file descriptor returned by usbmuxd_connect()
239 * @param data buffer to send
240 * @param len size of buffer to send
241 * @param sent_bytes how many bytes sent
242 *
243 * @return 0 on success, a negative errno value otherwise.
244 */
245 USBMUXD_API int usbmuxd_send(int sfd, const char *data, uint32_t len, uint32_t *sent_bytes);
246
247 /**
248 * Receive data from the specified socket.
249 *
250 * @param sfd socket file descriptor returned by usbmuxd_connect()
251 * @param data buffer to put the data to
252 * @param len number of bytes to receive
253 * @param recv_bytes number of bytes received
254 * @param timeout how many milliseconds to wait for data
255 *
256 * @return 0 on success, a negative errno value otherwise.
257 */
258 USBMUXD_API int usbmuxd_recv_timeout(int sfd, char *data, uint32_t len, uint32_t *recv_bytes, unsigned int timeout);
259
260 /**
261 * Receive data from the specified socket with a default timeout.
262 *
263 * @param sfd socket file descriptor returned by usbmuxd_connect()
264 * @param data buffer to put the data to
265 * @param len number of bytes to receive
266 * @param recv_bytes number of bytes received
267 *
268 * @return 0 on success, a negative errno value otherwise.
269 */
270 USBMUXD_API int usbmuxd_recv(int sfd, char *data, uint32_t len, uint32_t *recv_bytes);
271
272 /**
273 * Reads the SystemBUID
274 *
275 * @param buid pointer to a variable that will be set to point to a newly
276 * allocated string with the System BUID returned by usbmuxd
277 *
278 * @return 0 on success, a negative errno value otherwise.
279 */
280 USBMUXD_API int usbmuxd_read_buid(char** buid);
281
282 /**
283 * Read a pairing record
284 *
285 * @param record_id the record identifier of the pairing record to retrieve
286 * @param record_data pointer to a variable that will be set to point to a
287 * newly allocated buffer containing the pairing record data
288 * @param record_size pointer to a variable that will be set to the size of
289 * the buffer returned in record_data
290 *
291 * @return 0 on success, a negative error value otherwise.
292 */
293 USBMUXD_API int usbmuxd_read_pair_record(const char* record_id, char **record_data, uint32_t *record_size);
294
295 /**
296 * Save a pairing record
297 *
298 * @param record_id the record identifier of the pairing record to save
299 * @param record_data buffer containing the pairing record data
300 * @param record_size size of the buffer passed in record_data
301 *
302 * @return 0 on success, a negative error value otherwise.
303 */
304 USBMUXD_API int usbmuxd_save_pair_record(const char* record_id, const char *record_data, uint32_t record_size);
305
306 /**
307 * Save a pairing record with device identifier
308 *
309 * @param record_id the record identifier of the pairing record to save
310 * @param device_id the device identifier of the connected device, or 0
311 * @param record_data buffer containing the pairing record data
312 * @param record_size size of the buffer passed in record_data
313 *
314 * @return 0 on success, a negative error value otherwise.
315 */
316 USBMUXD_API int usbmuxd_save_pair_record_with_device_id(const char* record_id, uint32_t device_id, const char *record_data, uint32_t record_size);
317
318 /**
319 * Delete a pairing record
320 *
321 * @param record_id the record identifier of the pairing record to delete.
322 *
323 * @return 0 on success, a negative errno value otherwise.
324 */
325 USBMUXD_API int usbmuxd_delete_pair_record(const char* record_id);
326
327 /**
328 * Enable or disable the use of inotify extension. Enabled by default.
329 * Use 0 to disable and 1 to enable inotify support.
330 * This only has an effect on linux systems if inotify support has been built
331 * in. Otherwise and on all other platforms this function has no effect.
332 */
333 USBMUXD_API void libusbmuxd_set_use_inotify(int set);
334
335 USBMUXD_API void libusbmuxd_set_debug_level(int level);
336
337 /**
338 * Returns a static string of the libusbmuxd version.
339 *
340 * @return The libusbmuxd version as static ascii string
341 */
342 USBMUXD_API const char* libusbmuxd_version();
343
344 #ifdef __cplusplus
345 }
346 #endif
347
348 #endif /* USBMUXD_H */