From 6d0da414bfea35b4370ad820d28d4565521d7b12 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Stenberg?= Date: Tue, 17 Aug 2004 06:54:08 +0000 Subject: [PATCH] Plugin API documentation by Antoine Cellerier git-svn-id: svn://svn.rockbox.org/rockbox/trunk@4998 a1c6a512-1295-4272-9138-f99709370657 --- docs/PLUGIN_API | 911 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 911 insertions(+) create mode 100644 docs/PLUGIN_API diff --git a/docs/PLUGIN_API b/docs/PLUGIN_API new file mode 100644 index 0000000000..634100212d --- /dev/null +++ b/docs/PLUGIN_API @@ -0,0 +1,911 @@ +$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 fprintf(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); + + 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}