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.

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.

Enumeration Type Documentation

afc_file_mode_t

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

afc_lock_op_t

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_client_free()

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_client_new()

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 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_client_start_service()

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

device	The device to connect to.
client	Pointer that will point to a newly allocated afc_client_t upon successful return. Must be freed using afc_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

AFC_E_SUCCESS on success, or an AFC_E_* error code otherwise.

afc_dictionary_free()

afc_error_t afc_dictionary_free

(

char **

dictionary

)

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

Parameters

dictionary

The char array terminated by an empty string.

Returns

AFC_E_SUCCESS on success or an AFC_E_* error value.

afc_file_close()

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_file_lock()

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

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_file_open()

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.
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_file_read()

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_file_seek()

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_file_tell()

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_file_truncate()

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_file_write()

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_get_device_info()

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

client	The client to get device info for.
device_information	A 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_get_device_info_key()

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_get_file_info()

afc_error_t afc_get_file_info	(	afc_client_t	client,
		const char *	filename,
		char ***	file_information
	)

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.
file_information	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. Free with afc_dictionary_free().

Returns

AFC_E_SUCCESS on success or an AFC_E_* error value.

afc_make_directory()

afc_error_t afc_make_directory	(	afc_client_t	client,
		const char *	path
	)

Creates a directory on the device.

Parameters

client	The client to use to make a directory.
path	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_make_link()

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_read_directory()

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

client	The client to get a directory listing from.
path	The directory for listing. (must be a fully-qualified path)
directory_information	A 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_remove_path()

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_remove_path_and_contents()

afc_error_t afc_remove_path_and_contents	(	afc_client_t	client,
		const char *	path
	)

Deletes a file or directory including possible contents.

Parameters

client	The client to use.
path	The 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_rename_path()

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_set_file_time()

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_truncate()

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.