libimobiledevice 1.1.5

- Main Page
- Data Structures
- Files

- File List
- Globals

Typedefs | Enumerations | Functions
afc.h File Reference

Access the filesystem. More...

## Typedefs
typedef int16_t | afc_error_t
| Represents an error code.
typedef afc_client_private * | afc_client_t
| The client handle.

## Enumerations
enum | afc_file_mode_t { AFC_FOPEN_RDONLY = 0x00000001, AFC_FOPEN_RW = 0x00000002, AFC_FOPEN_WRONLY = 0x00000003, AFC_FOPEN_WR = 0x00000004, AFC_FOPEN_APPEND = 0x00000005, AFC_FOPEN_RDAPPEND = 0x00000006 }
| Flags for afc_file_open. More...
enum | afc_link_type_t { AFC_HARDLINK = 1, AFC_SYMLINK = 2 }
| Type of link for afc_make_link() calls.
enum | afc_lock_op_t { AFC_LOCK_SH = 1 | 4, AFC_LOCK_EX = 2 | 4, AFC_LOCK_UN = 8 | 4 }
| Lock operation flags. More...

## Functions
afc_error_t | afc_client_new (idevice_t device, lockdownd_service_descriptor_t service, afc_client_t *client)
| Makes a connection to the AFC service on the device.
afc_error_t | afc_client_free (afc_client_t client)
| Frees up an AFC client.
afc_error_t | afc_get_device_info (afc_client_t client, char ***infos)
| Get device information for a connected client.
afc_error_t | afc_read_directory (afc_client_t client, const char *dir, char ***list)
| Gets a directory listing of the directory requested.
afc_error_t | afc_get_file_info (afc_client_t client, const char *filename, char ***infolist)
| Gets information about a specific file.
afc_error_t | afc_file_open (afc_client_t client, const char *filename, afc_file_mode_t file_mode, uint64_t *handle)
| Opens a file on the device.
afc_error_t | afc_file_close (afc_client_t client, uint64_t handle)
| Closes a file on the device.
afc_error_t | afc_file_lock (afc_client_t client, uint64_t handle, afc_lock_op_t operation)
| Locks or unlocks a file on the device.
afc_error_t | afc_file_read (afc_client_t client, uint64_t handle, char *data, uint32_t length, uint32_t *bytes_read)
| Attempts to the read the given number of bytes from the given file.
afc_error_t | afc_file_write (afc_client_t client, uint64_t handle, const char *data, uint32_t length, uint32_t *bytes_written)
| Writes a given number of bytes to a file.
afc_error_t | afc_file_seek (afc_client_t client, uint64_t handle, int64_t offset, int whence)
| Seeks to a given position of a pre-opened file on the device.
afc_error_t | afc_file_tell (afc_client_t client, uint64_t handle, uint64_t *position)
| Returns current position in a pre-opened file on the device.
afc_error_t | afc_file_truncate (afc_client_t client, uint64_t handle, uint64_t newsize)
| Sets the size of a file on the device.
afc_error_t | afc_remove_path (afc_client_t client, const char *path)
| Deletes a file or directory.
afc_error_t | afc_rename_path (afc_client_t client, const char *from, const char *to)
| Renames a file or directory on the device.
afc_error_t | afc_make_directory (afc_client_t client, const char *dir)
| Creates a directory on the device.
afc_error_t | afc_truncate (afc_client_t client, const char *path, uint64_t newsize)
| Sets the size of a file on the device without prior opening it.
afc_error_t | afc_make_link (afc_client_t client, afc_link_type_t linktype, const char *target, const char *linkname)
| Creates a hard link or symbolic link on the device.
afc_error_t | afc_set_file_time (afc_client_t client, const char *path, uint64_t mtime)
| Sets the modification time of a file on the device.
afc_error_t | afc_get_device_info_key (afc_client_t client, const char *key, char **value)
| Get a specific key of the device info list for a client connection.

## Error Codes
#define | AFC_E_SUCCESS 0
#define | AFC_E_UNKNOWN_ERROR 1
#define | AFC_E_OP_HEADER_INVALID 2
#define | AFC_E_NO_RESOURCES 3
#define | AFC_E_READ_ERROR 4
#define | AFC_E_WRITE_ERROR 5
#define | AFC_E_UNKNOWN_PACKET_TYPE 6
#define | AFC_E_INVALID_ARG 7
#define | AFC_E_OBJECT_NOT_FOUND 8
#define | AFC_E_OBJECT_IS_DIR 9
#define | AFC_E_PERM_DENIED 10
#define | AFC_E_SERVICE_NOT_CONNECTED 11
#define | AFC_E_OP_TIMEOUT 12
#define | AFC_E_TOO_MUCH_DATA 13
#define | AFC_E_END_OF_DATA 14
#define | AFC_E_OP_NOT_SUPPORTED 15
#define | AFC_E_OBJECT_EXISTS 16
#define | AFC_E_OBJECT_BUSY 17
#define | AFC_E_NO_SPACE_LEFT 18
#define | AFC_E_OP_WOULD_BLOCK 19
#define | AFC_E_IO_ERROR 20
#define | AFC_E_OP_INTERRUPTED 21
#define | AFC_E_OP_IN_PROGRESS 22
#define | AFC_E_INTERNAL_ERROR 23
#define | AFC_E_MUX_ERROR 30
#define | AFC_E_NO_MEM 31
#define | AFC_E_NOT_ENOUGH_DATA 32
#define | AFC_E_DIR_NOT_EMPTY 33

## Detailed Description

Access the filesystem.

## Typedef Documentation

typedef afc_client_private* afc_client_t

The client handle.

typedef int16_t afc_error_t

Represents an error code.

## Enumeration Type Documentation

enum afc_file_mode_t

Flags for afc_file_open.

Enumerator:

  AFC_FOPEN_RDONLY | r O_RDONLY
  AFC_FOPEN_RW | r+ O_RDWR | O_CREAT
  AFC_FOPEN_WRONLY | w O_WRONLY | O_CREAT | O_TRUNC
  AFC_FOPEN_WR | w+ O_RDWR | O_CREAT | O_TRUNC
  AFC_FOPEN_APPEND | a O_WRONLY | O_APPEND | O_CREAT
  AFC_FOPEN_RDAPPEND | a+ O_RDWR | O_APPEND | O_CREAT

enum afc_lock_op_t

Lock operation flags.

Enumerator:

  AFC_LOCK_SH | shared lock
  AFC_LOCK_EX | exclusive lock
  AFC_LOCK_UN | unlock

## Function Documentation

afc_error_t afc_client_free | ( | afc_client_t | client | ) |

Frees up an AFC client.

If the connection was created by the client itself, the connection will be closed.

Parameters:

  client | The client to free.

afc_error_t afc_client_new | ( | idevice_t | device,
|  | lockdownd_service_descriptor_t | service,
|  | afc_client_t * | client
| ) |  |

Makes a connection to the AFC service on the device.

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 afc_client_t upon successful return.

Returns:
  AFC_E_SUCCESS on success, AFC_E_INVALID_ARG if device or port is invalid, AFC_E_MUX_ERROR if the connection cannot be established, or AFC_E_NO_MEM if there is a memory allocation problem.

afc_error_t afc_file_close | ( | afc_client_t | client,
|  | uint64_t | handle
| ) |  |

Closes a file on the device.

Parameters:

  client | The client to close the file with.
  handle | File handle of a previously opened file.

afc_error_t afc_file_lock | ( | afc_client_t | client,
|  | uint64_t | handle,
|  | afc_lock_op_t | operation
| ) |  |

Locks or unlocks a file on the device.

makes use of flock on the device, see http://developer.apple.com/documentation/Darwin/Reference/ManPages/man2/flock.2.html

Parameters:

  client | The client to lock the file with.
  handle | File handle of a previously opened file.
  operation | the lock or unlock operation to perform, this is one of AFC_LOCK_SH (shared lock), AFC_LOCK_EX (exclusive lock), or AFC_LOCK_UN (unlock).

afc_error_t afc_file_open | ( | afc_client_t | client,
|  | const char * | filename,
|  | afc_file_mode_t | file_mode,
|  | uint64_t * | handle
| ) |  |

Opens a file on the device.

Parameters:

  client | The client to use to open the file.
  filename | The file to open. (must be a fully-qualified path)
  file_mode | The mode to use to open the file. Can be AFC_FILE_READ or AFC_FILE_WRITE; the former lets you read and write, however, and the second one will create the file, destroying anything previously there.
  handle | Pointer to a uint64_t that will hold the handle of the file

Returns:
  AFC_E_SUCCESS on success or an AFC_E_* error value.

afc_error_t afc_file_read | ( | afc_client_t | client,
|  | uint64_t | handle,
|  | char * | data,
|  | uint32_t | length,
|  | uint32_t * | bytes_read
| ) |  |

Attempts to the read the given number of bytes from the given file.

Parameters:

  client | The relevant AFC client
  handle | File handle of a previously opened file
  data | The pointer to the memory region to store the read data
  length | The number of bytes to read
  bytes_read | The number of bytes actually read.

Returns:
  AFC_E_SUCCESS on success or an AFC_E_* error value.

afc_error_t afc_file_seek | ( | afc_client_t | client,
|  | uint64_t | handle,
|  | int64_t | offset,
|  | int | whence
| ) |  |

Seeks to a given position of a pre-opened file on the device.

Parameters:

  client | The client to use to seek to the position.
  handle | File handle of a previously opened.
  offset | Seek offset.
  whence | Seeking direction, one of SEEK_SET, SEEK_CUR, or SEEK_END.

Returns:
  AFC_E_SUCCESS on success or an AFC_E_* error value.

afc_error_t afc_file_tell | ( | afc_client_t | client,
|  | uint64_t | handle,
|  | uint64_t * | position
| ) |  |

Returns current position in a pre-opened file on the device.

Parameters:

  client | The client to use.
  handle | File handle of a previously opened file.
  position | Position in bytes of indicator

Returns:
  AFC_E_SUCCESS on success or an AFC_E_* error value.

afc_error_t afc_file_truncate | ( | afc_client_t | client,
|  | uint64_t | handle,
|  | uint64_t | newsize
| ) |  |

Sets the size of a file on the device.

Parameters:

  client | The client to use to set the file size.
  handle | File handle of a previously opened file.
  newsize | The size to set the file to.

Returns:
  AFC_E_SUCCESS on success or an AFC_E_* error value.

Note:
  This function is more akin to ftruncate than truncate, and truncate calls would have to open the file before calling this, sadly.

afc_error_t afc_file_write | ( | afc_client_t | client,
|  | uint64_t | handle,
|  | const char * | data,
|  | uint32_t | length,
|  | uint32_t * | bytes_written
| ) |  |

Writes a given number of bytes to a file.

Parameters:

  client | The client to use to write to the file.
  handle | File handle of previously opened file.
  data | The data to write to the file.
  length | How much data to write.
  bytes_written | The number of bytes actually written to the file.

Returns:
  AFC_E_SUCCESS on success or an AFC_E_* error value.

afc_error_t afc_get_device_info | ( | afc_client_t | client,
|  | char *** | infos
| ) |  |

Get device information for a connected client.

The device information returned is the device model as well as the free space, the total capacity and blocksize on the accessed disk partition.

Parameters:

  client | The client to get device info for.
  infos | A char ** list of parameters as given by AFC or NULL if there was an error.

Returns:
  AFC_E_SUCCESS on success or an AFC_E_* error value.

afc_error_t afc_get_device_info_key | ( | afc_client_t | client,
|  | const char * | key,
|  | char ** | value
| ) |  |

Get a specific key of the device info list for a client connection.

Known key values are: Model, FSTotalBytes, FSFreeBytes and FSBlockSize. This is a helper function for afc_get_device_info().

Parameters:

  client | The client to get device info for.
  key | The key to get the value of.
  value | The value for the key if successful or NULL otherwise.

Returns:
  AFC_E_SUCCESS on success or an AFC_E_* error value.

afc_error_t afc_get_file_info | ( | afc_client_t | client,
|  | const char * | path,
|  | char *** | infolist
| ) |  |

Gets information about a specific file.

Parameters:

  client | The client to use to get the information of the file.
  path | The fully-qualified path to the file.
  infolist | Pointer to a buffer that will be filled with a NULL-terminated list of strings with the file information. Set to NULL before calling this function.

Returns:
  AFC_E_SUCCESS on success or an AFC_E_* error value.

afc_error_t afc_make_directory | ( | afc_client_t | client,
|  | const char * | dir
| ) |  |

Creates a directory on the device.

Parameters:

  client | The client to use to make a directory.
  dir | The directory's path. (must be a fully-qualified path, I assume all other mkdir restrictions apply as well)

Returns:
  AFC_E_SUCCESS on success or an AFC_E_* error value.

afc_error_t afc_make_link | ( | afc_client_t | client,
|  | afc_link_type_t | linktype,
|  | const char * | target,
|  | const char * | linkname
| ) |  |

Creates a hard link or symbolic link on the device.

Parameters:

  client | The client to use for making a link
  linktype | 1 = hard link, 2 = symlink
  target | The file to be linked.
  linkname | The name of link.

Returns:
  AFC_E_SUCCESS on success or an AFC_E_* error value.

afc_error_t afc_read_directory | ( | afc_client_t | client,
|  | const char * | dir,
|  | char *** | list
| ) |  |

Gets a directory listing of the directory requested.

Parameters:

  client | The client to get a directory listing from.
  dir | The directory to list. (must be a fully-qualified path)
  list | A char list of files in that directory, terminated by an empty string or NULL if there was an error.

Returns:
  AFC_E_SUCCESS on success or an AFC_E_* error value.

afc_error_t afc_remove_path | ( | afc_client_t | client,
|  | const char * | path
| ) |  |

Deletes a file or directory.

Parameters:

  client | The client to use.
  path | The path to delete. (must be a fully-qualified path)

Returns:
  AFC_E_SUCCESS on success or an AFC_E_* error value.

afc_error_t afc_rename_path | ( | afc_client_t | client,
|  | const char * | from,
|  | const char * | to
| ) |  |

Renames a file or directory on the device.

Parameters:

  client | The client to have rename.
  from | The name to rename from. (must be a fully-qualified path)
  to | The new name. (must also be a fully-qualified path)

Returns:
  AFC_E_SUCCESS on success or an AFC_E_* error value.

afc_error_t afc_set_file_time | ( | afc_client_t | client,
|  | const char * | path,
|  | uint64_t | mtime
| ) |  |

Sets the modification time of a file on the device.

Parameters:

  client | The client to use to set the file size.
  path | Path of the file for which the modification time should be set.
  mtime | The modification time to set in nanoseconds since epoch.

Returns:
  AFC_E_SUCCESS on success or an AFC_E_* error value.

afc_error_t afc_truncate | ( | afc_client_t | client,
|  | const char * | path,
|  | uint64_t | newsize
| ) |  |

Sets the size of a file on the device without prior opening it.

Parameters:

  client | The client to use to set the file size.
  path | The path of the file to be truncated.
  newsize | The size to set the file to.

Returns:
  AFC_E_SUCCESS on success or an AFC_E_* error value.