libimobiledevice/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_from_connection (idevice_connection_t connection, afc_client_t *client)
 Makes a connection to the AFC service on the device using the given connection.
afc_error_t afc_client_new (idevice_t device, uint16_t port, 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 info for a client connection to phone.
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 phone.
afc_error_t afc_file_close (afc_client_t client, uint64_t handle)
 Closes a file on the phone.
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 phone.
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 phone.
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 phone.
afc_error_t afc_file_truncate (afc_client_t client, uint64_t handle, uint64_t newsize)
 Sets the size of a file on the phone.
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 phone.
afc_error_t afc_make_directory (afc_client_t client, const char *dir)
 Creates a directory on the phone.
afc_error_t afc_truncate (afc_client_t client, const char *path, uint64_t newsize)
 Sets the size of a file on the phone 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 phone.
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:
client The client to free.
afc_error_t afc_client_new ( idevice_t  device,
uint16_t  port,
afc_client_t client 
)

Makes a connection to the AFC service on the device.

This function calls afc_client_new_from_connection() after creating a connection to the specified device and port.

See also:
afc_client_new_from_connection
Parameters:
device The device to connect to.
Parameters:
port The destination port.
Parameters:
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_client_new_from_connection ( idevice_connection_t  connection,
afc_client_t client 
)

Makes a connection to the AFC service on the device using the given connection.

Parameters:
connection An idevice_connection_t that must have been previously connected using idevice_connect(). Note that this connection will not be closed by calling afc_client_free().
Parameters:
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 connection is invalid, 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 phone.

Parameters:
client The client to close the file with.
Parameters:
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 phone.

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.
Parameters:
handle File handle of a previously opened file.
Parameters:
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 phone.

Parameters:
client The client to use to open the file.
Parameters:
filename The file to open. (must be a fully-qualified path)
Parameters:
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.
Parameters:
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
Parameters:
handle File handle of a previously opened file
Parameters:
data The pointer to the memory region to store the read data
Parameters:
length The number of bytes to read
Parameters:
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 phone.

Parameters:
client The client to use to seek to the position.
Parameters:
handle File handle of a previously opened.
Parameters:
offset Seek offset.
Parameters:
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 phone.

Parameters:
client The client to use.
Parameters:
handle File handle of a previously opened file.
Parameters:
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 phone.

Parameters:
client The client to use to set the file size.
Parameters:
handle File handle of a previously opened file.
Parameters:
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.
Parameters:
handle File handle of previously opened file.
Parameters:
data The data to write to the file.
Parameters:
length How much data to write.
Parameters:
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 info for a client connection to phone.

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.
Parameters:
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.
Parameters:
key The key to get the value of.
Parameters:
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.
Parameters:
path The fully-qualified path to the file.
Parameters:
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 phone.

Parameters:
client The client to use to make a directory.
Parameters:
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
Parameters:
linktype 1 = hard link, 2 = symlink
Parameters:
target The file to be linked.
Parameters:
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.
Parameters:
dir The directory to list. (must be a fully-qualified path)
Parameters:
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.
Parameters:
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 phone.

Parameters:
client The client to have rename.
Parameters:
from The name to rename from. (must be a fully-qualified path)
Parameters:
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 phone.

Parameters:
client The client to use to set the file size.
Parameters:
path Path of the file for which the modification time should be set.
Parameters:
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 phone without prior opening it.

Parameters:
client The client to use to set the file size.
Parameters:
path The path of the file to be truncated.
Parameters:
newsize The size to set the file to.
Returns:
AFC_E_SUCCESS on success or an AFC_E_* error value.
Generated on Thu Dec 16 22:53:47 2010 for libimobiledevice by  doxygen 1.6.3