src/IBugTraqProvider/IBugTraqProvider.idl

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