NCSwitchプラグイン 開発ドキュメント

このドキュメントでは、NCSwitchプラグインの開発者を対象に、NCSwitchプラグイン開発に必要な情報を提供します。

NCSwitchプラグインとは、NCSwitchがサポートしていないシステム設定の保存／復元を可能にする、拡張プログラムです。

以下の図は、NCSwitchプラグインの仕組み・役割について説明しています。

カスタムプラグインの開発に取り掛かる前に、以下の点を調査・検討しておく必要があります。

• COM DLL の開発言語

  特に不特定多数に配布する場合は、ターゲットOS、依存ライブラリ (Visual Basicランタイム、.Net Frameworkなど) の制約を考慮する必要があります。

• 保存／復元処理の実現方法

  保存／復元処理に必要なAPI (Win32APIなど) や外部コマンドの呼び出し手順、設定情報の仕様について調査しておく必要があります。

• ユーザーによる選択・入力操作の有無

  保存処理時に、ユーザーによる選択・入力操作が必要な場合は、GUIを提供する必要があります。GUIは、プロパティページ (IPropertyPageインタフェース) として実装します。 (参考：API仕様 － IPlugin::Initialize)

1. IPlugin実装クラスを含む、COM DLLを作成します。

   IPlugin実装クラスの例 (VC++/ATL8.0)

   // PluginImpl.h : CPluginImpl の宣言 #pragma once // MIDLコンパイラが、SpiralwarePorwer.idlファイルから自動生成したヘッダーファイル #include "SpiralwarePower.h" // NCSwitch タイプライブラリをインポート #import "libid:FEEE0494-3BCC-4C6F-AE1B-89D796F46922" raw_interfaces_only, raw_native_types, named_guids // CPluginImpl - IPluginインタフェースの実装クラス 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)     {         //NCSwitchから渡されたオブジェクトをインスタンス変数に保持         m_spPluginSite = site;         m_spPluginSite->get_Parameter(&m_spParameter);         m_spPluginSite->get_Configuration(&m_spConfiguration);         //ユーザーによる選択・入力操作が必要な場合は、ここでIPropertyPage実装オブジェクトを登録します         // 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)     {         //OSから、現在の電源設定を取得         CString sPowerSchemeId = this->GetActivePwrScheme();                  if (! sPowerSchemeId.IsEmpty())         {             //取得成功             *result = 1;             //取得した設定情報を、NCSwitchに転送             m_spConfiguration->put_Item(CComBSTR(_T("PowerSchemeId")), CComBSTR(sPowerSchemeId));         }         else         {             //取得失敗             *result = 0;         }                  return S_OK;     }     STDMETHOD(SetSystemConfiguration)(long * result)     {         USES_CONVERSION;         //GetSystemConfigurationで取得した設定情報を変数に退避         CComBSTR bsId;         m_spConfiguration->get_Item(CComBSTR(_T("PowerSchemeId")), &bsId);         //電源設定を、OSに適用         if (this->SetActivePwrScheme(OLE2T(bsId)))         {             //復元成功 (再起動不要)             *result = 1;         }         else         {             //復元失敗             *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. plugin.xmlタグ仕様に従って、plugin.xmlファイルを作成します。

   plugin.xmlサンプル

   <?xml version="1.0" encoding="Shift_JIS" ?> <NCSwitchPlugin     name="電源設定"      description="電源設定を切り替えます"     support="support@spiralware.jp">   <Module codeBase="Spiralware.Power.dll" classId="{7B2F451A-6DC3-4175-A22D-F85E6295ACED}">   </Module> </NCSwitchPlugin>

   カスタムプラグインのサンプルは、プラグインルートディレクトリ内の「Spiralware.Power」にあります。 (Visual C++ 2005 プロジェクト)

1. NCSwitchプラグインを作成します (参考：NCSwitchプラグインの種類)
2. 作成したNCSwitchプラグインをpluginsディレクトリに配置します (参考：ファイル構成)
3. NCSwitchウィザードを起動して、保存処理を実行します
   

   復元項目の選択時に、開発したNCSwitchプラグインのプラグイン名称が表示されます。
   

   表示されない場合は、NCSwitchプラグインが正常に機能していません。以下の原因が考えられます。

   • Plugin.xmlのXMLフォーマットが誤っている
     

     plugin.xmlをInternet Explorerで開くと、誤りのある箇所が表示されます。誤りを修正してください。
     

   • IPlugin実装クラスのインスタンス生成に失敗した (カスタムプラグインの場合のみ)

     plugin.xmlに含まれるModuleタグのcodeBase設定、classId設定に誤りがあった場合、NCSwitchはIPlugin実装クラス を見つけられず、インスタンス生成に失敗します。設定の誤りを修正してください。

     IPlugin実装クラスのIPlugin::Initializeメソッド呼び出し中に実行時エラーが発生した場合、NCSwitchはインスタンス生成に失敗したとみなしてウィザード画面に表示しません。 IPlugin実装クラスにバグがあれば修正してください。

4. 保存内容を確認します
   

   保存に成功すると、デスクトップ上にショートカットが作成されます。ショートカットのプロパティに、config.xmlファイルの保存先が登録されています。
   

   

   config.xmlファイルを開くと、プラグインが保存した内容を確認できます。 意図したとおりにシステム設定が保存されているか確認してください。
   

1. 保存処理の動作確認手順で作成したショートカットをダブルクリックして、復元処理を実行します。

   NCSwitchがサポートしている復元項目と同様に、復元画面上に処理結果が表示されます。

NCSwitchプラグインは、下記のファイルから構成されています。 pluginsディレクトリ配下に構成ファイルを含むディレクトリをコピーすると、NCSwitchの起動時にロードされるようになります。 (レジストリへのCOM登録は不要です)

NCSwitchプラグインAPIは、COM仕様に基づいています。