libimobiledevice: libimobiledevice/heartbeat.h File Reference

libimobiledevice 1.3.0

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

Send "heartbeat" to device to allow service connections over network. More...

## Macros
#define | HEARTBEAT_SERVICE_NAME "com.apple.mobile.heartbeat"

## Typedefs
typedef struct heartbeat_client_private | heartbeat_client_private
typedef heartbeat_client_private * | heartbeat_client_t
| The client handle.

## Enumerations
enum | heartbeat_error_t { HEARTBEAT_E_SUCCESS = 0, HEARTBEAT_E_INVALID_ARG = -1, HEARTBEAT_E_PLIST_ERROR = -2, HEARTBEAT_E_MUX_ERROR = -3, HEARTBEAT_E_SSL_ERROR = -4, HEARTBEAT_E_NOT_ENOUGH_DATA = -5, HEARTBEAT_E_TIMEOUT = -6, HEARTBEAT_E_UNKNOWN_ERROR = -256 }
| Error Codes.

## Functions
heartbeat_error_t | heartbeat_client_new (idevice_t device, lockdownd_service_descriptor_t service, heartbeat_client_t *client)
| Connects to the heartbeat service on the specified device. More...
heartbeat_error_t | heartbeat_client_start_service (idevice_t device, heartbeat_client_t *client, const char *label)
| Starts a new heartbeat service on the specified device and connects to it. More...
heartbeat_error_t | heartbeat_client_free (heartbeat_client_t client)
| Disconnects a heartbeat client from the device and frees up the heartbeat client data. More...
heartbeat_error_t | heartbeat_send (heartbeat_client_t client, plist_t plist)
| Sends a plist to the service. More...
heartbeat_error_t | heartbeat_receive (heartbeat_client_t client, plist_t *plist)
| Receives a plist from the service. More...
heartbeat_error_t | heartbeat_receive_with_timeout (heartbeat_client_t client, plist_t *plist, uint32_t timeout_ms)
| Receives a plist using the given heartbeat client. More...

## Detailed Description

Send "heartbeat" to device to allow service connections over network.

## Function Documentation

## ◆ heartbeat_client_free()

heartbeat_error_t heartbeat_client_free | ( | heartbeat_client_t | client | ) |

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

Parameters

  client | The heartbeat client to disconnect and free.

Returns
  HEARTBEAT_E_SUCCESS on success, HEARTBEAT_E_INVALID_ARG when client is NULL, or an HEARTBEAT_E_* error code otherwise.

## ◆ heartbeat_client_new()

heartbeat_error_t heartbeat_client_new | ( | idevice_t | device,
|  | lockdownd_service_descriptor_t | service,
|  | heartbeat_client_t * | client
| ) |  |

Connects to the heartbeat 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 heartbeat_client_t upon successful return. Must be freed using heartbeat_client_free() after use.

Returns
  HEARTBEAT_E_SUCCESS on success, HEARTBEAT_E_INVALID_ARG when client is NULL, or an HEARTBEAT_E_* error code otherwise.

## ◆ heartbeat_client_start_service()

heartbeat_error_t heartbeat_client_start_service | ( | idevice_t | device,
|  | heartbeat_client_t * | client,
|  | const char * | label
| ) |  |

Starts a new heartbeat 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 heartbeat_client_t upon successful return. Must be freed using heartbeat_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
  HEARTBEAT_E_SUCCESS on success, or an HEARTBEAT_E_* error code otherwise.

## ◆ heartbeat_receive()

heartbeat_error_t heartbeat_receive | ( | heartbeat_client_t | client,
|  | plist_t * | plist
| ) |  |

Receives a plist from the service.

Parameters

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

Returns
  HEARTBEAT_E_SUCCESS on success, HEARTBEAT_E_INVALID_ARG when client or plist is NULL

## ◆ heartbeat_receive_with_timeout()

heartbeat_error_t heartbeat_receive_with_timeout | ( | heartbeat_client_t | client,
|  | plist_t * | plist,
|  | uint32_t | timeout_ms
| ) |  |

Receives a plist using the given heartbeat client.

Parameters

  client | The heartbeat client to use for receiving
  plist | pointer to a plist_t that will point to the received plist upon successful return
  timeout | Maximum time in milliseconds to wait for data.

Returns
  HEARTBEAT_E_SUCCESS on success, HEARTBEAT_E_INVALID_ARG when client or *plist is NULL, HEARTBEAT_E_NOT_ENOUGH_DATA when not enough data received, HEARTBEAT_E_TIMEOUT when the connection times out, HEARTBEAT_E_PLIST_ERROR when the received data cannot be converted to a plist, HEARTBEAT_E_MUX_ERROR when a communication error occurs, or HEARTBEAT_E_UNKNOWN_ERROR when an unspecified error occurs.

## ◆ heartbeat_send()

heartbeat_error_t heartbeat_send | ( | heartbeat_client_t | client,
|  | plist_t | plist
| ) |  |

Sends a plist to the service.

Parameters

  client | The heartbeat client
  plist | The plist to send

Returns
  HEARTBEAT_E_SUCCESS on success, HEARTBEAT_E_INVALID_ARG when client or plist is NULL