PluginSDK.QuickWalktrough

From Shareaza Wiki
Jump to navigation Jump to search

A Quick Walkthrough of Plugin Development (Part I)

In this short quide you will get to know how to create plugins for Shareaza using MS Visual Studio. In the Part I you will learn how to create basic files and setup a project.

In this example we will create a project having Library Builder and Image Services plugins implemented. So, let's go step-by-step:

1. Create a new ATL project (we will call it MyPlugin):

File:Atl project.png

Press OK and VS will open a dialog with options for the project. After that VS will create all files, required for it. We will do some cleaning later...

2. Click on “Application Settings”. We want a .dll file, not attributed. Optionally, you can tick “Support MFC” if you need it. However, binaries having MFC support usually are bigger. We ticked “Allow merging of proxy/stub code”, since we won't use any of such features, and this lets to clean a project more easily. In this example we won't use MFC support, so untick it.

File:Project options.png

3. Now you have all files created by VS. Open “MyPlugin.idl” file. It's an essence of the project. Replace the first 2 lines with the lines shown in the picture below. The second import directive which we removed is not needed, we included ShareazaOM.h file to have all declarations of GUIDs and other stuff available to the project.

File:Idl file.png

4. VS created all required methods to register and unregister .dll file as you can see from Class Viewer. We will review the code later. Double-click each method to view the code.

File:Class view.png

5. Remove all #ifdef _MERGE_PROXYSTUB from the code:

File:Remove proxy stuff 1.png

6. Remove dlldatax files from the project and its include from MyPlugin.cpp. The final list of files for the project is shown in the picture below.

File:Remove proxy stuff 2.png

7. Change project's settings, to have ShareazaOM.h file found by it. The project should compile fine after we point to the path where Shareaza code is located.

File:Shareaza includes.png

8. Now we will create our plugin class. Go to Class Viewer, right-click the project root and select “Add Class...” from the menu. From the dialog select “ATL Simple Object”

File:Add atl object.png

9. After clicking “Open” VS will display a wizard dialog where we will have to setup the class. Enter MyPluginClass in the first box, the rest will be filled in automatically. Replace “ProgID” field value to have the class registered with Shareaza name prefixed

File:Atl object properties 1.png

10. Select the second page in the wizard. We will setup some important options here. If you are implementing ImageServices plugin, it's enough to have “Apartment” selected as a threading model. If you are implementing LibraryBuilder plugin, the threading model has to be “Both”. We will use “Both” since we want to implement both plugins in one (please note: such merged plugins are supported only starting from Shareaza 2.3). To implement IUknown interface you must select “Custom” as an interface type

File:Atl object properties 2.png

11. Return back to “MyPlugin.idl” code, remove or hide the interface "IMyPluginClass" and make "IUnknown" interface as a default

File:Hide or remove default interface.png

12. Now, the most interesting part. We have to implement some interfaces which were defined by Shareaza. In this example we are implementing both Library Builder and Image Services plugins. Go to Class Viewer, right-click on the newly created class (we named it “CMyPluginClass”) and select “Implement Interface...” from the menu.

File:Implement interface 1.png

13. VS will open a dialog where we have to select Shareaza type library, available in Shareaza code. After that it will create all required code for us. Select interfaces which will be implemented (“IImageServicePlugin” and “ILibraryBuilderPlugin”)

File:Implement interface 2.png

14. We need to do some cleaning again. Delete the line containing Shareaza.tlb from StdAfx.h file, included by the wizard. Shareaza.tlb just helped us to implement the interfaces. Also delete the lines displayed in the picture below from “MyPluginClass.h” file. As you can see VS implemented all methods which are available for the selected interfaces. You can move them to “MyPluginClass.cpp” leaving only their prototypes here.

File:Implement interface cleaning.png

15. Open “MyPluginClass.rgs” file. Replace 'MyPluginClass Class' with something more descriptive. This line will be displayed in Shareaza Settings -> Plugins. Add the following script at the end of it: <source lang="c">HKLM {

 NoRemove Software
   {
     Shareaza
       {
         Shareaza
           {
             Plugins
               {
                 ImageService
                    {
                       ForceRemove val '.abc' = s '{E9F51B1E-DB0F-4EEE-9B36-46151994C715}'
                    }
                 LibraryBuilder
                    {
                       ForceRemove val '.abc' = s '{E9F51B1E-DB0F-4EEE-9B36-46151994C715}'
                    }
                }
            }
       }
   }

}</source></small> Change GUID values to the same values which were generated in the first part of the script. This script will register .abc extensions with Shareaza for the metadata extraction and thumbnailing. Compile the project, place any file with .abc extension to the Library and Shareaza will immediately start talking with the plugin. The only thing is that all the methods will return E_NOTIMPL. We will look at the implementation in the "Part II".