Posted Oct 14, 2004 by Geoff: this is my proposed API for libifp. If you have any suggestions or comments, please let me know or post them to the mailing list.. thanks!

ifp-driver homepage and workpage 		SourceForge.net Logo

ifp.h File Reference

An interface for iRiver's flash-based mp3 players. More...


Data Structures

struct  ifp_device
 An ifp_device handle. 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.
void * ifp_find_device (void)
int ifp_release_device (void *)
int ifp_selftest (struct ifp_device *dev)

Device status

int ifp_device_info (struct ifp_device *dev, char *s, 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 *s, 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:.

Read

int ifp_read_open (struct ifp_device *dev, 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 *buff, 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).

Write

int ifp_write_open (struct ifp_device *dev, 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 *buff, int bytes)
 Writes 'bytes' of data from buff to the file.

Metadata

int ifp_rename (struct ifp_device *dev, char *old_path, char *new_path)
 Renames a file or directory.
int ifp_delete (struct ifp_device *dev, char *f)
 Delete the file f.
int ifp_mkdir (struct ifp_device *dev, char *f)
 Creates a new directory, f.
int ifp_rmdir (struct ifp_device *dev, char *f)
 Deletes the directory f.
int ifp_list_dirs (struct ifp_device *dev, char *dirname, int(*callbk)(void *, int, char *, int), void *context)
 Reads directory contents.

Boolean tests

int ifp_is_file (struct ifp_device *dev, char *f)
 Tests if f is a file.
int ifp_is_dir (struct ifp_device *dev, char *f)
 Tests if f is a directory.
int ifp_exists (struct ifp_device *dev, char *f)
 Tests for the existance of f.

Defines

#define IFP_FILE   1
#define IFP_DIR   2

Functions

int ifp_read_file_progress (struct ifp_device *dev, FILE *dst, 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 *dst, int filesize, char *f, int(*progress)(void *, int), void *context)
 Uploads a file; includes a hook for a progress metre.
int ifp_write_file (struct ifp_device *dev, FILE *src, int filesize, char *f)
 Creates a new file 'f' from src.
int ifp_read_file (struct ifp_device *dev, FILE *dst, char *f)
 Reads the file 'f' into dst.

Detailed Description

An interface for iRiver's flash-based mp3 players.

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

Define Documentation

#define IFP_DIR   2
 

Dir 'type'.

#define IFP_FILE   1
 

File 'type'.

Function Documentation

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_delete (  struct ifp_device *  dev,
char *  f
) 
 

Delete the file f.

(f must be a regular file.)

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_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_exists (  struct ifp_device *  dev,
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_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   ) 
 

Searches the system for a compatible device, and returns a handle to it (or NULL if none could be found). The handle must be released with ifp_release_device.

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)

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:
1 if the self-test failed. (Ask the user to jiggle the handle.)

0 on success.

<0 on failure.

int ifp_is_dir (  struct ifp_device *  dev,
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_is_file (  struct ifp_device *  dev,
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_list_dirs (  struct ifp_device *  dev,
char *  filename,
int(*  callbk)(void *, int, char *, int),
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.

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

Creates a new directory, f.

(f's parent must exist.)

int ifp_model (  struct ifp_device *  dev,
char *  s,
int  size
) 
 

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

('size' is the ammount of memory available at s.) Typical results are "IFP-590T".

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_read_file_progress (  struct ifp_device *  dev,
FILE *  dst,
char *  f,
int(*  progress)(void *, int),
void *  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.)

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_release_device (  void *   ) 
 

Releases device handled allocated by ifp_find_device.

int ifp_rename (  struct ifp_device *  dev,
char *  old_path,
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.)

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

Deletes the directory f.

(f must be empty.)

int ifp_selftest (  struct ifp_device *  dev  ) 
 

Quick communications test with the device. Normally, users shouldn't have to use this because it's run automatically by ifp_init.

int ifp_write_file_progress (  struct ifp_device *  dev,
FILE *  src,
int  filesize,
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'.

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

int ifp_write_open (  struct ifp_device *  dev,
char *  f,
int  filesize
) 
 

Opens the file f for writing.

Creates and opens a new file of 'filesize' bytes with the name 'f'.

Generated on Thu Oct 14 22:42:59 2004 for libifp by doxygen 1.3.8