libimobiledevice: libimobiledevice/syslog_relay.h File Reference

libimobiledevice 1.3.0

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

Capture the syslog output from a device. More...

## Macros
#define | SYSLOG_RELAY_SERVICE_NAME "com.apple.syslog_relay"

## Typedefs
typedef struct syslog_relay_client_private | syslog_relay_client_private
typedef syslog_relay_client_private * | syslog_relay_client_t
| The client handle.
typedef void(* | syslog_relay_receive_cb_t) (char c, void *user_data)
| Receives each character received from the device.

## Enumerations
enum | syslog_relay_error_t { SYSLOG_RELAY_E_SUCCESS = 0, SYSLOG_RELAY_E_INVALID_ARG = -1, SYSLOG_RELAY_E_MUX_ERROR = -2, SYSLOG_RELAY_E_SSL_ERROR = -3, SYSLOG_RELAY_E_NOT_ENOUGH_DATA = -4, SYSLOG_RELAY_E_TIMEOUT = -5, SYSLOG_RELAY_E_UNKNOWN_ERROR = -256 }
| Error Codes.

## Functions
syslog_relay_error_t | syslog_relay_client_new (idevice_t device, lockdownd_service_descriptor_t service, syslog_relay_client_t *client)
| Connects to the syslog_relay service on the specified device. More...
syslog_relay_error_t | syslog_relay_client_start_service (idevice_t device, syslog_relay_client_t *client, const char *label)
| Starts a new syslog_relay service on the specified device and connects to it. More...
syslog_relay_error_t | syslog_relay_client_free (syslog_relay_client_t client)
| Disconnects a syslog_relay client from the device and frees up the syslog_relay client data. More...
syslog_relay_error_t | syslog_relay_start_capture (syslog_relay_client_t client, syslog_relay_receive_cb_t callback, void *user_data)
| Starts capturing the syslog of the device using a callback. More...
syslog_relay_error_t | syslog_relay_start_capture_raw (syslog_relay_client_t client, syslog_relay_receive_cb_t callback, void *user_data)
| Starts capturing the raw syslog of the device using a callback. More...
syslog_relay_error_t | syslog_relay_stop_capture (syslog_relay_client_t client)
| Stops capturing the syslog of the device. More...
syslog_relay_error_t | syslog_relay_receive_with_timeout (syslog_relay_client_t client, char *data, uint32_t size, uint32_t *received, unsigned int timeout)
| Receives data using the given syslog_relay client with specified timeout. More...
syslog_relay_error_t | syslog_relay_receive (syslog_relay_client_t client, char *data, uint32_t size, uint32_t *received)
| Receives data from the service. More...

## Detailed Description

Capture the syslog output from a device.

## Function Documentation

## ◆ syslog_relay_client_free()

syslog_relay_error_t syslog_relay_client_free | ( | syslog_relay_client_t | client | ) |

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

Parameters

  client | The syslog_relay client to disconnect and free.

Returns
  SYSLOG_RELAY_E_SUCCESS on success, SYSLOG_RELAY_E_INVALID_ARG when client is NULL, or an SYSLOG_RELAY_E_* error code otherwise.

## ◆ syslog_relay_client_new()

syslog_relay_error_t syslog_relay_client_new | ( | idevice_t | device,
|  | lockdownd_service_descriptor_t | service,
|  | syslog_relay_client_t * | client
| ) |  |

Connects to the syslog_relay 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 syslog_relay_client_t upon successful return. Must be freed using syslog_relay_client_free() after use.

Returns
  SYSLOG_RELAY_E_SUCCESS on success, SYSLOG_RELAY_E_INVALID_ARG when client is NULL, or an SYSLOG_RELAY_E_* error code otherwise.

## ◆ syslog_relay_client_start_service()

syslog_relay_error_t syslog_relay_client_start_service | ( | idevice_t | device,
|  | syslog_relay_client_t * | client,
|  | const char * | label
| ) |  |

Starts a new syslog_relay 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 syslog_relay_client_t upon successful return. Must be freed using syslog_relay_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
  SYSLOG_RELAY_E_SUCCESS on success, or an SYSLOG_RELAY_E_* error code otherwise.

## ◆ syslog_relay_receive()

syslog_relay_error_t syslog_relay_receive | ( | syslog_relay_client_t | client,
|  | char * | data,
|  | uint32_t | size,
|  | uint32_t * | received
| ) |  |

Receives data from the service.

Parameters

  client | The syslog_relay client
  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
  SYSLOG_RELAY_E_SUCCESS on success, SYSLOG_RELAY_E_INVALID_ARG when client or plist is NULL

## ◆ syslog_relay_receive_with_timeout()

syslog_relay_error_t syslog_relay_receive_with_timeout | ( | syslog_relay_client_t | client,
|  | char * | data,
|  | uint32_t | size,
|  | uint32_t * | received,
|  | unsigned int | timeout
| ) |  |

Receives data using the given syslog_relay client with specified timeout.

Parameters

  client | The syslog_relay 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
  SYSLOG_RELAY_E_SUCCESS on success, SYSLOG_RELAY_E_INVALID_ARG when one or more parameters are invalid, SYSLOG_RELAY_E_MUX_ERROR when a communication error occurs, or SYSLOG_RELAY_E_UNKNOWN_ERROR when an unspecified error occurs.

## ◆ syslog_relay_start_capture()

syslog_relay_error_t syslog_relay_start_capture | ( | syslog_relay_client_t | client,
|  | syslog_relay_receive_cb_t | callback,
|  | void * | user_data
| ) |  |

Starts capturing the syslog of the device using a callback.

Use syslog_relay_stop_capture() to stop receiving the syslog.

Parameters

  client | The syslog_relay client to use
  callback | Callback to receive each character from the syslog.
  user_data | Custom pointer passed to the callback function.

Returns
  SYSLOG_RELAY_E_SUCCESS on success, SYSLOG_RELAY_E_INVALID_ARG when one or more parameters are invalid or SYSLOG_RELAY_E_UNKNOWN_ERROR when an unspecified error occurs or a syslog capture has already been started.

## ◆ syslog_relay_start_capture_raw()

syslog_relay_error_t syslog_relay_start_capture_raw | ( | syslog_relay_client_t | client,
|  | syslog_relay_receive_cb_t | callback,
|  | void * | user_data
| ) |  |

Starts capturing the raw syslog of the device using a callback.

This function is like syslog_relay_start_capture with the difference that it will neither check nor process the received data before passing it to the callback function.

Use syslog_relay_stop_capture() to stop receiving the syslog.

Note
  Use syslog_relay_start_capture for a safer implementation.

Parameters

  client | The syslog_relay client to use
  callback | Callback to receive each character from the syslog.
  user_data | Custom pointer passed to the callback function.

Returns
  SYSLOG_RELAY_E_SUCCESS on success, SYSLOG_RELAY_E_INVALID_ARG when one or more parameters are invalid or SYSLOG_RELAY_E_UNKNOWN_ERROR when an unspecified error occurs or a syslog capture has already been started.

## ◆ syslog_relay_stop_capture()

syslog_relay_error_t syslog_relay_stop_capture | ( | syslog_relay_client_t | client | ) |

Stops capturing the syslog of the device.

Use syslog_relay_start_capture() to start receiving the syslog.

Parameters

  client | The syslog_relay client to use

Returns
  SYSLOG_RELAY_E_SUCCESS on success, SYSLOG_RELAY_E_INVALID_ARG when one or more parameters are invalid or SYSLOG_RELAY_E_UNKNOWN_ERROR when an unspecified error occurs or a syslog capture has already been started.