contrib/issue-tracker-plugins/inc/IBugTraqProvider.idl

   1 // TortoiseSVN - a Windows shell extension for easy version control
   2 //
   3 // Copyright (C) 2008, 2012 - TortoiseSVN
   4 //
   5 // IMPORTANT: While the rest of TortoiseSVN is licensed under the GPL,
   6 // this portion is public domain
   7
   8 midl_pragma warning(disable:2111) // identifier length exceeds 31 characters
   9 import "oaidl.idl";
  10 import "ocidl.idl";
  11 midl_pragma warning(default:2111) // identifier length exceeds 31 characters
  12
  13 [
  14     object,
  15     uuid(298B927C-7220-423C-B7B4-6E241F00CD93),
  16     helpstring("IBugTraqProvider Interface"),
  17     pointer_default(unique)
  18 ]
  19 interface IBugTraqProvider : IUnknown
  20 {
  21     /** A provider might need some parameters (e.g. a web service URL or a database connection string).
  22      * This information is passed as a simple string. It's up to the individual provider to parse and
  23      * validate it.
  24      *
  25      * The ValidateParameters method is called from the settings dialog. This allows the provider to check
  26      * that the parameters are OK. The provider can do basic syntax checking, it can check that the server
  27      * is reachable, or it can do nothing.
  28      *
  29      * If the provider needs to report a validation error, it should do this itself, using hParentWnd as
  30      * the parent of any displayed UI.
  31      */
  32     HRESULT ValidateParameters (
  33         [in] HWND hParentWnd,                   // Parent window for any UI that needs to be displayed during validation.
  34         [in] BSTR parameters,                   // The parameter string that needs to be validated.
  35         [out, retval] VARIANT_BOOL *valid       // Is the string valid?
  36     );
  37
  38     /** In the commit dialog, the provider is accessed from a button. It needs to know what text to
  39      * display (e.g. "Choose Bug" or "Select Ticket").
  40      */
  41     HRESULT GetLinkText (
  42         [in] HWND hParentWnd,                   // Parent window for any (error) UI that needs to be displayed.
  43         [in] BSTR parameters,                   // The parameter string, just in case you need to talk to your web
  44                                                 // service (e.g.) to find out what the correct text is.
  45         [out, retval] BSTR *linkText            // What text do you want to display? Use the current thread locale.
  46     );
  47
  48     /** Get the commit message. This would normally involve displaying a dialog with a list of the
  49      * issues assigned to the current user.
  50      */
  51     HRESULT GetCommitMessage (
  52         [in] HWND hParentWnd,                   // Parent window for your provider's UI.
  53         [in] BSTR parameters,                   // Parameters for your provider.
  54         [in] BSTR commonRoot,
  55         [in] SAFEARRAY(BSTR) pathList,
  56         [in] BSTR originalMessage,              // The text already present in the commit message.
  57                                                 // Your provider should include this text in the new message, where appropriate.
  58         [out, retval] BSTR *newMessage          // The new text for the commit message. This replaces the original message.
  59     );
  60 };
  61
  62 [
  63     object,
  64     uuid(C5C85E31-2F9B-4916-A7BA-8E27D481EE83),
  65     helpstring("IBugTraqProvider2 Interface"),
  66     pointer_default(unique)
  67 ]
  68 interface IBugTraqProvider2 : IBugTraqProvider
  69 {
  70     /** Get the commit message. This would normally involve displaying a dialog with a list of the
  71      * issues assigned to the current user.
  72      */
  73     HRESULT GetCommitMessage2 (
  74         [in] HWND hParentWnd,                   // Parent window for your provider's UI.
  75         [in] BSTR parameters,                   // Parameters for your provider.
  76         [in] BSTR commonURL,                    // the common url of the commit
  77         [in] BSTR commonRoot,
  78         [in] SAFEARRAY(BSTR) pathList,
  79         [in] BSTR originalMessage,              // The text already present in the commit message.
  80                                                 // Your provider should include this text in the new message, where appropriate.
  81         // you can assign custom revision properties to a commit by setting the next two params.
  82         // note: both safearrays must be of the same length. For every property name there must be a property value!
  83         [in] BSTR bugID,                        // the content of the bugID field (if shown)
  84         [out] BSTR * bugIDOut,                  // modified content of the bugID field
  85         [out] SAFEARRAY(BSTR) * revPropNames,   // a list of revision property names which are applied to the commit
  86         [out] SAFEARRAY(BSTR) * revPropValues,  // a list of revision property values which are applied to the commit
  87         [out, retval] BSTR * newMessage         // The new text for the commit message. This replaces the original message.
  88     );
  89
  90     /** Called right before the commit dialog is dismissed. This is the last chance to reject
  91      * a commit. You can check the commit log message here and return an error message if it does not
  92      * match your specification. An empty error string means the commit is allowed.
  93      */
  94     HRESULT CheckCommit (
  95         [in] HWND hParentWnd,
  96         [in] BSTR parameters,
  97         [in] BSTR commonURL,
  98         [in] BSTR commonRoot,
  99         [in] SAFEARRAY(BSTR) pathList,
 100         [in] BSTR commitMessage,
 101         [out, retval] BSTR * errorMessage
 102         );
 103
 104     HRESULT OnCommitFinished (
 105         [in] HWND hParentWnd,                   // Parent window for any (error) UI that needs to be displayed.
 106         [in] BSTR commonRoot,                   // The common root of all paths that got committed.
 107         [in] SAFEARRAY(BSTR) pathList,          // All the paths that got committed.
 108         [in] BSTR logMessage,                   // The text already present in the commit message.
 109         [in] ULONG revision,                    // The revision of the commit.
 110         [out, retval] BSTR * error              // An error to show to the user if this function returns something else than S_OK
 111         );
 112
 113     HRESULT HasOptions(
 114         [out, retval] VARIANT_BOOL *ret         // Whether the provider provides options
 115         );
 116
 117     // this method is called if HasOptions() returned true before.
 118     // Use this to show a custom dialog so the user doesn't have to
 119     // create the parameters string manually
 120     HRESULT ShowOptionsDialog(
 121         [in] HWND hParentWnd,                   // Parent window for the options dialog
 122         [in] BSTR parameters,                   // Parameters for your provider.
 123         [out, retval] BSTR * newparameters      // the parameters string
 124         );
 125 };