PMPlib APIs

The PMPlib APIs define the programing interface for both applications and driver modules. More...


Modules

 PMPlib device API
 PMPlib Device API is the root interface to a driver.
 PMPlib music API
 PMPlib Music API provides the interface to manage music files in a portable media device.
 PMPlib helper API
 The PMPlib Helper API provides the utility for choosing a suitable PMPlib driver from a number of installed drivers.
 PMPlib export functions for a driver module
 This API defines the interface that a driver module must implement.
 PMPlib miscellaneous routines
 PMPlib miscellaneous routines provide the utility for a driver module.

Defines

#define PMPFOURCC(a, b, c, d)   ((uint32_t)(a) << 24 | (uint32_t)(b) << 16 | (uint32_t)(c) << 8 | (uint32_t)(d))
 Macro to define FourCC representations of codecs.
#define PMPCODEC_NONE   PMPFOURCC(' ',' ',' ',' ')
 Unknown codec.
#define PMPCODEC_MPEGLAYER3   PMPFOURCC('M','P','A','3')
 MPEG Audio Layer III.
#define PMPCODEC_WMA   PMPFOURCC('W','M','A',' ')
 Windows Media Audio.
#define PMPCODEC_VORBIS   PMPFOURCC('O','g','g','V')
 Ogg Vorbis.
#define PMPCODEC_WAV   PMPFOURCC('W','A','V','E')
 Microsoft Riff WAVE.

Typedefs

typedef tag_pmp_t pmp_t
 Synonym of struct tag_pmp_t.
typedef tag_pmp_music_t pmp_music_t
 Synonym of struct tag_pmp_music_t.

Enumerations

enum  {
  PMP_SUCCESS = 0, PMPERR_ERROR = 0x80000000, PMPERR_DEVICENOTFOUND,
  PMPERR_INSUFFICIENTMEMORY, PMPERR_NOTIMPLIMENTED, PMPERR_ENTRYNOTFOUND,
  PMPERR_INCONSISTENCY, PMPERR_OPENFORREAD, PMPERR_OPENFORWRITE,
  PMPERR_READ, PMPERR_WRITE
}
 Status codes. More...
enum  {
  PMPOF_MUSIC_DB_READ = 0x0001, PMPOF_MUSIC_DB_WRITE = 0x0002, PMPOF_MUSIC_PL_READ = 0x0004,
  PMPOF_MUSIC_PL_WRITE = 0x0008
}
 Open flags for portable media device. More...
enum  {
  PMPF_NONE = 0x0000, PMPMF_SUPPORT = 0x0001, PMPMF_RECURSIVE = 0x0002,
  PMPPF_SUPPORT = 0x0010, PMPPF_RECURSIVE = 0x0020
}
 Flags for device functionality. More...

Variables

char pmp_device_description_t::manufacturer [PMP_DECLSIZE]
 Manufacturer (e.g., "iriver").
char pmp_device_description_t::name [PMP_DECLSIZE]
 Model name (e.g., "E10").
char pmp_device_description_t::mode [PMP_DECLSIZE]
 Firmware mode (e.g., "UM").
char pmp_device_description_t::language [PMP_DECLSIZE]
 Firmware default language (e.g., "JP").
char pmp_device_description_t::version [PMP_DECLSIZE]
 Firmware version (e.g., "1.4").
char pmp_device_description_t::min_version [PMP_DECLSIZE]
 Minimum firmware version (e.g., "1.0").
char pmp_device_description_t::max_version [PMP_DECLSIZE]
 Maximum firmware version (e.g., "1.4").
ucs2char_t pmp_device_information_t::path_to_system [MAX_PATH]
 Relative path to the system directory from the root.
ucs2char_t pmp_device_information_t::path_to_music [MAX_PATH]
 Relative path to the music directory from the root.
ucs2char_t pmp_device_information_t::path_to_playlist [MAX_PATH]
 Relative path to the playlist directory from the root.
uint32_t pmp_device_information_t::music_flag
 Music flags.
uint32_t pmp_device_information_t::playlist_flag
 Playlist flags.
uint32_t pmp_device_information_t::num_audio_codecs
 Number of elements in audio_codecs array.
uint32_t * pmp_device_information_t::audio_codecs
 Array of PMPFOURCC values corresponding to the supported audio codecs.
uint32_t pmp_device_information_t::num_audio_extensions
 Number of elements in audio_extensions array.
ucs2char_t ** pmp_device_information_t::audio_extensions
 Array of ucs2char_t string values for audio file extensions.
const pmp_device_description_t pmp_device_information_t::decl
 Description about the device.
uint32_t tag_pmp_t::ref_count
 Reference counter.
uint32_t tag_pmp_t::flag
 Open flags.
pmp_device_information_t tag_pmp_t::info
 PMP device decription.
pmp_music_t * tag_pmp_t::music
 The pointer to pmp_music_t interface.
uint32_t(* tag_pmp_t::add_ref )(pmp_t *pmp)
 Increment the reference counter.
uint32_t(* tag_pmp_t::release )(pmp_t *pmp)
 Decrement the reference counter.
result_t(* tag_pmp_t::open )(pmp_t *pmp, uint32_t flag)
 Open the PMP device.
result_t(* tag_pmp_t::close )(pmp_t *pmp)
 Close the PMP device.
ucs2char_t * tag_pmp_music_record_t::title
 Title name.
ucs2char_t * tag_pmp_music_record_t::artist
 Artist name.
ucs2char_t * tag_pmp_music_record_t::composer
 Composer.
ucs2char_t * tag_pmp_music_record_t::album
 Album name.
ucs2char_t * tag_pmp_music_record_t::genre
 Genre name.
ucs2char_t * tag_pmp_music_record_t::date
 Release date.
uint32_t tag_pmp_music_record_t::codec
 FourCC representation of the codec.
uint32_t tag_pmp_music_record_t::codec_version
 Codec version multiplied by 100.
uint8_t tag_pmp_music_record_t::is_vbr
 VBR flag.
uint32_t tag_pmp_music_record_t::track_number
 Track number.
uint32_t tag_pmp_music_record_t::total_tracks
 Total number of tracks in this disc.
uint32_t tag_pmp_music_record_t::disc_number
 Disc number.
uint32_t tag_pmp_music_record_t::total_discs
 Total number of discs in this series.
uint32_t tag_pmp_music_record_t::sample_rate
 Sample rate in [Hz].
uint32_t tag_pmp_music_record_t::bitrate
 Bitrate in [bps].
uint32_t tag_pmp_music_record_t::duration
 Duration in seconds.
uint64_t tag_pmp_music_record_t::num_samples
 Number of samples.
uint32_t tag_pmp_music_record_t::filesize
 File size in bytes.
uint32_t tag_pmp_music_record_t::ts_update
 Timestamp of the last update of the music file.
uint32_t tag_pmp_music_record_t::rating
 Rating.
uint32_t tag_pmp_music_record_t::play_count
 Play count on the device.
uint32_t tag_pmp_music_record_t::ts_playback
 Timestamp of the recent playback on the device.
uint32_t tag_pmp_music_record_t::ts_import
 timestamp when the track was imported.
int pmp_playlist_t::num_entries
 The number of entries in the playlist.
ucs2char_t ** pmp_playlist_t::entries
 Pointer to an array of entries referring to media files.
pmp_t * tag_pmp_music_t::pmp
 The pointer to pmp_t interface.
result_t(* tag_pmp_music_t::set_records )(pmp_music_t *music, const pmp_music_record_t *records, uint32_t num_records)
 Set a list of music records.
result_t(* tag_pmp_music_t::get_records )(pmp_music_t *music, pmp_music_record_t *records, uint32_t *num_records)
 Get a list of music records.
result_t(* tag_pmp_music_t::set_playlists )(pmp_music_t *music, const pmp_playlist_t *playlists, uint32_t num_playlists)
 Set a list of music playlists.
result_t(* tag_pmp_music_t::get_playlists )(pmp_music_t *music, pmp_playlist_t *playlists, uint32_t *num_playlists)
 Get a list of music playlists.
result_t(* tag_pmp_music_t::dump )(pmp_music_t *music, FILE *fp, int flag)
 Dump the music database.

Detailed Description

The PMPlib APIs define the programing interface for both applications and driver modules.

Define Documentation

#define PMPCODEC_MPEGLAYER3   PMPFOURCC('M','P','A','3')

MPEG Audio Layer III.

Definition at line 131 of file pmp.h.

#define PMPCODEC_NONE   PMPFOURCC(' ',' ',' ',' ')

Unknown codec.

Definition at line 129 of file pmp.h.

#define PMPCODEC_VORBIS   PMPFOURCC('O','g','g','V')

Ogg Vorbis.

Definition at line 135 of file pmp.h.

#define PMPCODEC_WAV   PMPFOURCC('W','A','V','E')

Microsoft Riff WAVE.

Definition at line 137 of file pmp.h.

#define PMPCODEC_WMA   PMPFOURCC('W','M','A',' ')

Windows Media Audio.

Definition at line 133 of file pmp.h.

#define PMPFOURCC ( a,
b,
c,
d   )     ((uint32_t)(a) << 24 | (uint32_t)(b) << 16 | (uint32_t)(c) << 8 | (uint32_t)(d))

Macro to define FourCC representations of codecs.

Definition at line 125 of file pmp.h.

Typedef Documentation

typedef struct tag_pmp_music_t pmp_music_t

Synonym of struct tag_pmp_music_t.

Definition at line 65 of file pmp.h.

typedef struct tag_pmp_t pmp_t

Synonym of struct tag_pmp_t.

Definition at line 61 of file pmp.h.

Enumeration Type Documentation

anonymous enum

Status codes.

Enumerator:
PMP_SUCCESS  Success.
PMPERR_ERROR  Undetermined error.
PMPERR_DEVICENOTFOUND  Device is not found or unsupported.
PMPERR_INSUFFICIENTMEMORY  Insufficient memory.
PMPERR_NOTIMPLIMENTED  Operation is not implemented.
PMPERR_ENTRYNOTFOUND  The entry is not found.
PMPERR_INCONSISTENCY  Inconsistent operation/data.
PMPERR_OPENFORREAD  Error while opening a file for reading.
PMPERR_OPENFORWRITE  Error while opening a file for writing.
PMPERR_READ  Error while reading a file.
PMPERR_WRITE  Error while writing a file.

Definition at line 70 of file pmp.h.

anonymous enum

Open flags for portable media device.

Specify one or more flags to pmp_t::open() member function.

Enumerator:
PMPOF_MUSIC_DB_READ  Read access to the music database.

The member function pmp_t::open() will read the music database.

PMPOF_MUSIC_DB_WRITE  Write access to the music database.

The member function pmp_t::close() will write the music database.

PMPOF_MUSIC_PL_READ  Read access to the music playlists.

The member function pmp_t::open() will read the music playlists.

PMPOF_MUSIC_PL_WRITE  Write access to the music playlists.

The member function pmp_t::close() will write the music playlists.

Definition at line 99 of file pmp.h.

anonymous enum

Flags for device functionality.

Enumerator:
PMPF_NONE  None.
PMPMF_SUPPORT  The device supports music database.
PMPMF_RECURSIVE  The device supports subdirs under music directory.
PMPPF_SUPPORT  The device supports music playlist.
PMPPF_RECURSIVE  The device supports subdirs under playlist directory.

Definition at line 142 of file pmp.h.

Variable Documentation

uint32_t(* tag_pmp_t::add_ref)(pmp_t *pmp) [inherited]

Increment the reference counter.

Parameters:
pmp The pointer to the pmp_t instance.

ucs2char_t* tag_pmp_music_record_t::album [inherited]

Album name.

e.g., "Abbey Road"

Assertions:
 album != NULL

Definition at line 354 of file pmp.h.

ucs2char_t* tag_pmp_music_record_t::artist [inherited]

Artist name.

e.g., "The Beatles"

Assertions:
 artist != NULL

Definition at line 340 of file pmp.h.

uint32_t* pmp_device_information_t::audio_codecs [inherited]

Array of PMPFOURCC values corresponding to the supported audio codecs.

Definition at line 217 of file pmp.h.

ucs2char_t** pmp_device_information_t::audio_extensions [inherited]

Array of ucs2char_t string values for audio file extensions.

Definition at line 222 of file pmp.h.

uint32_t tag_pmp_music_record_t::bitrate [inherited]

Bitrate in [bps].

e.g., 128000

Definition at line 422 of file pmp.h.

result_t(* tag_pmp_t::close)(pmp_t *pmp) [inherited]

Close the PMP device.

Parameters:
pmp The pointer to the pmp_t instance.

uint32_t tag_pmp_music_record_t::codec [inherited]

FourCC representation of the codec.

e.g., PMPCODEC_MPEGLAYER3

Definition at line 374 of file pmp.h.

uint32_t tag_pmp_music_record_t::codec_version [inherited]

Codec version multiplied by 100.

e.g., 100 for MPEG version 1.

Definition at line 380 of file pmp.h.

ucs2char_t* tag_pmp_music_record_t::composer [inherited]

Composer.

e.g., "John Lennon"

Assertions:
 composer != NULL

Definition at line 347 of file pmp.h.

ucs2char_t* tag_pmp_music_record_t::date [inherited]

Release date.

e.g., "1969"

Assertions:
 date != NULL

Definition at line 368 of file pmp.h.

const pmp_device_description_t pmp_device_information_t::decl [inherited]

Description about the device.

Definition at line 225 of file pmp.h.

uint32_t tag_pmp_music_record_t::disc_number [inherited]

Disc number.

e.g., 1

Definition at line 404 of file pmp.h.

result_t(* tag_pmp_music_t::dump)(pmp_music_t *music, FILE *fp, int flag) [inherited]

Dump the music database.

Parameters:
music The pointer to the pmp_music_t interface.
fp The pointer to an output stream.
flag The flags.
Return values:
result_t The status code after this operation.
Assertions: 
 music != NULL

uint32_t tag_pmp_music_record_t::duration [inherited]

Duration in seconds.

e.g., 260

Definition at line 428 of file pmp.h.

ucs2char_t** pmp_playlist_t::entries [inherited]

Pointer to an array of entries referring to media files.

Definition at line 493 of file pmp.h.

uint32_t tag_pmp_music_record_t::filesize [inherited]

File size in bytes.

e.g., 4160000

Definition at line 440 of file pmp.h.

uint32_t tag_pmp_t::flag [inherited]

Open flags.

This member variable is reserved for the library to store the flags specified in open() function. Do not modify the value.

Definition at line 264 of file pmp.h.

ucs2char_t* tag_pmp_music_record_t::genre [inherited]

Genre name.

e.g., "Rock"

Assertions:
 genre != NULL

Definition at line 361 of file pmp.h.

result_t(* tag_pmp_music_t::get_playlists)(pmp_music_t *music, pmp_playlist_t *playlists, uint32_t *num_playlists) [inherited]

Get a list of music playlists.

This function gets the list of music playlists in the device or set by set_playlists call.

If the argument playlists is NULL, this function returns the number of music playlists to the variable whose address is specified by the argument num_playlists. You can use this for determining the size of array playlists necessary to obtain all playlists.

If the argument playlists is not NULL, this function copies the current music playlists to the array whose address is specified by the argument playlists and whose size is specified by the variable pointed by the argument num_playlists.

Parameters:
music The pointer to the pmp_music_t interface.
playlists An array of music playlists.
num_playlists The pointer to the variable presenting the number of elements in playlists array.
Return values:
result_t The status code after this operation.
Assertions: 
 music != NULL 

 num_playlists != NULL

result_t(* tag_pmp_music_t::get_records)(pmp_music_t *music, pmp_music_record_t *records, uint32_t *num_records) [inherited]

Get a list of music records.

This function gets the list of music records in the existing music database or set by set_records call.

If the argument records is NULL, this function returns the number of music records to the variable whose address is specified by the argument num_records. You can use this for determining the size of array records necessary to obtain all records from this function.

If the argument records is not NULL, this function copies the current music records to the array whose address is specified by the argument records and whose size is specified by the variable pointed by the argument num_records.

Parameters:
music The pointer to the pmp_music_t interface.
records An array of music records.
num_records The pointer to the variable presenting the number of elements in records array.
Return values:
result_t The status code after this operation.
Assertions: 
 music != NULL 

 num_records != NULL

pmp_device_information_t tag_pmp_t::info [inherited]

PMP device decription.

Definition at line 269 of file pmp.h.

uint8_t tag_pmp_music_record_t::is_vbr [inherited]

VBR flag.

e.g., 1 for MP3 VBR files.

Definition at line 386 of file pmp.h.

char pmp_device_description_t::language[PMP_DECLSIZE] [inherited]

Firmware default language (e.g., "JP").

Definition at line 186 of file pmp.h.

char pmp_device_description_t::manufacturer[PMP_DECLSIZE] [inherited]

Manufacturer (e.g., "iriver").

Definition at line 180 of file pmp.h.

char pmp_device_description_t::max_version[PMP_DECLSIZE] [inherited]

Maximum firmware version (e.g., "1.4").

Definition at line 192 of file pmp.h.

char pmp_device_description_t::min_version[PMP_DECLSIZE] [inherited]

Minimum firmware version (e.g., "1.0").

Definition at line 190 of file pmp.h.

char pmp_device_description_t::mode[PMP_DECLSIZE] [inherited]

Firmware mode (e.g., "UM").

Definition at line 184 of file pmp.h.

pmp_music_t* tag_pmp_t::music [inherited]

The pointer to pmp_music_t interface.

Definition at line 274 of file pmp.h.

uint32_t pmp_device_information_t::music_flag [inherited]

Music flags.

Definition at line 210 of file pmp.h.

char pmp_device_description_t::name[PMP_DECLSIZE] [inherited]

Model name (e.g., "E10").

Definition at line 182 of file pmp.h.

uint32_t pmp_device_information_t::num_audio_codecs [inherited]

Number of elements in audio_codecs array.

Definition at line 215 of file pmp.h.

uint32_t pmp_device_information_t::num_audio_extensions [inherited]

Number of elements in audio_extensions array.

Definition at line 220 of file pmp.h.

int pmp_playlist_t::num_entries [inherited]

The number of entries in the playlist.

Definition at line 488 of file pmp.h.

uint64_t tag_pmp_music_record_t::num_samples [inherited]

Number of samples.

e.g., 260*44100.

Definition at line 434 of file pmp.h.

result_t(* tag_pmp_t::open)(pmp_t *pmp, uint32_t flag) [inherited]

Open the PMP device.

Parameters:
pmp The pointer to the pmp_t instance.
flag The open flags.

ucs2char_t pmp_device_information_t::path_to_music[MAX_PATH] [inherited]

Relative path to the music directory from the root.

Definition at line 205 of file pmp.h.

ucs2char_t pmp_device_information_t::path_to_playlist[MAX_PATH] [inherited]

Relative path to the playlist directory from the root.

Definition at line 207 of file pmp.h.

ucs2char_t pmp_device_information_t::path_to_system[MAX_PATH] [inherited]

Relative path to the system directory from the root.

Definition at line 203 of file pmp.h.

uint32_t tag_pmp_music_record_t::play_count [inherited]

Play count on the device.

e.g., 23

Definition at line 458 of file pmp.h.

uint32_t pmp_device_information_t::playlist_flag [inherited]

Playlist flags.

Definition at line 212 of file pmp.h.

pmp_t* tag_pmp_music_t::pmp [inherited]

The pointer to pmp_t interface.

Assertions: 
 this->pmp->music == this

Definition at line 525 of file pmp.h.

uint32_t tag_pmp_music_record_t::rating [inherited]

Rating.

e.g., 5

Definition at line 452 of file pmp.h.

uint32_t tag_pmp_t::ref_count [inherited]

Reference counter.

This member variable is reserved for the library to manage the reference counter. Do not modify the value directly. Call member functions add_ref() and release() to increase and decrease the reference counter.

Definition at line 256 of file pmp.h.

uint32_t(* tag_pmp_t::release)(pmp_t *pmp) [inherited]

Decrement the reference counter.

If the reference counter becomes zero after this decrement, this function will destroy the pmp_t instance.

Parameters:
pmp The pointer to the pmp_t instance.

uint32_t tag_pmp_music_record_t::sample_rate [inherited]

Sample rate in [Hz].

e.g., 44100

Definition at line 416 of file pmp.h.

result_t(* tag_pmp_music_t::set_playlists)(pmp_music_t *music, const pmp_playlist_t *playlists, uint32_t num_playlists) [inherited]

Set a list of music playlists.

This function sets a list of music playlists. PMPlib will generate the playlists on the device based on this list.

This function does not write out any content on the player immediately; playlist generation is prolonged until the device is closed by pmp->close() call.

Parameters:
music The pointer to the pmp_music_t interface.
playlists An array of music playlists.
num_playlists The number of elements in playlists array.
Return values:
result_t The status code after this operation.
Assertions: 
 music != NULL 

 playlists != NULL

result_t(* tag_pmp_music_t::set_records)(pmp_music_t *music, const pmp_music_record_t *records, uint32_t num_records) [inherited]

Set a list of music records.

This function sets a list of music records that provide a complete information about all music files on a device. Based on this list, PMPlib will build a music database on the device.

This function does not write out any content on the player immediately for the following reason. Some portable devices manage a music database and playlists separately, but some integrate playlist information into a music database. In the latter case, PMPlib cannot build a music database until a definitive list of playlists is obtained. In order to support various devices in a unified interface, this function reserves a future update of the music database; a database update is prolonged until the device is closed by pmp->close() call.

Parameters:
music The pointer to the pmp_music_t interface.
records An array of music records.
num_records The number of elements in records array.
Return values:
result_t The status code after this operation.
Assertions: 
 music != NULL 

 records != NULL

ucs2char_t* tag_pmp_music_record_t::title [inherited]

Title name.

e.g., "Come Together"

Assertions:
 title != NULL

Definition at line 333 of file pmp.h.

uint32_t tag_pmp_music_record_t::total_discs [inherited]

Total number of discs in this series.

e.g., 2

Definition at line 410 of file pmp.h.

uint32_t tag_pmp_music_record_t::total_tracks [inherited]

Total number of tracks in this disc.

e.g., 12

Definition at line 398 of file pmp.h.

uint32_t tag_pmp_music_record_t::track_number [inherited]

Track number.

e.g., 1

Definition at line 392 of file pmp.h.

uint32_t tag_pmp_music_record_t::ts_import [inherited]

timestamp when the track was imported.

Definition at line 468 of file pmp.h.

uint32_t tag_pmp_music_record_t::ts_playback [inherited]

Timestamp of the recent playback on the device.

Definition at line 463 of file pmp.h.

uint32_t tag_pmp_music_record_t::ts_update [inherited]

Timestamp of the last update of the music file.

The value is equivalent to st.st_mtime after stat(&st, filename);

Definition at line 446 of file pmp.h.

char pmp_device_description_t::version[PMP_DECLSIZE] [inherited]

Firmware version (e.g., "1.4").

Definition at line 188 of file pmp.h.