libimobiledevice: libimobiledevice/service.h File Reference

libimobiledevice 1.3.0

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

Generic basic service implementation to inherit. More...

## Macros
#define | SERVICE_CONSTRUCTOR(x) (int32_t (*)(idevice_t, lockdownd_service_descriptor_t, void**))(x)

## Typedefs
typedef struct service_client_private | service_client_private
typedef service_client_private * | service_client_t
| The client handle.

## Enumerations
enum | service_error_t { SERVICE_E_SUCCESS = 0, SERVICE_E_INVALID_ARG = -1, SERVICE_E_MUX_ERROR = -3, SERVICE_E_SSL_ERROR = -4, SERVICE_E_START_SERVICE_ERROR = -5, SERVICE_E_NOT_ENOUGH_DATA = -6, SERVICE_E_TIMEOUT = -7, SERVICE_E_UNKNOWN_ERROR = -256 }
| Error Codes.

## Functions
service_error_t | service_client_new (idevice_t device, lockdownd_service_descriptor_t service, service_client_t *client)
| Creates a new service for the specified service descriptor. More...
service_error_t | service_client_factory_start_service (idevice_t device, const char *service_name, void **client, const char *label, int32_t(*constructor_func)(idevice_t, lockdownd_service_descriptor_t, void **), int32_t *error_code)
| Starts a new service on the specified device with given name and connects to it. More...
service_error_t | service_client_free (service_client_t client)
| Frees a service instance. More...
service_error_t | service_send (service_client_t client, const char *data, uint32_t size, uint32_t *sent)
| Sends data using the given service client. More...
service_error_t | service_receive_with_timeout (service_client_t client, char *data, uint32_t size, uint32_t *received, unsigned int timeout)
| Receives data using the given service client with specified timeout. More...
service_error_t | service_receive (service_client_t client, char *data, uint32_t size, uint32_t *received)
| Receives data using the given service client. More...
service_error_t | service_enable_ssl (service_client_t client)
| Enable SSL for the given service client. More...
service_error_t | service_disable_ssl (service_client_t client)
| Disable SSL for the given service client. More...
service_error_t | service_disable_bypass_ssl (service_client_t client, uint8_t sslBypass)
| Disable SSL for the given service client without sending SSL terminate messages. More...

## Detailed Description

Generic basic service implementation to inherit.

## Function Documentation

## ◆ service_client_factory_start_service()

service_error_t service_client_factory_start_service | ( | idevice_t | device,
|  | const char * | service_name,
|  | void ** | client,
|  | const char * | label,
|  | int32_t(*)(idevice_t, lockdownd_service_descriptor_t, void **) | constructor_func,
|  | int32_t * | error_code
| ) |  |

Starts a new service on the specified device with given name and connects to it.

Parameters

  device | The device to connect to.
  service_name | The name of the service to start.
  client | Pointer that will point to a newly allocated service_client_t upon successful return. Must be freed using service_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
  SERVICE_E_SUCCESS on success, or a SERVICE_E_* error code otherwise.

## ◆ service_client_free()

service_error_t service_client_free | ( | service_client_t | client | ) |

Frees a service instance.

Parameters

  client | The service instance to free.

Returns
  SERVICE_E_SUCCESS on success, SERVICE_E_INVALID_ARG when client is invalid, or a SERVICE_E_UNKNOWN_ERROR when another error occurred.

## ◆ service_client_new()

service_error_t service_client_new | ( | idevice_t | device,
|  | lockdownd_service_descriptor_t | service,
|  | service_client_t * | client
| ) |  |

Creates a new service for the specified service descriptor.

Parameters

  device | The device to connect to.
  service | The service descriptor returned by lockdownd_start_service.
  client | Pointer that will be set to a newly allocated service_client_t upon successful return.

Returns
  SERVICE_E_SUCCESS on success, SERVICE_E_INVALID_ARG when one of the arguments is invalid, or SERVICE_E_MUX_ERROR when connecting to the device failed.

## ◆ service_disable_bypass_ssl()

service_error_t service_disable_bypass_ssl | ( | service_client_t | client,
|  | uint8_t | sslBypass
| ) |  |

Disable SSL for the given service client without sending SSL terminate messages.

Parameters

  client | The connected service client for that SSL should be disabled.

Returns
  SERVICE_E_SUCCESS on success, SERVICE_E_INVALID_ARG if client or client->connection is NULL, or SERVICE_E_UNKNOWN_ERROR otherwise.

## ◆ service_disable_ssl()

service_error_t service_disable_ssl | ( | service_client_t | client | ) |

Disable SSL for the given service client.

Parameters

  client | The connected service client for that SSL should be disabled.

Returns
  SERVICE_E_SUCCESS on success, SERVICE_E_INVALID_ARG if client or client->connection is NULL, or SERVICE_E_UNKNOWN_ERROR otherwise.

## ◆ service_enable_ssl()

service_error_t service_enable_ssl | ( | service_client_t | client | ) |

Enable SSL for the given service client.

Parameters

  client | The connected service client for that SSL should be enabled.

Returns
  SERVICE_E_SUCCESS on success, SERVICE_E_INVALID_ARG if client or client->connection is NULL, SERVICE_E_NOT_ENOUGH_DATA when not enough data received, SERVICE_E_TIMEOUT when the connection times out, SERVICE_E_SSL_ERROR when SSL could not be enabled, or SERVICE_E_UNKNOWN_ERROR otherwise.

## ◆ service_receive()

service_error_t service_receive | ( | service_client_t | client,
|  | char * | data,
|  | uint32_t | size,
|  | uint32_t * | received
| ) |  |

Receives data using the given service client.

Parameters

  client | The service client to use for receiving
  data | Buffer that will be filled with the data received
  size | Number of bytes to receive
  received | Number of bytes received (can be NULL to ignore)

Returns
  SERVICE_E_SUCCESS on success, SERVICE_E_INVALID_ARG when one or more parameters are invalid, SERVICE_E_NOT_ENOUGH_DATA when not enough data received, SERVICE_E_TIMEOUT when the connection times out, SERVICE_E_MUX_ERROR when a communication error occurs, or SERVICE_E_UNKNOWN_ERROR when an unspecified error occurs.

## ◆ service_receive_with_timeout()

service_error_t service_receive_with_timeout | ( | service_client_t | client,
|  | char * | data,
|  | uint32_t | size,
|  | uint32_t * | received,
|  | unsigned int | timeout
| ) |  |

Receives data using the given service client with specified timeout.

Parameters

  client | The service client to use for receiving
  data | Buffer that will be filled with the data received
  size | Number of bytes to receive
  received | Number of bytes received (can be NULL to ignore)
  timeout | Maximum time in milliseconds to wait for data.

Returns
  SERVICE_E_SUCCESS on success, SERVICE_E_INVALID_ARG when one or more parameters are invalid, SERVICE_E_MUX_ERROR when a communication error occurs, or SERVICE_E_UNKNOWN_ERROR when an unspecified error occurs.

## ◆ service_send()

service_error_t service_send | ( | service_client_t | client,
|  | const char * | data,
|  | uint32_t | size,
|  | uint32_t * | sent
| ) |  |

Sends data using the given service client.

Parameters

  client | The service client to use for sending.
  data | Data to send
  size | Size of the data to send
  sent | Number of bytes sent (can be NULL to ignore)

Returns
  SERVICE_E_SUCCESS on success, SERVICE_E_INVALID_ARG when one or more parameters are invalid, or SERVICE_E_UNKNOWN_ERROR when an unspecified error occurs.