Basic Plugin Guide - Tutorial - Revision history

SMonty: /* Another API call */

2009-08-07T15:56:14Z

‎Another API call

SMonty: /* Adding another API */

2009-08-07T15:49:08Z

‎Adding another API

SMonty: /* Adding another API */

2009-08-07T15:47:07Z

‎Adding another API

SMonty: /* Examining the Code */

2009-08-07T15:41:36Z

‎Examining the Code

SMonty: /* Calling an API Method */

2009-08-07T15:37:21Z

‎Calling an API Method

SMonty: /* Calling an API Method */

2009-08-07T15:35:07Z

‎Calling an API Method

SMonty: /* wa_ipc.h */

2009-08-07T15:34:09Z

‎wa_ipc.h

SMonty: /* Accessing information from Winamp */

2009-08-07T15:30:32Z

‎Accessing information from Winamp

Gistbane: /* Another API call */

2009-07-13T22:19:59Z

‎Another API call

Gistbane: /* wa_ipc.h */

2009-07-13T22:12:14Z

‎wa_ipc.h

@@ Line 88: / Line 88: @@
 SendMessage(plugin.hwndParent,WM_WA_IPC,(WPARAM)&eFWMS,IPC_ENQUEUEFILE);
 </source>
-You can use a real filename if you have one.  The title and length fields are only used by Winamp in the Winamp playlist until the file is actually played, then Winamp will look inside the file for the real title and length.
+You can use a real filename if you have one.  The title and length fields are only used by Winamp in the Winamp playlist until the file is actually played. At that point Winamp will look inside the file for the real title and length.
-This example shows how to use that WPARAM thingy (thingy is a technical term).  In this method the WPARAM gives Winamp information to use along with the request, in this case the filename and path, a title and length.  This method will Enqueue the file to be played at the bottom of the Winamp playlist.
+This example shows how to use that WPARAM thingy (thingy is a technical term).  In this method the WPARAM gives Winamp information to use along with the request, in this case a pointer to a structure.  The enqueueFileWithMetaStruct structure is defined in WA_IPC.h.  The structure contains the path and filename, a title and the length of the song in seconds.  This method will Enqueue the file to be played at the bottom of the Winamp playlist.
-Compile, copy, restart Winamp and configure your plugin. After four message boxes (less if you became fed up with them all and removed some), you will notice that the specified file has been added to the Winamp Playlist with the specified title and length.  Note, that if the file does not actually exist, Winamp will simply skip over it when you try and play it.
+Compile, copy, restart Winamp and configure your plugin. After four message boxes (less if you became fed up with them and removed some), you will notice that the specified file has been added to the Winamp Playlist with the specified title and length.  Note, that if the file does not actually exist, Winamp will simply skip over it when you try and play it.
 ===What's in a UI===
 Now that I think I've gotten the point across let's get rid of those Message Boxes and create some real UI.  The first thing we need to....hmmm, footsteps....gotta go....talk about this next time.

@@ Line 77: / Line 77: @@
 MessageBox(plugin.hwndParent,msg,L"Winamp Version 3", MB_OK);
 </source>
-See it works.  Notice the '%S' in wsprintf.  "%S" says the input value is an ANSI string and wsprintf can handle it correctly to create the string used in the MessageBox (since UNICODE is defined for this project).
+See it works.  Notice the "%S" (upper case S) in wsprintf this time rather than "%s" (lower case s).  "%S" says the input value is an ANSI string and wsprintf can handle it correctly to create the string used in the MessageBox (since UNICODE is defined for this project MessageBox will invoke MessageBoxW).
 ===Another API call===

@@ Line 68: / Line 68: @@
 MessageBoxA(NULL,winampVersion,"Winamp Version 2",MB_OK);
 </source>
-The SendMessage in this code is requesting a string version of the Winamp executable.  It will return a char * to a string such as '5.57 build 2514 Beta'.  This is useful for displaying the version and build number, such as in the Help->About dialog.
+The SendMessage in this code is requesting a string containing the version of the Winamp executable.  It will return a char * to a string such as '5.57 build 2514 Beta'.  This is useful for fields such as in the Help->About dialog.
-The next line invokes the Windows MessageBoxA API to display a ANSI string.  I meant to do that. No, no, I really did.  I wanted to point out that some Winamp 2 API methods return simple char pointers not wchar_t pointers.  This means that there may be some conversion required before using strings.  Just in case, the "A" on the end of the method is a specialized version of MessageBox that takes ANSI strings rather than UNICODE strings.
+The next line invokes the Windows MessageBoxA API to display an ANSI string.  I meant to do that. No, no, I really did.  I wanted to point out that some Winamp 2 API methods return simple char pointers not wchar_t pointers.  This means that there may be some conversion required before using strings.  Just in case, the "A" on the end of the method is a specialized version of MessageBox that takes ANSI strings rather than UNICODE strings.  The UNICODE version would have a "W" on the end.  Versions with neither actually depend on whether the preprocessor directive UNICODE is defined (a setting in the project).
 Replace the line with the call to MessageBoxA with the following:
@@ Line 77: / Line 77: @@
 MessageBox(plugin.hwndParent,msg,L"Winamp Version 3", MB_OK);
 </source>
-See it works.  Notice the '%S' in wsprintf.  "%S" says the input value is an ANSI string and wsprintf can handle it correctly.
+See it works.  Notice the '%S' in wsprintf.  "%S" says the input value is an ANSI string and wsprintf can handle it correctly to create the string used in the MessageBox (since UNICODE is defined for this project).
 ===Another API call===

@@ Line 47: / Line 47: @@
 The second line uses Windows SendMessage API to send a message, WM_WA_IPC (second parameter), in this case to plugin.hwndParent (first parameter).  WM_WA_IPC indicates a message that Winamp is supposed to handle rather than Windows itself.  The third parameter is usually used to pass a parameter (known as a WPARAM in Windows) and is set to 0.  The fourth parameter (known as an LPARAM in Windows) is a constant that identifies what we want Winamp to do for us, in this case 'get me the version of winamp'.
-But 'Hold on Thar Partner' you might be saying.  Where did that plugin.hwndParent come from?  We didn't set it in our plug-in.  Turns out that Winamp stored the handle to its main window into the plugin structure when it loaded it.  Notice the method used to retrieve the plugin (winampGetGeneralPurposePlugin) actually returns a reference to the plugin?  Cool huh, Winamp can then load the hwndParent and hDllInstance and it becomes available to the plug-in.  The point is that we are sending messages to the Winamp main window so that it can give us the info we're looking for.
+But 'Hold on Thar Partner' you might be saying.  Where did that plugin.hwndParent come from?  We didn't set it in our plug-in.  Turns out that Winamp stored the handle to its main window into the plugin structure when it loaded it.  Notice the method winampGetGeneralPurposePlugin(), it is called by Winamp to retrieve the plugin.  This method actually returns a reference to the plugin.  Cool huh?  Winamp can then load the hwndParent and hDllInstance and it becomes available to the plug-in.  The point is that we are sending messages to the Winamp main window so that it can give us the info we're looking for.
 The next two lines use macros defined in WA_IPC.h to break apart the version into major and minor numbers.  Another useful feature when you need to know the version of Winamp to determine whether a feature is supported.
 The rest of the new lines format a wide string (wsprintf) so we can use it in MessageBox to print it to the screen.
 ===Examining the wa_ipc.h file===
 How did I know what to use for WPARAM and LPARAM?  Well the wa_ipc.h file of course.  Go ahead and open it in Visual Studio.  The first thing you'll notice is blocks of comments.  Blocks of comments?  OH YEAH.  Let's just look at the comments for five minutes, I'll wait......Seriously, if you scroll down in this file you'll see the Winamp 2 API methods.  Searching for IPC_GETVERSION will take you right to the description of how the method works.

@@ Line 40: / Line 40: @@
 </source>
-Compile the plugin and move the dll over into the Winamp plug-ins directory (make sure to exit Winamp before trying to copy the dll, Windows can be so possessive.)  Start Winamp.  After Winamp starts and you see the message about the 'init' being called, 'configure' the plugin and you should see the 'config' event message, press OK.  If you've done everything correctly you should now see the version message box appear.
+Compile the plugin and move the dll over into the Winamp plug-ins directory (make sure to exit Winamp before trying to copy the dll, Windows can be so possessive.)  Start Winamp.  The first thing you should see is the message about 'init' being called. 'Configure' the plugin and you should see the 'config' event message, press OK.  If you've done everything correctly you should now see the version message box appear.
 ===Examining the Code===

@@ Line 21: / Line 21: @@
 ===Calling an API Method===
-Hmmm, what should we do....How about we get the version of Winamp that is currently running?  Sounds like a useful thing for a plug-in to do.  Place the following code into the 'config' method, immediately under the MessageBox about the config event.
+Hmmm, what should we do....What to do?....I know.  How about we get the version of Winamp that is currently running?  Sounds like a useful thing for a plug-in to do.  Place the following code into the 'config' method, immediately under the MessageBox about the config event.
 <source lang="cpp">

@@ Line 18: / Line 18: @@
 </source>
-But wait! This isn't enough.  There's always a catch.  The compiler has no idea where to find wa_ipc.h.  So we have to tell it.  Navigate to Project->gen_myplugin Properties->Configuration Properties->C/C++->General and enter the path to the Winamp directory under the base directory where you installed the Winamp SDK.  Now Visual studio should be able to find the header.
+But wait! This isn't enough.  There's always a catch.  The compiler has no idea where to find wa_ipc.h.  So we have to tell it.  So, in Visual Studio, navigate to Project->gen_myplugin Properties->Configuration Properties->C/C++->General and enter the path to the Winamp subdirectory under the directory where you installed the Winamp SDK.  Now Visual studio should be able to find the header.
 ===Calling an API Method===

@@ Line 1: / Line 1: @@
 ==Accessing information from Winamp==
-Our first page [[Beginner's Basic Plugin Guide]] showed you how to create a general plugin dll that will be invoked by Winamp when it is loaded, configured and quit.  While this is really cool, it lacks something.  Let's fix that now.
+Our first page [[Beginner's Basic Plugin Guide]] showed you how to create a general plugin dll that will be invoked by Winamp when it is loaded, configured and quit.  While this is really cool, it lacks something.  Maybe it needs to do something.  Let's fix that now.
 ===Keeping it simple===

@@ Line 85: / Line 85: @@
 eFWMS.title = "Test It Good";
 eFWMS.length = 300;
-SendMessage(plugin.hwndParent,WM_WA_IPC,(WPARAM)&eFWMS,IPC_ENQUUEFILE);
+SendMessage(plugin.hwndParent,WM_WA_IPC,(WPARAM)&eFWMS,IPC_ENQUEUEFILE);
 </source>
 You can use a real filename if you have one.  The title and length fields are only used by Winamp in the Winamp playlist until the file is actually played, then Winamp will look inside the file for the real title and length.

@@ Line 12: / Line 12: @@
 The top secret, knows everything, key to the executive washroom file is called wa_ipc.h.  This file defines constants for all of the Winamp 2 API methods that are made available for external developers.  And they are fairly well documented (gasp).  Yes, I know this sounds impossible, when do developers actually write documentation?  Well trust me this file is very well documented so it does happen.
-This header can be found in the SDK under the Winamp SDK\Winamp directory.  Add these two lines to the top of gen_myplugin.cpp:
+This header can be found in the SDK under the Winamp SDK\Winamp directory.  Add these two lines to the top of gen_myplugin.cpp, beneath the existing includes:
 <source lang="cpp">
 #include "wa_ipc.h"