home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 10 / AU_CD10.iso / Updates / AMP / !Amp / Docs / PluginSpec < prev    next >
Text File  |  2000-05-14  |  6KB  |  178 lines
  1. Plug-in Protocol
  2. ----------------
  3.  
  4. The !Amp plug-in protocol is fairly simple. It works by using the "pollword
  5. non-zero" feature of the Wimp_Poll SWI. However, if your plugin is fairly
  6. simple, you don't even need to know this much. You can just use the supplied
  7. library (assuming you're writing in BASIC, otherwise you'll have to write
  8. your own library).
  9.  
  10. If in doubt about any of the following information, take a look at on of the
  11. existing plugins to see how it works!
  12.  
  13.  
  14. Using the library
  15. -----------------
  16.  
  17. If you want to use the library, simply have the following line at or near the
  18. start of your program:
  19.  
  20.  LIBRARY"<Amp$PluginDir>.Library.BASIC"
  21.  
  22. The next thing to do is to load any modules you might need (from
  23. <Amp$ModuleDir>) and then call PROCinit. If you pass TRUE as a parameter,
  24. "Wimp_Initialise" will automatically be called, otherwise you'll have to call
  25. it yourself. 
  26.  
  27. If you wish to support a specific version of the protocol, you can tell the
  28. library by calling PROCversion. This takes the version supported and the
  29. major filetype of the plugin. Valid versions are currently:
  30.  
  31.  (0) version_basic%    -    minumum plugin protocol
  32.  (1) version_info%    -    supports info window
  33.  (2) version_config%    -    supports config protocol
  34.  
  35. If you pass a major filetype which is not -1 then templates will
  36. automatically be loaded from !Amp.Plug-ins.Templates.<territory>.<filetype>
  37. The window "fileinfo" will be created with window handle plugin_infoh% and
  38. the window "config" will be created with window handle plugin_configh%. If
  39. you're not supporting the config protocol, simply copy the config window from
  40. the "default" template file.
  41.  
  42. Once you've done all the set up you need, simply call PROCpoll and the rest
  43. of your code will be called as needed. There are various procedures you'll
  44. need to add. This is a list of the ones required for version_basic%:
  45.  
  46.  DEFPROCmessage(pollblock%)
  47.    Called when a wimp user message is received. Passed the wimp poll block.
  48.    
  49.  DEFFNtime(RETURN min%, RETURN sec%, RETURN base%)
  50.    Called to get the current song position. You'll need to set the min%, sec%
  51.    and base% variables. (base% is how many secs there are in a min). You'll
  52.    also need to return a value. This can be ipc_time% if everything's ok,
  53.    ipc_stop% if the song is finished, ipc_pause% if the song has been paused,
  54.    or ipc_none% if the song is still paused.
  55.    
  56.  DEFPROCpause(pause%)
  57.    Called to pause/unpause the song. pause% is TRUE or FALSE.
  58.    
  59.  DEFFNload
  60.    Called to load a new song. You should try to load the file
  61.    "<Amp$SongName>" and return TRUE or FALSE as an indication of success.
  62.    
  63.  DEFPROCstop
  64.    Called to stop a song.
  65.    
  66.  DEFPROCvolume(volume%,balance%)
  67.    Called to set the volume/balance. 
  68.    volume% is 0 to 27, balance% is -127 to +127
  69.    
  70.  DEFPROCsongInfo(RETURN length%, RETURN songname$, RETURN stereo%, RETURN
  71. kbps$, RETURN khz$)
  72.    Called to get the song information. You'll need to return the length (in
  73.    whatever you're using for secs), the songname, TRUE/FALSE for stereo% and
  74.    values to display in the kbps and kHz fields.
  75.    
  76.  DEFPROCjumpto(min%,sec%)
  77.    Called to set the song position to min%:sec%
  78.    
  79. If you passed version_info% (or later) as the version supported, you'll also
  80. need to write the following:
  81.  
  82.  DEFPROCinfoWindow
  83.    Called to open the infoWindow. You should call "Wimp_GetPointerInfo" to
  84.    work out where you should open it, and you should open it with
  85.    "Wimp_CreateMenu" rather than "Wimp_OpenWindow"
  86.    
  87.  DEFPROCeject
  88.    Called when the eject button on the frontend is pressed. Most plugins just
  89.    return without doing anything.
  90.    
  91. If you passed version_config% (or later) as the version supported, you'll
  92. also need to write the following:
  93.  
  94.   DEFPROCconfigok
  95.     Called when the ok button is pressed in the config window - you should
  96.     read the state of the window and update options as appropriate.
  97.     
  98.   DEFPROCconfigcancel
  99.     Called when the cancel button is pressed in the config window - you
  100.     should update the window with the current options. This is also called
  101.     just before the window is opened, to ensure it contains correct
  102.     information.
  103.     
  104.   DEFPROCconfigsave
  105.     Called to save the current config. You should save the options as they
  106.     are currently. If it was due to the save button in the config window,
  107.     PROCconfigok will be called first to ensure the options are set as they
  108.     are displayed in the window.
  109.     
  110. Finally, if you want to update the song information at any time, you can call
  111. PROCsendinfo with the details:
  112.  
  113.  PROCsendinfo(length%,songname$,stereo%,kbps$,khz$)
  114.  
  115.  
  116. More technical information
  117. --------------------------
  118.  
  119. If you want to write a plugin without using the library or in C or some other
  120. language, it's perfectly possible. The only info you need is the format of
  121. the pollword block. When your task is started, you should read the value of
  122. <Amp$Pollword> - this gives you the memory address of the ipc block. The
  123. format of it is like this (c syntax):
  124.  
  125.   typedef enum {false=0,true=~false} Boolean;
  126.   
  127.   typedef enum 
  128.   {
  129.     IPC_NONE,
  130.     IPC_TIME,
  131.     IPC_PAUSE,
  132.     IPC_STOP,
  133.     IPC_LOAD,
  134.     IPC_VOLUME,
  135.     IPC_SONG_INFO,
  136.     IPC_PLUGIN_INFO,
  137.     IPC_REPEAT,
  138.     IPC_JUMPTO,
  139.     IPC_PLAYING,
  140.     IPC_NEXT,
  141.     IPC_PREV,
  142.     IPC_EJECT,
  143.     IPC_INFOWIN,
  144.     IPC_CONFIG,
  145.     IPC_CONFIGCANCEL,
  146.     IPC_CONFIGSAVE,
  147.     IPC_CONFIGOK
  148.    } Ipc;
  149.  
  150.   typedef struct
  151.   {
  152.     char kbps[8];
  153.     char khz[4];
  154.     Boolean stereo;
  155.     int length;
  156.     char name[128]; 
  157.   } SongInfo;
  158.     
  159.   typedef struct
  160.   {
  161.     Ipc request; /* What you're being asked for */
  162.     Ipc supply;  /* What you're supplying */
  163.     union
  164.     {
  165.       struct { int min,sec,base,type; } time;
  166.       struct { int paused; } pause;
  167.       struct { int stop; } stop;
  168.       struct { int success; } load;
  169.       struct { int volume,balance; } volume;
  170.       SongInfo songInfo;
  171.       struct { int dummy; } pluginInfo;
  172.       struct { int repeat; } repeat;
  173.       struct { int min,sec; } jumpto;
  174.       struct { int type; } playing;
  175.       struct { int parent; } config;
  176.     } data; 
  177.   } IpcBlock;
  178.