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

Access the filesystem on the device. More...

Macros

#define AFC_SERVICE_NAME   "com.apple.afc"
 

Typedefs

typedef struct afc_client_private afc_client_private
 
typedef afc_client_private * afc_client_t
 The client handle. More...
 

Enumerations

enum  afc_error_t {
  AFC_E_SUCCESS = 0,
  AFC_E_UNKNOWN_ERROR = 1,
  AFC_E_OP_HEADER_INVALID = 2,
  AFC_E_NO_RESOURCES = 3,
  AFC_E_READ_ERROR = 4,
  AFC_E_WRITE_ERROR = 5,
  AFC_E_UNKNOWN_PACKET_TYPE = 6,
  AFC_E_INVALID_ARG = 7,
  AFC_E_OBJECT_NOT_FOUND = 8,
  AFC_E_OBJECT_IS_DIR = 9,
  AFC_E_PERM_DENIED = 10,
  AFC_E_SERVICE_NOT_CONNECTED = 11,
  AFC_E_OP_TIMEOUT = 12,
  AFC_E_TOO_MUCH_DATA = 13,
  AFC_E_END_OF_DATA = 14,
  AFC_E_OP_NOT_SUPPORTED = 15,
  AFC_E_OBJECT_EXISTS = 16,
  AFC_E_OBJECT_BUSY = 17,
  AFC_E_NO_SPACE_LEFT = 18,
  AFC_E_OP_WOULD_BLOCK = 19,
  AFC_E_IO_ERROR = 20,
  AFC_E_OP_INTERRUPTED = 21,
  AFC_E_OP_IN_PROGRESS = 22,
  AFC_E_INTERNAL_ERROR = 23,
  AFC_E_MUX_ERROR = 30,
  AFC_E_NO_MEM = 31,
  AFC_E_NOT_ENOUGH_DATA = 32,
  AFC_E_DIR_NOT_EMPTY = 33,
  AFC_E_FORCE_SIGNED_TYPE = -1
}
 Error Codes.
 
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. More...
 
afc_error_t afc_client_start_service (idevice_t device, afc_client_t *client, const char *label)
 Starts a new AFC service on the specified device and connects to it. More...
 
afc_error_t afc_client_free (afc_client_t client)
 Frees up an AFC client. More...
 
afc_error_t afc_get_device_info (afc_client_t client, char ***device_information)
 Get device information for a connected client. More...
 
afc_error_t afc_read_directory (afc_client_t client, const char *path, char ***directory_information)
 Gets a directory listing of the directory requested. More...
 
afc_error_t afc_get_file_info (afc_client_t client, const char *filename, char ***file_information)
 Gets information about a specific file. More...
 
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. More...
 
afc_error_t afc_file_close (afc_client_t client, uint64_t handle)
 Closes a file on the device. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
afc_error_t afc_remove_path (afc_client_t client, const char *path)
 Deletes a file or directory. More...
 
afc_error_t afc_rename_path (afc_client_t client, const char *from, const char *to)
 Renames a file or directory on the device. More...
 
afc_error_t afc_make_directory (afc_client_t client, const char *path)
 Creates a directory on the device. More...
 
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. More...
 
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. More...
 
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. More...
 
afc_error_t afc_remove_path_and_contents (afc_client_t client, const char *path)
 Deletes a file or directory including possible contents. More...
 
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. More...
 
afc_error_t afc_dictionary_free (char **dictionary)
 Frees up a char dictionary as returned by some AFC functions. More...
 

Detailed Description

Access the filesystem on the device.

Typedef Documentation

typedef afc_client_private* afc_client_t

The client handle.

Enumeration Type Documentation

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

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
clientThe 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
deviceThe device to connect to.
serviceThe service descriptor returned by lockdownd_start_service.
clientPointer 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 service 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_client_start_service ( idevice_t  device,
afc_client_t client,
const char *  label 
)

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

Parameters
deviceThe device to connect to.
clientPointer that will point to a newly allocated afc_client_t upon successful return. Must be freed using afc_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
AFC_E_SUCCESS on success, or an AFC_E_* error code otherwise.
afc_error_t afc_dictionary_free ( char **  dictionary)

Frees up a char dictionary as returned by some AFC functions.

Parameters
dictionaryThe char array terminated by an empty string.
Returns
AFC_E_SUCCESS on success or an AFC_E_* error value.
afc_error_t afc_file_close ( afc_client_t  client,
uint64_t  handle 
)

Closes a file on the device.

Parameters
clientThe client to close the file with.
handleFile 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 also
http://developer.apple.com/documentation/Darwin/Reference/ManPages/man2/flock.2.html
Parameters
clientThe client to lock the file with.
handleFile handle of a previously opened file.
operationthe 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
clientThe client to use to open the file.
filenameThe file to open. (must be a fully-qualified path)
file_modeThe mode to use to open the file.
handlePointer 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
clientThe relevant AFC client
handleFile handle of a previously opened file
dataThe pointer to the memory region to store the read data
lengthThe number of bytes to read
bytes_readThe 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
clientThe client to use to seek to the position.
handleFile handle of a previously opened.
offsetSeek offset.
whenceSeeking 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
clientThe client to use.
handleFile handle of a previously opened file.
positionPosition 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
clientThe client to use to set the file size.
handleFile handle of a previously opened file.
newsizeThe 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
clientThe client to use to write to the file.
handleFile handle of previously opened file.
dataThe data to write to the file.
lengthHow much data to write.
bytes_writtenThe 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 ***  device_information 
)

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
clientThe client to get device info for.
device_informationA char list of device information terminated by an empty string or NULL if there was an error. Free with afc_dictionary_free().
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
clientThe client to get device info for.
keyThe key to get the value of.
valueThe 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 *  filename,
char ***  file_information 
)

Gets information about a specific file.

Parameters
clientThe client to use to get the information of the file.
pathThe fully-qualified path to the file.
file_informationPointer 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. Free with afc_dictionary_free().
Returns
AFC_E_SUCCESS on success or an AFC_E_* error value.
afc_error_t afc_make_directory ( afc_client_t  client,
const char *  path 
)

Creates a directory on the device.

Parameters
clientThe client to use to make a directory.
pathThe 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
clientThe client to use for making a link
linktype1 = hard link, 2 = symlink
targetThe file to be linked.
linknameThe 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 *  path,
char ***  directory_information 
)

Gets a directory listing of the directory requested.

Parameters
clientThe client to get a directory listing from.
pathThe directory for listing. (must be a fully-qualified path)
directory_informationA char list of files in the directory terminated by an empty string or NULL if there was an error. Free with afc_dictionary_free().
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
clientThe client to use.
pathThe 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_remove_path_and_contents ( afc_client_t  client,
const char *  path 
)

Deletes a file or directory including possible contents.

Parameters
clientThe client to use.
pathThe path to delete. (must be a fully-qualified path)
Since
libimobiledevice 1.1.7
Note
Only available in iOS 6 and later.
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
clientThe client to have rename.
fromThe name to rename from. (must be a fully-qualified path)
toThe 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
clientThe client to use to set the file size.
pathPath of the file for which the modification time should be set.
mtimeThe 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
clientThe client to use to set the file size.
pathThe path of the file to be truncated.
newsizeThe size to set the file to.
Returns
AFC_E_SUCCESS on success or an AFC_E_* error value.