src/IBugTraqProvider/IBugTraqProvider.idl

   1 // TortoiseSVN - a Windows shell extension for easy version control
   2 //
   3 // Copyright (C) 2008 - 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 all items in the commit dialog (checked or unchecked!),
  77                                                                                                 // with the url of the item that was selected to bring up the commit dialog having precedence.
  78                 [in] BSTR commonRoot,
  79                 [in] SAFEARRAY(BSTR) pathList,
  80                 [in] BSTR originalMessage,                              // The text already present in the commit message.
  81                                                                                                 // Your provider should include this text in the new message, where appropriate.
  82                 // you can assign custom revision properties to a commit by setting the next two params.
  83                 // note: both safearrays must be of the same length. For every property name there must be a property value!
  84                 [in] BSTR bugID,                                                // the content of the bugID field (if shown)
  85                 [out] BSTR * bugIDOut,                                  // modified content of the bugID field
  86                 [out] SAFEARRAY(BSTR) * revPropNames,   // a list of revision property names which are applied to the commit
  87                 [out] SAFEARRAY(BSTR) * revPropValues,  // a list of revision property values which are applied to the commit
  88                 [out, retval] BSTR * newMessage                 // The new text for the commit message. This replaces the original message.
  89         );
  90
  91         /** Called right before the commit dialog is dismissed. This is the last chance to reject
  92          * a commit. You can check the commit log message here and return an error message if it does not
  93          * match your specification. An empty error string means the commit is allowed.
  94          */
  95         HRESULT CheckCommit (
  96                 [in] HWND hParentWnd,
  97                 [in] BSTR parameters,
  98                 [in] BSTR commonURL,
  99                 [in] BSTR commonRoot,
 100                 [in] SAFEARRAY(BSTR) pathList,
 101                 [in] BSTR commitMessage,
 102                 [out, retval] BSTR * errorMessage
 103                 );
 104
 105         HRESULT OnCommitFinished (
 106                 [in] HWND hParentWnd,                                   // Parent window for any (error) UI that needs to be displayed.
 107                 [in] BSTR commonRoot,                                   // The common root of all paths that got committed.
 108                 [in] SAFEARRAY(BSTR) pathList,                  // All the paths that got committed.
 109                 [in] BSTR logMessage,                                   // The text already present in the commit message.
 110                 [in] ULONG revision,                                    // The revision of the commit.
 111                 [out, retval] BSTR * error                              // An error to show to the user if this function returns something else than S_OK
 112                 );
 113
 114         HRESULT HasOptions(
 115                 [out, retval] VARIANT_BOOL *ret                 // Whether the provider provides options
 116                 );
 117
 118         // this method is called if HasOptions() returned true before.
 119         // Use this to show a custom dialog so the user doesn't have to
 120         // create the parameters string manually
 121         HRESULT ShowOptionsDialog(
 122                 [in] HWND hParentWnd,                                   // Parent window for the options dialog
 123                 [in] BSTR parameters,                                   // Parameters for your provider.
 124                 [out, retval] BSTR * newparameters              // the parameters string
 125                 );
 126 };