Package org.kapott.hbci.manager

# Class HBCIHandler

java.lang.Object
org.kapott.hbci.manager.HBCIHandler

All Implemented Interfaces:
  `IHandlerData`

public final class HBCIHandler extends Object implements IHandlerData

Ein Handle für genau einen HBCI-Zugang. Diese Klasse stellt das Verbindungsglied zwischen der Anwendung und dem HBCI-Kernel dar. Für jeden HBCI-Zugang, den die Anwendung benutzt, muss ein entsprechender HBCI-Handler angelegt werden. Darin sind folgende Daten zusammengefasst:

- Ein `HBCIPassport`, welches die Nutzeridentifikationsdaten sowie die Zugangsdaten zum entsprechenden HBCI-Server enthält
- Die zu benutzende HBCI-Versionsnummer
- interne Daten zur Verwaltung der Dialoge bei der Kommunikation mit dem HBCI-Server

Alle Anfragen der Anwendung an den HBCI-Kernel laufen über einen solchen Handler, womit gleichzeit eindeutig festgelegt ist, welche HBCI-Verbindung diese Anfrage betrifft.

Die prinzipielle Benutzung eines Handlers sieht in etwa wiefolgt aus:

    // ...
    HBCIPassport passport=AbstractHBCIPassport.getInstance();
    HBCIHandler handle=new HBCIHandler(passport.getHBCIVersion(),passport);

    HBCIJob jobSaldo=handle.newJob("SaldoReq");       // nächster Auftrag ist Saldenabfrage
    jobSaldo.setParam("number","1234567890");         // Kontonummer für Saldenabfrage
    jobSaldo.addToQueue();

    HBCIJob jobUeb=handle.newJob("Ueb");
    jobUeb.setParam("src.number","1234567890");
    jobUeb.setParam("dst.number","9876543210");
    // ...
    jobUeb.addToQueue();

    // ...

    HBCIExecStatus status=handle.execute();

    // Auswerten von status
    // Auswerten der einzelnen job-Ergebnisse

    handle.close();

## Field Summary

Fields
Modifier and Type
Field
Description
`static final int`
`REFRESH_BPD`
`static final int`
`REFRESH_UPD`

## Constructor Summary

Constructors
Constructor
Description
`HBCIHandler(String hbciversion, HBCIPassport passport)`
Anlegen eines neuen HBCI-Handler-Objektes.
`HBCIHandler(String hbciversion, HBCIPassport passport, boolean lazyInit)`
Anlegen eines neuen HBCI-Handler-Objektes.

## Method Summary

Modifier and Type
Method
Description
`void`
`addJob(String customerId, HBCIJob job)`
Deprecated.
use `HBCIJob.addToQueue(String)` instead
`void`
`addJob(HBCIJob job)`
Deprecated.
use `HBCIJob.addToQueue()` instead
`void`
`addJobToDialog(String customerId, HBCIJob job)`
Do NOT use! Use `HBCIJob.addToQueue(String)` instead
`void`
`close()`
Schließen des Handlers.
`HBCIExecThreadedStatus`
`continueThreaded(String retData)`
Setzt bei Verwendung des threaded-callback-Mechanismus einen noch aktiven HBCI-Dialog fort.
`void`
`createEmptyDialog()`
Entspricht `createEmptyDialog(null)`
`void`
`createEmptyDialog(String customerId)`
Erzeugen eines leeren HBCI-Dialoges.
`HBCIExecStatus`
`execute()`
Ausführen aller bisher erzeugten Aufträge.
`HBCIExecThreadedStatus`
`executeThreaded()`
Entspricht `execute()`, allerdings können Callbacks hier auch synchron behandelt werden.
`String`
`getHBCIVersion()`
Gibt die HBCI-Versionsnummer zurück, für die der aktuelle HBCIHandler konfiguriert ist.
`HBCIKernel`
`getKernel()`
Gibt das HBCI-Kernel-Objekt zurück, welches von diesem HBCI-Handler benutzt wird.
`List<String>`
`getLowlevelJobParameterNames(String gvname)`
Gibt alle Parameter zurück, die für einen Lowlevel-Job gesetzt werden können.
`Properties`
`getLowlevelJobRestrictions(String gvname)`
Gibt für einen Job alle bekannten Einschränkungen zurück, die bei der Ausführung des jeweiligen Jobs zu beachten sind.
`List<String>`
`getLowlevelJobResultNames(String gvname)`
Gibt eine Liste mit Strings zurück, welche Bezeichnungen für die einzelnen Rückgabedaten eines Lowlevel-Jobs darstellen.
`MsgGen`
`getMsgGen()`
`HBCIPassport`
`getPassport()`
Gibt das Passport zurück, welches in diesem Handle benutzt wird.
`Properties`
`getSupportedLowlevelJobs()`
Gibt die Namen aller vom aktuellen HBCI-Zugang (d.h.
`HBCIExecThreadedStatus`
`initThreaded()`
Führt die Abfrage von BPD und UPD aus, die normalerweise in `HBCIHandler(String, HBCIPassport)` bzw.
`boolean`
`isSupported(String jobnameHL)`
Überprüfen, ein bestimmter Highlevel-Job von der Bank angeboten wird.
`void`
`lockKeys()`
Sperren der Nutzerschlüssel.
`HBCIJob`
`newJob(String jobname)`
Erzeugen eines neuen Highlevel-HBCI-Jobs.
`void`
`newKeys()`
Erzeugen neuer kryptografischer Schlüssel für den Nutzer.
`HBCIJob`
`newLowlevelJob(String gvname)`
Erzeugt ein neues Lowlevel-Job-Objekt.
`void`
`newMsg()`
Erzwingen einer neuen Nachricht im Dialog für die aktuelle Kunden-ID.
`void`
`newMsg(String customerId)`
Beginn einer neuen HBCI-Nachricht innerhalb eines Dialoges festlegen.
`HBCIDialogStatus`
`refreshXPD(int selectX)`
Abholen der BPD bzw.
`void`
`reset()`
Zurücksetzen des Handlers auf den Ausgangszustand.
`void`
`setKeys(KeyPair sigKey, KeyPair encKey)`
Setzen der Nutzerschlüssel auf vorgegebene Daten.
`void`
`sync(boolean force)`
Fuehrt eine Neu-Synchronisierung durch.
`HBCIExecStatus`
`verifyTAN()`
Entspricht `verifyTAN(null)`.
`HBCIExecStatus`
`verifyTAN(String customerId)`
Key-Management: Überprüfen einer TAN (nur für PinTan-Passports!).

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### REFRESH_BPD

public static final int REFRESH_BPD

See Also:
  - Constant Field Values

### REFRESH_UPD

public static final int REFRESH_UPD

See Also:
  - Constant Field Values

## Constructor Details

### HBCIHandler

public HBCIHandler(String hbciversion, HBCIPassport passport)
Anlegen eines neuen HBCI-Handler-Objektes. Beim Anlegen wird überprüft, ob für die angegebene HBCI-Version eine entsprechende Spezifikation verfügbar ist. Außerdem wird das übergebene Passport überprüft. Dabei werden - falls nicht vorhanden - die BPD und die UPD vom Kreditinstitut geholt. Bei Passports, die asymmetrische Verschlüsselungsverfahren benutzen (RDH), wird zusätzlich überprüft, ob alle benötigten Schlüssel vorhanden sind. Gegebenenfalls werden diese aktualisiert.

Parameters:
  `hbciversion` - zu benutzende HBCI-Version. gültige Werte sind:
  - `null` - es wird die HBCI-Version benutzt, die bei der letzten Verwendung dieses Passports benutzt wurde
  - "`201`" für HBCI 2.01
  - "`210`" für HBCI 2.1
  - "`220`" für HBCI 2.2
  - "`plus`" für HBCI+
  - "`300`" für FinTS 3.0
  `passport` - das zu benutzende Passport. Dieses muss vorher mit `AbstractHBCIPassport.getInstance()` erzeugt worden sein

### HBCIHandler

public HBCIHandler(String hbciversion, HBCIPassport passport, boolean lazyInit)
Anlegen eines neuen HBCI-Handler-Objektes. Beim Anlegen wird überprüft, ob für die angegebene HBCI-Version eine entsprechende Spezifikation verfügbar ist. Außerdem wird das übergebene Passport überprüft. Dabei werden - falls nicht vorhanden und falls

Parameters:
  `lazyInit` - nicht auf true gesetzt ist - die BPD und die UPD vom Kreditinstitut geholt. Bei Passports, die asymmetrische Verschlüsselungsverfahren benutzen (RDH), wird zusätzlich überprüft, ob alle benötigten Schlüssel vorhanden sind. Gegebenenfalls werden diese aktualisiert.
  `hbciversion` - zu benutzende HBCI-Version. gültige Werte sind:
  - `null` - es wird die HBCI-Version benutzt, die bei der letzten Verwendung dieses Passports benutzt wurde
  - "`201`" für HBCI 2.01
  - "`210`" für HBCI 2.1
  - "`220`" für HBCI 2.2
  - "`plus`" für HBCI+
  - "`300`" für FinTS 3.0
  `passport` - das zu benutzende Passport. Dieses muss vorher mit `AbstractHBCIPassport.getInstance()` erzeugt worden sein
  `lazyInit` - auf true setzen, um den UPD nachgelagert per `initThreaded()` zu laden (zum Handling der eventuellen TAN-Abfrage)

## Method Details

### initThreaded

public HBCIExecThreadedStatus initThreaded()

Führt die Abfrage von BPD und UPD aus, die normalerweise in `HBCIHandler(String, HBCIPassport)` bzw. `HBCIHandler(String, HBCIPassport, boolean)` mit lazyInit=false durchgeführt wird, allerdings können Callbacks hier auch synchron behandelt werden. Bei einem Aufruf von `initThreaded()` wird der eigentliche HBCI-Dialog in einem separaten Thread geführt. Bei evtl. auftretenden Callbacks wird geprüft, ob diese synchron oder asynchron zu behandeln sind. Im asynchronen Fall wird der Callback wie gewohnt durch Aufruf der `callback()`-Methode des registrierten "normalen" Callback-Objektes behandelt. Soll ein Callback synchron behandelt werden, terminiert diese Methode.

Das zurückgegebene Status-Objekt zeigt an, ob diese Methode terminierte, weil ein synchron zu behandelnder Callback aufgetreten ist oder weil die Ausführung aller HBCI-Dialoge abgeschlossen ist.

Mehr Informationen dazu in der Datei `README.ThreadedCallbacks`.

### sync

public void sync(boolean force)
Description copied from interface: `IHandlerData`
Fuehrt eine Neu-Synchronisierung durch.

Specified by:
  `sync` in interface `IHandlerData`
Parameters:
  `force` - true, wenn die Neu-Synchronisierung forciert werden soll.
See Also:
  - `IHandlerData.sync(boolean)`

### close

public void close()

Schließen des Handlers. Diese Methode sollte immer dann aufgerufen werden, wenn die entsprechende HBCI-Verbindung nicht mehr benötigt wird.

Beim Schließen des Handlers wird das Passport ebenfalls geschlossen. Sowohl das Passport-Objekt als auch das Handler-Objekt können anschließend nicht mehr benutzt werden.

### newMsg

public void newMsg(String customerId)

Beginn einer neuen HBCI-Nachricht innerhalb eines Dialoges festlegen. Normalerweise muss diese Methode niemals manuell aufgerufen zu werden!

Mit dieser Methode wird der HBCI-Kernel gezwungen, eine neue HBCI-Nachricht anzulegen, in die alle nachfolgenden Geschäftsvorfälle aufgenommen werden. Die `customerId` legt fest, für welchen Dialog die neue Nachricht erzeugt werden soll. Für eine genauere Beschreibung von Dialogen und `customerid`s siehe `HBCIJob.addToQueue(String)`.

Parameters:
  `customerId` - die Kunden-ID, für deren Dialog eine neue Nachricht begonnen werden soll

### newMsg

public void newMsg()
Erzwingen einer neuen Nachricht im Dialog für die aktuelle Kunden-ID. Diese Methode arbeitet analog zu `newMsg(String)`, nur dass hier die `customerid` mit der Kunden-ID vorbelegt ist, wie sie im aktuellen Passport gespeichert ist. Siehe dazu auch `HBCIJob.addToQueue(String)`.

### newJob

public HBCIJob newJob(String jobname)

Erzeugen eines neuen Highlevel-HBCI-Jobs. Diese Methode gibt ein neues Job-Objekt zurück. Dieses Objekt wird allerdings noch nicht zum HBCI-Dialog hinzugefügt. Statt dessen müssen erst alle zur Beschreibung des jeweiligen Jobs benötigten Parameter mit `HBCIJob.setParam(String,String)` gesetzt werden. Anschließend kann der Job mit `HBCIJob.addToQueue(String)` zum HBCI-Dialog hinzugefügt werden.

Eine Beschreibung aller unterstützten Geschäftsvorfälle befindet sich im Package `org.kapott.hbci.GV`.

Parameters:
  `jobname` - der Name des Jobs, der erzeugt werden soll. Gültige Job-Namen sowie die benötigten Parameter sind in der Beschreibung des Packages `org.kapott.hbci.GV` zu finden.
Returns:
  ein Job-Objekt, für das die entsprechenden Job-Parameter gesetzt werden müssen und welches anschließend zum HBCI-Dialog hinzugefügt werden kann.

### newLowlevelJob

public HBCIJob newLowlevelJob(String gvname)
Erzeugt ein neues Lowlevel-Job-Objekt. Für eine Beschreibung des Unterschiedes zwischen High- und Lowlevel-Definition von Jobs siehe Package `org.kapott.hbci.GV`.

Parameters:
  `gvname` - der Lowlevel-Name des zu erzeugenden Jobs
Returns:
  ein neues Job-Objekt, für das erst alle benötigten Lowlevel-Parameter gesetzt werden müssen und das anschließend zum HBCI-Dialog hinzugefügt werden kann

### addJobToDialog

public void addJobToDialog(String customerId, HBCIJob job)
Do NOT use! Use `HBCIJob.addToQueue(String)` instead

### addJob

public void addJob(String customerId, HBCIJob job)
Deprecated.
use `HBCIJob.addToQueue(String)` instead

### addJob

public void addJob(HBCIJob job)
Deprecated.
use `HBCIJob.addToQueue()` instead

### createEmptyDialog

public void createEmptyDialog(String customerId)
Erzeugen eines leeren HBCI-Dialoges.

Im Normalfall werden HBCI-Dialoge automatisch erzeugt, wenn Geschäftsvorfälle mit der Methode `HBCIJob.addToQueue(String)` zur Liste der auszuführenden Jobs hinzugefügt werden. `createEmptyDialog()` kann explizit aufgerufen werden, wenn ein Dialog erzeugt werden soll, der keine Geschäftsvorfälle enthält, also nur aus Dialog-Initialisierung und Dialog-Ende besteht.

Ist die angegebene `customerId=null`, so wird der Dialog für die aktuell im Passport gespeicherte Customer-ID erzeugt.

Parameters:
  `customerId` - die Kunden-ID, für die der Dialog erzeugt werden soll.

### createEmptyDialog

public void createEmptyDialog()
Entspricht `createEmptyDialog(null)`

### execute

public HBCIExecStatus execute()

Ausführen aller bisher erzeugten Aufträge. Diese Methode veranlasst den HBCI-Kernel, die Aufträge, die durch die Aufrufe der Methode `HBCIJob.addToQueue(String)` zur Auftragsliste hinzugefügt wurden, auszuführen.

Beim Hinzufügen der Aufträge zur Auftragsqueue (mit `HBCIJob.addToQueue()` oder `HBCIJob.addToQueue(String)`) wird implizit oder explizit eine Kunden-ID mit angegeben, unter der der jeweilige Auftrag ausgeführt werden soll. In den meisten Fällen hat ein Benutzer nur eine einzige Kunden-ID, so dass die Angabe entfallen kann, es wird dann automatisch die richtige verwendet. Werden aber mehrere Aufträge via `addToQueue()` zur Auftragsqueue hinzugefügt, und sind diese Aufträge unter teilweise unterschiedlichen Kunden-IDs auszuführen, dann wird für jede verwendete Kunden-ID ein separater HBCI-Dialog erzeugt und ausgeführt. Das äußert sich dann also darin, dass beim Aufrufen der Methode `execute()` u.U. mehrere HBCI-Dialog mit der Bank geführt werden, und zwar je einer für jede Kunden-ID, für die wenigstens ein Auftrag existiert. Innerhalb eines HBCI-Dialoges werden alle auszuführenden Aufträge in möglichst wenige HBCI-Nachrichten verpackt.

Dazu wird eine Reihe von HBCI-Nachrichten mit dem HBCI-Server der Bank ausgetauscht. Die Menge der dazu verwendeten HBCI-Nachrichten kann dabei nur bedingt beeinflusst werden, da HBCI4Java u.U. selbstständig Nachrichten erzeugt, u.a. wenn ein Auftrag nicht mehr mit in eine Nachricht aufgenommen werden konnte, oder wenn eine Antwortnachricht nicht alle verfügbaren Daten zurückgegeben hat, so dass HBCI4Java mit einer oder mehreren weiteren Nachrichten den Rest der Daten abholt.

Nach dem Nachrichtenaustausch wird ein Status-Objekt zurückgegeben, welches zur Auswertung aller ausgeführten Dialoge benutzt werden kann.

Returns:
  ein Status-Objekt, anhand dessen der Erfolg oder das Fehlschlagen der Dialoge festgestellt werden kann.

### executeThreaded

public HBCIExecThreadedStatus executeThreaded()

Entspricht `execute()`, allerdings können Callbacks hier auch synchron behandelt werden. Bei einem Aufruf von `executeThreaded()` anstelle von `execute()` wird der eigentliche HBCI-Dialog in einem separaten Thread geführt. Bei evtl. auftretenden Callbacks wird geprüft, ob diese synchron oder asynchron zu behandeln sind. Im asynchronen Fall wird der Callback wie gewohnt durch Aufruf der `callback()`-Methode des registrierten "normalen" Callback-Objektes behandelt. Soll ein Callback synchron behandelt werden, terminiert diese Methode.

Das zurückgegebene Status-Objekt zeigt an, ob diese Methode terminierte, weil ein synchron zu behandelnder Callback aufgetreten ist oder weil die Ausführung aller HBCI-Dialoge abgeschlossen ist.

Mehr Informationen dazu in der Datei `README.ThreadedCallbacks`.

### continueThreaded

public HBCIExecThreadedStatus continueThreaded(String retData)

Setzt bei Verwendung des threaded-callback-Mechanismus einen noch aktiven HBCI-Dialog fort. Trat bei der Ausführung eines HBCI-Dialoges via `executeThreaded()` ein synchroner Callback auf, so dass `executeThreaded()` terminierte und der Rückgabewert anzeigte, dass Callback-Daten benötigt werden (`HBCIExecThreadedStatus.isCallback()``==true`), dann müssen die benötigten Callback-Daten mit `continueThreaded(String)` an den HBCI-Kernel übergeben werden.

Das führt dazu, dass der HBCI-Kernel die übergebenen Callback-Daten an den wartenden HBCI-Thread übergibt (der immer noch mit der Ausführung des HBCI-Dialoges beschäftigt ist und auf Daten von der Anwendung wartet).

Der Rückgabewert von `continueThreaded(String)` ist wieder ein `HBCIExecThreadedStatus`-Objekt (analog zu `executeThreaded()`), welches anzeigt, ob weitere Callback- Daten benötigt werden oder ob der HBCI-Dialog nun beendet ist. Falls weitere Callback-Daten benötigt werden, sind diese wiederum via `continueThreaded(String)` an den HBCI-Kernel zu übergeben, und zwar so lange, bis der HBCI-Dialog tatsächlich beendet ist.

Mehr Informationen zu threaded callbacks in der Datei `README.ThreadedCallbacks`.

### lockKeys

public void lockKeys()

Sperren der Nutzerschlüssel. Das ist nur dann sinnvoll, wenn zwei Bedinungen erfüllt sind:

1. Das verwendete Passport erlaubt die Sperrung der Schlüssel des Nutzers (nur RDH)
2. Im verwendeten Passport sind auch tatsächlich bereits Nutzerschlüssel hinterlegt.

Ist mindestens eine der beiden Bedingungen nicht erfüllt, so wird diese Methode mit einer Exception abgebrochen.

Nach dem erfolgreichen Aufruf dieser Methode muss dieses HBCIHandler-Objekt mit `close()` geschlossen werden. Anschließend muss mit dem gleichen Passport-Objekt ein neues HBCIHandler-Objekt angelegt werden, damit das Passport neu initialisiert wird. Bei dieser Neu-Initialisierung werden neue Nutzerschlüssel für das Passport generiert.

    // ...
    hbciHandle.lockKeys();
    hbciHandle.close();

    hbciHandle=new HBCIHandle(hbciversion,passport);
    // ...

Um die Nutzerschlüssel eines Passport nur zu ändern, kann die Methode `setKeys(java.security.KeyPair,java.security.KeyPair)` oder `newKeys()` aufgerufen werden.

Ab Version 2.4.0 von HBCI4Java muss der HBCIHandler nach dem Schlüsselsperren nicht mehr geschlossen werden. Statt dessen können direkt nach der Schlüsselsperrung neue Schlüssel erzeugt oder manuell gesetzt werden (mit den Methoden `setKeys(java.security.KeyPair,java.security.KeyPair)` bzw. `newKeys()`.

In jedem Fall muss für die neuen Schlüssel, die nach einer Schlüsselsperrung erzeugt werden, ein neuer INI-Brief generiert und an die Bank versandt werden.

### newKeys

public void newKeys()

Erzeugen neuer kryptografischer Schlüssel für den Nutzer. Mit dieser Methode wird für den Nutzer sowohl ein neues Signier- als auch ein neues Chiffrierschlüsselpaar erzeugt. Die neuen Schlüsseldaten werden anschließend automatisch an die Bank übermittelt. Sofern diese Aktion erfolgreich verläuft, werden die neuen Schlüssel in der Passport-Datei (Schlüsseldatei) gespeichert.

ACHTUNG! Vor dieser Aktion sollte unbedingt ein Backup der aktuellen Schlüsseldatei durchgeführt werden. Bei ungünstigen Konstellationen von Fehlermeldungen seitens des Kreditinstitutes kann es nämlich passieren, dass die neuen Schlüssel trotz eingegangener Fehlermeldung gespeichert werden, dann wären aber die alten (noch gültigen) Schlüssel überschrieben.

ACHTUNG! In noch ungünstigeren Fällen kann es auch vorkommen, dass neue Schlüssel generiert und erfolgreich an die Bank übermittelt werden, die neuen Schlüssel aber nicht in der Schlüsseldatei gespeichert werden. Das ist insofern der ungünstigste Fall, da die Bank dann schon die neuen Schlüssel kennt, in der Passport-Datei aber noch die alten Schlüssel enthalten sind und die soeben generierten neuen Schlüssel "aus Versehen" weggeworfen wurden.

### setKeys

public void setKeys(KeyPair sigKey, KeyPair encKey)

Setzen der Nutzerschlüssel auf vorgegebene Daten. Mit dieser Methode wird für den Nutzer sowohl ein neues Signier- als auch ein neues Chiffrierschlüsselpaar gesetzt. Die neuen Schlüsseldaten werden anschließend automatisch an die Bank übermittelt. Sofern diese Aktion erfolgreich verläuft, werden die neuen Schlüssel in der Passport-Datei (Schlüsseldatei) gespeichert.

ACHTUNG! Vor dieser Aktion sollte unbedingt ein Backup der aktuellen Schlüsseldatei durchgeführt werden. Bei ungünstigen Konstellationen von Fehlermeldungen seitens des Kreditinstitutes kann es nämlich passieren, dass die neuen Schlüssel trotz eingegangener Fehlermeldung gespeichert werden, dann wären aber die alten (noch gültigen) Schlüssel überschrieben.

### verifyTAN

public HBCIExecStatus verifyTAN(String customerId)
Key-Management: Überprüfen einer TAN (nur für PinTan-Passports!). Durch den Aufruf dieser Methode wird ein "leerer" HBCI-Dialog (also ein HBCI-Dialog, der nur aus Dialog-Initialisierung und Dialog-Ende besteht) gestartet. Im Verlauf dieses Dialoges wird über den Callback-Mechanismus nach einer TAN gefragt. Diese TAN wird serverseitig auf Gültigkeit überprüft, die Status-Information im Rückgabewert dieser Methode enthalten entsprechende Infos über das Ergebnis dieser Überprüfung.

Parameters:
  `customerId` - Kunden-ID, für die der Dialog ausgeführt werden soll (`null` für aktuelle Kunden-ID)
Returns:
  ein Status-Objekt, anhand dessen der Erfolg oder das Fehlschlagen der TAN-Überprüfung festgestellt werden kann.

### verifyTAN

public HBCIExecStatus verifyTAN()
Entspricht `verifyTAN(null)`.

### reset

public void reset()
Zurücksetzen des Handlers auf den Ausgangszustand. Diese Methode kann aufgerufen werden, wenn alle bisher hinzugefügten Nachrichten und Aufträge wieder entfernt werden sollen. Nach dem Ausführen eines Dialoges mit `execute()` wird diese Methode automatisch aufgerufen.

### getPassport

public HBCIPassport getPassport()
Gibt das Passport zurück, welches in diesem Handle benutzt wird.

Specified by:
  `getPassport` in interface `IHandlerData`
Returns:
  Passport-Objekt, mit dem dieses Handle erzeugt wurde

### getKernel

public HBCIKernel getKernel()
Gibt das HBCI-Kernel-Objekt zurück, welches von diesem HBCI-Handler benutzt wird. Das HBCI-Kernel-Objekt kann u.a. benutzt werden, um alle für die aktuellen HBCI-Version (siehe `getHBCIVersion()`) implementierten Geschäftsvorfälle abzufragen.

Returns:
  HBCI-Kernel-Objekt, mit dem der HBCI-Handler arbeitet

### getMsgGen

public MsgGen getMsgGen()

Specified by:
  `getMsgGen` in interface `IHandlerData`

### getHBCIVersion

public String getHBCIVersion()
Gibt die HBCI-Versionsnummer zurück, für die der aktuelle HBCIHandler konfiguriert ist.

Returns:
  HBCI-Versionsnummer, mit welcher dieses Handler-Objekt arbeitet

### getSupportedLowlevelJobs

public Properties getSupportedLowlevelJobs()

Gibt die Namen aller vom aktuellen HBCI-Zugang (d.h. Passport) unterstützten Lowlevel-Jobs zurück. Alle hier zurückgegebenen Job-Namen können als Argument beim Aufruf der Methode `newLowlevelJob(String)` benutzt werden.

In dem zurückgegebenen Properties-Objekt enthält jeder Eintrag als Key den Lowlevel-Job-Namen; als Value wird die Versionsnummer des jeweiligen Geschäftsvorfalls angegeben, die von HBCI4Java mit dem aktuellen Passport und der aktuell eingestellten HBCI-Version benutzt werden wird.

(Prinzipiell unterstützt HBCI4Java für jeden Geschäftsvorfall mehrere GV-Versionen. Auch eine Bank bietet i.d.R. für jeden GV mehrere Versionen an. Wird mit HBCI4Java ein HBCI-Job erzeugt, so verwendet HBCI4Java immer automatisch die höchste von der Bank unterstützte GV-Versionsnummer. Diese Information ist für den Anwendungsentwickler kaum von Bedeutung und dient hauptsächlich zu Debugging-Zwecken.)

Zum Unterschied zwischen High- und Lowlevel-Jobs siehe die Beschreibung im Package `org.kapott.hbci.GV`.

Returns:
  Sammlung aller vom aktuellen Passport unterstützten HBCI- Geschäftsvorfallnamen (Lowlevel) mit der jeweils von HBCI4Java verwendeten GV-Versionsnummer.

### getLowlevelJobParameterNames

public List<String> getLowlevelJobParameterNames(String gvname)

Gibt alle Parameter zurück, die für einen Lowlevel-Job gesetzt werden können. Wird ein Job mit `newLowlevelJob(String)` erzeugt, so kann der gleiche `gvname` als Argument dieser Methode verwendet werden, um eine Liste aller Parameter zu erhalten, die für diesen Job durch Aufrufe der Methode `HBCIJob.setParam(String,String)` gesetzt werden können bzw. müssen.

Aus der zurückgegebenen Liste ist nicht ersichtlich, ob ein bestimmter Parameter optional ist oder gesetzt werden muss. Das kann aber durch Benutzen des Tools `ShowLowlevelGVs` ermittelt werden.

Jeder Eintrag der zurückgegebenen Liste enthält einen String, welcher als erster Parameter für den Aufruf von `HBCIJob.setParam()` benutzt werden kann - vorausgesetzt, der entsprechende Job wurde mit `newLowlevelJob(String)` erzeugt.

Diese Methode verwendet intern die Methode `HBCIKernel.getLowlevelJobParameterNames(String, String)`. Unterschied ist, dass diese Methode zum einen überprüft, ob der angegebene Lowlevel-Job überhaupt vom aktuellen Passport unterstützt wird. Außerdem wird automatisch die richtige Versionsnummer an `HBCIKernel.getLowlevelJobParameterNames(String, String)` übergeben (nämlich die Versionsnummer, die HBCI4Java auch beim Anlegen eines Jobs via `newLowlevelJob(String)` verwenden wird).

Zur Beschreibung von High- und Lowlevel-Jobs siehe auch die Dokumentation im Package `org.kapott.hbci.GV`.

Parameters:
  `gvname` - der Lowlevel-Jobname, für den eine Liste der Job-Parameter ermittelt werden soll
Returns:
  eine Liste aller Parameter-Bezeichnungen, die in der Methode `HBCIJob.setParam(String,String)` benutzt werden können

### getLowlevelJobResultNames

public List<String> getLowlevelJobResultNames(String gvname)

Gibt eine Liste mit Strings zurück, welche Bezeichnungen für die einzelnen Rückgabedaten eines Lowlevel-Jobs darstellen. Jedem `HBCIJob` ist ein Result-Objekt zugeordnet, welches die Rückgabedaten und Statusinformationen zu dem jeweiligen Job enthält (kann mit `HBCIJob.getJobResult()` ermittelt werden). Bei den meisten Highlevel-Jobs handelt es sich dabei um bereits aufbereitete Daten (Kontoauszüge werden z.B. nicht in dem ursprünglichen SWIFT-Format zurückgegeben, sondern bereits als fertig geparste Buchungseinträge).

Bei Lowlevel-Jobs gibt es diese Aufbereitung der Daten nicht. Statt dessen müssen die Daten manuell aus der Antwortnachricht extrahiert und interpretiert werden. Die einzelnen Datenelemente der Antwortnachricht werden in einem Properties-Objekt bereitgestellt (`HBCIJobResult.getResultData()`). Jeder Eintrag darin enthält den Namen und den Wert eines Datenelementes aus der Antwortnachricht.

Die Methode `getLowlevelJobResultNames()` gibt nun alle gültigen Namen zurück, für welche in dem Result-Objekt Daten gespeichert sein können. Ob für ein Datenelement tatsächlich ein Wert in dem Result-Objekt existiert, wird damit nicht bestimmt, da einzelne Datenelemente optional sind.

Diese Methode verwendet intern die Methode `HBCIKernel.getLowlevelJobResultNames(String, String)`. Unterschied ist, dass diese Methode zum einen überprüft, ob der angegebene Lowlevel-Job überhaupt vom aktuellen Passport unterstützt wird. Außerdem wird automatisch die richtige Versionsnummer an `HBCIKernel.getLowlevelJobResultNames(String, String)` übergeben (nämlich die Versionsnummer, die HBCI4Java auch beim Anlegen eines Jobs via `newLowlevelJob(String)` verwenden wird).

Mit dem Tool `ShowLowlevelGVRs` kann offline eine Liste aller Job-Result-Datenelemente erzeugt werden.

Zur Beschreibung von High- und Lowlevel-Jobs siehe auch die Dokumentation im Package `org.kapott.hbci.GV`.

Parameters:
  `gvname` - Lowlevelname des Geschäftsvorfalls, für den die Namen der Rückgabedaten benötigt werden.
Returns:
  Liste aller möglichen Property-Keys, für die im Result-Objekt eines Lowlevel-Jobs Werte vorhanden sein könnten

### getLowlevelJobRestrictions

public Properties getLowlevelJobRestrictions(String gvname)

Gibt für einen Job alle bekannten Einschränkungen zurück, die bei der Ausführung des jeweiligen Jobs zu beachten sind. Diese Daten werden aus den Bankparameterdaten des aktuellen Passports extrahiert. Sie können von einer HBCI-Anwendung benutzt werden, um gleich entsprechende Restriktionen bei der Eingabe von Geschäftsvorfalldaten zu erzwingen (z.B. die maximale Anzahl von Verwendungszweckzeilen, ob das Ändern von terminierten Überweisungen erlaubt ist usw.).

Die einzelnen Einträge des zurückgegebenen Properties-Objektes enthalten als Key die Bezeichnung einer Restriktion (z.B. "`maxusage`"), als Value wird der entsprechende Wert eingestellt. Die Bedeutung der einzelnen Restriktionen ist zur Zeit nur der HBCI-Spezifikation zu entnehmen. In späteren Programmversionen werden entsprechende Dokumentationen zur internen HBCI-Beschreibung hinzugefügt, so dass dafür eine Abfrageschnittstelle implementiert werden kann.

I.d.R. werden mehrere Versionen eines Geschäftsvorfalles von der Bank angeboten. Diese Methode ermittelt automatisch die "richtige" Versionsnummer für die Ermittlung der GV-Restriktionen aus den BPD (und zwar die selbe, die HBCI4Java beim Erzeugen eines Jobs benutzt).

Siehe dazu auch `HBCIJob.getJobRestrictions()`.

Parameters:
  `gvname` - Lowlevel-Name des Geschäftsvorfalles, für den die Restriktionen ermittelt werden sollen
Returns:
  Properties-Objekt mit den einzelnen Restriktionen

### isSupported

public boolean isSupported(String jobnameHL)

Überprüfen, ein bestimmter Highlevel-Job von der Bank angeboten wird. Diese Methode kann benutzt werden, um vor dem Erzeugen eines `HBCIJob`-Objektes zu überprüfen, ob der gewünschte Job überhaupt von der Bank angeboten wird. Ist das nicht der Fall, so würde der Aufruf von `newJob(String)` zu einer Exception führen.

Eine Liste aller zur Zeit verfügbaren Highlevel-Jobnamen ist in der Paketbeschreibung des Packages `org.kapott.hbci.GV` zu finden. Wird hier nach einem Highlevel-Jobnamen gefragt, der nicht in dieser Liste enthalten ist, so wird eine Exception geworfen.

Mit dieser Methode können nur Highlevel-Jobs überprüft werden. Zum Überprüfen, ob ein bestimmter Lowlevel-Job unterstützt wird, ist die Methode `getSupportedLowlevelJobs()` zu verwenden.

Parameters:
  `jobnameHL` - der Highlevel-Name des Jobs, dessen Unterstützung überprüft werden soll
Returns:
  `true`, wenn dieser Job von der Bank unterstützt wird und mit HBCI4Java verwendet werden kann; ansonsten `false`

### refreshXPD

public HBCIDialogStatus refreshXPD(int selectX)
Abholen der BPD bzw. UPD erzwingen. Beim Aufruf dieser Methode wird automatisch ein HBCI-Dialog ausgeführt, der je nach Wert von `selectX` die BPD und/oder UPD erneut abholt. Alle bis zu diesem Zeitpunkt erzeugten (`HBCIJob.addToQueue()`) und noch nicht ausgeführten Jobs werden dabei wieder aus der Job-Schlange entfernt.

Parameters:
  `selectX` - kann aus einer Kombination (Addition) der Werte `REFRESH_BPD` und `REFRESH_UPD` bestehen
Returns:
  Status-Objekt, welches Informationen über den ausgeführten HBCI-Dialog enthält