$Id$ __________ __ ___. Open \______ \ ____ ____ | | _\_ |__ _______ ___ Source | _// _ \_/ ___\| |/ /| __ \ / _ \ \/ / Jukebox | | ( <_> ) \___| < | \_\ ( <_> > < < Firmware |____|_ /\____/ \___ >__|_ \|___ /\____/__/\_ \ \/ \/ \/ \/ \/ Plugin API summmary Plugin API Version 26 (backwards compability up to version 25) Info: To get the latest plugin api specs: look at struct plugin_api in apps/plugin.h (and apps/plugins/helloworld.c for an example) Plugin Skeleton =============== #include "plugin.h" static struct plugin_api* rb; //plugin entry point enum plugin_status plugin_start(struct plugin_api* api, void* parameter) { TEST_PLUGIN_API(api); (void)parameter; rb = api; //insert your code here return PLUGIN_OK; } to call a function, use the plugin_api structure this way : rb->function() Plugin Internals ================ int version; Plugin version number. int plugin_test(int api_version, int model, int memsize); This function is called by the TEST_PLUGIN_API() macro to test compability of the plugin with current software. Returns PLUGIN_OK if plugin is supported. Returns PLUGIN_WRONG_API_VERSION if plugin version isn't compatible. Returns PLUGIN_WRONG_MODEL if the model or memsize is wrong. LCD === Generic ------- Most LCD functions are specific for which output we work with, due to the huge differences. void lcd_clear_display(void); Clear the whole display void backlight_on(void); Turn the backlight on void backlight_off(void); Turn the backlight off void splash(int ticks, bool center, char *fmt, ...); Display a formated string in a box durring time ticks. If center is FALSE, the display is left justified. If center is TRUE, the display is centered horizontaly and verticaly. The string is formated as with the printf function. (There are HZ ticks per second) void lcd_puts(int x, int y, const unsigned char *string); Write a string at given character position. void lcd_puts_scroll(int x, int y, unsigned char* string); Print a scrolling string at screen coordinates (x,y). The scrolling style is STYLE_DEFAULT. void lcd_stop_scroll(void); Stop all scrolling lines on the screen. void lcd_set_contrast(int val); Set the screen contrast. Argument val should be a value between MIN_CONTRAST_SETTING and MAX_CONTRAST_SETTING. Recorder -------- All the functions operate on a display buffer. You make the buffer get shown on screen by calling lcd_update(). void lcd_update(void); Update the LCD according to the internal buffer. void lcd_update_rect(int x, int y, int width, int height); Update the given rectangle to the LCD. Give arguments measured in pixels. Notice that the smallest vertical resolution in updates that the hardware supports is even 8 pixels. This function will adjust to those. void lcd_setfont(int font); Set default font struc font* font_get(int font); Return a pointer to an incore font structure. If the requested font isn't loaded/compiled-in, decrement the font number and try again. void lcd_putsxy(int x, int y, const unsigned char *string); Put a string at given coordinates. void lcd_puts_style(int x, int y, const unsigned char *str, int style); Put a string at given coordinates. Intger style can be STYLE_DEFAULT for black text display or STYLE_INVERT for white text display. void lcd_puts_scroll_style(int x, int y, unsigned char* string, int style); Same as lcd_puts_style and scrolling is enabled. {new in plugin API version 26} void lcd_bitmap(const unsigned char *src, int x, int y, int width, int height, bool clear); Put a bitmap at given coordinates. If clear is true, the area is cleared before the bitmap is put. Element src[i] is the binary representation of column number i of the bitmap read from bottom to top. void lcd_clearrect(int x, int y, int width, int height); Clear a rectangle area. void lcd_fillrect(int x, int y, int width, int height); Fill a rectangle area. void lcd_drawrect(int x, int y, int width, int height); Draw a rectangle. void lcd_invertrect(int x, int y, int width, int height); Revert the graphics of the given area. void lcd_drawline(int x1, int y1, int x2, int y2); Draw a line between the coordinates. void lcd_clearline(int x1, int y1, int x2, int y2); Clear a line between two coordinates. void lcd_drawpixel(int x, int y); Draw a pixel on the given coordinate. void lcd_clearpixel(int x, int y); Clear the pixel at the given coordinate. int lcd_getstringsize(const unsigned char *str, int *w, int *h); Get the height and width of string str as it would appear on display. Return value is the width. void scrollbar(int x, int y, int width, int height, int items, int min_shown, int max_shown, int orientation); Print a scroll bar at coordinates (x,y) of size width*height. orientation can be VERTICAL for a vertical scroll bar or anything else for a horizontal scroll bar. Item is the total number of items which the scroll bar refers to, min_show the rank of the first item displayed and max_show the rank of the last displayed item. void checkbox(int x, int y, int width, int height, bool checked); Draw a checkbox area. If checked is TRUE, the checkbox is drawn checked ! void lcd_blit(unsigned char* p_data, int x, int y, int width, int height, int stride); ??? (see firmware/drivers/lcd-recorder.c:168) void lcd_roll(int pixels); Rolls up the lcd display by the specified amount of lines. Lines that are rolled out over the top of the screen are rolled in from the bottom again. This is a hardware remapping only and all operations on the lcd are affected. The screen is rolled up of pixel lines. The value must be between 0 and LCD_HEIGHT. [Not for simulator] Player ------ void lcd_define_pattern(int pat, char *pattern); Define a custom pattern of index pat. char *pattern is a 8x8 pixel bitmap. unsigned char lcd_get_locked_pattern(void); Get a locked pattern index. (see firmware/drivers/lcd-player.c:382) void lcd_unlock_pattern(unsigned char pat); Unlock pattern of index pat. void lcd_putc(int x, int y, unsigned char ch); Put character c at coordinates (x,y). void lcd_put_cursor(int x, int y, char cursor_char); Put cursor at coordinated (x,y). See firmware/export/lcd.h for possible cursor_char values. void lcd_remove_cursor(void); Remove the cursor from the screen. void lcd_icon(int icon, bool enable); ??? (see firmware/drivers/lcd-player.c:463) Buttons ======= These functions work the same regardless of which keypad you have, but they return a different set of values. Note that the Recorder keypad has 10 keys, while the Player keypad only features 6. Possible return values can be found in the firmware/export/button.h file. int button_get(bool block); Returns a bitmask for which keys were pressed. If 'block' is set TRUE it won't return until a key is pressed. int button_get_w_tmo(int ticks); Wait for a key press for ticks ticks. (There are HZ ticks per second) Returns a bitmask for which keys were pressed. If no key was pressed, return BUTTON_NONE. int button_status(void); Returns a bitmask for which keys are currently pressed. void button_clear_queue(void); Empty the button queue. Files ===== (These functions are POSIX look-alikes) int open(const char *pathname, int flags); The open() function establishes the connection between a file and a file descriptor. It creates an open file description that refers to a file and a file descriptor that refers to that open file description. The file descriptor is used by other I/O functions to refer to that file. ssize_t read(int fd, void *buf, size_t count); The read() function attempts to read count bytes from the file associated with the open file descriptor, fd, into the buffer pointed to by buf. off_t lseek(int fd, off_t offset, int whence); The lseek() function sets the file pointer associated with the open file descriptor specified by fd as follows: o If whence is SEEK_SET, the pointer is set to offset bytes. o If whence is SEEK_CUR, the pointer is set to its current location plus offset. o If whence is SEEK_END, the pointer is set to the size of the file plus offset. int creat(const char *pathname, mode_t mode) Create a file with mode O_RDONLY, O_WRONLY or O_RDWR. Returns the file descriptor associated to this file. ssize_t write(int fd, const void *buf, size_t count); Write writes up to count bytes to the file referenced by the file descriptor fd from the buffer starting at buf. int close(int fd); The close() function will deallocate the file descriptor indicated by fd. To deallocate means to make the file descriptor available for return by subsequent calls to open() or other functions that allocate file descriptors. Returns 0 upon success. int rename(const char *path, const char *newname); The rename() function changes the name of a file. The path argument points to the pathname of the file to be renamed. The newname argument points to the new pathname of the file. int remove(const char *pathname); remove() deletes a name from the filesystem. It calls unlink for files, and rmdir for directories. int ftruncate(int fd, off_t length); Truncate file to the specified length. int filesize(int fd); Returns size of a file. Upon error, returns -1. int fdprintf(int fd, const char *fmt, ...); Write a formated string in the fd. Returns the number of characters writen to file. Returns a negative value upon error. int read_line(int fd, char* buffer, int buffer_size); Read (up to) a line of text from fd into buffer and return number of bytes read (which may be larger than the number of bytes stored in buffer). If an error occurs, -1 is returned (and buffer contains whatever could be read). A line is terminated by a LF char. Neither LF nor CR chars are stored in buffer. int settings_parseline(char* line, char** name, char** value); Parse a line from a configuration file. The line format is: name: value Any whitespace before setting name or value (after ':') is ignored. A # as first non-whitespace character discards the whole line. Function sets pointers to null-terminated setting name and value. Returns false if no valid config entry was found int ata_sleep(void) Give the disk some rest. [Not for simulator] Directories =========== DIR *opendir(const char *name); The opendir() function opens a directory stream corresponding to the directory name, and returns a pointer to the directory stream. The stream is positioned at the first entry in the directory. struct dirent *readdir(DIR *dir); The readdir() function returns a pointer to a dirent structure representing the next directory entry in the directory stream pointed to by dir. It returns NULL on reaching the end-of-file or if an error occurred. struct dirent { unsigned char d_name[MAX_PATH]; int attribute; int size; int startcluster; unsigned short wrtdate; /* Last write date */ unsigned short wrttime; /* Last write time */ }; int closedir(DIR *dir); The closedir() function closes the directory stream associated with dir. The directory stream descriptor dir is not available after this call. Kernel ====== void sleep(ticks); Sleep a specified number of ticks, we have HZ ticks per second. void yield(void); Let another thread run. This should be used as soon as you have to "wait" for something or similar, and also if you do anything that takes "a long time". This function is the entire foundation that our "cooperative multitasking" is based on. Use it. void usb_screen(void); Show the usb connection screen. long current_tick; The global tick variable. int default_event_handler(int event); If event == SYS_USB_CONNECTED, call usb_screen and return SYS_USB_CONNECTED. Else do nothing and return 0. int create_thread(void* function, void* stack, int stack_size, const char *name IF_PRIO(int priority) IF_COP(, unsigned int core, bool fallback)); Create a thread. ??? (see firmware/thread.c:145) Return its ID if context area could be allocated, else return -1. void remove_thread(int threadnum); Remove a thread from the scheduler. Parameter is the ID as returned from create_thread(). void reset_poweroff_timer(void); The function name pretty much says what it's supposed to do. String/Memory ============= int strcmp(const char *a, const char *b); strcmp compares the string a to string b. If a sorts lexicographically after b, strcmp returns a number greater than zero. If the two strings match, strcmp returns zero. If a sorts lexicographically before b, strcmp returns a number less than zero. char *strcpy(char *dst, const char *src); strcpy copies the string pointed to by src (including the terminating null character) to the arra pointed to by dst. This function returns the initial value of dst. void *memcpy(void *out, const void *in, size_t length); Copies length bytes of data in memory from source to dest. void *memset(void *dst, int c, size_t length); Fills a memory region with specified byte value. int snprintf(char *buf, size_t size, const char *fmt, ...); Write a formated formated string in buffer buf of size size (including the trailing '\0'). Upon success, return the number of characters printed or that would have been printed if the output was truncated (not including the trailing '\0'). These support %c, %s, %d and %x only with the width and zero padding flag only. char *strncpy(char *dst, const char *src, size_t length); strncpy copies not more than length characters from the string pointed to by src (including the terminating null character) to the array pointed to by dst. If the string pointed to by src is shorter than length characters, null characters are apended to the destination array until a total of length characters have been written. This function returns the initial value of dst. size_t strlen(const char *str); The strlen function works out the length of the string starting at str by counting characters until it reaches a null character. strlen returns the character count. char *strrchr(const char *string, int c); This function finds the last occurence of c (converted to a char) in the string pointed to by string (including the terminating null character). Returns a pointer to the located character, or a null pointer if c does not occur in string. int strcasecmp(const char *s1, const char *s2); The strcasecmp() function compares the two strings s1 and s2, ignoring the case of the characters. It returns an integer less than, equal to, or greater than zero if s1 is found, respectively, to be less than, to match, or be greater than s2. int strncasecmp(const char *s1, const char *s2, size_t n); Like strncasecmp() but only on the first n characters. {new in plugin API version 26} const char *_ctype_; ??? (see firmware/common/ctype.c) [Not for simulator] int atoi(const char *str); The atoi() function converts the initial portion of a string pointed to by str to int. Sound ===== void mpeg_sound_set(int setting, int value); The function mpeg_sound_set() is used to set sound output characteristics. This characterisitic is chosen with the setting argument. Possible settings (and the effective values) are : SOUND_VOLUME 0 <= value <= 100 SOUND_BALANCE (only effective with MAS3587F) -100 <= value <= 100 SOUND_BASS -32 <= value <= 32 SOUND_TREBLE -32 <= value <= 32 SOUND_CHANNEL value : MPEG_SOUND_STEREO MPEG_SOUND_MONO MPEG_SOUND_MONO_LEFT MPEG_SOUND_MONO_RIGHT MPEG_SOUND_STEREO_NARROW MPEG_SOUND_STEREO_WIDE MPEG_SOUND_KARAOKE only available with MAS3587F : SOUND_LOUDNESS 0 <= value <= 17 SOUND_AVC value : 1 : 20ms 2 : 2s 3 : 4s 4 : 8s -1 : off then on other : off SOUND_MDB_STRENGTH 0 <= value <= 127 SOUND_MDB_HARMONICS 0 <= value <= 100 SOUND_MDB_CENTER value : ??? SOUND_MDB_SHAPE value : ??? SOUND_MDB_ENABLE value == 0 : off other : on SOUND_SUPERBASS value == 0 : off other : on void mp3_play_data(unsigned char* start, int size, void (*get_more)(unsigned char** start, int* size)); Plays a chunk of an mp3 file. start points to the begining of the file to play. size is the size to play. getmore is a callback function. ??? (see firmware/mp3_playback.c:1062) [Not for simulator] void mp3_play_pause(bool play); If playback was paused and play is TRUE, resume playback. If playback isn't paused and play is FALSE, pause playback. [Not for simulator] void mp3_play_stop(void); Stop playback. [Not for simulator] bool mp3_is_playing(void); Return true if an mp3 is playing, else return false. Note : a paused mp3 is considered as a playing mp3. [Not for simulator] void bitswap(unsigned char *data, int length); Swap the bits for each element of array data of size length. [Not for simulator] Playback Control ================ void mpeg_play(int offset); Start playback. ??? what does offset do (see firmware/mpeg.c:2459) void mpeg_stop(void); Stop playback. void mpeg_pause(void); Pause playback. void mpeg_resume(void); Resume playback. void mpeg_next(void); Play the next item in playlist. void mpeg_prev(void); Play the previous item in playlist. void mpeg_ff_rewind(int newtime); Change playback time. Has no effect in simulator. struct mp3entry *mpeg_next_track(void); Return info about the next track. struct mp3entry is defined in file firmware/export/id3.h int playlist_amount(void); Returns the number of tracks in current playlist. int mpeg_status(void); Returns a bitmask about current mpeg stream status. Possibilities are : MPEG_STATUS_PLAY MPEG_STATUS_PAUSE MPEG_STATUS_RECORD [MAS3587F only] MPEG_STATUS_PRERECORD [MAS3587F only] MPEG_STATUS_ERROR bool mpeg_has_changed_track(void); Returns true if track has changed since last call of this function. Else returns false. struct mp3entry *mpeg_current_track(void); Return info about current track struct mp3entry is defined in file firmware/export/id3.h MAS communication ================= [Not for simulator] int mas_readmem(int bank, int addr, unsigned long* dest, int len); ??? int mas_writemem(int bank, int addr, unsigned long* src, int len); ??? int mas_readreg(int reg); ??? int mas_writereg(int reg, unsigned int val); ??? int mas_codec_writereg(int reg, unsigned int val); ??? [MAS3587F only] int mas_codec_readreg(int reg); ??? [MAS3587F only] Misc ==== void srand(unsigned int seed); Seed the random number generator. int rand(void); Return a pseudo random number between 0 and 0x7fffffff. void qsort(void *base, size_t nmemb, size_t size, int(*compar)(const void *, const void *)); qsort sorts an array (begining at base) of nmemb objects, size describes the size of each element of the array. You must supply a pointer to a comparison function, using the argument shown as compar. (This permits the sorting objects of unknown properties.) Define the comparison function to accept two arguments, each a pointer to an element of the array starting at base. The result of (*compar) must be negative if the first argument is less than the second, zero if the two arguments match, and positive if the first argument is greater than the second (chere ``less than'' and ``greter than'' refer to whatever arbitrary ordering is appropriate). The arra is sorted in place; that is, when qsort returns, the array elements begining at base have been reordered. int kbd_input(char *buffer, int buflen); Prompt for a string to be stored in buffer which is of length buflen. Return FALSE upon success. struct tm *get_time(void); Return current time. struct tm { int tm_sec; int tm_min; int tm_hour; int tm_mday; int tm_mon; int tm_year; int tm_wday; int tm_yday; int tm_isdst; }; int set_time(struct tm *tm); Set current time. Return FALSE upon success. (see get_time() for a description of struct tm) void *plugin_get_buffer(int *buffer_size); Returns a pointer to the portion of the plugin buffer that is not already being used. If no plugin is loaded, returns the entire plugin buffer. Upon return, *buffer_size is the memory size left in plugin buffer. void *plugin_get_mp3_buffer(int *buffer_size); Returns a pointer to the mp3 buffer. Playback gets stopped to avoid conflicts. int plugin_register_timer(int cycles, int prio, void (*timer_callback)(void)); Register a periodic time callbeck, called every 'cycles' CPU clocks. Note that this function will be called in interrupt context! [Not for simulator] void plugin_unregister_timer(void); Disable the user timer. [Not for simulator] void plugin_tsr(void (*exit_callback)(void)); The plugin wants to stay resdent after leaving its main function, e.g. runs from timer or own thread. The callback is registered to later instruct it to free its resources before a new plugin gets loaded. void debugf(char *fmt, ...); Debug output in formated string format. [Simulator or debug only] struct user_settings *global_settings; Access to rockbox's settings. struct user_settings is defined in apps/settings.h void backlight_set_timeout(int index); Set the backlight timeout. index possible values : 0 : backlight always off 1 : no time out 2 : 1s 3 : 2s 4 : 3s 5 : 4s 6 : 5s 7 : 6s 8 : 7s 9 : 8s 10 : 9s 11 : 10s 12 : 15s 13 : 20s 14 : 25s 15 : 30s 16 : 45s 17 : 60s 18 : 90s other : backlight always off bool mp3info(mp3entry *entry, char *filename); Return FALSE if successful. The given mp3entry is then filled in with whatever id3 info it could find about the given file. struct mp3entry is defined in file firmware/export/id3.h int count_mp3_frames(int fd, int startpos, int filesize, void (*progressfunc)(int)); ??? (see firmware/mp3data.c:531) something related to VBR files int create_xing_header(int fd, int startpos, int filesize, unsigned char *buf, int num_frames, unsigned long header_template, void (*progressfunc)(int), bool generate_toc); ??? (see firmware/mp3data.c:593) int battery_level(void); Returns battery level in percent. On the simulator, battery_level always returns 75. void mpeg_set_pitch(int pitch); Change the pitch of audio playback. pitch is given in tenths of percent. [MAS3587F only] {new in plugin API version 26} unsigned short peak_meter_scale_value(unsigned short val, int meterwidth); Scales a peak value as read from the MAS to the range of meterwidth. The scaling is performed according to the scaling method (dBfs / linear) and the range (peak_meter_range_min .. peak_meter_range_max). unsigned short val is the volume value. Range: 0 <= val < MAX_PEAK int meterwidht is the widht of the meter in pixel Returns an a value between 0 and meterwidth [MAS3587F only] {new in plugin API version 26} void peak_meter_set_use_dbfs(int use); Specifies wether the values displayed are scaled as dBfs or as linear percent values. If use is 0 use linear percent scale, else use dBfs. [MAS3587F only] {new in plugin API version 26} int peak_meter_get_use_dbfs(void); Returns 1 if the meter currently is displaying dBfs values, 0 if the meter is displaying percent values. [MAS3587F only] {new in plugin API version 26} void mpeg_flush_and_reload_tracks(void); ??? Flush the mpeg buffer and reload data ??? (see firmware/mpeg.c:2597) (has no effect on simulator) {new in plugin API version 26} int mpeg_get_file_pos(void); ??? Returns the current cursor position in mpeg file ??? (see firmware/mpeg.c:260) {new in plugin API version 26} unsigned long find_next_frame(int fd, int *offset, int max_offset, unsigned long last_header); ??? (see firmware/mp3data.c:262) {new in plugin API version 26} unsigned long mpeg_get_last_header(void); ??? (see firmware/mpeg.c:320) {new in plugin API version 26}