第6章 IBugtraqProvider インターフェース

TortoiseSVN 1.5 では、IBugtraqProvider インターフェースを実装したプラグインを利用できます。このインターフェースは、プラグインが課題管理システムとやりとりするのに使用する、いくつかのメソッドを提供しています。

HRESULT ValidateParameters (
  // Parent window for any UI that needs to be
  // displayed during validation.
  [in] HWND hParentWnd,

  // The parameter string that needs to be validated.
  [in] BSTR parameters,

  // Is the string valid?
  [out, retval] VARIANT_BOOL *valid
);

このメソッドは、ユーザがプラグインを追加し、設定した設定ダイアログから呼ばれます。parameters 文字列は、課題管理システムの URL やログイン情報などの必要な追加情報を取得するため、プラグインが使用します。プラグインは parameters 文字列を検証し、不正であればエラーダイアログを表示するべきです。hParentWnd パラメータは、プラグインが表示するダイアログで、親ウィンドウとして使われます。parameters 文字列の検証が成功したら、プラグインは TRUE を返さねばなりません。プラグインが FALSE を返すと、作業コピーパスへのプラグインの追加は失敗します。

HRESULT GetLinkText (
  // Parent window for any (error) UI that needs to be displayed.
  [in] HWND hParentWnd,

  // The parameter string, just in case you need to talk to your
  // web service (e.g.) to find out what the correct text is.
  [in] BSTR parameters,

  // What text do you want to display?
  // Use the current thread locale.
  [out, retval] BSTR *linkText
);

TortoiseSVN のコミットダイアログで、プラグインを起動するためのボタンで使用する文字列 ("Choose issue" や "Select ticket") をここで提供できます。文字列は長すぎないようにしてください。そうでないとボタンに入り切りません。このメソッドがエラー (E_NOTIMPL など) を返すと、デフォルトの文字列をボタンに使用します。

HRESULT GetCommitMessage (
  // Parent window for your provider's UI.
  [in] HWND hParentWnd,

  // Parameters for your provider.
  [in] BSTR parameters,
  [in] BSTR commonRoot,
  [in] SAFEARRAY(BSTR) pathList,

  // The text already present in the commit message.
  // Your provider should include this text in the new message,
  // where appropriate.
  [in] BSTR originalMessage,

  // The new text for the commit message.
  // This replaces the original message.
  [out, retval] BSTR *newMessage
);

これがプラグインのメインメソッドです。TortoiseSVN のコミットダイアログで、ユーザがプラグインボタンをクリックすると、このメソッドが呼ばれます。parameters 文字列は、設定ダイアログで、プラグインの設定をしたときに入力してあった文字列になります。プラグインは通常、課題管理システムの URL やログイン情報、もしくはさらにその他のものを、このパラメータから取得します。commonRoot 文字列には、コミットダイアログが表示するために選択した、すべての項目の上位パスが格納されています。コミットダイアログでユーザが選択した項目すべてのルートパスは含まれていないことにご注意ください。pathList パラメータには、コミットするとユーザが選択したパス (文字列) の配列を格納しています。originalMessage パラメータには、コミットダイアログのログメッセージボックスに入力したテキストを格納しています。ユーザがまだテキストを入力していない場合は、空文字列となります。newMessage 返却文字列は、既に入力されている文字列を置き換えて、ログメッセージエディットボックスにコピーされます。プラグインが originalMessage 文字列を変更しない場合、同じ文字列を返さなければなりません。そうしないと、ユーザが入力したテキストが失われてしまいます。