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 Eigenschafsnamen.
  [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 bugtraq:message Eigenschaft so konfiguriert wurde.

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

Die revPropNames und revPropValues Rückgabewerte 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. Falls 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, welche 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, so dass 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, falls
  // die Funktion etwas anderes als S_OK zurück gibt.
  [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(
  // Falls das Modul einen eigenen Einstellungsdialog hat.
  [out, retval] VARIANT_BOOL *ret
);

Diese Methode wird aus dem Einstellungsdialog für Module heraus aufgerufen. Falls 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 Optionen Schaltfläche klickt, die angezeigt wird, falls HasOptions TRUE zurückgibt. Ein Modul kann einen Einstellungsdialog anzeigen, um die Einrichtung für den Anwender zu vereinfachen.

Die parameters Zeichenfolge 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.