libimobiledevice  1.2.0
Macros | Typedefs | Enumerations | Functions
debugserver.h File Reference

Communicate with debugserver on the device. More...

Macros

#define DEBUGSERVER_SERVICE_NAME   "com.apple.debugserver"
 

Typedefs

typedef struct
debugserver_client_private 
debugserver_client_private
 
typedef
debugserver_client_private * 
debugserver_client_t
 The client handle. More...
 
typedef struct
debugserver_command_private 
debugserver_command_private
 
typedef
debugserver_command_private * 
debugserver_command_t
 The command handle. More...
 

Enumerations

enum  debugserver_error_t {
  DEBUGSERVER_E_SUCCESS = 0,
  DEBUGSERVER_E_INVALID_ARG = -1,
  DEBUGSERVER_E_MUX_ERROR = -2,
  DEBUGSERVER_E_SSL_ERROR = -3,
  DEBUGSERVER_E_RESPONSE_ERROR = -4,
  DEBUGSERVER_E_UNKNOWN_ERROR = -256
}
 Error Codes.
 

Functions

debugserver_error_t debugserver_client_new (idevice_t device, lockdownd_service_descriptor_t service, debugserver_client_t *client)
 Connects to the debugserver service on the specified device. More...
 
debugserver_error_t debugserver_client_start_service (idevice_t device, debugserver_client_t *client, const char *label)
 Starts a new debugserver service on the specified device and connects to it. More...
 
debugserver_error_t debugserver_client_free (debugserver_client_t client)
 Disconnects a debugserver client from the device and frees up the debugserver client data. More...
 
debugserver_error_t debugserver_client_send (debugserver_client_t client, const char *data, uint32_t size, uint32_t *sent)
 Sends raw data using the given debugserver service client. More...
 
debugserver_error_t debugserver_client_receive_with_timeout (debugserver_client_t client, char *data, uint32_t size, uint32_t *received, unsigned int timeout)
 Receives raw data using the given debugserver client with specified timeout. More...
 
debugserver_error_t debugserver_client_receive (debugserver_client_t client, char *data, uint32_t size, uint32_t *received)
 Receives raw data from the debugserver service. More...
 
debugserver_error_t debugserver_client_send_command (debugserver_client_t client, debugserver_command_t command, char **response)
 Sends a command to the debugserver service. More...
 
debugserver_error_t debugserver_client_receive_response (debugserver_client_t client, char **response)
 Receives and parses response of debugserver service. More...
 
debugserver_error_t debugserver_client_set_ack_mode (debugserver_client_t client, int enabled)
 Controls status of ACK mode when sending commands or receiving responses. More...
 
debugserver_error_t debugserver_client_set_argv (debugserver_client_t client, int argc, char *argv[], char **response)
 Sets the argv which launches an app. More...
 
debugserver_error_t debugserver_client_set_environment_hex_encoded (debugserver_client_t client, const char *env, char **response)
 Adds or sets an environment variable. More...
 
debugserver_error_t debugserver_command_new (const char *name, int argc, char *argv[], debugserver_command_t *command)
 Creates and initializes a new command object. More...
 
debugserver_error_t debugserver_command_free (debugserver_command_t command)
 Frees memory of command object. More...
 
void debugserver_encode_string (const char *buffer, char **encoded_buffer, uint32_t *encoded_length)
 Encodes a string into hex notation. More...
 
void debugserver_decode_string (const char *encoded_buffer, size_t encoded_length, char **buffer)
 Decodes a hex encoded string. More...
 

Detailed Description

Communicate with debugserver on the device.

Typedef Documentation

typedef debugserver_client_private* debugserver_client_t

The client handle.

typedef debugserver_command_private* debugserver_command_t

The command handle.

Function Documentation

debugserver_error_t debugserver_client_free ( debugserver_client_t  client)

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

Parameters
clientThe debugserver client to disconnect and free.
Returns
DEBUGSERVER_E_SUCCESS on success, DEBUGSERVER_E_INVALID_ARG when client is NULL, or an DEBUGSERVER_E_* error code otherwise.
debugserver_error_t debugserver_client_new ( idevice_t  device,
lockdownd_service_descriptor_t  service,
debugserver_client_t client 
)

Connects to the debugserver service on the specified device.

Parameters
deviceThe device to connect to.
serviceThe service descriptor returned by lockdownd_start_service.
clientPointer that will point to a newly allocated debugserver_client_t upon successful return. Must be freed using debugserver_client_free() after use.
Returns
DEBUGSERVER_E_SUCCESS on success, DEBUGSERVER_E_INVALID_ARG when client is NULL, or an DEBUGSERVER_E_* error code otherwise.
debugserver_error_t debugserver_client_receive ( debugserver_client_t  client,
char *  data,
uint32_t  size,
uint32_t *  received 
)

Receives raw data from the debugserver service.

Parameters
clientThe debugserver client
dataBuffer that will be filled with the data received
sizeNumber of bytes to receive
receivedNumber of bytes received (can be NULL to ignore)
Note
The default read timeout is 10 seconds.
Returns
DEBUGSERVER_E_SUCCESS on success, DEBUGSERVER_E_INVALID_ARG when client or plist is NULL
debugserver_error_t debugserver_client_receive_response ( debugserver_client_t  client,
char **  response 
)

Receives and parses response of debugserver service.

Parameters
clientThe debugserver client
responseResponse received for last command (can be NULL to ignore)
Returns
DEBUGSERVER_E_SUCCESS on success, DEBUGSERVER_E_INVALID_ARG when client is NULL
debugserver_error_t debugserver_client_receive_with_timeout ( debugserver_client_t  client,
char *  data,
uint32_t  size,
uint32_t *  received,
unsigned int  timeout 
)

Receives raw data using the given debugserver client with specified timeout.

Parameters
clientThe debugserver client to use for receiving
dataBuffer that will be filled with the data received
sizeNumber of bytes to receive
receivedNumber of bytes received (can be NULL to ignore)
timeoutMaximum time in milliseconds to wait for data.
Returns
DEBUGSERVER_E_SUCCESS on success, DEBUGSERVER_E_INVALID_ARG when one or more parameters are invalid, DEBUGSERVER_E_MUX_ERROR when a communication error occurs, or DEBUGSERVER_E_UNKNOWN_ERROR when an unspecified error occurs.
debugserver_error_t debugserver_client_send ( debugserver_client_t  client,
const char *  data,
uint32_t  size,
uint32_t *  sent 
)

Sends raw data using the given debugserver service client.

Parameters
clientThe debugserver client to use for sending
dataData to send
sizeSize of the data to send
sentNumber of bytes sent (can be NULL to ignore)
Returns
DEBUGSERVER_E_SUCCESS on success, DEBUGSERVER_E_INVALID_ARG when one or more parameters are invalid, or DEBUGSERVER_E_UNKNOWN_ERROR when an unspecified error occurs.
debugserver_error_t debugserver_client_send_command ( debugserver_client_t  client,
debugserver_command_t  command,
char **  response 
)

Sends a command to the debugserver service.

Parameters
clientThe debugserver client
commandCommand to process and send
responseResponse received for the command (can be NULL to ignore)
Returns
DEBUGSERVER_E_SUCCESS on success, DEBUGSERVER_E_INVALID_ARG when client or command is NULL
debugserver_error_t debugserver_client_set_ack_mode ( debugserver_client_t  client,
int  enabled 
)

Controls status of ACK mode when sending commands or receiving responses.

See also
debugserver_client_send_command, debugserver_client_receive_response
Parameters
clientThe debugserver client
enabledA boolean flag indicating whether the internal ACK mode handling should be enabled or disabled.
Returns
DEBUGSERVER_E_SUCCESS on success, or an DEBUGSERVER_E_* error code otherwise.
debugserver_error_t debugserver_client_set_argv ( debugserver_client_t  client,
int  argc,
char *  argv[],
char **  response 
)

Sets the argv which launches an app.

Parameters
clientThe debugserver client
argcNumber of arguments
argvArray starting with the executable to be run followed by it's arguments
responseResponse received for the command (can be NULL to ignore)
Returns
DEBUGSERVER_E_SUCCESS on success, DEBUGSERVER_E_INVALID_ARG when client is NULL
debugserver_error_t debugserver_client_set_environment_hex_encoded ( debugserver_client_t  client,
const char *  env,
char **  response 
)

Adds or sets an environment variable.

Parameters
clientThe debugserver client
envThe environment variable in "KEY=VALUE" notation
responseResponse received for the command (can be NULL to ignore)
Returns
DEBUGSERVER_E_SUCCESS on success, DEBUGSERVER_E_INVALID_ARG when client is NULL
debugserver_error_t debugserver_client_start_service ( idevice_t  device,
debugserver_client_t client,
const char *  label 
)

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

Parameters
deviceThe device to connect to.
clientPointer that will point to a newly allocated debugserver_client_t upon successful return. Must be freed using debugserver_client_free() after use.
labelThe label to use for communication. Usually the program name. Pass NULL to disable sending the label in requests to lockdownd.
Returns
DEBUGSERVER_E_SUCCESS on success, or an DEBUGSERVER_E_* error code otherwise.
debugserver_error_t debugserver_command_free ( debugserver_command_t  command)

Frees memory of command object.

Parameters
commandThe command object
Returns
DEBUGSERVER_E_SUCCESS on success, DEBUGSERVER_E_INVALID_ARG when command is NULL
debugserver_error_t debugserver_command_new ( const char *  name,
int  argc,
char *  argv[],
debugserver_command_t command 
)

Creates and initializes a new command object.

Parameters
nameThe name of the command which is sent in plain text
argvArray of tokens for the command ment to be encoded
argcNumber of items in the token array
commandNew command object
Returns
DEBUGSERVER_E_SUCCESS on success, DEBUGSERVER_E_INVALID_ARG when name or command is NULL
void debugserver_decode_string ( const char *  encoded_buffer,
size_t  encoded_length,
char **  buffer 
)

Decodes a hex encoded string.

Parameters
encoded_bufferThe buffer with a hex encoded string
encoded_lengthLength of the encoded buffer
bufferDecoded string to be freed by the caller
void debugserver_encode_string ( const char *  buffer,
char **  encoded_buffer,
uint32_t *  encoded_length 
)

Encodes a string into hex notation.

Parameters
bufferString to encode into hex notiation
encoded_bufferThe buffer receives a hex encoded string
encoded_lengthLength of the hex encoded string