HBCICallbackNative (HBCI4Java Dokumentation)

java.lang.Object
- org.kapott.hbci.callback.AbstractHBCICallback
- - org.kapott.hbci.callback.HBCICallbackNative

All Implemented Interfaces:: HBCICallback

public final class HBCICallbackNative
extends AbstractHBCICallback

Callback-Klasse für native-Applikationen, die HBCI4Java durch Aufrufe des JNI benutzen. Diese Klasse wird in Java-Anwendungen selbst nicht benötigt, sondern stellt nur eine Schnittstelle dar, um die Callbacks via JNI zu realisieren.

Diese Klasse überschreibt die drei Methoden log, callback und status. In dieser Klasse werden die jeweiligen Methoden-Aufrufe nicht direkt behandelt, sondern es wird jeweils eine native Methode mit der gleichen Signatur aufgerufen, nur dass sich der Methodenname durch ein vorangestelltes Prefix "native" unterscheidet.

Eine Anwendung muss vor dem Initialisieren des HBCI-Kernels diese nativen Methoden via JNI registrieren. Folgender Programmcode kann als Vorlage für die Verwendung von HBCI4Java-Callbacks aus einer C++-Anwendung heraus dienen:

#include "jni.h"

void myOwnLog(JNIEnv *env,jobject obj,jstring jmsg,jint level,jobject date,jobject trace)
{
    const char *msg=env->GetStringUTFChars(jmsg,NULL);
    printf("log: %s\n",msg);
    env->ReleaseStringUTFChars(jmsg,msg);
}

void myOwnCallback(JNIEnv *env,jobject obj,jobject passport,jint reason,jstring msg,jint datatype,jobject retData)
{
    switch ((int)reason) {
        // ...
    }
}

void myOwnStatus(JNIEnv *env,jobject obj,jobject passport,jint statusTag,jarray o)
{
    printf("status-callback\n");
}

int main(int argc,char **argv)
{
    JavaVM *jvm;
    JNIEnv *env;
    JavaVMInitArgs vm_args;
    JavaVMOption options[1];
    JNINativeMethod methods[3];
    
    // initialize JVM 
    options[0].optionString="-Djava.class.path=/home/kleiner/projects/hbci2/classes";
    vm_args.version=JNI_VERSION_1_4;
    vm_args.options=options;
    vm_args.nOptions=1;
    printf("create: %i\n",JNI_CreateJavaVM(&jvm,(void**)&env,&vm_args));
    
    // build array for registering native callback-methods
    methods[0].name="nativeLog";
    methods[0].signature="(Ljava/lang/String;ILjava/util/Date;Ljava/lang/StackTraceElement;)V";
    methods[0].fnPtr=myOwnLog;
    methods[1].name="nativeCallback";
    methods[1].signature="(Lorg/kapott/hbci/passport/HBCIPassport;ILjava/lang/String;ILjava/lang/StringBuffer;)V";
    methods[1].fnPtr=myOwnCallback;
    methods[2].name="nativeStatus";
    methods[2].signature="(Lorg/kapott/hbci/passport/HBCIPassport;I[Ljava/lang/Object;)V";
    methods[2].fnPtr=myOwnStatus;
    
    // get class HBCICallbackNative
    jclass callbacknative=env->FindClass("org/kapott/hbci/callback/HBCICallbackNative");
    printf("callbacknative: %p\n",callbacknative);
    
    // register native methods
    printf("register: %i\n",env->RegisterNatives(callbacknative,methods,3));
    
    // get constructor for HBCICallbackNative
    jmethodID callbacknative_init=env->GetMethodID(callbacknative,"","()V");
    printf("callbacknative_init: %p\n",callbacknative_init);
    
    // create new HBCICallbackNative-object
    jobject callback=env->NewObject(callbacknative,callbacknative_init);
    printf("callback: %p\n",callback);
    
    // get class HBCIUtils
    jclass utils=env->FindClass("org/kapott/hbci/manager/HBCIUtils");
    printf("utils: %p\n",utils);
    
    // get method HBCIUtils.setParam()
    jmethodID utils_setparam=env->GetStaticMethodID(utils,"setParam","(Ljava/lang/String;Ljava/lang/String;)V");
    printf("utils_setparam: %p\n",utils_setparam);

    // set loglevel to DEBUG
    jstring name=env->NewStringUTF("log.loglevel.default");
    jstring value=env->NewStringUTF("4");
    env->CallStaticVoidMethod(utils,utils_setparam,name,value);
    
    // get method HBCIUtils.init()
    jmethodID utils_init=env->GetStaticMethodID(utils,"init","(Ljava/lang/ClassLoader;Ljava/lang/String;Lorg/kapott/hbci/callback/HBCICallback;)V");
    printf("utils_init: %p\n",utils_init);
    
    // call HBCIUtils.init()
    env->CallStaticVoidMethod(utils,utils_init,NULL,NULL,callback);
    
    // ...
    // do HBCI stuff here
    // ...
    
    jvm->DestroyJavaVM();
}

Field Summary
- Fields inherited from interface org.kapott.hbci.callback.HBCICallback
  CLOSE_CONNECTION, HAVE_CHIPCARD, HAVE_CRC_ERROR, HAVE_ERROR, HAVE_HARDPIN, HAVE_IBAN_ERROR, HAVE_INST_MSG, HAVE_NEW_MY_KEYS, NEED_BLZ, NEED_CHIPCARD, NEED_CONNECTION, NEED_COUNTRY, NEED_CUSTOMERID, NEED_FILTER, NEED_HARDPIN, NEED_HOST, NEED_INFOPOINT_ACK, NEED_NEW_INST_KEYS_ACK, NEED_PASSPHRASE_LOAD, NEED_PASSPHRASE_SAVE, NEED_PORT, NEED_PROXY_PASS, NEED_PROXY_USER, NEED_PT_PHOTOTAN, NEED_PT_PIN, NEED_PT_SECMECH, NEED_PT_TAN, NEED_PT_TANMEDIA, NEED_REMOVE_CHIPCARD, NEED_SIZENTRY_SELECT, NEED_SOFTPIN, NEED_USERID, STATUS_DIALOG_END, STATUS_DIALOG_END_DONE, STATUS_DIALOG_INIT, STATUS_DIALOG_INIT_DONE, STATUS_INIT_SIGID, STATUS_INIT_SIGID_DONE, STATUS_INIT_SYSID, STATUS_INIT_SYSID_DONE, STATUS_INIT_UPD, STATUS_INIT_UPD_DONE, STATUS_INST_BPD_INIT, STATUS_INST_BPD_INIT_DONE, STATUS_INST_GET_KEYS, STATUS_INST_GET_KEYS_DONE, STATUS_LOCK_KEYS, STATUS_LOCK_KEYS_DONE, STATUS_MSG_CREATE, STATUS_MSG_CRYPT, STATUS_MSG_DECRYPT, STATUS_MSG_PARSE, STATUS_MSG_RAW_RECV, STATUS_MSG_RAW_SEND, STATUS_MSG_RECV, STATUS_MSG_SEND, STATUS_MSG_SIGN, STATUS_MSG_VERIFY, STATUS_SEND_INFOPOINT_DATA, STATUS_SEND_KEYS, STATUS_SEND_KEYS_DONE, STATUS_SEND_TASK, STATUS_SEND_TASK_DONE, TYPE_BOOLEAN, TYPE_NONE, TYPE_SECRET, TYPE_TEXT, USERID_CHANGED, WRONG_PIN

Constructor Summary

Constructors
Constructor and Description

HBCICallbackNative()

Constructors
Constructor and Description
`HBCICallbackNative()`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`callback(HBCIPassport passport, int reason, java.lang.String msg, int datatype, java.lang.StringBuffer retData)` Ruft `nativeCallback(HBCIPassport, int, String, int, StringBuffer)` auf.
`void`	`log(java.lang.String msg, int level, java.util.Date date, java.lang.StackTraceElement trace)` Ruft `nativeLog(String, int, Date, StackTraceElement)` auf.
`void`	`nativeCallback(HBCIPassport passport, int reason, java.lang.String msg, int datatype, java.lang.StringBuffer retData)` Externe, von der Anwendung zu implementierende Methode.
`void`	`nativeLog(java.lang.String msg, int level, java.util.Date date, java.lang.StackTraceElement trace)` Externe, von der Anwendung zu implementierende Methode.
`void`	`nativeStatus(HBCIPassport passport, int statusTag, java.lang.Object[] o)` Externe, von der Anwendung zu implementierende Methode.
`void`	`status(HBCIPassport passport, int statusTag, java.lang.Object[] o)` Ruft `nativeStatus(HBCIPassport, int, Object[])` auf.

Methods inherited from class org.kapott.hbci.callback.AbstractHBCICallback
createDefaultLogLine, status, useThreadedCallback

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - HBCICallbackNative
```
public HBCICallbackNative()
```
- Method Detail
  - nativeLog
```
public void nativeLog(java.lang.String msg,
                      int level,
                      java.util.Date date,
                      java.lang.StackTraceElement trace)
```
    Externe, von der Anwendung zu implementierende Methode. Es muss von der nativen Anwendung eine Methode mit dieser Signatur erzeugt und via JNI registriert werden.
  - nativeCallback
```
public void nativeCallback(HBCIPassport passport,
                           int reason,
                           java.lang.String msg,
                           int datatype,
                           java.lang.StringBuffer retData)
```
    Externe, von der Anwendung zu implementierende Methode. Es muss von der nativen Anwendung eine Methode mit dieser Signatur erzeugt und via JNI registriert werden.
  - nativeStatus
```
public void nativeStatus(HBCIPassport passport,
                         int statusTag,
                         java.lang.Object[] o)
```
    Externe, von der Anwendung zu implementierende Methode. Es muss von der nativen Anwendung eine Methode mit dieser Signatur erzeugt und via JNI registriert werden.
  - log
```
public void log(java.lang.String msg,
                int level,
                java.util.Date date,
                java.lang.StackTraceElement trace)
```
    Ruft nativeLog(String, int, Date, StackTraceElement) auf.
    Parameters:
    
    msg - die eigentliche Text-Meldung des HBCI-Kernels
    level - Loglevel, welcher die "Wichtigkeit" dieser Meldung angibt. Die möglichen Werte dafür sind in HBCIUtils definiert und lauten
    
    LOG_CHIPCARD
    
    LOG_DEBUG
    
    LOG_INFO
    
    LOG_WARN
    
    LOG_ERR
    date - Zeitpunkt, zu dem die Logausgabe generiert wurde
    
    trace - ein StackTrace-Element, welches die Stelle im Code beschreibt, an der die Logausgabe erzeugt wurde (kann benutzt werden, um die Klasse, Methode, Zeilennummer etc. des Aufrufes zu ermitteln)
  - callback
```
public void callback(HBCIPassport passport,
                     int reason,
                     java.lang.String msg,
                     int datatype,
                     java.lang.StringBuffer retData)
```
    Ruft nativeCallback(HBCIPassport, int, String, int, StringBuffer) auf.
    
    Parameters:
    
    passport - enthält das Passport-Objekt, bei dessen Benutzung der Callback erzeugt wurde. Falls also in einer Anwendung mehrere Passport-Objekte gleichzeitig benutzt werden, so kann anhand dieses Parameters festgestellt werden, welches Passport (und damit welches HBCIHandle) HBCI4Java gerade benutzt.
    
    reason - gibt den Grund für diesen Aufruf an. Dieser Parameter kann alle Werte annehmen, die als "Ursache des Callback-Aufrufes" in der Dokumentation aufgeführt sind. Je nach Wert dieses Parameters werden vom Nutzer Aktionen oder Eingaben erwartet.
    
    msg - ein Hinweistext, der den Grund des Callbacks näher beschreibt. Dieser Parameter muss nicht ausgewertet werden, der Parameter reason ist bereits eindeutig. Er dient nur dazu, bei Anwendungen, die nicht für jeden Ursache des Callback-Aufrufes einen eigenen Hinweistext bereitstellen wollen, eine Art default-Wert für den anzuzeigenden Text bereitzustellen.
    
    datatype - legt fest, welchen Datentyp die vom HBCI-Kernel erwarteten Antwortdaten haben müssen. Ist dieser Wert gleich TYPE_NONE, so werden keine Antwortdaten (also keine Nutzereingabe) erwartet, bei TYPE_SECRET und TYPE_TEXT wird ein normaler String erwartet.
    Der Unterschied zwischen beiden ist der, dass bei TYPE_SECRET sensible Daten (Passwörter usw.) eingegeben werden sollen, so dass die Eingaberoutine evtl. anders arbeiten muss (z.B. Sternchen anstatt dem eingegebenen Text darstellen).
    
    retData - In diesem StringBuffer-Objekt müssen die Antwortdaten abgelegt werden. Beim Aufruf der Callback-Methode von HBCI4Java wird dieser StringBuffer u.U. mit einem vorgeschlagenen default-Wert für die Nutzereingabe gefüllt.
  - status
```
public void status(HBCIPassport passport,
                   int statusTag,
                   java.lang.Object[] o)
```
    Ruft nativeStatus(HBCIPassport, int, Object[]) auf.
    
    Parameters:
    
    passport - gibt an, welches Passport (und damit welches HBCIHandle) benutzt wurde, als der Callback erzeugt wurde (siehe auch HBCICallback.callback(org.kapott.hbci.passport.HBCIPassport,int,String,int,StringBuffer)).
    
    statusTag - gibt an, welche Stufe der Abarbeitung gerade erreicht wurde (alle oben beschriebenen Konstanten, die mit STATUS_ beginnen)
    
    o - ein Array aus Objekten, das zusätzliche Informationen zum jeweiligen Status enthält. In den meisten Fällen handelt es sich um einen String, der zusätzliche Informationen im Klartext enthält. Welche Informationen das jeweils sind, ist der Beschreibung zu den einzelnen STATUS_*-Tag-Konstanten zu entnehmen.

Class HBCICallbackNative

Field Summary

Fields inherited from interface org.kapott.hbci.callback.HBCICallback

Constructor Summary

Method Summary

Methods inherited from class org.kapott.hbci.callback.AbstractHBCICallback

Methods inherited from class java.lang.Object

Constructor Detail

HBCICallbackNative

Method Detail

nativeLog

nativeCallback

nativeStatus

log

callback

status