Media Library Plugin

From Winamp Developer Wiki
Jump to: navigation, search

Plugin struct definition <source lang="cpp"> typedef struct {

 int version;
 char *description;
 int (*init)(); // return 0 on success, non-zero for failure (quit WON'T be called) 
 void (*quit)();


 // return NONZERO if you accept this message as yours, otherwise 0 to pass it 
 // to other plugins
 INT_PTR (*MessageProc)(int message_type, INT_PTR param1, INT_PTR param2, INT_PTR param3); 
 //note: INT_PTR becomes 64bit on 64bit compiles...  if you don't like windows types or caps, you can #include <stddef.h> and use intptr_t
 //all the following data is filled in by the library
 HWND hwndWinampParent;
 HWND hwndLibraryParent; // send this any of the WM_ML_IPC messages
 HINSTANCE hDllInstance;

} winampMediaLibraryPlugin; </source>

  • Plugins work by defining a struct full of functions for Winamp to call. For Media Library plugins, there are three functions.
  1. Init - called after your plugin is loaded. We need an Init() function (rather than having the plugin doing init is the winampGetMediaLibraryPlugin function) because Winamp needs to give YOU data before you can really do your initialization stuff
  2. Quit - duh
  3. MessageProc. This is a function that the Winamp calls when certain events happen, such as someone activating your treeview node in the media library, or someone invoking the send-to menu
  • You communicate with Winamp one of two basic ones
  1. By using SendMessage and sending Winamp or the Media Library window custom messages which are defined in Winamp/wa_ipc.h (for Winamp HWND) and gen_ml/ml.h (for Media Libary HWND). This is the "old" way of doing things but even some newer APIs are still built on this mechanism.
  2. By retrieving pointers to objects from the Wasabi Service Manager. Winamp has a bunch of APIs that you can grab, and plugins can add additional features that you might want to use. Examples of useful Wasabi objects are the Local Media API (which lets you query against the media library), the Application API (let's you get version #, build #, path to winamp settings folder, etc), and the Playlist Manager API (lets you parse playlists, among other things)

ml_xmlex is probably the most useful example of the bunch. ml_ stands for media library plugin. __declspec(dllexport) is a magic keyword for Visual C++ that means that the DLL "exports" this function, meaning that a program that loads the DLL can locate and call this function. Winamp goes through and loads ml_*.dll plugins, looks for "winampGetMediaLibraryPlugin" and if it it exists it calls it. From that function you are supposed to return a struct that defines your plugin. It has the plugin name, some function pointers and some data that winamp will populate with information that'll be helpful to you, like winamp's HWND (window handle).

winampMediaLibraryPlugin is defined in gen_ml/ml.h which is one ugly beast of a file benski> reupload to File:WinampMediaLibraryPlugin.png http://shup.com/Shup/57721/10872016431-ml_xmlex-Microsoft-Visual-C__-%5Bdesign%5D-ml.h.png

So you supply "init", "quit" and "MessageProc" functions as well as a description. Winamp calls Init(), at which point ml_xmlex does two things

  1. Gets the all-important Wasabi Service Manager object
  2. tells the media library to add a node to the treeview for itself File:Ml xmlex in ml.png http://shup.com/Shup/57726/10872016155-Main-Window.png

Plugins can manifest themselves in many ways (or be completely invisible!), just this media library plugin is a good starting point because you don't have to write too much busy-work GUI code.

For Media Library plugins, when the media library needs your plugin (e.g. when the user clicked on you in the media library) it calls your message procedure. xmlview.cpp line 147 is the message procedure. this plugin is only handling one message which is to create a view. there are other messages like "do you want to be on the send-to menu" but this example is keeping it simple.