IBugtraqProvider2 接口

在 TortoiseSVN 1.6 中增加了一个可以为插件提供更多功能的接口。这个接口就是 IBugtraqProvider2，它继承自 IBugtraqProvider。

HRESULT GetCommitMessage2 (
  // 您提供者的UI的父窗体。
  [in] HWND hParentWnd,
 
  // 为您的提供者准备的参数。
  [in] BSTR parameters,
  // 提交的通用URL
  [in] BSTR commonURL,
  [in] BSTR commonRoot,
  [in] SAFEARRAY(BSTR) pathList,
 
  // 在提交信息中已经显示过的文字。
  // 您的提供者应该在适当的地方包含这些文字。
  [in] BSTR originalMessage,
 
  // 通过下面两个参数，
  // 你可以给提交指定版本属性。
  // 注意：所有的 SAFEARRAY 必须是同一长度。
  //       对于每一个属性名，必须有属性值！
 
  // bugID 字段的内容（如果显示）
  [in] BSTR bugID,
 
  // bugID 字段中被修改的内容。
  [out] BSTR * bugIDOut,
 
  // 版本属性名的列表。
  [out] SAFEARRAY(BSTR) * revPropNames,
 
  // 版本属性值的列表。
  [out] SAFEARRAY(BSTR) * revPropValues,
 
  // 新的提交信息文本。
  // 它将替换原始的提交信息。
  [out, retval] BSTR * newMessage
);

当用户点击插件按钮时，这个方法被 TortoiseSVN 提交对话框调用。这个方法代替了 GetCommitMessage() 被调用。有些属性在 GetCommitMessage 中使用，具体请参考 GetCommitMessage 文档。

commonURL 属性是所有被选中的项目的父URL（在这些项目上打开的提交对话框）。从根本上说，这个URL就是 commonRoot 路径的URL。

The parameter bugID contains the content of the bug-ID field (if it is shown, configured with the property bugtraq:message).

The return parameter bugIDOut is used to fill the bug-ID field when the method returns.

The revPropNames and revPropValues return parameters can contain name/value pairs for revision properties that the commit should set. A plugin must make sure that both arrays have the same size on return! Each property name in revPropNames must also have a corresponding value in revPropValues. If no revision properties are to be set, the plugin must return empty arrays.

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
);

This method is called right before the commit dialog is closed and the commit begins. A plugin can use this method to validate the selected files/folders for the commit and/or the commit message entered by the user. The parameters are the same as for GetCommitMessage2(), with the difference that commonURL is now the common URL of all checked items, and commonRoot the root path of all checked items.

For the branch/tag dialog, the commonURL is the source URL of the copy, and commonRoot is set to the target URL of the copy.

The return parameter errorMessage must either contain an error message which TortoiseSVN shows to the user or be empty for the commit to start. If an error message is returned, TortoiseSVN shows the error string in a dialog and keeps the commit dialog open so the user can correct whatever is wrong. A plugin should therefore return an error string which informs the user what is wrong and how to correct it.

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
);

This method is called after a successful commit. A plugin can use this method to e.g., close the selected issue or add information about the commit to the issue. The parameters are the same as for GetCommitMessage2.

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

This method is called from the settings dialog where the user can configure the plugins. If a plugin provides its own configuration dialog with ShowOptionsDialog, it must return TRUE here, otherwise it must return 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
);

This method is called from the settings dialog when the user clicks on the "Options" button that is shown if HasOptions returns TRUE. A plugin can show an options dialog to make it easier for the user to configure the plugin.

The parameters string contains the plugin parameters string that is already set/entered.

The newparameters return parameter must contain the parameters string which the plugin constructed from the info it gathered in its options dialog. That paramameters string is passed to all other IBugtraqProvider and IBugtraqProvider2 methods.