libimobiledevice  1.1.5
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_privateafc_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

The client handle.

typedef int16_t afc_error_t

Represents an error code.


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 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:
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 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. 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.
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 ***  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:
clientThe client to get device info for.
infosA 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:
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 *  path,
char ***  infolist 
)

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.
infolistPointer 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:
clientThe client to use to make a directory.
dirThe 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 *  dir,
char ***  list 
)

Gets a directory listing of the directory requested.

Parameters:
clientThe client to get a directory listing from.
dirThe directory to list. (must be a fully-qualified path)
listA 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:
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_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.