NCSwitch Plugin developer's manual

This document offers essential information about NCSwitch Plugin development.

"NCSwitch Plugin" is a program module that extends NCSwitch features. It enables to save and restore various setting items that NCSwitch built-in functions cannot restore.

The following figure explains about structures and roles of NCSwitch Plugin.

Before you start developing a custom plugin, You should consider following:

• Programing language

  Particularly, if you will distribute your custom plugin to other parties, you should check out system requirements of your plugin (Visual Basic runtime, .NET Framework, and so on).

• How to save and restore settings

  You should check out something, such as API specification (Win32 API or others) that is used for implementing, how to call external commands, formats of configuration data, and so on.

• Whether your plugin needs user input or not.

  You have to develop a GUI window prompting a user during restoring process if the plugin needs user inputs. A GUI window is implemented as a property page (IPropertyPage interface). (ref.API specification − IPlugin::Initialize)

1. Create a COM dll contains a class implementing IPlugin.

   IPlugin implementation sample

   // PluginImpl.h : CPluginImpl declaration #pragma once //A header file auto generated from SpiralwarePower.idl by MIDL compiler. #include "SpiralwarePower.h" // Import NCSwitch type library #import "libid:FEEE0494-3BCC-4C6F-AE1B-89D796F46922" raw_interfaces_only, raw_native_types, named_guids // CPluginImpl - implementing IPlugin interface class ATL_NO_VTABLE CPluginImpl :     public CComObjectRootEx<CComSingleThreadModel>,     public CComCoClass<CPluginImpl, &CLSID_PluginImpl>,     public NCSwitchLib::IPlugin { public:     CPluginImpl()     {     }     DECLARE_REGISTRY_RESOURCEID(IDR_PLUGINIMPL)     BEGIN_COM_MAP(CPluginImpl)         COM_INTERFACE_ENTRY(IPlugin)     END_COM_MAP()     DECLARE_PROTECT_FINAL_CONSTRUCT()     HRESULT FinalConstruct()     {         return S_OK;     }     void FinalRelease()     {     } public:     // IPlugin Methods     STDMETHOD(Initialize)(NCSwitchLib::IPluginSite * site)     { ///Hold object references sent by NCSwitch into instance variables.         m_spPluginSite = site;         m_spPluginSite->get_Parameter(&m_spParameter);         m_spPluginSite->get_Configuration(&m_spConfiguration); // Register IPropertyPage object if this plugin needs user inputs.         // CComPtr<IPropertyPage> spPage;         // spPage.CoCreateInstance(_T("XXX.XXX"));         //         // CComPtr<NCSwitchLib::IPluginPages> spPages;         // m_spPluginSite->get_PluginPages(&spPages);         // spPages->Add(spPage);         return S_OK;     }     STDMETHOD(GetSystemConfiguration)(long * result)     { //Get current power settings of OS         CString sPowerSchemeId = this->GetActivePwrScheme();                  if (! sPowerSchemeId.IsEmpty())         { //Succeeded             *result = 1; //Send values to NCSwitch.             m_spConfiguration->put_Item(CComBSTR(_T("PowerSchemeId")), CComBSTR(sPowerSchemeId));         }         else         { //Failed             *result = 0;         }                  return S_OK;     }     STDMETHOD(SetSystemConfiguration)(long * result)     {         USES_CONVERSION; //Hold values that are read in GetSystemConfiguration into variables.         CComBSTR bsId;         m_spConfiguration->get_Item(CComBSTR(_T("PowerSchemeId")), &bsId); //Apply power settings of OS.         if (this->SetActivePwrScheme(OLE2T(bsId)))         { //Succeeded (need no reboot)             *result = 1;         }         else         { //Failed             *result = 0;         }         return S_OK;     } private:     CString GetActivePwrScheme();     bool SetActivePwrScheme(LPCTSTR pszSchemeId);     CComPtr<NCSwitchLib::IPluginSite> m_spPluginSite;     CComPtr<NCSwitchLib::IDictionary> m_spConfiguration;     CComPtr<NCSwitchLib::IDictionary> m_spParameter; }; OBJECT_ENTRY_AUTO(__uuidof(PluginImpl), CPluginImpl)

2. Create plugin.xml file based on plugin.xml format

   plugin.xml sample

   <?xml version="1.0" encoding="Shift_JIS" ?> <NCSwitchPlugin name="Power Options"  description="Switch active power scheme"     support="support@spiralware.jp">   <Module codeBase="Spiralware.Power.dll" classId="{7B2F451A-6DC3-4175-A22D-F85E6295ACED}">   </Module> </NCSwitchPlugin>

   There is a custom plugin sample at "Spiralware.Power" directory that is located at plugin root directory. (Visual C++ 2005 project)

1. Develop NCSwitch Plugin (ref. Sort of NCSwitch Plugin )
2. Locate your NCSwitch Plugin at "plugins" directory (ref. Organization of files).
3. Start NCSwitch Wizard and proceed saving procedure.
   

   "Setting items" page will show you your NCSwitch Plugin into the item list.
   

   If not, your NCSwitch Plugin has any trouble. Possible reasons are below:

   • Plugin.xml has been invalid XML format.
     

     If you open this plugin.xml with Internet Explorer, invalid location will be shown. Correct it.
     

   • Your IPlugin object fails to be created (only custom plugin)

     NCSwitch cannot find the class definition of your IPlugin object because "codeBase" or "classId" of "Module" element 's attributes have been wrong. As the result of it, your IPlugin object fails to be created. Correct values of these attributes.

     NCSwitch cannot create your IPlugin object because IPlugin::Initialize method call has failed. Debug source code of your IPlugin class.

4. Confirm saved settings.
   

   After you have saved your configurations, a shortcut created by NCSwitch will be on your desktop. There is config.xml path written in property page of the shortcut.
   

   

   To read config.xml, you can check out the contents of saved settings. Confirm their values are same as you expected.
   

1. Double click the shortcut created at Testing for saving function in order to start restoring procedure.

   A status window shows you a restoring plan and indicates results of restoring processes in real time.

NCSwitch Plugin consists of following files: After you have copied a directory containing these files into "plugins" directory, NCSwitch will load it at startup. (No COM registration into Windows registry needs.)

NCSwitch Plugin API is based on COM specification.