docs/PLUGIN_API

$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}