Die IBugtraqProvider2-Schnittstelle

In TortoiseSVN 1.6 wurde eine neue Schnittstelle eingeführt, die mehr Funktionalität für die COM-Module zur Verfügung stellt. Die IBugtraqProvider2-Schnittstelle erbt von IBugtraqProvider.

HRESULT GetCommitMessage2 (
  // Elternfenster für die Bedienoberfläche des Moduls.
  [in] HWND hParentWnd,

  // Parameter für Ihr Modul
  [in] BSTR parameters,
  // Die gemeinsame URL für die Übertragung
  [in] BSTR commonURL,
  [in] BSTR commonRoot,
  [in] SAFEARRAY(BSTR) pathList,

  // Der Text, der bereits in der Logmeldung steht.
  // Ihr Modul sollte diesen Text, wo angebracht,
  // in die neue Meldung einfügen.
  [in] BSTR originalMessage,

  // Sie können einer Übertragung eigene Revisionseigenschaften
  // zuweisen, indem Sie die nächsten beiden Parameter setzen.
  // ACHTUNG: Beide safearrays müssen dieselbe Länge haben.
  //          Für jeden Eigenschaftsnamen muss es einen Wert geben!

  // Der Inhalt des bugID-Feldes (falls angezeigt)
  [in] BSTR bugID,

  // Der geänderte Inhalt des bugID-Feldes
  [out] BSTR * bugIDOut,

  // Die Liste der Eigenschaftsnamen.
  [out] SAFEARRAY(BSTR) * revPropNames,

  // Die Liste der Eigenschaftswerte.
  [out] SAFEARRAY(BSTR) * revPropValues,

  // Der neue Text für die Logmeldung.
  // Ersetzt den Originaltext.
  [out, retval] BSTR * newMessage
);

Diese Methode wird aus dem TortoiseSVN-Übertragen-Dialog aufgerufen, wenn der Anwender auf die Modulschaltfläche klickt. Sie wird anstelle von GetCommitMessage() aufgerufen. In der Dokumentation zu GetCommitMessage werden die verwendeten Parameter beschrieben.

Der Parameter commonURL ist die Eltern-URL aller beim Start des Übertragen-Dialogs gewählten Objekte. Er entspricht im Wesentlichen der URL des commonRoot-Pfades.

Der Parameter bugID enthält den Wert des Bug-ID-Feldes, falls es über die Eigenschaft bugtraq:message so konfiguriert wurde.

Der Rückgabewert bugIDOut wird verwendet, um das Bug-ID-Feld beim Beenden der Methode zu füllen.

Die Rückgabewerte revPropNames und revPropValues können Namen/Wertepaare für Revisionseigenschaften enthalten, die beim Übertragen gesetzt werden sollen. Ein Modul muss sicherstellen, dass beide Felder beim Rücksprung dieselbe Größe haben! Jeder Eigenschaftswert in revPropNames muss einen entsprechenden Wert in revPropValues besitzen. Wenn keine Revisionseigenschaften gesetzt werden sollen, muss das Modul leere Felder zurückgeben.

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

Diese Methode wird aufgerufen, kurz bevor der Übertragen-Dialog geschlossen wird, und die eigentliche Übertragung beginnt. Ein Modul kann mit Hilfe dieser Methode die Logmeldung und/oder die zu übertragenden Dateien/Ordner überprüfen und die Übertragung entweder zulassen oder blockieren. Die Parameter sind dieselben wie für GetCommitMessage2() mit dem Unterschied, dass commonURL die gemeinsame URL aller ausgewählten Dateien/Ordner und commonRoot der gemeinsame Pfad aller ausgewählten Dateien/Ordner ist.

Beim Verzweigen/Markieren-Dialog ist commonURL die Quell-URL und commonRoot die Ziel-URL der Kopie.

Der Rückgabewert errorMessage muss entweder eine Fehlermeldung enthalten, die TortoiseSVN dem Benutzer anzeigt oder leer sein, um die Übertragung zuzulassen. Wenn eine Fehlermeldung zurückgegeben wird, zeigt TortoiseSVN diese dem Benutzer in einem Fehlerdialog an und hält den Übertragen-Dialog offen, sodass der Benutzer den Fehler korrigieren kann. Ein Modul sollte deshalb in der Fehlermeldung mitteilen, was genau falsch ist und wie der Benutzer dies korrigieren kann.

HRESULT  OnCommitFinished (
  // Elternfenster für die Bedienoberfläche des Moduls.
  [in] HWND hParentWnd,

  // Die gemeinsame Basis aller übertragenen Pfade.
  [in] BSTR commonRoot,

  // Alle übertragenen Pfade.
  [in] SAFEARRAY(BSTR) pathList,


  // Der Text, der bereits in der Logmeldung steht.
  [in] BSTR logMessage,

  // Die Revision der Übertragung.
  [in] ULONG revision,


  // Ein Fehler, der dem Anwender angezeigt wird, wenn
  // die Funktion etwas anderes als S_OK zurückgibt.
  [out, retval] BSTR * error
);

Diese Methode wird nach einer erfolgreichen Übertragung aufgerufen. Ein Modul kann diese Methode verwenden, um zum Beispiel einen offenen Eintrag zu schließen oder weitere Informationen an den Eintrag anzuhängen. Die Parameter sind die gleichen wie bei GetCommitMessage2.

HRESULT HasOptions(
  // Wenn das Modul einen eigenen Einstellungsdialog hat.
  [out, retval] VARIANT_BOOL *ret
);

Diese Methode wird aus dem Einstellungsdialog für Module heraus aufgerufen. Wenn ein Modul einen eigenen Einstellungsdialog über ShowOptionsDialog bereitstellt, muss es TRUE zurückliefern, sonst FALSE.

HRESULT ShowOptionsDialog(
  // Elternfenster für den Einstellungsdialog des Moduls.
  [in] HWND hParentWnd,

  // Parameter für Ihr Modul.
  [in] BSTR parameters,

  // Die neuen Parameter als Zeichenkette
  [out, retval] BSTR * newparameters
);

Diese Methode wird aus dem Einstellungsdialog aufgerufen, wenn der Anwender auf die Schaltfläche Optionen klickt, die angezeigt wird, wenn HasOptions TRUE zurückgibt. Ein Modul kann einen Einstellungsdialog anzeigen, um die Einrichtung für den Anwender zu vereinfachen.

Die Zeichenfolge parameters enthält die bereits gesetzten/eingegebenen Modulparameter.

Der Rückgabewert newparameters muss die neuen Parameter enthalten, die das Modul aus dem Einstellungsdialog ermittelt hat. Die Zeichenkette parameters wird an alle anderen IBugtraqProvider- und IBugtraqProvider2-Methoden übergeben.