手冊

IBugtraqProvider2 介面

TortoiseSVN 1.6 中新增了一個介面,可提供更多功能,供外掛程式使用。這個 IBugtraqProvider2 介面繼承自 IBugtraqProvider。

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

  // Parameters for your provider.
  [in] BSTR parameters,
  // The common URL of the commit
  [in] BSTR commonURL,
  [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,

  // You can assign custom revision properties to a commit
  // by setting the next two params.
  // note: Both safearrays must be of the same length.
  //       For every property name there must be a property value!

  // The content of the bugID field (if shown)
  [in] BSTR bugID,

  // Modified content of the bugID field
  [out] BSTR * bugIDOut,

  // The list of revision property names.
  [out] SAFEARRAY(BSTR) * revPropNames,

  // The list of revision property values.
  [out] SAFEARRAY(BSTR) * revPropValues,

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

當使用者按下外掛程式按鈕時,會從 TortoiseSVN commit 對話框中呼叫這個方法。會呼叫這個方法,而不是 GetCommitMessage()。請參閱 GetCommitMessage 的文件,以取得有關相關引數的資訊。

引數 commonURL 是引發 commit 對話框的所有選取項目之父 URL。這基本上是 commonRoot 路徑的 URL。

引數 bugID 包含 bug-ID 欄位的內容 (若是顯示,則使用 bugtraq:message 屬性設定)。

當方法傳回時,回傳引數 bugIDOut 用來填入 bug-ID 欄位。

revPropNamesrevPropValues 回傳引數可能包含用於 commit 應設定的版本屬性的名稱/值對。外掛程式必須確定兩個陣列在回傳時大小相同!revPropNames 中的每個屬性名稱在 revPropValues 中也必須有相應值。若不設定任何版本屬性,外掛程式必須回傳空的陣列。

HRESULT CheckCommit (
  [in] HWND hParentWnd,
  [in] BSTR parameters,
  [in] BSTR commonURL,
  [in] BSTR commonRoot,
  [in] SAFEARRAY(BSTR) pathList,
  [in] BSTR commitMessage,
  [out, retval] BSTR * errorMessage
);

這個方法在 commit 對話框關閉並開始 commit 之前立即呼叫。外掛程式可以使用這個方法來驗證選取的檔案/資料夾是否已提交,或者驗證使用者輸入的提交訊息。這些引數與 GetCommitMessage2() 相同,不同之處在於 commonURL 現在是所有 已勾選 項目的共用 URL,而 commonRoot 是所有已勾選項目的根路徑。

對於分支/標籤對話框,commonURL 是複本的來源 URL,而 commonRoot 設定為複本的目標 URL。

回傳引數 errorMessage 必須包含一個錯誤訊息,TortoiseSVN 會將該錯誤訊息顯示給使用者,或保留空白,以便開始 commit。若傳回錯誤訊息,TortoiseSVN 會在對話框中顯示錯誤字串,然後保持 commit 對話框開啟,以便使用者更正任何錯誤。因此,外掛程式應傳回一個錯誤字串,告知使用者 什麼 出錯了,以及如何更正。

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

  // The common root of all paths that got committed.
  [in] BSTR commonRoot,

  // All the paths that got committed.
  [in] SAFEARRAY(BSTR) pathList,


  // The text already present in the commit message.
  [in] BSTR logMessage,

  // The revision of the commit.
  [in] ULONG revision,


  // An error to show to the user if this function
  // returns something else than S_OK
  [out, retval] BSTR * error
);

在成功 commit 之後會呼叫這個方法。外掛程式可以使用這個方法,例如,關閉選取的議題或將 commit 的資訊新增至議題。這些引數與 GetCommitMessage2 相同。

HRESULT HasOptions(
  // Whether the provider provides options
  [out, retval] VARIANT_BOOL *ret
);

此方法將從設定對話框中呼叫,使用者可以在其中設定外掛程式。如果外掛程式提供自己的組態對話框和 ShowOptionsDialog,這裡必須傳回 TRUE,否則必須傳回 FALSE。

HRESULT ShowOptionsDialog(
  // Parent window for the options dialog
  [in] HWND hParentWnd,

  // Parameters for your provider.
  [in] BSTR parameters,

  // The parameters string
  [out, retval] BSTR * newparameters
);

當使用者按一下如果 HasOptions 傳回 TRUE 時顯示的「選項」按鈕時,此方法會從設定對話框呼叫。外掛程式可以顯示選項對話框,讓使用者更輕鬆地設定外掛程式。

parameters 字串包含已設定或已輸入的外掛程式參數字串。

newparameters 回傳參數必須包含外掛程式從在選項對話框中收集到的資訊建構的參數字串。此 paramameters 字串會傳遞給所有其他 IBugtraqProvider 和 IBugtraqProvider2 方法。

TortoiseSVN 首頁