include/usbmuxd.h

/*
 * usbmuxd.h - A client library to talk to the usbmuxd daemon.
 *
 * Copyright (C) 2009-2018 Nikias Bassen <nikias@gmx.li>
 * Copyright (C) 2014 Martin Szulecki <m.szulecki@libimobiledevice.org>
 * Copyright (C) 2009 Paul Sladen <libiphone@paul.sladen.org>
 *
 * This library is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation, either version 2.1 of the
 * License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 */

#ifndef USBMUXD_H
#define USBMUXD_H
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/** Device lookup options for usbmuxd_get_device. */
enum usbmux_lookup_options {
	DEVICE_LOOKUP_USBMUX = 1 << 1, /**< include USBMUX devices during lookup */
	DEVICE_LOOKUP_NETWORK = 1 << 2, /**< include network devices during lookup */
	DEVICE_LOOKUP_PREFER_NETWORK = 1 << 3 /**< prefer network connection if device is available via USBMUX *and* network */
};

/** Type of connection a device is available on */
enum usbmux_connection_type {
	CONNECTION_TYPE_USB = 1,
	CONNECTION_TYPE_NETWORK
};

/**
 * Device information structure holding data to identify the device.
 * The relevant 'handle' should be passed to 'usbmuxd_connect()', to
 * start a proxy connection.  The value 'handle' should be considered
 * opaque and no presumption made about the meaning of its value.
 */
typedef struct {
	uint32_t handle;
	uint32_t product_id;
	char udid[44];
	enum usbmux_connection_type conn_type;
	char conn_data[200];
} usbmuxd_device_info_t;

/**
 * event types for event callback function
 */
enum usbmuxd_event_type {
    UE_DEVICE_ADD = 1,
    UE_DEVICE_REMOVE,
    UE_DEVICE_PAIRED
};

/**
 * Event structure that will be passed to the callback function.
 * 'event' will contains the type of the event, and 'device' will contains
 * information about the device.
 */
typedef struct {
    int event;
    usbmuxd_device_info_t device;
} usbmuxd_event_t;

/**
 * Callback function prototype.
 */
typedef void (*usbmuxd_event_cb_t) (const usbmuxd_event_t *event, void *user_data);

/**
 * Subscription context type.
 */
typedef struct usbmuxd_subscription_context* usbmuxd_subscription_context_t;

/**
 * Subscribe a callback function to be called upon device add/remove events.
 * This method can be called multiple times to register multiple callbacks
 * since every subscription will have its own context (returned in the
 * first parameter).
 *
 * @param context A pointer to a usbmuxd_subscription_context_t that will be
 *    set upon creation of the subscription. The returned context must be
 *    passed to usbmuxd_events_unsubscribe() to unsubscribe the callback.
 * @param callback A callback function that is executed when an event occurs.
 * @param user_data Custom data passed on to the callback function. The data
 *    needs to be kept available until the callback function is unsubscribed.
 *
 * @return 0 on success or a negative errno value.
 */
int usbmuxd_events_subscribe(usbmuxd_subscription_context_t *context, usbmuxd_event_cb_t callback, void *user_data);

/**
 * Unsubscribe callback function
 *
 * @param context A valid context as returned from usbmuxd_events_subscribe().
 *
 * @return 0 on success or a negative errno value.
 */
int usbmuxd_events_unsubscribe(usbmuxd_subscription_context_t context);

/**
 * Subscribe a callback (deprecated)
 *
 * @param callback A callback function that is executed when an event occurs.
 * @param user_data Custom data passed on to the callback function. The data
 *    needs to be kept available until the callback function is unsubscribed.
 *
 * @return 0 on success or negative on error.
 *
 * @note Deprecated. Use usbmuxd_events_subscribe and usbmuxd_events_unsubscribe instead.
 * @see usbmuxd_events_subscribe
 */
int usbmuxd_subscribe(usbmuxd_event_cb_t callback, void *user_data);

/**
 * Unsubscribe callback (deprecated)
 *
 * @return 0 on success or negative on error.
 *
 * @note Deprecated. Use usbmuxd_events_subscribe and usbmuxd_events_unsubscribe instead.
 * @see usbmuxd_events_unsubscribe
 */
int usbmuxd_unsubscribe(void);

/**
 * Contacts usbmuxd and retrieves a list of connected devices.
 *
 * @param device_list A pointer to an array of usbmuxd_device_info_t
 *      that will hold records of the connected devices. The last record
 *      is a null-terminated record with all fields set to 0/NULL.
 * @note The user has to free the list returned.
 *
 * @return number of attached devices, zero on no devices, or negative
 *   if an error occured.
 */
int usbmuxd_get_device_list(usbmuxd_device_info_t **device_list);

/**
 * Frees the device list returned by an usbmuxd_get_device_list call
 *
 * @param device_list A pointer to an array of usbmuxd_device_info_t to free.
 *
 * @return 0 on success, -1 on error.
 */
int usbmuxd_device_list_free(usbmuxd_device_info_t **device_list);

/**
 * Looks up the device specified by UDID and returns device information.
 *
 * @note This function only considers devices connected through USB. To
 *      query devices available via network, use usbmuxd_get_device().
 *
 * @see usbmuxd_get_device
 *
 * @param udid A device UDID of the device to look for. If udid is NULL,
 *      This function will return the first device found.
 * @param device Pointer to a previously allocated (or static) 
 *      usbmuxd_device_info_t that will be filled with the device info.
 *
 * @return 0 if no matching device is connected, 1 if the device was found,
 *    or a negative value on error.
 */
int usbmuxd_get_device_by_udid(const char *udid, usbmuxd_device_info_t *device);

/**
 * Looks up the device specified by UDID with given options and returns
 * device information.
 *
 * @param udid A device UDID of the device to look for. If udid is NULL,
 *      this function will return the first device found.
 * @param device Pointer to a previously allocated (or static)
 *      usbmuxd_device_info_t that will be filled with the device info.
 * @param options Specifying what device connection types should be
 *      considered during lookup. Accepts bitwise or'ed values of
 *      usbmux_lookup_options.
 *      If 0 (no option) is specified it will default to DEVICE_LOOKUP_USBMUX.
 *      To lookup both USB and network-connected devices, pass
 *      DEVICE_LOOKUP_USBMUX | DEVICE_LOOKUP_NETWORK. If a device is available
 *      both via USBMUX *and* network, it will select the USB connection.
 *      This behavior can be changed by adding DEVICE_LOOKUP_PREFER_NETWORK
 *      to the options in which case it will select the network connection.
 *
 * @see enum usbmux_lookup_options
 *
 * @return 0 if no matching device is connected, 1 if the device was found,
 *    or a negative value on error.
 */
int usbmuxd_get_device(const char *udid, usbmuxd_device_info_t *device, enum usbmux_lookup_options options);

/**
 * Request proxy connection to the specified device and port.
 *
 * @param handle returned in the usbmux_device_info_t structure via
 *      usbmuxd_get_device() or usbmuxd_get_device_list().
 *
 * @param tcp_port TCP port number on device, in range 0-65535.
 *	common values are 62078 for lockdown, and 22 for SSH.
 *
 * @return socket file descriptor of the connection, or a negative errno
 *    value on error.
 */
int usbmuxd_connect(const uint32_t handle, const unsigned short tcp_port);

/**
 * Disconnect. For now, this just closes the socket file descriptor.
 *
 * @param sfd socket file descriptor returned by usbmuxd_connect()
 *
 * @return 0 on success, -1 on error.
 */
int usbmuxd_disconnect(int sfd);

/**
 * Send data to the specified socket.
 *
 * @param sfd socket file descriptor returned by usbmuxd_connect()
 * @param data buffer to send
 * @param len size of buffer to send
 * @param sent_bytes how many bytes sent
 *
 * @return 0 on success, a negative errno value otherwise.
 */
int usbmuxd_send(int sfd, const char *data, uint32_t len, uint32_t *sent_bytes);

/**
 * Receive data from the specified socket.
 *
 * @param sfd socket file descriptor returned by usbmuxd_connect()
 * @param data buffer to put the data to
 * @param len number of bytes to receive
 * @param recv_bytes number of bytes received
 * @param timeout how many milliseconds to wait for data
 *
 * @return 0 on success, a negative errno value otherwise.
 */
int usbmuxd_recv_timeout(int sfd, char *data, uint32_t len, uint32_t *recv_bytes, unsigned int timeout);

/**
 * Receive data from the specified socket with a default timeout.
 *
 * @param sfd socket file descriptor returned by usbmuxd_connect()
 * @param data buffer to put the data to
 * @param len number of bytes to receive
 * @param recv_bytes number of bytes received
 *
 * @return 0 on success, a negative errno value otherwise.
 */
int usbmuxd_recv(int sfd, char *data, uint32_t len, uint32_t *recv_bytes);

/**
 * Reads the SystemBUID
 *
 * @param buid pointer to a variable that will be set to point to a newly
 *     allocated string with the System BUID returned by usbmuxd
 *
 * @return 0 on success, a negative errno value otherwise.
 */
int usbmuxd_read_buid(char** buid);

/**
 * Read a pairing record
 *
 * @param record_id the record identifier of the pairing record to retrieve
 * @param record_data pointer to a variable that will be set to point to a
 *     newly allocated buffer containing the pairing record data
 * @param record_size pointer to a variable that will be set to the size of
 *     the buffer returned in record_data
 *
 * @return 0 on success, a negative error value otherwise.
 */
int usbmuxd_read_pair_record(const char* record_id, char **record_data, uint32_t *record_size);

/**
 * Save a pairing record
 *
 * @param record_id the record identifier of the pairing record to save
 * @param record_data buffer containing the pairing record data
 * @param record_size size of the buffer passed in record_data
 *
 * @return 0 on success, a negative error value otherwise.
 */
int usbmuxd_save_pair_record(const char* record_id, const char *record_data, uint32_t record_size);

/**
 * Save a pairing record with device identifier
 *
 * @param record_id the record identifier of the pairing record to save
 * @param device_id the device identifier of the connected device, or 0
 * @param record_data buffer containing the pairing record data
 * @param record_size size of the buffer passed in record_data
 *
 * @return 0 on success, a negative error value otherwise.
 */
int usbmuxd_save_pair_record_with_device_id(const char* record_id, uint32_t device_id, const char *record_data, uint32_t record_size);

/**
 * Delete a pairing record
 *
 * @param record_id the record identifier of the pairing record to delete.
 *
 * @return 0 on success, a negative errno value otherwise.
 */
int usbmuxd_delete_pair_record(const char* record_id);

/**
 * Enable or disable the use of inotify extension. Enabled by default.
 * Use 0 to disable and 1 to enable inotify support.
 * This only has an effect on linux systems if inotify support has been built
 * in. Otherwise and on all other platforms this function has no effect.
 */
void libusbmuxd_set_use_inotify(int set);

void libusbmuxd_set_debug_level(int level);

#ifdef __cplusplus
}
#endif

#endif /* USBMUXD_H */