libimobiledevice: libimobiledevice/companion_proxy.h File Reference

libimobiledevice 1.3.0

Macros | Typedefs | Enumerations | Functions
companion_proxy.h File Reference

Companion proxy support. More...

## Macros
#define | COMPANION_PROXY_SERVICE_NAME "com.apple.companion_proxy"

## Typedefs
typedef struct companion_proxy_client_private | companion_proxy_client_private
typedef companion_proxy_client_private * | companion_proxy_client_t
| The client handle.
typedef void(* | companion_proxy_device_event_cb_t) (plist_t event, void *userdata)

## Enumerations
enum | companion_proxy_error_t { COMPANION_PROXY_E_SUCCESS = 0, COMPANION_PROXY_E_INVALID_ARG = -1, COMPANION_PROXY_E_PLIST_ERROR = -2, COMPANION_PROXY_E_MUX_ERROR = -3, COMPANION_PROXY_E_SSL_ERROR = -4, COMPANION_PROXY_E_NOT_ENOUGH_DATA = -5, COMPANION_PROXY_E_TIMEOUT = -6, COMPANION_PROXY_E_OP_IN_PROGRESS = -7, COMPANION_PROXY_E_NO_DEVICES = -100, COMPANION_PROXY_E_UNSUPPORTED_KEY = -101, COMPANION_PROXY_E_TIMEOUT_REPLY = -102, COMPANION_PROXY_E_UNKNOWN_ERROR = -256 }
| Error Codes.

## Functions
companion_proxy_error_t | companion_proxy_client_new (idevice_t device, lockdownd_service_descriptor_t service, companion_proxy_client_t *client)
| Connects to the companion_proxy service on the specified device. More...
companion_proxy_error_t | companion_proxy_client_start_service (idevice_t device, companion_proxy_client_t *client, const char *label)
| Starts a new companion_proxy service on the specified device and connects to it. More...
companion_proxy_error_t | companion_proxy_client_free (companion_proxy_client_t client)
| Disconnects a companion_proxy client from the device and frees up the companion_proxy client data. More...
companion_proxy_error_t | companion_proxy_send (companion_proxy_client_t client, plist_t plist)
| Sends a plist to the service. More...
companion_proxy_error_t | companion_proxy_receive (companion_proxy_client_t client, plist_t *plist)
| Receives a plist from the service. More...
companion_proxy_error_t | companion_proxy_get_device_registry (companion_proxy_client_t client, plist_t *paired_devices)
| Retrieves a list of paired devices. More...
companion_proxy_error_t | companion_proxy_start_listening_for_devices (companion_proxy_client_t client, companion_proxy_device_event_cb_t callback, void *userdata)
| Starts listening for paired devices. More...
companion_proxy_error_t | companion_proxy_stop_listening_for_devices (companion_proxy_client_t client)
| Stops listening for paired devices. More...
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)
| Returns a value for the given key. More...
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)
| Start forwarding a service port on the companion device to a port on the idevice. More...
companion_proxy_error_t | companion_proxy_stop_forwarding_service_port (companion_proxy_client_t client, uint16_t remote_port)
| Stop forwarding a service port between companion device and idevice. More...

## Detailed Description

Companion proxy support.

## Function Documentation

## ◆ companion_proxy_client_free()

companion_proxy_error_t companion_proxy_client_free | ( | companion_proxy_client_t | client | ) |

Disconnects a companion_proxy client from the device and frees up the companion_proxy client data.

Parameters

  client | The companion_proxy client to disconnect and free.

Returns
  COMPANION_PROXY_E_SUCCESS on success, COMPANION_PROXY_E_INVALID_ARG when client is NULL, or an COMPANION_PROXY_E_* error code otherwise.

## ◆ companion_proxy_client_new()

companion_proxy_error_t companion_proxy_client_new | ( | idevice_t | device,
|  | lockdownd_service_descriptor_t | service,
|  | companion_proxy_client_t * | client
| ) |  |

Connects to the companion_proxy service on the specified device.

Parameters

  device | The device to connect to.
  service | The service descriptor returned by lockdownd_start_service.
  client | Pointer that will point to a newly allocated companion_proxy_client_t upon successful return. Must be freed using companion_proxy_client_free() after use.

Returns
  COMPANION_PROXY_E_SUCCESS on success, COMPANION_PROXY_E_INVALID_ARG when the arguments are invalid, or an COMPANION_PROXY_E_* error code otherwise.

## ◆ companion_proxy_client_start_service()

companion_proxy_error_t companion_proxy_client_start_service | ( | idevice_t | device,
|  | companion_proxy_client_t * | client,
|  | const char * | label
| ) |  |

Starts a new companion_proxy service on the specified device and connects to it.

Parameters

  device | The device to connect to.
  client | Pointer that will point to a newly allocated companion_proxy_client_t upon successful return. Must be freed using companion_proxy_client_free() after use.
  label | The label to use for communication. Usually the program name. Pass NULL to disable sending the label in requests to lockdownd.

Returns
  COMPANION_PROXY_E_SUCCESS on success, or an COMPANION_PROXY_E_* error code otherwise.

## ◆ companion_proxy_get_device_registry()

companion_proxy_error_t companion_proxy_get_device_registry | ( | companion_proxy_client_t | client,
|  | plist_t * | paired_devices
| ) |  |

Retrieves a list of paired devices.

Parameters

  client | The companion_proxy client
  devices | Point that will receive a PLIST_ARRAY with paired device UDIDs

Note
  The device closes the connection after sending the reply.

Returns
  COMPANION_PROXY_E_SUCCESS on success, COMPANION_PROXY_E_NO_DEVICES if no devices are paired, or a COMPANION_PROXY_E_* error code otherwise.

## ◆ companion_proxy_get_value_from_registry()

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
| ) |  |

Returns a value for the given key.

Parameters

  client | The companion_proxy client
  companion_udid | UDID of the (paired) companion device
  key | The key to retrieve the value for

Note
  The device closes the connection after sending the reply.

Returns
  COMPANION_PROXY_E_SUCCESS on success, COMPANION_PROXY_E_INVALID_ARG when client or paired_devices is invalid, COMPANION_PROXY_E_UNSUPPORTED_KEY if the companion device doesn't support the given key, or a COMPANION_PROXY_E_* error code otherwise.

## ◆ companion_proxy_receive()

companion_proxy_error_t companion_proxy_receive | ( | companion_proxy_client_t | client,
|  | plist_t * | plist
| ) |  |

Receives a plist from the service.

Parameters

  client | The companion_proxy client
  plist | The plist to store the received data

Returns
  COMPANION_PROXY_E_SUCCESS on success, COMPANION_PROXY_E_INVALID_ARG when client or plist is NULL

## ◆ companion_proxy_send()

companion_proxy_error_t companion_proxy_send | ( | companion_proxy_client_t | client,
|  | plist_t | plist
| ) |  |

Sends a plist to the service.

Parameters

  client | The companion_proxy client
  plist | The plist to send

Returns
  COMPANION_PROXY_E_SUCCESS on success, COMPANION_PROXY_E_INVALID_ARG when client or plist is NULL

## ◆ companion_proxy_start_forwarding_service_port()

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
| ) |  |

Start forwarding a service port on the companion device to a port on the idevice.

See also
  companion_proxy_stop_forwarding_service_port

Parameters

  client | The companion_proxy client
  remote_port | remote port
  service_name | The name of the service that shall be forwarded
  forward_port | Pointer that will receive the newly-assigned port accessible via USB/Network on the idevice
  options | PLIST_DICT with additional options. Currently known are IsServiceLowPriority (boolean) and PreferWifi (boolean).

Returns
  COMPANION_PROXY_E_SUCCESS on success, or a COMPANION_PROXY_E_* error code otherwise.

## ◆ companion_proxy_start_listening_for_devices()

companion_proxy_error_t companion_proxy_start_listening_for_devices | ( | companion_proxy_client_t | client,
|  | companion_proxy_device_event_cb_t | callback,
|  | void * | userdata
| ) |  |

Starts listening for paired devices.

Parameters

  client | The companion_proxy client
  callback | Callback function that will be called when a new device is detected
  userdata | Pointer that that will be passed to the callback function

Note
  The event parameter that gets passed to the callback function is freed internally after returning from the callback. The consumer needs to make a copy if required.

Returns
  COMPANION_PROXY_E_SUCCESS on success, or a COMPANION_PROXY_E_* error code otherwise.

## ◆ companion_proxy_stop_forwarding_service_port()

companion_proxy_error_t companion_proxy_stop_forwarding_service_port | ( | companion_proxy_client_t | client,
|  | uint16_t | remote_port
| ) |  |

Stop forwarding a service port between companion device and idevice.

See also
  companion_proxy_start_forwarding_service_port

Parameters

  client | The companion_proxy client
  remote_port | remote port

Returns
  COMPANION_PROXY_E_SUCCESS on success, or a COMPANION_PROXY_E_* error code otherwise.

## ◆ companion_proxy_stop_listening_for_devices()

companion_proxy_error_t companion_proxy_stop_listening_for_devices | ( | companion_proxy_client_t | client | ) |

Stops listening for paired devices.

Parameters

  client | The companion_proxy client

Returns
  COMPANION_PROXY_E_SUCCESS on success, or a COMPANION_PROXY_E_* error code otherwise.