-=[	documentation	]=-
	libifp: ifp.h File Reference

ifp.h File Reference

Detailed Description

An interface for iRiver's flash-based portable music players.

Author:: Copyright (C) Geoff Oakham, 2004; <oakhamg@users.sourceforge.net>

Calling Conventions (unless otherwise stated):

integer return value 0 indicates success, error otherwise
argument 'dev' is a device handle
argument 'f' is the full path to a remote file or directory. (eg. '\foo\bar.mp3')
argument 'b' is a buffer for returning data
remote pathnames use '\' instead of '/' for separating directories (eg '\classical\mozart\magicflute.ogg')
functions that return numerical values (eg. ifp_freespace) return negative values on error

Data Structures

struct ifp_device

An ifp_device handle. More...

struct ifp_transfer_status

Statistics about a file transfer in progress. More...

struct ifp_treewalk_entry

A remote file or directory. More...

Setup and initialization

int ifp_init (struct ifp_device *dev, void *dev_handle)

Initializes device.

int ifp_finalize (struct ifp_device *dev)

Releases device. Releases any resources aquired by ifp_init. Basically, when ifp_init returns 0 (success), ifp_finalize must be called after you're finished with dev.

void * ifp_find_device (void)

Scans the system and returns the first compatible iFP device.

int ifp_release_device (void *)

Releases device handle allocated by ifp_find_device.

int ifp_selftest (struct ifp_device *dev)

Tests communications with the device.

int ifp_format (struct ifp_device *dev)

Reformats the device's storage media.

int ifp_update_firmware (struct ifp_device *dev, const char *localfile, ifp_progress fn, void *context)

Upgrades the firmware.

Device status

int ifp_device_info (struct ifp_device *dev, char *b, int n)

Creates a human readable status string.

int ifp_battery (struct ifp_device *dev)

Reports the battery's status on the scale from 0 to 4.

int ifp_capacity (struct ifp_device *dev)

Reports the device's capacity in bytes.

int ifp_freespace (struct ifp_device *dev)

Reports the device's available free space in bytes.

int ifp_model (struct ifp_device *dev, char *b, int n)

Reads in the device's model number into 's'.

int ifp_delta (struct ifp_device *dev, int *values)

(experimental) retrieves a mystery value.

int ifp_firmware_version (struct ifp_device *dev)

Reads the device's firmware version. The firmware version is returned in raw BCD. For human consumption, I suggest:.

const char * ifp_error_message (int n)

Return an English string describing an error number.

Metadata

int ifp_rename (struct ifp_device *dev, const char *old_path, const char *new_path)

Renames a file or directory.

int ifp_delete (struct ifp_device *dev, const char *f)

Delete the file f.

int ifp_mkdir (struct ifp_device *dev, const char *f)

Creates a new directory, f.

int ifp_rmdir (struct ifp_device *dev, const char *f)

Deletes the directory f.

int ifp_list_dirs (struct ifp_device *dev, const char *dirname, int(*callbk)(void *, int, const char *, int), void *context)

Reads directory contents.

int ifp_treewalk_open (struct ifp_device *dev, const char *directory, void **handle)

Recursively walk a remote directory. (Interface similar to "fts.h".).

int ifp_treewalk_close (void *tws_p)

Releases the resources used in a treewalk.

ifp_treewalk_entry * ifp_treewalk_next (void *tws_p)

Returns the next file or directory in a treewalk.

Reading files

int ifp_read_open (struct ifp_device *dev, const char *f)

Opens the file f for reading.

int ifp_read_close (struct ifp_device *dev)

Closes a file open for reading.

int ifp_read_seek (struct ifp_device *dev, int abs_position)

Fast-forward within the current file.

int ifp_read_data (struct ifp_device *dev, void *b, int bytes)

Reads from an open file. Reads the next 'bytes' of data into 'buff'.

int ifp_read_eof (struct ifp_device *dev)

Check if we've reached the end of the file. (EOF).

int ifp_read_size (struct ifp_device *dev)

Returns the size of the current file in bytes.

Creating files

int ifp_write_open (struct ifp_device *dev, const char *f, int fsize)

Opens the file f for writing.

int ifp_write_close (struct ifp_device *dev)

Closes a file open for writing.

int ifp_write_data (struct ifp_device *dev, void *b, int bytes)

Writes 'bytes' of data from buff to the file.

Bulk file transfers (userland only)

int ifp_read_file_progress (struct ifp_device *dev, FILE *dst, const char *f, int(*progress)(void *, int), void *context)

Downloads a file; includes a hook for a progress metre.

int ifp_write_file_progress (struct ifp_device *dev, FILE *src, int filesize, const char *f, int(*progress)(void *, int), void *context)

Uploads a file; includes a hook for a progress metre. Creates a new file 'f' on the device and populates it with data from 'src'. Filesize is the number of bytes to be uploaded from 'src'.

int ifp_read_file (struct ifp_device *dev, FILE *dst, const char *f)

Reads the file 'f' into dst.

int ifp_write_file (struct ifp_device *dev, FILE *src, int filesize, const char *f)

Creates a new file 'f' from src.

int ifp_download_file (struct ifp_device *dev, const char *remotefile, const char *localfile, ifp_progress fn, void *fn_context)

Downloads 'remotefile' and saves it directly on the filesystem as 'localfile'.

int ifp_upload_file (struct ifp_device *dev, const char *localfile, const char *remotefile, ifp_progress fn, void *fn_context)

Uploads 'localfile' from the filesystem onto the device as 'remotefile'.

int ifp_delete_dir_recursive (struct ifp_device *dev, const char *f)

Deletes the directory 'f', its files and subdirectories. (Think of 'rm -Rf'.).

int ifp_download_dir (struct ifp_device *dev, const char *remotedir, const char *localdir, ifp_progress fn, void *fn_context)

Downloads the contents of 'remotedir' (including all subdirectories) and saves it as 'localdir'.

int ifp_upload_dir (struct ifp_device *dev, const char *localdir, const char *remotedir, ifp_progress fn, void *fn_context)

Uploads the contents of 'localdir' (including all subdirectories) to the device as 'remotedir'.

Boolean tests

int ifp_is_file (struct ifp_device *dev, const char *f)

Tests if f is a file.

int ifp_is_dir (struct ifp_device *dev, const char *f)

Tests if f is a directory.

int ifp_exists (struct ifp_device *dev, const char *f)

Tests for the existance of f.

FM Tuner preset station manipulation

int ifp_get_tuner_presets (struct ifp_device *dev, void *data, int n)

Retrieves the tuner preset file into 'data'.

int ifp_set_tuner_presets (struct ifp_device *dev, void *data, int n)

Stores the tuner preset file 'data' on the device.

int ifp_get_station (int n, void *b, char *callsign, int *freq)

Reads station #n from the binary datablock into more useful forms.

int ifp_set_station (int n, void *data, const char *callsign, int freq)

Sets station #n to 'freq' and 'callsign'.

Defines

#define IFP_FILE   1

#define IFP_DIR   2

#define IFP_ERR_DEV_FUBAR   8

#define IFP_ERR_BAD_FREQUENCY   9

#define IFP_ERR_BAD_FILENAME   10

#define IFP_ERR_USER_CANCEL   11

#define IFP_TUNER_PRESET_DATA   240

#define IFP_FREQ_MIN   8750

#define IFP_FREQ_MAX   10800

#define IFP_PRESET_TOTAL   20

#define IFP_TUNER_LABEL   6

Typedefs

typedef int(* ifp_progress )(void *, struct ifp_transfer_status *)

Callback for implementing a progress metre.

Enumerations

enum { IFP_WALK_FILE = IFP_FILE, IFP_WALK_DIR_PRE = IFP_DIR, IFP_WALK_DIR_POST, IFP_WALK_NONE }

File types for treewalking. More...

Define Documentation

#define IFP_FILE 1

File 'type'.

#define IFP_DIR 2

Dir 'type'.

#define IFP_ERR_DEV_FUBAR 8

device not responding; try jiggling handle

#define IFP_ERR_BAD_FREQUENCY 9

tuner frequency out of range

#define IFP_ERR_BAD_FILENAME 10

filename is invalid. Likely causes are unsupported characters, or a filename that's too long (more than ::IFP_MAXFILENAMELEN chars).
note: linux's fatfs returns EINVAL instead. Should we switch?

#define IFP_ERR_USER_CANCEL 11

A user callback requested the transfer be cancelled.

#define IFP_TUNER_PRESET_DATA 240

Tuner preset buffer size.

#define IFP_FREQ_MIN 8750

lowist valid frequency (87.5kHz)

#define IFP_FREQ_MAX 10800

highist valid frequency (108.0kHz)

#define IFP_PRESET_TOTAL 20

number of preset stations.

#define IFP_TUNER_LABEL 6

max size of label string.

Typedef Documentation

typedef int(* ifp_progress)(void *, struct ifp_transfer_status *)

Callback for implementing a progress metre.
If provided, this function is typically called several times during a file transfer to give GUI applications a chance provide user feedback.
This function should return 0 for 'success' or 1 to request the transfer be cancelled when possible. (The request might be ignored.) Other values are considered 'error values'.
The first parameter is whatever if you passed to the main function as 'context'. You may use this for anything you like or leave it NULL.
The second parameter is a pointer to information about the transfer in progress. The only value guaranteed to be valid for _all_ transfers is file_bytes. Which values *are* valid should be obvious from context. To be on the safe side, please guard against NULL pointers and divide-by -zero errors. (The structure itself won't be NULL. I promise.)

Enumeration Type Documentation

anonymous enum

File types for treewalking.

Enumeration values:

IFP_WALK_FILE file

IFP_WALK_DIR_PRE directory, before visiting its children

IFP_WALK_DIR_POST directory, after visiting its children

IFP_WALK_NONE none of the above

Function Documentation

int ifp_init ( struct ifp_device * dev,

void * device_handle

)

Initializes device.
Initialzies and tests the device for use with device_handle. (ifp_finalize should be called when you're finished with 'dev'.)

Parameters:

dev Unitialized memory ready for use as an ifp_device.

device_handle The iFP USB hardware device handle.

Returns:
IFP_ERR_DEV_FUBAR if the self-test failed. (Ask the user to jiggle the handle.)
0 on success.

void* ifp_find_device ( void )

Scans the system and returns the first compatible iFP device.
If no device is found, NULL is returned. The handle must be released with ifp_release_device.
Examples:
simple.c.

int ifp_selftest ( struct ifp_device * dev )

Tests communications with the device.
This is done automatically on startup by ifp_init, so normal shouldn't need to call this.. unless they really want to.

int ifp_format ( struct ifp_device * dev )

Reformats the device's storage media.
(Deletes all your stuff.) Returns 0 on success, 1 on error. This function hasn't been tested--please report if you've successfully used it.

int ifp_update_firmware ( struct ifp_device * dev,

const char * localfile,

ifp_progress fn,

void * fn_context

)

Upgrades the firmware.
This is much like a file upload, except: the filename on the local disk must be in the format "IFP-?XXT.HEX" or "IFP-1XXTC.HEX". The progress meter only tracks the firmware upload. The flash-upgrading itself and reboot take extra time we can't predict.
Immediately after calling ifp_update_firmware, the caller should release 'dev', and wait a healthy ammount of time (10 or more seconds) before trying to reconnect. During this time, you'll see the message "upgrading firmware please don't touch" on the device, after which the device will shutdown: user will likely have to turn it back on themselves.
I welcome suggestions and/or code on how to help monitor the device status during a firmware upgrade.

int ifp_device_info ( struct ifp_device * dev,

char * s,

int n

)

Creates a human readable status string.
Creates a human readable status string similar to "model IFP-007T, firmware 1.14, battery =[####], delta 1.8.4.42".

int ifp_battery ( struct ifp_device * dev )

Reports the battery's status on the scale from 0 to 4.
Typical values are 4, 0 and occasionally 2.

int ifp_model ( struct ifp_device * dev,

char * s,

int size

)

Reads in the device's model number into 's'.
('size' is the size of the buffer s points to.) Typical results look like "IFP-590T".

int ifp_delta ( struct ifp_device * dev,

int * values

)

(experimental) retrieves a mystery value.
I've coined this mystery value "Delta" until a better name is chosen.

Parameters:

values an empty int[4] for the output values.

Integers returned in 'values' are my interpretation of the data. The actual raw data has been varried widely:

0108 0312 ffff ffff 0108 0415 ffff ffff 0108 0616 ffff ffff 0108 0417 0000 0000 0108 0418 ffff ffff
Two devices returned 4 bytes instead of 8.

int ifp_firmware_version ( struct ifp_device * dev )

Reads the device's firmware version. The firmware version is returned in raw BCD. For human consumption, I suggest:.

sprintf(s, "%x.%02x", r/0x0100, r%0x100)

const char* ifp_error_message ( int n )

Return an English string describing an error number.
(Available only in userland.)

int ifp_rename ( struct ifp_device * dev,

const char * old_path,

const char * new_path

)

Renames a file or directory.
Renames or moves the object 'old_path' to 'new_path'.

Parameters:

old_path an existing file or directory.

new_path an available path for a new file or directory. (Ie, the path's parent directory exists and the path isn't in use by another object in that directory.)

Returns 0 on success and -ENOENT, -EEXIST, -EACCES, IFP_ERR_BAD_FILENAME on failure, as appropriate.

int ifp_delete ( struct ifp_device * dev,

const char * f

)

Delete the file f.
Returns -ENOENT if f doesn't exist.

int ifp_mkdir ( struct ifp_device * dev,

const char * f

)

Creates a new directory, f.
Returns -ENOENT if f's parent doesn't exist, -EEXISTS the dirname 'f' is allready in use, and IFP_ERR_BAD_FILENAME if 'f' contains unsupported characters.

int ifp_rmdir ( struct ifp_device * dev,

const char * d

)

Deletes the directory f.
Returns 0 on success or: -ENOENT -ENOTEMPTY -EACCES

int ifp_list_dirs ( struct ifp_device * dev,

const char * filename,

int(*)(void *, int, const char *, int) callbk,

void * context

)

Reads directory contents.
Passes the contents of 'dirname' to a callback function, one entry at a time. The parameters given to the callback function are:

void * context is the same context passed to list_dirs
int type is either IFP_FILE or IFP_DIR
char * name is the entry name without a full path. (Ie, no '\' chars)
int filesize is the number of bytes in a file (undefied for directories)
The callback can return '0' on success, '1' to "break" (leave early without error) or <0 on error.
Returns 0 on success or -ENOENT if the directory doesn't exist.

int ifp_treewalk_open ( struct ifp_device * dev,

const char * directory,

void ** handle

)

Recursively walk a remote directory. (Interface similar to "fts.h".).
Start a treewalk for the 'directory' on the device. The handle for this session is placed at *handle; this handle is freed by calling ifp_treewalk_close.
'dev' won't be left in a "special state" after calling treewalk-family functions. Likewise, please don't leave dev in a "special state" before calling ifp_treewalk_open or ifp_treewalk_next.
Returns -ENOENT if the directory doesn't exist.

int ifp_treewalk_close ( void * tws_p )

Releases the resources used in a treewalk.
Must be called after each successful call of ifp_treewalk_open.

struct ifp_treewalk_entry* ifp_treewalk_next ( void * tws_p )

Returns the next file or directory in a treewalk.
The structure returned is valid until the next ifp_treewalk_next or ifp_treewalk_close function call. See ifp_treewalk_entry for details about the fields.
Likewise, please don't leave 'dev' in a "special state" before calling ifp_treewalk_next.
NULL is returned after the last entry.

int ifp_read_open ( struct ifp_device * dev,

const char * f

)

Opens the file f for reading.
Returns -ENOENT if 'f' doesn't exist and -EACCES if 'f' is read-protected by the device.

int ifp_read_seek ( struct ifp_device * dev,

int bytes

)

Fast-forward within the current file.
In the current open file, skip forward to 'bytes' (ignoring the data). Caution: the implementation isn't particularily fast, and can only seek forward. Avoid it if you can.

int ifp_read_data ( struct ifp_device * dev,

void * buff,

int bytes

)

Reads from an open file. Reads the next 'bytes' of data into 'buff'.

Returns:
the number of bytes read, or <0 on error.

int ifp_write_open ( struct ifp_device * dev,

const char * f,

int filesize

)

Opens the file f for writing.
Creates and opens a new file of 'filesize' bytes with the name 'f'. Returns -EEXIST if the name 'f' isn't available. (Ie, if there allready exists a file or directory with the same name.) Returns -ENOENT, -ENOSPC, or IFP_ERR_BAD_FILENAME

int ifp_write_data ( struct ifp_device * dev,

void * buff,

int bytes

)

Writes 'bytes' of data from buff to the file.
Returns 0 on success. (Does not return the number of bytes written--it's all or nothing.)

int ifp_read_file_progress ( struct ifp_device * dev,

FILE * dst,

const char * f,

int(*)(void *, int) fn,

void * fn_context

)

Downloads a file; includes a hook for a progress metre.
Reads the file 'f' from the device and saves it in 'dst'.
Parameters:

f name of the remote file we're downloading

dst where the data will be saved

progress Optional. If given, this function will be called occationally so an application can update a progress metre. (For example.)

context Context for the progress metre. (Safe to leave NULL.)

(Available only in userland.)
Returns -ENOENT if 'f' doesn't exist; -EACCES if 'f' is read-protected by the device; and IFP_ERR_USER_CANCEL if the callback requested the transfer cancelled.
(Available only in userland.)

int ifp_write_file_progress ( struct ifp_device * dev,

FILE * src,

int filesize,

const char * f,

int(*)(void *, int) fn,

void * fn_context

)

Uploads a file; includes a hook for a progress metre. Creates a new file 'f' on the device and populates it with data from 'src'. Filesize is the number of bytes to be uploaded from 'src'.
(Note: it appears the device might not need to know the number of bytes in a file ahead time. The current implementation doesn't support this, but if you don't have access to the filesize ahead of time, you might be able to hack libifp to let you do it anyways.)

Parameters:

src data to be uploaded

filesize number of bytes to copy from src

f name of the file to be created

progress Optional. If given, this function will be called occationally so an application can update its progress metre.

context Context for the progress metre. (Safe to leave NULL.)

Returns -EEXIST, -ENOENT, -ENOSPC, IFP_ERR_BAD_FILENAME, IFP_ERR_USER_CANCEL
(Available only in userland.)

int ifp_download_file ( struct ifp_device * dev,

const char * remotefile,

const char * localfile,

ifp_progress fn,

void * fn_context

)

Downloads 'remotefile' and saves it directly on the filesystem as 'localfile'.
The progress callback function 'fn' and its context pointer are optional. See ifp_progress and ifp_transfer_status for more information.
Returns -ENOENT, -EACCES, IFP_ERR_USER_CANCEL (Available only in userland.)
Note: There is currently a 'EPIPE' bug in the wild that is relatively rare but causes file corruption during download. ifp_download_file and ifp_download_dir detect and recover from it automatically, but you might see the progress numbers "jump backwards" occasionally.

int ifp_upload_file ( struct ifp_device * dev,

const char * localfile,

const char * remotefile,

ifp_progress fn,

void * fn_context

)

Uploads 'localfile' from the filesystem onto the device as 'remotefile'.
The progress callback function 'fn' and its context pointer are optional. See ifp_progress and ifp_transfer_status for more information.
Returns -EEXIST, -ENOENT, -ENOSPC, IFP_ERR_BAD_FILENAME, IFP_ERR_USER_CANCEL (Available only in userland.)

int ifp_delete_dir_recursive ( struct ifp_device * dev,

const char * f

)

Deletes the directory 'f', its files and subdirectories. (Think of 'rm -Rf'.).
Will return -ENOENT if 'f' doesn't exist or isn't a directory.
(Available only in userland, at this time.)

int ifp_download_dir ( struct ifp_device * dev,

const char * remotedir,

const char * localdir,

ifp_progress fn,

void * fn_context

)

Downloads the contents of 'remotedir' (including all subdirectories) and saves it as 'localdir'.
Note that 'localdir' must not allready exist. Example: suppose localdir was '/tmp/tunes/tame' and remotedir was '\classical\junk'. The directory '/tmp/tunes/tame' will be created and the file '\classical\junk\buz\fud.ogg' will be copied as '/tmp/tunes/tame/buz/fud.ogg'
The progress callback function 'fn' and its context pointer are optional. See ifp_progress and ifp_transfer_status for more information.
Returns -ENOENT, -EACCES, IFP_ERR_USER_CANCEL
(Available only in userland.)
Note: There is currently a 'EPIPE' bug in the wild that is relatively rare but causes file corruption during download. ifp_download_file and ifp_download_dir detect and recover from it automatically, but you might see the progress numbers "jump backwards" occasionally.

int ifp_upload_dir ( struct ifp_device * dev,

const char * localdir,

const char * remotedir,

ifp_progress fn,

void * fn_context

)

Uploads the contents of 'localdir' (including all subdirectories) to the device as 'remotedir'.
Note that 'remotedir' must not exist on the remote device. Example: suppose localdir was '/tmp/tunes/tame' and remotedir was '\classical\junk'. The directory '\classical\junk' will be created and the file '/tmp/tunes/tame/buz/fud.ogg' will be copied as '\classical\junk\buz\fud.ogg'.
The progress callback function 'fn' and its context pointer are optional. See ifp_progress and ifp_transfer_status for more information.
Returns -EEXIST, -ENOENT, -ENOSPC, IFP_ERR_BAD_FILENAME, or IFP_ERR_USER_CANCEL. FIXME: handle invalid filenames from local filesystem with more grace
(Available only in userland.)

int ifp_is_file ( struct ifp_device * dev,

const char * f

)

Tests if f is a file.
Returns 1 if it is, and 0 if it doesn't exist or isn't a file.

int ifp_is_dir ( struct ifp_device * dev,

const char * f

)

Tests if f is a directory.
Returns 1 if it is, and 0 if it doesn't exist or isn't a dir.

int ifp_exists ( struct ifp_device * dev,

const char * f

)

Tests for the existance of f.

Returns:
IFP_FILE if f is a file
IFP_DIR if f is a directory
0 if f doesn't exist
<0 error.

int ifp_get_tuner_presets ( struct ifp_device * dev,

void * data,

int n

)

Retrieves the tuner preset file into 'data'.
'data' is a buffer of 'n' bytes.. n must be at least IFP_TUNER_PRESET_DATA bytes.

int ifp_set_tuner_presets ( struct ifp_device * dev,

void * data,

int n

)

Stores the tuner preset file 'data' on the device.
'data' is tuner preset file to be stored.. it is extactly IFP_TUNER_PRESET_DATA bytes. 'n' must be exactly IFP_TUNER_PRESET_DATA

int ifp_get_station ( int n,

void * b,

char * callsign,

int * freq

)

Reads station #n from the binary datablock into more useful forms.
b is the block of data loaded using ifp_get_tuner_presets, n is a number between 0 and IFP_PRESET_TOTAL-1, callsign is a pointer to a buffer of at least IFP_TUNER_LABEL+1 bytes, freq is a pointer to an integer, where the station's frequency will be saved. The frequency units are 10*kHz and range from IFP_FREQ_MIN to IFP_FREQ_MAX.
Apon successful return, 'callsign' will be loaded the station's label as a zero-terminated string, and 'freq' will be the station's frequency in 10*kHz.

int ifp_set_station ( int n,

void * b,

const char * callsign,

int freq

)

Sets station #n to 'freq' and 'callsign'.
b is the block of data loaded using ifp_get_tuner_presets, n is a number between 0 and IFP_PRESET_TOTAL-1, callsign is a zero-terminated string (but only the first 6 characters will be used), freq is the FM frequency in units of Hz*10^4 (Or kHz*10); freq can range range from IFP_FREQ_MIN to IFP_FREQ_MAX.
eg: //sets station #4 to 91.5MHz and labeled 'bbc' i = ifp_set_station(3, p, "bbc", 9150);
Notes: -you must call ifp_set_tuner_presets for the changes to take affect.
-Although the interface suggests frequency accuracy of 0.01MHz is possible, I've found the player only supports increments 0.05MHz. Setting a frequency to a more accurate value is *not* an error: the hardware will silently truncate to an acceptable value.
-User interfaces can provide feedback to the user of the above "effect" by saving and reloading the preset data after every change. Any data modification by the hardware will be immediately obvious.
Returns IFP_ERR_BAD_FREQUENCY if the frequency is out of range.

Generated on Sun Dec 5 22:07:55 2004 for libifp


Data Structures
struct	ifp_device
	An ifp_device handle. More...
struct	ifp_transfer_status
	Statistics about a file transfer in progress. More...
struct	ifp_treewalk_entry
	A remote file or directory. More...
Setup and initialization
int	ifp_init (struct ifp_device dev, void dev_handle)
	Initializes device.
int	ifp_finalize (struct ifp_device *dev)
	Releases device. Releases any resources aquired by ifp_init. Basically, when ifp_init returns 0 (success), ifp_finalize must be called after you're finished with dev.
void *	ifp_find_device (void)
	Scans the system and returns the first compatible iFP device.
int	ifp_release_device (void *)
	Releases device handle allocated by ifp_find_device.
int	ifp_selftest (struct ifp_device *dev)
	Tests communications with the device.
int	ifp_format (struct ifp_device *dev)
	Reformats the device's storage media.
int	ifp_update_firmware (struct ifp_device dev, const char localfile, ifp_progress fn, void *context)
	Upgrades the firmware.
Device status
int	ifp_device_info (struct ifp_device dev, char b, int n)
	Creates a human readable status string.
int	ifp_battery (struct ifp_device *dev)
	Reports the battery's status on the scale from 0 to 4.
int	ifp_capacity (struct ifp_device *dev)
	Reports the device's capacity in bytes.
int	ifp_freespace (struct ifp_device *dev)
	Reports the device's available free space in bytes.
int	ifp_model (struct ifp_device dev, char b, int n)
	Reads in the device's model number into 's'.
int	ifp_delta (struct ifp_device dev, int values)
	(experimental) retrieves a mystery value.
int	ifp_firmware_version (struct ifp_device *dev)
	Reads the device's firmware version. The firmware version is returned in raw BCD. For human consumption, I suggest:.
const char *	ifp_error_message (int n)
	Return an English string describing an error number.
Metadata
int	ifp_rename (struct ifp_device dev, const char old_path, const char *new_path)
	Renames a file or directory.
int	ifp_delete (struct ifp_device dev, const char f)
	Delete the file f.
int	ifp_mkdir (struct ifp_device dev, const char f)
	Creates a new directory, f.
int	ifp_rmdir (struct ifp_device dev, const char f)
	Deletes the directory f.
int	ifp_list_dirs (struct ifp_device dev, const char dirname, int(callbk)(void , int, const char , int), void context)
	Reads directory contents.
int	ifp_treewalk_open (struct ifp_device dev, const char directory, void **handle)
	Recursively walk a remote directory. (Interface similar to "fts.h".).
int	ifp_treewalk_close (void *tws_p)
	Releases the resources used in a treewalk.
ifp_treewalk_entry *	ifp_treewalk_next (void *tws_p)
	Returns the next file or directory in a treewalk.
Reading files
int	ifp_read_open (struct ifp_device dev, const char f)
	Opens the file f for reading.
int	ifp_read_close (struct ifp_device *dev)
	Closes a file open for reading.
int	ifp_read_seek (struct ifp_device *dev, int abs_position)
	Fast-forward within the current file.
int	ifp_read_data (struct ifp_device dev, void b, int bytes)
	Reads from an open file. Reads the next 'bytes' of data into 'buff'.
int	ifp_read_eof (struct ifp_device *dev)
	Check if we've reached the end of the file. (EOF).
int	ifp_read_size (struct ifp_device *dev)
	Returns the size of the current file in bytes.
Creating files
int	ifp_write_open (struct ifp_device dev, const char f, int fsize)
	Opens the file f for writing.
int	ifp_write_close (struct ifp_device *dev)
	Closes a file open for writing.
int	ifp_write_data (struct ifp_device dev, void b, int bytes)
	Writes 'bytes' of data from buff to the file.
Bulk file transfers (userland only)
int	ifp_read_file_progress (struct ifp_device dev, FILE dst, const char f, int(progress)(void , int), void context)
	Downloads a file; includes a hook for a progress metre.
int	ifp_write_file_progress (struct ifp_device dev, FILE src, int filesize, const char f, int(progress)(void , int), void context)
	Uploads a file; includes a hook for a progress metre. Creates a new file 'f' on the device and populates it with data from 'src'. Filesize is the number of bytes to be uploaded from 'src'.
int	ifp_read_file (struct ifp_device dev, FILE dst, const char *f)
	Reads the file 'f' into dst.
int	ifp_write_file (struct ifp_device dev, FILE src, int filesize, const char *f)
	Creates a new file 'f' from src.
int	ifp_download_file (struct ifp_device dev, const char remotefile, const char localfile, ifp_progress fn, void fn_context)
	Downloads 'remotefile' and saves it directly on the filesystem as 'localfile'.
int	ifp_upload_file (struct ifp_device dev, const char localfile, const char remotefile, ifp_progress fn, void fn_context)
	Uploads 'localfile' from the filesystem onto the device as 'remotefile'.
int	ifp_delete_dir_recursive (struct ifp_device dev, const char f)
	Deletes the directory 'f', its files and subdirectories. (Think of 'rm -Rf'.).
int	ifp_download_dir (struct ifp_device dev, const char remotedir, const char localdir, ifp_progress fn, void fn_context)
	Downloads the contents of 'remotedir' (including all subdirectories) and saves it as 'localdir'.
int	ifp_upload_dir (struct ifp_device dev, const char localdir, const char remotedir, ifp_progress fn, void fn_context)
	Uploads the contents of 'localdir' (including all subdirectories) to the device as 'remotedir'.
Boolean tests
int	ifp_is_file (struct ifp_device dev, const char f)
	Tests if f is a file.
int	ifp_is_dir (struct ifp_device dev, const char f)
	Tests if f is a directory.
int	ifp_exists (struct ifp_device dev, const char f)
	Tests for the existance of f.
FM Tuner preset station manipulation
int	ifp_get_tuner_presets (struct ifp_device dev, void data, int n)
	Retrieves the tuner preset file into 'data'.
int	ifp_set_tuner_presets (struct ifp_device dev, void data, int n)
	Stores the tuner preset file 'data' on the device.
int	ifp_get_station (int n, void b, char callsign, int *freq)
	Reads station #n from the binary datablock into more useful forms.
int	ifp_set_station (int n, void data, const char callsign, int freq)
	Sets station #n to 'freq' and 'callsign'.
Defines
#define	IFP_FILE 1
#define	IFP_DIR 2
#define	IFP_ERR_DEV_FUBAR 8
#define	IFP_ERR_BAD_FREQUENCY 9
#define	IFP_ERR_BAD_FILENAME 10
#define	IFP_ERR_USER_CANCEL 11
#define	IFP_TUNER_PRESET_DATA 240
#define	IFP_FREQ_MIN 8750
#define	IFP_FREQ_MAX 10800
#define	IFP_PRESET_TOTAL 20
#define	IFP_TUNER_LABEL 6
Typedefs
typedef int(*	ifp_progress )(void , struct ifp_transfer_status )
	Callback for implementing a progress metre.
Enumerations
enum	{ IFP_WALK_FILE = IFP_FILE, IFP_WALK_DIR_PRE = IFP_DIR, IFP_WALK_DIR_POST, IFP_WALK_NONE }
	File types for treewalking. More...