libimobiledevice/afc.h File Reference

AFC Implementation. 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, uint16_t port, afc_client_t *client)
 Makes a connection to the AFC service on the phone.
afc_error_t afc_client_free (afc_client_t client)
 Disconnects an AFC client from the phone.
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

AFC Implementation.


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

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  ) 

Disconnects an AFC client from the phone.

Parameters:
client The client to disconnect.

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 phone.

Parameters:
device The device to connect to.
port The destination port.
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 when device or port is invalid, AFC_E_MUX_ERROR when the connection failed, 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.
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.
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 phone.

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 phone.

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 phone.

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 phone.

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 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.
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 phone.

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 phone.

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 phone.

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 phone 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.


doxygen