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