ERiC API-Referenz 43.3.2.0

Lade ...
Suche ...
Keine Treffer
Funktionen
ericmtapi.h-Dateireferenz

Deklaration der ERiC API-Funktionen für die Multithreading-API. Mehr ...

`#include "platform.h"`
`#include "ericapiExport.h"`
`#include "eric_types.h"`
`#include "ericdef.h"`
Include-Abhängigkeitsdiagramm für ericmtapi.h:

gehe zum Quellcode dieser Datei

## Funktionen
ERICAPI_IMPORT int | EricMtBearbeiteVorgang (EricInstanzHandle instanz, const char *datenpuffer, const char *datenartVersion, uint32_t bearbeitungsFlags, const eric_druck_parameter_t *druckParameter, const eric_verschluesselungs_parameter_t *cryptoParameter, EricTransferHandle *transferHandle, EricRueckgabepufferHandle rueckgabeXmlPuffer, EricRueckgabepufferHandle serverantwortXmlPuffer)
| Diese API-Funktion ist die zentrale Schnittstellenfunktion zur Kommunikation mit dem ELSTER-Annahmeserver.
ERICAPI_IMPORT int | EricMtChangePassword (EricInstanzHandle instanz, const byteChar *psePath, const byteChar *oldPin, const byteChar *newPin)
| Die PIN für ein clientseitig erzeugtes Zertifikat (CEZ) wird geändert.
ERICAPI_IMPORT int | EricMtPruefeBuFaNummer (EricInstanzHandle instanz, const byteChar *steuernummer)
| Die Bundesfinanzamtsnummer wird überprüft.
ERICAPI_IMPORT int | EricMtCheckXML (EricInstanzHandle instanz, const char *xml, const char *datenartVersion, EricRueckgabepufferHandle fehlertextPuffer)
| Das `xml` wird gegen das Schema der `datenartVersion` validiert.
ERICAPI_IMPORT int | EricMtCloseHandleToCertificate (EricInstanzHandle instanz, EricZertifikatHandle hToken)
| Das Zertifikat-Handle `hToken` wird freigegeben.
ERICAPI_IMPORT int | EricMtCreateKey (EricInstanzHandle instanz, const byteChar *pin, const byteChar *pfad, const eric_zertifikat_parameter_t *zertifikatInfo)
| Es werden die Kryptomittel für ein clientseitig erzeugtes Zertifikat (CEZ) in einem Verzeichnis des Dateisystems erstellt.
ERICAPI_IMPORT int | EricMtCreateTH (EricInstanzHandle instanz, const char *xml, const char *verfahren, const char *datenart, const char *vorgang, const char *testmerker, const char *herstellerId, const char *datenLieferant, const char *versionClient, const byteChar *publicKey, EricRueckgabepufferHandle xmlRueckgabePuffer)
| Diese Funktion erzeugt einen TransferHeader.
ERICAPI_IMPORT int | EricMtCreateUUID (EricInstanzHandle instanz, EricRueckgabepufferHandle uuidRueckgabePuffer)
| Erzeugt einen Version 4 Universally Unique Identifier (UUID) gemäß RFC 4122.
ERICAPI_IMPORT int | EricMtDekodiereDaten (EricInstanzHandle instanz, EricZertifikatHandle zertifikatHandle, const byteChar *pin, const byteChar *base64Eingabe, EricRueckgabepufferHandle rueckgabePuffer)
| Es werden die mit der Datenabholung abgeholten und verschlüsselten Daten entschlüsselt.
ERICAPI_IMPORT int | EricMtEinstellungAlleZuruecksetzen (EricInstanzHandle instanz)
| Alle Einstellungen, der übergebenen ERiC-Instanz werden auf den jeweiligen Standardwert zurückgesetzt.
ERICAPI_IMPORT int | EricMtEinstellungLesen (EricInstanzHandle instanz, const char *name, EricRueckgabepufferHandle rueckgabePuffer)
| Der Wert der API-Einstellung `name` wird im `rueckgabePuffer` zurückgeliefert.
ERICAPI_IMPORT int | EricMtEinstellungSetzen (EricInstanzHandle instanz, const char *name, const char *wert)
| Die API-Einstellung `name` wird auf den `wert` gesetzt.
ERICAPI_IMPORT int | EricMtEinstellungZuruecksetzen (EricInstanzHandle instanz, const char *name)
| Der Wert der API-Einstellung `name` wird auf den Standardwert zurückgesetzt.
ERICAPI_IMPORT int | EricMtEntladePlugins (EricInstanzHandle instanz)
| Für die übergebene ERiC-Instanz werden alle verwendeten Plugin-Bibliotheken entladen und deren Speicher wird freigegeben.
ERICAPI_IMPORT int | EricMtFormatEWAz (EricInstanzHandle instanz, const byteChar *ewAzElster, EricRueckgabepufferHandle ewAzBescheidPuffer)
| Konvertiert ein Einheitswert-Aktenzeichen im ELSTER-Format in ein landesspezifisches Bescheidformat.
ERICAPI_IMPORT int | EricMtFormatStNr (EricInstanzHandle instanz, const byteChar *eingabeSteuernummer, EricRueckgabepufferHandle rueckgabePuffer)
| Die Steuernummer `eingabeSteuernummer` wird in das Bescheid-Format des jeweiligen Bundeslandes umgewandelt.
ERICAPI_IMPORT int | EricMtGetAuswahlListen (EricInstanzHandle instanz, const char *datenartVersion, const char *feldkennung, EricRueckgabepufferHandle rueckgabeXmlPuffer)
| Die Auswahlliste(n) für `datenartVersion` oder `feldkennung` wird zurückgeliefert.
ERICAPI_IMPORT int | EricMtGetErrormessagesFromXMLAnswer (EricInstanzHandle instanz, const char *xml, EricRueckgabepufferHandle transferticketPuffer, EricRueckgabepufferHandle returncodeTHPuffer, EricRueckgabepufferHandle fehlertextTHPuffer, EricRueckgabepufferHandle returncodesUndFehlertexteNDHXmlPuffer)
| Aus dem Antwort-XML des Finanzamtservers wird das Transferticket und Returncodes/Fehlermeldungen zurückgegeben.
ERICAPI_IMPORT int | EricMtGetHandleToCertificate (EricInstanzHandle instanz, EricZertifikatHandle *hToken, uint32_t *iInfoPinSupport, const byteChar *pathToKeystore)
| Für das übergebene Zertifikat in `pathToKeystore` wird das Handle `hToken` und die unterstützten PIN-Werte `iInfoPinSupport` zurückgeliefert.
ERICAPI_IMPORT int | EricMtZertifikatOeffnenAusBytes (EricInstanzHandle instanz, EricZertifikatHandle *hToken, const byteChar *pkcs12Container, uint32_t containerGroesse, const byteChar *pkcs12Passwort)
| Für das im Speicher übergebene Zertifikat wird das Handle `hToken` zurückgeliefert.
ERICAPI_IMPORT int | EricMtGetPinStatus (EricInstanzHandle instanz, EricZertifikatHandle hToken, uint32_t *pinStatus, uint32_t keyType)
| Der PIN-Status wird für ein passwortgeschütztes Kryptomittel abgefragt und in `pinStatus` zurückgegeben.
ERICAPI_IMPORT int | EricMtGetPublicKey (EricInstanzHandle instanz, const eric_verschluesselungs_parameter_t *cryptoParameter, EricRueckgabepufferHandle rueckgabePuffer)
| Es wird der öffentliche Schlüssel als base64-kodierte Zeichenkette für das übergebene Zertifikat-Handle in `cryptoParameter` zurückgeliefert. Von den beiden öffentlichen Schlüsseln, die in ELSTER-Zertifikaten enthalten sind, wird der Verschlüsselungsschlüssel (Encryption Key) zurückgegeben.
ERICAPI_IMPORT int | EricMtHoleFehlerText (EricInstanzHandle instanz, int fehlerkode, EricRueckgabepufferHandle rueckgabePuffer)
| Es wird die Klartextfehlermeldung zu dem `fehlerkode` ermittelt.
ERICAPI_IMPORT int | EricMtHoleFinanzaemter (EricInstanzHandle instanz, const byteChar *finanzamtLandNummer, EricRueckgabepufferHandle rueckgabeXmlPuffer)
| Es wird die Finanzamtliste für eine bestimmte `finanzamtLandNummer` zurückgegeben.
ERICAPI_IMPORT int | EricMtHoleFinanzamtLandNummern (EricInstanzHandle instanz, EricRueckgabepufferHandle rueckgabeXmlPuffer)
| Die Liste aller Finanzamtlandnummern wird zurückgegeben.
ERICAPI_IMPORT int | EricMtHoleFinanzamtsdaten (EricInstanzHandle instanz, const byteChar bufaNr[5], EricRueckgabepufferHandle rueckgabeXmlPuffer)
| Die `finanzamtsdaten` werden für eine Bundesfinanzamtsnummer zurückgegeben.
ERICAPI_IMPORT int | EricMtHoleTestfinanzaemter (EricInstanzHandle instanz, EricRueckgabepufferHandle rueckgabeXmlPuffer)
| Die Testfinanzamtliste wird in `rueckgabeXmlPuffer` zurückgegeben.
ERICAPI_IMPORT int | EricMtHoleZertifikatEigenschaften (EricInstanzHandle instanz, EricZertifikatHandle hToken, const byteChar *pin, EricRueckgabepufferHandle rueckgabeXmlPuffer)
| Die Eigenschaften des übergebenen Zertifikats werden im `rueckgabeXmlPuffer` zurückgegeben.
ERICAPI_IMPORT int | EricMtHoleZertifikatFingerabdruck (EricInstanzHandle instanz, const eric_verschluesselungs_parameter_t *cryptoParameter, EricRueckgabepufferHandle fingerabdruckPuffer, EricRueckgabepufferHandle signaturPuffer)
| Der Fingerabdruck und dessen Signatur wird für das übergebene Zertifikat zurückgegeben.
ERICAPI_IMPORT EricInstanzHandle | EricMtInstanzErzeugen (const char *pluginPfad, const char *logPfad)
| Erstellt und initialisiert eine neue ERiC-Instanz.
ERICAPI_IMPORT int | EricMtInstanzFreigeben (EricInstanzHandle instanz)
| Die übergebene ERiC-Instanz wird beendet und deren Speicher freigegeben.
ERICAPI_IMPORT int | EricMtMakeElsterStnr (EricInstanzHandle instanz, const byteChar *steuernrBescheid, const byteChar landesnr[2+1], const byteChar bundesfinanzamtsnr[4+1], EricRueckgabepufferHandle steuernrPuffer)
| Es wird eine Steuernummer im ELSTER-Steuernummerformat erzeugt.
ERICAPI_IMPORT int | EricMtMakeElsterEWAz (EricInstanzHandle instanz, const byteChar *ewAzBescheid, const byteChar *landeskuerzel, EricRueckgabepufferHandle ewAzElsterPuffer)
| Konvertiert ein Einheitswert-Aktenzeichen in das ELSTER-Format.
ERICAPI_IMPORT int | EricMtPruefeBIC (EricInstanzHandle instanz, const byteChar *bic)
| Die `bic` wird auf Gültigkeit überprüft.
ERICAPI_IMPORT int | EricMtPruefeIBAN (EricInstanzHandle instanz, const byteChar *iban)
| Die `iban` wird auf Gültigkeit überprüft.
ERICAPI_IMPORT int | EricMtPruefeEWAz (EricInstanzHandle instanz, const byteChar *einheitswertAz)
| Überprüft ein `Einheitswert-Aktenzeichen` im ELSTER-Format auf Gültigkeit.
ERICAPI_IMPORT int | EricMtPruefeIdentifikationsMerkmal (EricInstanzHandle instanz, const byteChar *steuerId)
| Die `steuerId` wird auf Gültigkeit überprüft.
ERICAPI_IMPORT int | EricMtPruefeSteuernummer (EricInstanzHandle instanz, const byteChar *steuernummer)
| Die `steuernummer` wird einschließlich Bundesfinanzamtsnummer auf formale Richtigkeit geprüft.
ERICAPI_IMPORT int | EricMtPruefeWIdNr (EricInstanzHandle instanz, const byteChar *wIdNr)
| Die `Wirtschafts-Identifikationsnummer` (`W-IdNr`.) wird auf formale Gültigkeit überprüft.
ERICAPI_IMPORT int | EricMtPruefeZertifikatPin (EricInstanzHandle instanz, const byteChar *pathToKeystore, const byteChar *pin, uint32_t keyType)
| Prüft, ob die `pin` zum Zertifikat `pathToKeystore` passt. Nicht anwendbar auf Ad Hoc-Zertifikate (AHZ), die für einen neuen Personalausweis (nPA) ausgestellt sind.
ERICAPI_IMPORT int | EricMtRegistriereFortschrittCallback (EricInstanzHandle instanz, EricFortschrittCallback funktion, void *benutzerdaten)
| Die `funktion` wird als Callback-Funktion für EricMtBearbeiteVorgang() registriert.
ERICAPI_IMPORT int | EricMtRegistriereGlobalenFortschrittCallback (EricInstanzHandle instanz, EricFortschrittCallback funktion, void *benutzerdaten)
| Die registrierte `funktion` wird als Callback-Funktion von EricMtBearbeiteVorgang() aufgerufen und zeigt den Gesamtfortschritt der Verarbeitung an.
ERICAPI_IMPORT int | EricMtRegistriereLogCallback (EricInstanzHandle instanz, EricLogCallback funktion, uint32_t schreibeEricLogDatei, void *benutzerdaten)
| Die registrierte `funktion` wird als Callback-Funktion für jede Lognachricht aufgerufen. Die Ausgabe entspricht einer Zeile im eric.log.
ERICAPI_IMPORT EricRueckgabepufferHandle | EricMtRueckgabepufferErzeugen (EricInstanzHandle instanz)
| Diese API-Funktion erzeugt einen Rückgabepuffer und gibt ein Handle darauf zurück.
ERICAPI_IMPORT int | EricMtRueckgabepufferFreigeben (EricInstanzHandle instanz, EricRueckgabepufferHandle handle)
| Der durch das `handle` bezeichnete Rückgabepuffer wird freigegeben.
ERICAPI_IMPORT const char * | EricMtRueckgabepufferInhalt (EricInstanzHandle instanz, EricRueckgabepufferHandle handle)
| Der durch das `handle` bezeichnete Inhalt des Rückgabepuffers wird zurückgegeben.
ERICAPI_IMPORT uint32_t | EricMtRueckgabepufferLaenge (EricInstanzHandle instanz, EricRueckgabepufferHandle handle)
| Die Länge des Rückgabepufferinhalts wird zurückgegeben.
ERICAPI_IMPORT int | EricMtSystemCheck (EricInstanzHandle instanz)
| Es werden Plattform-, Betriebssystem- und ERiC-Informationen ausgegeben.
ERICAPI_IMPORT int | EricMtVersion (EricInstanzHandle instanz, EricRueckgabepufferHandle rueckgabeXmlPuffer)
| Es wird eine Liste sämtlicher Produkt- und Dateiversionen der verwendeten ERiC-Bibliotheken als XML-Daten zurückgegeben.

## Ausführliche Beschreibung

Deklaration der ERiC API-Funktionen für die Multithreading-API.

Definiert in Datei ericmtapi.h.

## Dokumentation der Funktionen

## ◆ EricMtBearbeiteVorgang()

ERICAPI_IMPORT int EricMtBearbeiteVorgang | ( | EricInstanzHandle | instanz,
|  | const char * | datenpuffer,
|  | const char * | datenartVersion,
|  | uint32_t | bearbeitungsFlags,
|  | const eric_druck_parameter_t * | druckParameter,
|  | const eric_verschluesselungs_parameter_t * | cryptoParameter,
|  | EricTransferHandle * | transferHandle,
|  | EricRueckgabepufferHandle | rueckgabeXmlPuffer,
|  | EricRueckgabepufferHandle | serverantwortXmlPuffer )

Diese API-Funktion ist die zentrale Schnittstellenfunktion zur Kommunikation mit dem ELSTER-Annahmeserver.

Als Austauschformat wird XML verwendet, siehe Kap. "Datenverarbeitung mit ERiC" im ERiC-Entwicklerhandbuch.pdf. Dort sind die Arbeitsabläufe von Einzel- und Sammellieferung beschrieben.

Die Funktion kann Steuerdaten plausibilisieren, an den ELSTER-Annahmeserver übertragen und ausdrucken, sowie Protokolle der Übertragung erzeugen. Die ProcessingFlags im Parameter `bearbeitungsFlags` definieren, welche der Schritte wie ausgeführt werden.

Je nach Anwendungsfall können die Daten authentifiziert übertragen werden und es kann ein PDF-Druck der Daten erfolgen. In diesen Fällen sind die Parameter `cryptoParameter` und `druckParameter` entsprechend zu befüllen. Die möglichen Parameterkombinationen und Druckkennzeichnungen können im ERiC-Entwicklerhandbuch.pdf nachgelesen werden.

Sind für einen Anwendungsfall mehrere voneinander abhängige Aufrufe von EricMtBearbeiteVorgang() nötig, so ist der Parameter `transferHandle` zu übergeben. Dies ist derzeit nur für die Datenabholung der Fall.

Es werden an bestimmten Punkten der Verarbeitung benutzerdefinierte Callback Funktionen aufgerufen. Siehe hierzu Fortschrittcallbacks.

Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | datenpuffer | Enthält die zu verarbeitenden XML-Daten.
  [in] | datenartVersion | Die `datenartVersion` ist der Datenartversionmatrix.xml zu entnehmen. Dieser Parameter darf nicht NULL sein und muss zu den XML-Eingangsdaten passen. Siehe auch ERiC-Entwicklerhandbuch.pdf.
  [in] | bearbeitungsFlags | Oder-Verknüpfung von Bearbeitungsvorgaben. Anhand dieser Vorgaben werden die übergebenen Daten verarbeitet. Der Parameter darf nicht 0 sein, zu gültigen Werten siehe eric_bearbeitung_flag_t. Bei welchen Anwendungsfällen welche Flags möglich oder notwendig sind, ist im ERiC-Entwicklerhandbuch.pdf nachzulesen.
  [in] | druckParameter | Parameter, der für den PDF-Druck benötigt wird, siehe eric_druck_parameter_t. Bei welchen Anwendungsfällen der Druckparameter möglich oder notwendig ist, ist im ERiC-Entwicklerhandbuch.pdf nachzulesen. Soll kein PDF-Druck erfolgen, so ist NULL zu übergeben.
  [in] | cryptoParameter | Enthält die für den authentifizierten Versand benötigten Informationen und darf nur dann übergeben werden, siehe eric_verschluesselungs_parameter_t. Erfolgt kein authentifizierter Versand, so ist NULL zu übergeben.
  [in,out] | transferHandle | Bei der Datenabholung ist ein Zeiger auf ein vom Aufrufer verwaltetes und anfangs mit 0 befülltes EricTransferHandle zu übergeben, über das die zusammenhängenden Versandvorgänge einer Datenabholung gebündelt werden (Bündelung der Versandvorgänge "Anforderung", "Abholung" und optional "Quittierung"). Wenn bei der Datenabholung kein Versandflag gesetzt ist (nur Validierung), darf dem transferHandle auch ein Nullzeiger (NULL) übergeben werden. Bei allen anderen Anwendungsfällen ist immer NULL zu übergeben.
  [out] | rueckgabeXmlPuffer | Handle auf einen Rückgabepuffer, in den beim Versand Telenummer und Ordnungsbegriff, Hinweise oder Fehler bei der Regelprüfung geschrieben werden. Siehe Inhalt des Rückgabepuffers und des Serverantwortpuffers und EricRueckgabepufferHandle.
  [out] | serverantwortXmlPuffer | Handle auf einen Rückgabepuffer, in den beim Versand die Antwort des Empfangsservers geschrieben wird. Siehe Inhalt des Rückgabepuffers und des Serverantwortpuffers und EricRueckgabepufferHandle.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_UNGUELTIGER_PARAMETER
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_DATENARTVERSION_UNBEKANNT
  - ERIC_GLOBAL_VERSCHLUESSELUNGS_PARAMETER_NICHT_ANGEGEBEN
  - ERIC_GLOBAL_PRUEF_FEHLER Plausibilitätsfehler in den Eingabedaten, die Fehlermeldungen werden im Rückgabepuffer `rueckgabeXmlPuffer` zurückgegeben. Siehe Abschnitt Plausibilitätsfehler.
  - ERIC_GLOBAL_HINWEISE Kann nur zurückgegeben werden, falls das Bearbeitungsflag ERIC_PRUEFE_HINWEISE angegeben wurde. Es wurden ausschließlich Hinweise zu den Eingabedaten gemeldet, die Hinweise werden im Rückgabepuffer `rueckgabeXmlPuffer` zurückgegeben. Siehe Abschnitt Hinweise.
  - ERIC_GLOBAL_DATENSATZ_ZU_GROSS Die maximal zulässige Größe des XML-Eingangsdatensatzes oder des zu übermittelnden, komprimierten, verschlüsselten und base64-kodierten Datenteils, siehe ERiC-Entwicklerhandbuch.pdf, Kap. "Größenbegrenzung der Eingangsdaten", ist überschritten.
  - ERIC_TRANSFER_ERR_XML_THEADER, ERIC_TRANSFER_ERR_XML_NHEADER Die Serverantwort enthält Fehlermeldungen. Zur Auswertung kann entweder die Serverantwort selbst ausgewertet werden oder es wird EricMtGetErrormessagesFromXMLAnswer() aufgerufen.
  - ERIC_IO_READER_SCHEMA_VALIDIERUNGSFEHLER
  - ERIC_IO_PARSE_FEHLER
  - ERIC_GLOBAL_COMMONDATA_NICHT_VERFUEGBAR
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - weitere, siehe eric_fehlercodes.h

# Inhalt des Rückgabepuffers und des Serverantwortpuffers

Der Inhalt der Pufferspeicher kann mit EricMtRueckgabepufferInhalt() abgefragt und ausgewertet werden. `rueckgabeXmlPuffer` gibt im Erfolgsfall oder bei Plausibilitätsfehler XML-Daten nach Schema Dokumentation\API-Rueckgabe-Schemata\EricBearbeiteVorgang.xsd zurück. `serverantwortXmlPuffer` gibt bei Sendevorgängen die Antwort des ELSTER- Annahmeservers zurück.

Nach dem Aufruf der Funktion müssen programmatisch folgende Fälle aufgrund des Rückgabewerts unterschieden werden.

## Erfolgsfall

Sind alle Bearbeitungsschritte fehlerfrei durchlaufen worden, dann ist der Rückgabewert ERIC_OK und der Text im Pufferspeicher `rueckgabeXmlPuffer` enthält beim Versand XML-Daten mit generierter Telenummer und bei Neuaufnahmen den Ordnungsbegriff.

Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<EricBearbeiteVorgang xmlns="http://www.elster.de/EricXML/1.1/EricBearbeiteVorgang">
<Erfolg>
<Telenummer>N55</Telenummer>
</Erfolg>
</EricBearbeiteVorgang>

Beim Versand befindet sich zusätzlich im Pufferspeicher `serverantwortXmlPuffer` die Antwort des ELSTER-Annahmeservers. Bei einer Datenabholung kann diese ausgewertet werden. Details hierzu befinden sich im ERiC-Entwicklerhandbuch.pdf

## Hinweise

Falls das Bearbeitungsflag ERIC_PRUEFE_HINWEISE angegeben worden ist, kann der Rückgabewert ERIC_GLOBAL_HINWEISE zurückgegeben werden. Der Rückgabepuffer enthält dann die gemeldeten Hinweise.

Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<EricBearbeiteVorgang xmlns="http://www.elster.de/EricXML/1.1/EricBearbeiteVorgang">
<Hinweis>
<Nutzdatenticket>1075</Nutzdatenticket>
<Feldidentifikator>100001</Feldidentifikator>
<Mehrfachzeilenindex>1</Mehrfachzeilenindex>
<LfdNrVordruck>1</LfdNrVordruck>
<VordruckZeilennummer>4</VordruckZeilennummer>
<SemantischerIndex>PersonA</SemantischerIndex>
<Untersachbereich>5</Untersachbereich>
<RegelName>testRegelName</RegelName>
<FachlicheHinweisId>9995</FachlicheHinweisId>
<Text>Weitere Angaben können erforderlich sein</Text>
</Hinweis>
</EricBearbeiteVorgang>

Die einzelnen Elemente sind in der Schemadefinition Dokumentation\API-Rueckgabe-Schemata\EricBearbeiteVorgang.xsd dokumentiert. Wenn die Bearbeitungsflags ERIC_PRUEFE_HINWEISE und ERIC_VALIDIERE übergeben worden sind, wurden bei der Plausibilisierung keine Fehler gefunden. Es sind keine Fehler im Rückgabepuffer enthalten.

## Plausibilitätsfehler

Bei fehlgeschlagener Plausibilitätsprüfung ist der Rückgabewert ERIC_GLOBAL_PRUEF_FEHLER, und die Fehler werden im Rückgabepuffer als XML-Daten zurückgeliefert.

Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<EricBearbeiteVorgang xmlns="http://www.elster.de/EricXML/1.1/EricBearbeiteVorgang">
<FehlerRegelpruefung>
<Nutzdatenticket>1075</Nutzdatenticket>
<Feldidentifikator>100001</Feldidentifikator>
<Mehrfachzeilenindex>1</Mehrfachzeilenindex>
<LfdNrVordruck>1</LfdNrVordruck>
<VordruckZeilennummer>4</VordruckZeilennummer>
<SemantischerIndex>PersonA</SemantischerIndex>
<Untersachbereich>5</Untersachbereich>
<RegelName>testRegelName</RegelName>
<FachlicheFehlerId>9995</FachlicheFehlerId>
<Text>Beim Ankreuzfeld muss der Wert 'X' angegeben werden.</Text>
</FehlerRegelpruefung>
</EricBearbeiteVorgang>

Die einzelnen Elemente sind in der Schemadefinition Dokumentation\API-Rueckgabe-Schemata\EricBearbeiteVorgang.xsd dokumentiert. Wenn die Bearbeitungsflags ERIC_PRUEFE_HINWEISE und ERIC_VALIDIERE übergeben worden sind, kann der Rückgabepuffer auch Hinweise enthalten.

## Fehler in der Serverantwort

Ist der Rückgabewert ERIC_TRANSFER_ERR_XML_THEADER oder ERIC_TRANSFER_ERR_XML_NHEADER so enthält der Serverantwortpuffer Fehlermeldungen. Zur Auswertung kann entweder die Serverantwort selbst ausgewertet werden oder es wird EricMtGetErrormessagesFromXMLAnswer() aufgerufen.

## Sonstige Fehler

Bei sonstigen Fehlern ist der Inhalt der Rückgabepuffer undefiniert. Um nähere Informationen über die Fehlerursache herauszufinden, kann EricMtHoleFehlerText() mit dem Rückgabewert aufgerufen werden.

# Fortschrittcallbacks

Während der Verarbeitung eines Anwendungsfalls werden die durch die Funktionen EricMtRegistriereFortschrittCallback() und EricMtRegistriereGlobalenFortschrittCallback() registrierten Callbacks aufgerufen.

Siehe auch
  - ERiC-Entwicklerhandbuch.pdf, Kap. "Anwendungsfälle von EricBearbeiteVorgang()"
  - ERiC-Entwicklerhandbuch.pdf, Kap. der jeweiligen Datenart
  - ERiC-Entwicklerhandbuch.pdf, Kap. "ElsterDatenabholung"
  - ERiC-Entwicklerhandbuch.pdf, Kap. "Größenbegrenzung der Eingangsdaten"
  - ERiC-Entwicklerhandbuch.pdf, Kap. "Funktionen für Fortschrittcallbacks"
  - EricMtHoleFehlerText()
  - EricMtGetErrormessagesFromXMLAnswer()
  - EricMtRegistriereFortschrittCallback()
  - EricMtRegistriereGlobalenFortschrittCallback()

## ◆ EricMtChangePassword()

ERICAPI_IMPORT int EricMtChangePassword | ( | EricInstanzHandle | instanz,
|  | const byteChar * | psePath,
|  | const byteChar * | oldPin,
|  | const byteChar * | newPin )

Die PIN für ein clientseitig erzeugtes Zertifikat (CEZ) wird geändert.

Die Funktion ändert die bei der Funktion EricMtCreateKey() angegebene PIN und entsprechend hierfür die Prüfsumme in der Datei `eric.sfv`. Falls die Datei `eric.sfv` nicht vorhanden ist, wird sie, wie bei EricMtCreateKey(), erstellt. Eine PIN-Änderung von einem Portalzertifikat (POZ) ist nicht möglich.

Pfade müssen auf Windows in der für Datei-Funktionen benutzten ANSI-Codepage, auf Linux, AIX und Linux Power in der für das Dateisystem benutzten Locale und auf macOS in der "decomposed form" von UTF-8 übergeben werden. Bitte weitere Betriebssystemspezifika bzgl. nicht erlaubter Zeichen in Pfaden und Pfadtrennzeichen beachten.

Für Details zu Pfaden im ERiC siehe ERiC-Entwicklerhandbuch.pdf, Kapitel "Übergabe von Pfaden an ERiC API-Funktionen"

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | psePath | In dem angegebenen Pfad liegt das Schlüsselpaar `eric_private.p12` und `eric_public.cer`
  [in] | oldPin | Bisherige PIN.
  [in] | newPin | Neue PIN. Die Mindestlänge beträgt 4 Stellen. Zulässige Zeichen sind alle ASCII-Zeichen ohne die Steuerzeichen.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_UNGUELTIGER_PARAMETER
  - ERIC_GLOBAL_UNGUELTIGER_PARAMETER
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN
  - ERIC_CRYPT_PIN_STAERKE_NICHT_AUSREICHEND
  - ERIC_CRYPT_PIN_ENTHAELT_UNGUELTIGE_ZEICHEN
  - ERIC_CRYPT_E_PSE_PATH
  - ERIC_CRYPT_NICHT_UNTERSTUETZTES_PSE_FORMAT
  - ERIC_CRYPT_ERROR_CREATE_KEY

Siehe auch
  - EricMtCreateKey()
  - ERiC-Entwicklerhandbuch.pdf, Kap. "Zuordnung der API-Funktionen zur Verwendung von POZ, CEZ und AHZ"

## ◆ EricMtCheckXML()

ERICAPI_IMPORT int EricMtCheckXML | ( | EricInstanzHandle | instanz,
|  | const char * | xml,
|  | const char * | datenartVersion,
|  | EricRueckgabepufferHandle | fehlertextPuffer )

Das `xml` wird gegen das Schema der `datenartVersion` validiert.

Das verwendete Schema kann nachgeschlagen werden unter Dokumentation\Schnittstellenbeschreibungen\

Nicht unterstützte Datenartversionen:

- ElsterKMV
- alle Bilanz Datenartversionen

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | xml | XML-Zeichenfolge
  [in] | datenartVersion | Die `datenartVersion` ist der Datenartversionmatrix.xml zu entnehmen. Dieser Parameter darf nicht NULL sein und muss zu den XML-Eingangsdaten passen. Siehe auch ERiC-Entwicklerhandbuch.pdf.
  [out] | fehlertextPuffer | Handle auf einen Rückgabepuffer, in den Fehlertexte geschrieben werden. Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_FUNKTION_NICHT_UNTERSTUETZT: Schemavalidierung wird für die übergebene `datenartVersion` nicht unterstützt.
  - ERIC_GLOBAL_COMMONDATA_NICHT_VERFUEGBAR
  - ERIC_GLOBAL_DATENARTVERSION_UNBEKANNT
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_IO_READER_SCHEMA_VALIDIERUNGSFEHLER:
    Die Fehlerbeschreibung steht im `fehlertextPuffer`.
  - ERIC_IO_PARSE_FEHLER:
    Die Fehlerbeschreibung steht im `fehlertextPuffer`.
  - weitere, siehe eric_fehlercodes.h

## ◆ EricMtCloseHandleToCertificate()

ERICAPI_IMPORT int EricMtCloseHandleToCertificate | ( | EricInstanzHandle | instanz,
|  | EricZertifikatHandle | hToken )

Das Zertifikat-Handle `hToken` wird freigegeben.

Diese Funktion gibt das übergebene Zertifikat-Handle frei. Zertifikat-Handles sollten möglichst frühzeitig, d.h. wenn sie nicht mehr benötigt werden, mit EricMtCloseHandleToCertificate() freigegeben werden, spätestens jedoch zum Programmende bzw. vor dem Entladen der ericapi Bibliothek.

Das Ad Hoc-Zertifikat eines neuen Personalausweises sollte immer genau dann freigegeben werden, wenn es nicht mehr benötigt wird, jedoch spätestens vor Ablauf der 24 Stunden, die das Ad Hoc-Zertifikat gültig ist.

Tritt ein Fehler auf, kann die Fehlermeldung mit EricMtHoleFehlerText() ausgelesen werden.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | hToken | Zertifikat-Handle wie von der Funktion EricMtGetHandleToCertificate() zurückgeliefert.

Rückgabe
  - ERIC_OK
  - ERIC_CRYPT_E_INVALID_HANDLE
  - ERIC_GLOBAL_UNGUELTIGER_PARAMETER
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

Zu beachten
  Die folgenden Rückgabewerte gelten nur bei Verwendung des neuen Personalausweises.

Rückgabe
  - ERIC_TRANSFER_EID_CLIENTFEHLER
  - ERIC_TRANSFER_EID_FEHLENDEFELDER
  - ERIC_TRANSFER_EID_IDENTIFIKATIONABGEBROCHEN
  - ERIC_TRANSFER_EID_NPABLOCKIERT
  - ERIC_TRANSFER_EID_IDNRNICHTEINDEUTIG
  - ERIC_TRANSFER_EID_KEINCLIENT
  - ERIC_TRANSFER_EID_KEINKONTO
  - ERIC_TRANSFER_EID_SERVERFEHLER
  - ERIC_TRANSFER_ERR_CONNECTSERVER
  - ERIC_TRANSFER_ERR_NORESPONSE
  - ERIC_TRANSFER_ERR_PROXYAUTH
  - ERIC_TRANSFER_ERR_PROXYCONNECT
  - ERIC_TRANSFER_ERR_SEND
  - ERIC_TRANSFER_ERR_SEND_INIT
  - ERIC_TRANSFER_ERR_TIMEOUT

Siehe auch
  - EricMtGetHandleToCertificate()
  - EricMtZertifikatOeffnenAusBytes()
  - EricMtGetPinStatus()
  - ERiC-Entwicklerhandbuch.pdf, Kap. "Authentifizierung mit dem neuen Personalausweis (nPA)"

## ◆ EricMtCreateKey()

ERICAPI_IMPORT int EricMtCreateKey | ( | EricInstanzHandle | instanz,
|  | const byteChar * | pin,
|  | const byteChar * | pfad,
|  | const eric_zertifikat_parameter_t * | zertifikatInfo )

Es werden die Kryptomittel für ein clientseitig erzeugtes Zertifikat (CEZ) in einem Verzeichnis des Dateisystems erstellt.

Im angegebenen Verzeichnis `pfad` sind nach Ausführung der Funktion EricMtCreateKey() drei Dateien erstellt worden:

- `eric_public.cer:`
  Enthält das Zertifikat mit den Daten aus `zertifikatInfo` und darin den öffentlichen Schlüssel.
- `eric_private.p12:`
  Enthält den privaten Schlüssel. Der Zugriff ist über die `pin` geschützt.
- `eric.sfv:`
  Enthält die Prüfsumme der Dateien `eric_public.cer` und `eric_private.p12`. Die Integrität dieser beiden Dateien kann damit jederzeit überprüft werden.

Ein CEZ kann unter anderem für die Bescheiddaten-Rückübermittlung verwendet werden. Weitere Informationen zur Datenabholung lesen Sie bitte im ERiC-Entwicklerhandbuch.pdf nach.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | pin | PIN (Passwort), mit der auf den privaten Schlüssel zugegriffen werden kann. Die Mindestlänge beträgt 4 Stellen. Zulässige Zeichen sind alle ASCII-Zeichen ohne die Steuerzeichen.
  [in] | pfad | Pfad (1), in dem die Kryptomittel erzeugt werden sollen. Das durch den angegebenen Pfad bezeichnete Verzeichnis muss im Dateisystem bereits existieren und beschreibbar sein. Es gibt folgende Möglichkeiten: Absoluter Pfad: Empfehlung. Relativer Pfad: Wird an das Arbeitsverzeichnis angehängt. Leere Zeichenkette: In diesem Fall wird das Arbeitsverzeichnis verwendet.
  [in] | zertifikatInfo | Daten, die zur Identifikation des Schlüsselinhabers im Zertifikat abgelegt werden.

(1) Pfade müssen auf Windows in der für Datei-Funktionen benutzten ANSI-Codepage, auf Linux, AIX und Linux Power in der für das Dateisystem benutzten Locale und auf macOS in der "decomposed form" von UTF-8 übergeben werden. Bitte weitere Betriebssystemspezifika bzgl. nicht erlaubter Zeichen in Pfaden und Pfadtrennzeichen beachten.

Für Details zu Pfaden im ERiC siehe ERiC-Entwicklerhandbuch.pdf, Kapitel "Übergabe von Pfaden an ERiC API-Funktionen".

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_UNGUELTIGE_PARAMETER_VERSION
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN
  - ERIC_CRYPT_ZERTIFIKATSPFAD_KEIN_VERZEICHNIS
  - ERIC_CRYPT_ZERTIFIKATSDATEI_EXISTIERT_BEREITS
  - ERIC_CRYPT_PIN_STAERKE_NICHT_AUSREICHEND
  - ERIC_CRYPT_PIN_ENTHAELT_UNGUELTIGE_ZEICHEN
  - ERIC_CRYPT_ERROR_CREATE_KEY

Siehe auch
  - EricMtChangePassword()
  - ERiC-Entwicklerhandbuch.pdf, Kap. "Zertifikate und Authentifizierungsverfahren"
  - ERiC-Entwicklerhandbuch.pdf, Kap. "Übergabe von Pfaden an ERiC API-Funktionen"

## ◆ EricMtCreateTH()

ERICAPI_IMPORT int EricMtCreateTH | ( | EricInstanzHandle | instanz,
|  | const char * | xml,
|  | const char * | verfahren,
|  | const char * | datenart,
|  | const char * | vorgang,
|  | const char * | testmerker,
|  | const char * | herstellerId,
|  | const char * | datenLieferant,
|  | const char * | versionClient,
|  | const byteChar * | publicKey,
|  | EricRueckgabepufferHandle | xmlRueckgabePuffer )

Diese Funktion erzeugt einen TransferHeader.

Dieser ist der oberste Header in der Datenstruktur. Er enthält Felder für die Kommunikation zwischen Server und Client. Es wird nur die Kombination NutzdatenHeader-Version "11" und TransferHeader-Version "11" unterstützt.

Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | xml | XML-Datensatz, für den der <TransferHeader>-Block erzeugt werden soll. Es kann entweder ein komplettes Elster-XML oder nur der Datenteil übergeben werden. ERiC nimmt bei diesem Parameter keine Konvertierung von Sonderzeichen in Entitätenreferenzen vor. Attribute, die in den Start-Tags der Elemente <Elster> bzw. <DatenTeil> im übergebenen XML-Datensatz definiert werden, werden nicht in das Rückgabe-XML übernommen. Namespace-Definitionen, die in den Start-Tags der Elemente <Elster> bzw. <DatenTeil> im übergebenen XML-Datensatz definiert werden, führen zu einem ERIC_IO_PARSE_FEHLER. Im Rückgabe-XML werden im Start-Tag des Elements <Elster> die URI "http://www.elster.de/elsterxml/schema/v11" als Default-Namensraum definiert. Die dem Element <DatenTeil> untergeordneten Elemente aus dem übergebenen XML-Datensatz werden unverändert übernommen. Der allgemeine Aufbau des Elster-XMLs wird im ERiC-Entwicklerhandbuch.pdf, Kap. "Datenverarbeitung mit ERiC" beschrieben.
  [in] | verfahren | Name des Verfahrens, z.B: 'ElsterAnmeldung', siehe ERiC-Entwicklerhandbuch.pdf, Tabelle "Eigenschaften der Datenart" im jeweiligen Kapitel zur Datenart.
  [in] | datenart | Name der Datenart, z.B.:'LStB' oder 'UStVA', siehe ERiC-Entwicklerhandbuch.pdf, Tabelle "Eigenschaften der Datenart" im jeweiligen Kapitel zur Datenart.
  [in] | vorgang | Name der Übertragungsart, z.B. 'send-NoSig', siehe ERiC-Entwicklerhandbuch.pdf, Tabelle "Eigenschaften der Datenart" im jeweiligen Kapitel zur Datenart.
  [in] | testmerker | Für eine Testübertragung muss der entsprechende Testmerker angegeben werden, siehe ERiC-Entwicklerhandbuch.pdf, Kap. "Test Unterstützung bei der ERiC-Anbindung". Falls ein Echtfall übertragen werden soll, muss der Wert NULL angegeben werden.
  [in] | herstellerId | Hersteller-ID des Softwareproduktes.
  [in] | datenLieferant | Der Wert entspricht dem XML-Element <DatenLieferant>, wie es im Schema des Transferheaders der ElsterBasis-XML-Schnittstelle definiert ist. ERiC konvertiert bei diesem Parameter Sonderzeichen in Entitätenreferenzen.
  [in] | versionClient | Angabe von Versionsinformation, die in der Serverantwort auch zurückgegeben wird und ausgewertet werden kann. Der Wert NULL entspricht "keine Angabe von Versionsinformation", d.h. es wird kein XML-Element <VersionClient> im <TransferHeader>-Block erzeugt. ERiC konvertiert bei diesem Parameter Sonderzeichen in Entitätenreferenzen.
  [in] | publicKey | Öffentlicher Schlüssel für die Transportverschlüsselung beim Verfahren ElsterLohn. Bei anderen Verfahren sollte NULL übergeben werden. Dieser Wert kann mit dem Rückgabewert von EricMtGetPublicKey() befüllt werden. Der Inhalt dieses Parameters wird in das <TransportSchluessel>-Element der Rückgabe-XML geschrieben.
  [out] | xmlRueckgabePuffer | Handle auf einen Rückgabepuffer, in den das Elster-XML mit dem erzeugten TransportHeader geschrieben wird, siehe EricRueckgabepufferHandle. Es wird immer ein vollständiger Elster-XML-Datensatz mit dem <Elster>-Element als Wurzel-Element zurückgeliefert. Bzgl. der darin enthaltenen XML-Namespace-Definitionen sind die bei der Beschreibung des Parameters "xml" genannten Einschränkungen zu berücksichtigen.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_TRANSFER_ERR_XML_ENCODING: Die übergebenen XML-Daten sind nicht UTF-8 kodiert.
  - ERIC_IO_PARSE_FEHLER
  - ERIC_IO_DATENTEILNOTFOUND
  - ERIC_IO_DATENTEILENDNOTFOUND
  - weitere, siehe eric_fehlercodes.h

Siehe auch
  - ERiC-Entwicklerhandbuch.pdf, Kap. "Datenverarbeitung mit ERiC"
  - ERiC-Entwicklerhandbuch.pdf, Kap. "Anwendungsfälle von EricBearbeiteVorgang()"
  - ERiC-Returncodes und Fehlertexte sind in eric_fehlercodes.h zu finden.

## ◆ EricMtCreateUUID()

ERICAPI_IMPORT int EricMtCreateUUID | ( | EricInstanzHandle | instanz,
|  | EricRueckgabepufferHandle | uuidRueckgabePuffer )

Erzeugt einen Version 4 Universally Unique Identifier (UUID) gemäß RFC 4122.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [out] | uuidRueckgabePuffer | Handle auf einen Rückgabepuffer, in den die erzeugte UUID geschrieben wird.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

## ◆ EricMtDekodiereDaten()

ERICAPI_IMPORT int EricMtDekodiereDaten | ( | EricInstanzHandle | instanz,
|  | EricZertifikatHandle | zertifikatHandle,
|  | const byteChar * | pin,
|  | const byteChar * | base64Eingabe,
|  | EricRueckgabepufferHandle | rueckgabePuffer )

Es werden die mit der Datenabholung abgeholten und verschlüsselten Daten entschlüsselt.

Falls während der Bearbeitung ein Fehler auftritt, liefert die Funktion EricMtHoleFehlerText() den dazugehörigen Fehlertext.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | zertifikatHandle | Handle auf das zum Entschlüsseln zu verwendende Zertifikat.
  [in] | pin | PIN zum Zugriff auf das Zertifikat.
  [in] | base64Eingabe | Base64-kodierte verschlüsselte Daten oder Anhänge, welche mit dem Verfahren ElsterDatenabholung abgeholt wurden. Die Abholdaten befinden sich im Element `/Elster[1]/DatenTeil[1]/Nutzdatenblock/Nutzdaten[1]/Datenabholung[1]/Abholung[1]/Datenpaket` Die optionalen Anhänge befinden sich im Element `/Elster[1]/DatenTeil[1]/Nutzdatenblock/Nutzdaten[1]/Datenabholung[1]/Abholung[1]/Anhaenge[1]/Anhang[1]/Dateiinhalt`
  [out] | rueckgabePuffer | Handle auf einen Rückgabepuffer, in den die entschlüsselten Daten geschrieben werden. Im Fehlerfall ist der Inhalt des Rückgabepuffers undefiniert. Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe EricRueckgabepufferHandle.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_ERR_DEKODIEREN
  - ERIC_GLOBAL_UNKNOWN
  - Ein Zertifikatsfehler aus dem Statuscodebereich von ERIC_CRYPT_E_INVALID_HANDLE = 610201101 bis 610201212

Siehe auch
  - EricMtHoleFehlerText()
  - ERiC-Entwicklerhandbuch.pdf, Kap. "ElsterDatenabholung"

## ◆ EricMtEinstellungAlleZuruecksetzen()

ERICAPI_IMPORT int EricMtEinstellungAlleZuruecksetzen | ( | EricInstanzHandle | instanz | ) |

Alle Einstellungen, der übergebenen ERiC-Instanz werden auf den jeweiligen Standardwert zurückgesetzt.

Die Standardwerte sind im Dokument ERiC-Entwicklerhandbuch.pdf, Kap. "Vorbelegung der ERiC-Einstellungen" zu finden.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_UNKNOWN
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNGUELTIGER_PARAMETER

Siehe auch
  - EricMtEinstellungSetzen()
  - EricMtEinstellungLesen()
  - EricMtEinstellungZuruecksetzen()
  - ERiC-Entwicklerhandbuch.pdf, Kap. "Bedeutung der ERiC-Einstellungen"

## ◆ EricMtEinstellungLesen()

ERICAPI_IMPORT int EricMtEinstellungLesen | ( | EricInstanzHandle | instanz,
|  | const char * | name,
|  | EricRueckgabepufferHandle | rueckgabePuffer )

Der Wert der API-Einstellung `name` wird im `rueckgabePuffer` zurückgeliefert.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | name | Name der API-Einstellung, NULL-terminierte Zeichenfolge.
  [out] | rueckgabePuffer | Handle auf einen Rückgabepuffer, in den der Wert der API-Einstellung geschrieben wird. Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe EricRueckgabepufferHandle.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_EINSTELLUNG_NAME_UNGUELTIG
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

Siehe auch
  - EricMtEinstellungSetzen()
  - EricMtEinstellungZuruecksetzen()
  - EricMtEinstellungAlleZuruecksetzen()
  - ERiC-Entwicklerhandbuch.pdf, Kap. "Bedeutung der ERiC-Einstellungen"

## ◆ EricMtEinstellungSetzen()

ERICAPI_IMPORT int EricMtEinstellungSetzen | ( | EricInstanzHandle | instanz,
|  | const char * | name,
|  | const char * | wert )

Die API-Einstellung `name` wird auf den `wert` gesetzt.

Nach dem Laden der ERiC-Bibliotheken hat jede API-Einstellung ihren Standardwert. Mit dieser Funktion kann der Wert verändert werden. Der Wertebereich der jeweiligen API-Einstellung ist zu beachten.

Bei Pfad-Einstellungen muss auf Windows der Wert in der für Datei-Funktionen benutzten ANSI-Codepage, auf Linux, AIX und Linux Power in der für das Dateisystem benutzten Locale und auf macOS in der "decomposed form" von UTF-8 übergeben werden. Bitte weitere Betriebssystemspezifika bzgl. nicht erlaubter Zeichen in Pfaden und Pfadtrennzeichen beachten.

Für Details zu Pfaden im ERiC siehe ERiC-Entwicklerhandbuch.pdf, Kapitel "Übergabe von Pfaden an ERiC API-Funktionen"

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | name | Name der API-Einstellung, NULL-terminierte Zeichenfolge.
  [in] | wert | Wert der API-Einstellung, NULL-terminierte Zeichenfolge.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_EINSTELLUNG_NAME_UNGUELTIG
  - ERIC_GLOBAL_EINSTELLUNG_WERT_UNGUELTIG
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

Siehe auch
  - EricMtEinstellungLesen()
  - EricMtEinstellungZuruecksetzen()
  - EricMtEinstellungAlleZuruecksetzen()
  - ERiC-Entwicklerhandbuch.pdf, Kap. "Bedeutung der ERiC-Einstellungen"

## ◆ EricMtEinstellungZuruecksetzen()

ERICAPI_IMPORT int EricMtEinstellungZuruecksetzen | ( | EricInstanzHandle | instanz,
|  | const char * | name )

Der Wert der API-Einstellung `name` wird auf den Standardwert zurückgesetzt.

Die Standardwerte sind im Dokument ERiC-Entwicklerhandbuch.pdf, Kap. "Vorbelegung der ERiC-Einstellungen" zu finden.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | name | Name der API-Einstellung, NULL-terminierte Zeichenfolge.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_EINSTELLUNG_NAME_UNGUELTIG
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

Siehe auch
  - EricMtEinstellungSetzen()
  - EricMtEinstellungLesen()
  - EricMtEinstellungAlleZuruecksetzen()
  - ERiC-Entwicklerhandbuch.pdf, Kap. "Bedeutung der ERiC-Einstellungen"

## ◆ EricMtEntladePlugins()

ERICAPI_IMPORT int EricMtEntladePlugins | ( | EricInstanzHandle | instanz | ) |

Für die übergebene ERiC-Instanz werden alle verwendeten Plugin-Bibliotheken entladen und deren Speicher wird freigegeben.

Der ERiC lädt die für die Bearbeitung notwendigen Plugin-Bibliotheken permanent in den Speicher und gibt diese erst mit dem Aufruf dieser Funktion wieder frei.

Zu beachten
  EricMtEntladePlugins() sollte erste dann aufgerufen werden, wenn die Plugin-Bibliotheken definitiv nicht mehr benötigt werden. Ein erneutes Laden der Bibliotheken ist verhältnismäßig zeitintensiv.

Falls eine Plugin-Bibliothek nicht entladen werden kann, wird dies in eric.log protokolliert. Der Returncode ist immer ERIC_OK.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_UNGUELTIGER_PARAMETER
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

Siehe auch
  - ERiC-Entwicklerhandbuch.pdf, Kap. "Verwendung von EricEntladePlugins()"

## ◆ EricMtFormatEWAz()

ERICAPI_IMPORT int EricMtFormatEWAz | ( | EricInstanzHandle | instanz,
|  | const byteChar * | ewAzElster,
|  | EricRueckgabepufferHandle | ewAzBescheidPuffer )

Konvertiert ein Einheitswert-Aktenzeichen im ELSTER-Format in ein landesspezifisches Bescheidformat.

Konvertiert ein Einheitswert-Aktenzeichen im ELSTER-Format (z.B. 2831400190001250002) in ein landesspezifisches Einheitswert-Aktenzeichen im Bescheidformat (z.B. 3100190001250002).

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | ewAzElster | Zeiger auf ein Einheitswert-Aktenzeichen im ELSTER-Format (z.B. 2831400190001250002)
  [out] | ewAzBescheidPuffer | Handle auf einen Rückgabepuffer, in den das Einheitswert-Aktenzeichen im Bescheidformat (z.B. 3100190001250002) geschrieben wird. Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_EWAZ_UNGUELTIG
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

## ◆ EricMtFormatStNr()

ERICAPI_IMPORT int EricMtFormatStNr | ( | EricInstanzHandle | instanz,
|  | const byteChar * | eingabeSteuernummer,
|  | EricRueckgabepufferHandle | rueckgabePuffer )

Die Steuernummer `eingabeSteuernummer` wird in das Bescheid-Format des jeweiligen Bundeslandes umgewandelt.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | eingabeSteuernummer | Gültige, zu formatierende Steuernummer im ELSTER-Steuernummernformat.
  [out] | rueckgabePuffer | Handle auf einen Rückgabepuffer, in den die formatierte Steuernummer im Bescheid-Format des jeweiligen Bundeslandes geschrieben wird. Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_STEUERNUMMER_UNGUELTIG
  - ERIC_GLOBAL_COMMONDATA_NICHT_VERFUEGBAR
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

Siehe auch
  - Pruefung_der_Steuer_und_Steueridentifikatsnummer.pdf, siehe Entwicklerbereich bei ELSTER.

## ◆ EricMtGetAuswahlListen()

ERICAPI_IMPORT int EricMtGetAuswahlListen | ( | EricInstanzHandle | instanz,
|  | const char * | datenartVersion,
|  | const char * | feldkennung,
|  | EricRueckgabepufferHandle | rueckgabeXmlPuffer )

Die Auswahlliste(n) für `datenartVersion` oder `feldkennung` wird zurückgeliefert.

Anwendungsfälle:

1. Parameter `feldkennung` ist nicht NULL:
   Die Funktion liefert die zur `feldkennung` und `datenartVersion` gehörige Auswahlliste.
2. Parameter `feldkennung` ist NULL:
   Die Funktion liefert alle zur `datenartVersion` gehörigen Feldkennungen mit hinterlegten Auswahllisten.

Für die Ermittlung der Auswahllisten vieler Feldkennungen wird aus Performanzgründen Anwendungsfall 2 empfohlen. Die Funktion liefert Auswahllisten zu Feldkennungen vom Format "NichtAbgeschlosseneEnumeration" zurück. Diese Auswahllisten werden auch in der Jahres-/Deltadokumentation dokumentiert.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | datenartVersion | Dieser Parameter darf nicht NULL sein. Die gültigen Datenartversionen sind in der Datenartversionmatrix.xml enthalten.
  [in] | feldkennung | Feldkennung, für welche die Auswahlliste zu ermitteln ist.
  [out] | rueckgabeXmlPuffer | Handle auf einen Rückgabepuffer, in den die angeforderten Auswahlliste(n) als XML-Daten geschrieben werden. Die XML-Daten folgen der XML Schema Definition in Dokumentation\API-Rueckgabe-Schemata\EricGetAuswahlListen.xsd. Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe EricRueckgabepufferHandle.

Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<EricGetAuswahlListen xmlns="http://www.elster.de/EricXML/1.0/EricGetAuswahlListen">
<AuswahlListe>
<Feldkennung>0104110</Feldkennung>
<ListenElement>Arbeitslosengeld</ListenElement>
<ListenElement>Elterngeld</ListenElement>
<ListenElement>Insolvenzgeld</ListenElement>
<ListenElement>Krankengeld</ListenElement>
<ListenElement>Mutterschaftsgeld</ListenElement>
</AuswahlListe>
</EricGetAuswahlListen>

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_KEINE_DATEN_VORHANDEN
  - ERIC_GLOBAL_DATENARTVERSION_UNBEKANNT
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

## ◆ EricMtGetErrormessagesFromXMLAnswer()

ERICAPI_IMPORT int EricMtGetErrormessagesFromXMLAnswer | ( | EricInstanzHandle | instanz,
|  | const char * | xml,
|  | EricRueckgabepufferHandle | transferticketPuffer,
|  | EricRueckgabepufferHandle | returncodeTHPuffer,
|  | EricRueckgabepufferHandle | fehlertextTHPuffer,
|  | EricRueckgabepufferHandle | returncodesUndFehlertexteNDHXmlPuffer )

Aus dem Antwort-XML des Finanzamtservers wird das Transferticket und Returncodes/Fehlermeldungen zurückgegeben.

Die Funktion liefert bei erfolgreicher Ausführung:

- Das Transferticket aus dem Antwort-XML in dem Parameter `transferticketPuffer`.
- Den Returncode und die Fehlermeldung aus dem Transferheader in den Parametern `returncodeTHPuffer` und `fehlertextTHPuffer`.
- Für jeden Nutzdatenheader dessen Returncode und Fehlermeldung als XML-Daten im Parameter `returncodesUndFehlertexteNDHXmlPuffer` nach XML Schema Definition Dokumentation\API-Rueckgabe-Schemata\EricGetErrormessagesFromXMLAnswer.xsd. Enthält das Antwort-XML keine Nutzdaten, wird kein <Fehler> Element zurückgegeben.

Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | xml | Antwort-XML des ELSTER-Servers, das ausgewertet werden soll. Der originale XML-Server-Datenstrom sollte unverändert übergeben werden und darf insbesondere keine Zeilenumbruchzeichen enthalten.
  [out] | transferticketPuffer | Handle auf einen Rückgabepuffer, in den das Transferticket geschrieben wird, siehe EricRueckgabepufferHandle.
  [out] | returncodeTHPuffer | Handle auf einen Rückgabepuffer, in den der Returncode aus dem Transferheader geschrieben wird. Siehe EricRueckgabepufferHandle.
  [out] | fehlertextTHPuffer | Handle auf einen Rückgabepuffer, in den die Fehlermeldung aus dem Transferheader geschrieben wird, siehe EricRueckgabepufferHandle.
  [out] | returncodesUndFehlertexteNDHXmlPuffer | Handle auf einen Rückgabepuffer, in den die Liste der Returncodes nach XML-Schema Dokumentation\API-Rueckgabe-Schemata\EricGetErrormessagesFromXMLAnswer.xsd geschrieben werden, siehe EricRueckgabepufferHandle.

Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<EricGetErrormessagesFromXMLAnswer xmlns="http://www.elster.de/EricXML/1.0/EricGetErrormessagesFromXMLAnswer">
<Fehler>
<Code>1</Code>
<Meldung>Fehlermeldung 1</Meldung>
</Fehler>
<Fehler>
<Code>2</Code>
<Meldung>Fehlermeldung 2</Meldung>
</Fehler>
(...)
</EricGetErrormessagesFromXMLAnswer>

Rückgabe
  - ERIC_OK
  - ERIC_IO_PARSE_FEHLER
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_PUFFER_ZUGRIFFSKONFLIKT
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

Zu beachten
  Diese Funktion kann nicht dafür verwendet werden, die Antwort im Datenteil aus einer dekodierten Serverantwort für Lohnsteuerbescheinigungen auszuwerten.

Siehe auch
  - XML-Schema des Transferheaders: Dokumentation\Schnittstellenbeschreibungen\ElsterBasisSchema\Schema\th000011_extern.xsd
  - XML-Schema des Nutzdatenheaders: Dokumentation\Schnittstellenbeschreibungen\ElsterBasisSchema\Schema\ndh000011.xsd
  - ERiC-Entwicklerhandbuch.pdf, Kap. "Schnittstellenbeschreibungen", Tabelle "Ergänzende Softwarepakete und Dateien – Schnittstellenbeschreibungen"

## ◆ EricMtGetHandleToCertificate()

ERICAPI_IMPORT int EricMtGetHandleToCertificate | ( | EricInstanzHandle | instanz,
|  | EricZertifikatHandle * | hToken,
|  | uint32_t * | iInfoPinSupport,
|  | const byteChar * | pathToKeystore )

Für das übergebene Zertifikat in `pathToKeystore` wird das Handle `hToken` und die unterstützten PIN-Werte `iInfoPinSupport` zurückgeliefert.

Die ERiC API benötigt Zertifikat-Handles typischerweise bei kryptografischen Operationen.

Zertifikat-Handles sollten möglichst frühzeitig, d.h. wenn sie nicht mehr benötigt werden, mit EricMtCloseHandleToCertificate() freigegeben werden, spätestens jedoch zum Programmende bzw. vor dem Entladen der ericapi Bibliothek.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [out] | hToken | Handle zu einem der folgenden Zertifikate: Portalzertifikat clientseitig erzeugtes Zertifikat Ad Hoc-Zertifikat für den neuen Personalausweis
  [out] | iInfoPinSupport | Wird in `iInfoPinSupport` ein Zeiger ungleich NULL übergeben und die Funktion mit ERIC_OK beendet, dann enthält `iInfoPinSupport` einen vorzeichenlosen Integer-Wert. In diesem Wert ist kodiert abgelegt, ob eine PIN-Eingabe erforderlich ist und welche PIN-Statusinformationen unterstützt werden. Die kodierten Werte (nachfolgend in hexadezimaler Form angegeben) können durch ein binäres ODER kombiniert werden und bedeuten im Einzelnen: `0x00:` Keine PIN-Angabe erforderlich, kein PIN-Status unterstützt. `0x01:` PIN-Angabe für Signatur erforderlich. `0x02:` PIN-Angabe für Entschlüsselung erforderlich. `0x04:` PIN-Angabe für Verschlüsselung des Zertifikats erforderlich. `0x08:` reserviert (wird derzeit nicht verwendet) `0x10:` PIN-Status "Pin Ok" wird unterstützt. `0x20:` PIN-Status "Der letzte Versuch der Pin-Eingabe schlug fehl" wird unterstützt. `0x40:` PIN-Status "Beim nächsten fehlerhaften Versuch wird die Pin gesperrt" wird unterstützt. `0x80:` PIN-Status "Pin ist gesperrt" wird unterstützt. Falls vom Aufrufer NULL übergeben wird, gibt die Funktion nichts zurück.
  [in] | pathToKeystore | Folgende Zertifikatstypen werden unterstützt: Clientseitig erzeugtes Zertifikat: Pfad zum Verzeichnis, in dem sich die Zertifikats-Datei (.cer) und die Datei mit dem privaten Schlüssel (.p12) befinden. Diese Kryptomittel wurden mit EricMtCreateKey() erzeugt. Der Pfad zum Verzeichnis ist bei clientseitig erzeugten Zertifikaten relativ zum aktuellen Arbeitsverzeichnis oder absolut anzugeben. Software-Portalzertifikat: Pfad zur Software-Zertifikatsdatei (i.d.R. mit der Endung .pfx). Der Pfad zur Datei ist bei Software-Zertifikaten relativ zum aktuellen Arbeitsverzeichnis oder absolut anzugeben. Sicherheitsstick: Pfad zur Treiberdatei, siehe (1). Bitte beachten, dass der Treiber betriebssystemabhängig sein kann. Weitere Informationen in der Anleitung zum Sicherheitsstick oder unter https://www.sicherheitsstick.de. Signaturkarte: Pfad zur Treiberdatei, welcher einen Zugriff auf die Signaturkarte ermöglicht, siehe (1). Weitere Informationen in der Anleitung zur Signaturkarte. Neuer Personalausweis (nPA): URL des eID-Clients wie zum Beispiel der AusweisApp 2 In den meisten Fällen lautet diese URL: http://127.0.0.1:24727/eID-Client Optional kann auf die folgende Weise noch ein Testmerker angehängt werden: http://127.0.0.1:24727/eID-Client?testmerker=520000000. Zu den verfügbaren Testmerkern siehe ERiC-Entwicklerhandbuch.pdf, Kap. "Test Unterstützung bei der ERiC-Anbindung". Wichtig: Das Ad Hoc-Zertifikat, das in diesem Fall für den neuen Personalausweis erzeugt wird, ist nur 24 Stunden gültig.

(1) Bei Sicherheitssticks und Signaturkarten ist bei der Angabe des Treibers der Suchmechanismus nach dynamischen Modulen des jeweiligen Betriebssystems zu berücksichtigen. Weitere Informationen sind z.B. unter Windows der Dokumentation der `LoadLibrary()` oder unter Linux und macOS der Dokumentation der `dlopen()` zu entnehmen.

Pfade müssen auf Windows in der für Datei-Funktionen benutzten ANSI-Codepage, auf Linux, AIX und Linux Power in der für das Dateisystem benutzten Locale und auf macOS in der "decomposed form" von UTF-8 übergeben werden. Bitte weitere Betriebssystemspezifika bzgl. nicht erlaubter Zeichen in Pfaden und Pfadtrennzeichen beachten.

Für Details zu Pfaden im ERiC siehe ERiC-Entwicklerhandbuch.pdf, Kapitel "Übergabe von Pfaden an ERiC API-Funktionen".

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN
  - ERIC_CRYPT_NICHT_UNTERSTUETZTES_PSE_FORMAT
  - ERIC_CRYPT_E_MAX_SESSION
  - ERIC_CRYPT_E_PSE_PATH
  - ERIC_CRYPT_E_BUSY
  - ERIC_CRYPT_E_P11_SLOT_EMPTY
  - ERIC_CRYPT_E_NO_SIG_ENC_KEY
  - ERIC_CRYPT_E_LOAD_DLL
  - ERIC_CRYPT_E_NO_SERVICE
  - ERIC_CRYPT_E_ESICL_EXCEPTION

Zu beachten
  Die folgenden Rückgabewerte gelten nur bei Verwendung des neuen Personalausweises.

Rückgabe
  - ERIC_TRANSFER_EID_CLIENTFEHLER
  - ERIC_TRANSFER_EID_FEHLENDEFELDER
  - ERIC_TRANSFER_EID_IDENTIFIKATIONABGEBROCHEN
  - ERIC_TRANSFER_EID_NPABLOCKIERT
  - ERIC_TRANSFER_EID_IDNRNICHTEINDEUTIG
  - ERIC_TRANSFER_EID_KEINCLIENT
  - ERIC_TRANSFER_EID_KEINKONTO
  - ERIC_TRANSFER_EID_SERVERFEHLER
  - ERIC_TRANSFER_ERR_CONNECTSERVER
  - ERIC_TRANSFER_ERR_NORESPONSE
  - ERIC_TRANSFER_ERR_PROXYAUTH
  - ERIC_TRANSFER_ERR_PROXYCONNECT
  - ERIC_TRANSFER_ERR_SEND
  - ERIC_TRANSFER_ERR_SEND_INIT
  - ERIC_TRANSFER_ERR_TIMEOUT

Siehe auch
  - EricMtCloseHandleToCertificate()
  - EricMtGetPinStatus()

## ◆ EricMtGetPinStatus()

ERICAPI_IMPORT int EricMtGetPinStatus | ( | EricInstanzHandle | instanz,
|  | EricZertifikatHandle | hToken,
|  | uint32_t * | pinStatus,
|  | uint32_t | keyType )

Der PIN-Status wird für ein passwortgeschütztes Kryptomittel abgefragt und in `pinStatus` zurückgegeben.

Der PIN-Status wird für einen passwortgeschützten Bereich ermittelt, der durch das übergebene Zertifikat-Handle im Parameter `hToken` referenziert wird. Da bei Sicherheitssticks und Signaturkarten durch ein einziges Zertifikat-Handle zwei Schlüsselpaare referenziert werden können (eines für die Signatur und eines für die Verschlüsselung von Daten), muss grundsätzlich der Parameter `keyType` gesetzt werden.

Mit dem Rückgabewert der Funktion kann der Endanwender rechtzeitig informiert werden, falls bei einer weiteren falschen PIN-Eingabe das Kryptomittel gesperrt wird. Im Fehlerfall ist `pinStatus` nicht definiert.

Der Karten- bzw. Stickhersteller ist verantwortlich, dass seine Implementierung den korrekten PIN-Status zurückgibt, siehe auch Tabelle "PIN-Statusabfrage für POZ" im Unterkap. "Das Portalzertifikat (POZ)" im Dokument ERiC-Entwicklerhandbuch.pdf.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | hToken | Zertifikat-Handle, für dessen passwortgeschützten Bereich der PIN-Status ermittelt werden soll. Wird von der Funktion EricMtGetHandleToCertificate() zurückgeliefert.
  [out] | pinStatus | Mögliche Rückgabewerte: 0: StatusPinOk: Kein Fehlversuch oder keine Informationen verfügbar 1: StatusPinLocked: PIN gesperrt 2: StatusPreviousPinError: Die letzte PIN-Eingabe war fehlerhaft 3: StatusLockedIfPinError: Beim nächsten fehlerhaften Versuch wird die PIN gesperrt
  [in] | keyType | Mögliche Eingabewerte: 0: eSignatureKey: Schlüssel für die Signatur von Daten 1: eEncryptionKey: Schlüssel für die Verschlüsselung von Daten

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - weitere, siehe eric_fehlercodes.h

Siehe auch
  - EricMtGetHandleToCertificate()
  - ERiC-Entwicklerhandbuch.pdf, Kap. "Zertifikate und Authentifizierungsverfahren"

## ◆ EricMtGetPublicKey()

ERICAPI_IMPORT int EricMtGetPublicKey | ( | EricInstanzHandle | instanz,
|  | const eric_verschluesselungs_parameter_t * | cryptoParameter,
|  | EricRueckgabepufferHandle | rueckgabePuffer )

Es wird der öffentliche Schlüssel als base64-kodierte Zeichenkette für das übergebene Zertifikat-Handle in `cryptoParameter` zurückgeliefert. Von den beiden öffentlichen Schlüsseln, die in ELSTER-Zertifikaten enthalten sind, wird der Verschlüsselungsschlüssel (Encryption Key) zurückgegeben.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | cryptoParameter | Die Struktur enthält das Zertifikat-Handle und die PIN. Falls der Zugriff auf den öffentlichen Schlüssel keine PIN erfordert, ist PIN=NULL anzugeben.
  [out] | rueckgabePuffer | Handle auf den Rückgabepuffer. Bei Erfolg enthält der Rückgabepuffer den öffentlichen Schlüssel als base64-kodierte Zeichenkette. Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_CRYPT_E_INVALID_HANDLE
  - ERIC_CRYPT_E_P12_ENC_KEY
  - ERIC_CRYPT_E_PIN_WRONG
  - ERIC_CRYPT_E_PIN_LOCKED
  - weitere, siehe eric_fehlercodes.h

## ◆ EricMtHoleFehlerText()

ERICAPI_IMPORT int EricMtHoleFehlerText | ( | EricInstanzHandle | instanz,
|  | int | fehlerkode,
|  | EricRueckgabepufferHandle | rueckgabePuffer )

Es wird die Klartextfehlermeldung zu dem `fehlerkode` ermittelt.

Die Funktion liefert die Klartextfehlermeldung zu einem ERiC Fehlercode - definiert in eric_fehlercodes.h

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | fehlerkode | Eingabe-Fehlercode, definiert in eric_fehlercodes.h.
  [out] | rueckgabePuffer | Handle auf einen Rückgabepuffer, in den die Klartextfehlermeldung geschrieben wird. Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle. Die Klartextfehlermeldung ist gemäß UTF-8 kodiert.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_FEHLERMELDUNG_NICHT_VORHANDEN
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

## ◆ EricMtHoleFinanzaemter()

ERICAPI_IMPORT int EricMtHoleFinanzaemter | ( | EricInstanzHandle | instanz,
|  | const byteChar * | finanzamtLandNummer,
|  | EricRueckgabepufferHandle | rueckgabeXmlPuffer )

Es wird die Finanzamtliste für eine bestimmte `finanzamtLandNummer` zurückgegeben.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | finanzamtLandNummer | Die Finanzamtlandnummer besteht aus den ersten zwei Stellen der Bundesfinanzamtsnummer. Eine Liste aller Finanzamtlandnummern wird von EricMtHoleFinanzamtLandNummern() zurückgegeben.
  [out] | rueckgabeXmlPuffer | Handle auf einen Rückgabepuffer, in den die Ergebnis XML-Daten geschrieben werden. Die XML-Daten folgen der XML Schema Definition Dokumentation\API-Rueckgabe-Schemata\EricHoleFinanzaemter.xsd. Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<EricHoleFinanzaemter xmlns="http://www.elster.de/EricXML/1.0/EricHoleFinanzaemter">
<Finanzamt>
<BuFaNummer>2801</BuFaNummer>
<Name>Finanzamt Offenburg Außenstelle Achern</Name>
</Finanzamt>
<Finanzamt>
<BuFaNummer>2804</BuFaNummer>
<Name>Finanzamt Villingen-Schwenningen Außenstelle Donaueschingen</Name>
</Finanzamt>
(...)
</EricHoleFinanzaemter>

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_UTI_COUNTRY_NOT_SUPPORTED
  - ERIC_GLOBAL_COMMONDATA_NICHT_VERFUEGBAR
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

## ◆ EricMtHoleFinanzamtLandNummern()

ERICAPI_IMPORT int EricMtHoleFinanzamtLandNummern | ( | EricInstanzHandle | instanz,
|  | EricRueckgabepufferHandle | rueckgabeXmlPuffer )

Die Liste aller Finanzamtlandnummern wird zurückgegeben.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [out] | rueckgabeXmlPuffer | Handle auf einen Rückgabepuffer, in den die Ergebnis XML-Daten geschrieben werden. Die XML-Daten folgen der XML Schema Definition Dokumentation\API-Rueckgabe-Schemata\EricHoleFinanzamtLandNummern.xsd. Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<EricHoleFinanzamtLandNummern xmlns="http://www.elster.de/EricXML/1.0/EricHoleFinanzamtLandNummern">
<FinanzamtLand>
<FinanzamtLandNummer>28</FinanzamtLandNummer>
<Name>Baden-Württemberg</Name>
</FinanzamtLand>
<FinanzamtLand>
<FinanzamtLandNummer>91</FinanzamtLandNummer>
<Name>Bayern (Zuständigkeit LfSt - München)</Name>
</FinanzamtLand>
(...)
</EricHoleFinanzamtLandNummern>

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_COMMONDATA_NICHT_VERFUEGBAR
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

## ◆ EricMtHoleFinanzamtsdaten()

ERICAPI_IMPORT int EricMtHoleFinanzamtsdaten | ( | EricInstanzHandle | instanz,
|  | const byteChar | bufaNr[5],
|  | EricRueckgabepufferHandle | rueckgabeXmlPuffer )

Die `finanzamtsdaten` werden für eine Bundesfinanzamtsnummer zurückgegeben.

Die Bundesfinanzamtsnummer kann über die Kombination der Funktionen EricMtHoleFinanzamtLandNummern() und EricMtHoleFinanzaemter() ermittelt werden.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | bufaNr | Übergabe der 4-stelligen Bundesfinanzamtsnummer.
  [out] | rueckgabeXmlPuffer | Handle auf einen Rückgabepuffer, in den die Ergebnis XML-Daten geschrieben werden. Die XML-Daten folgen der XML Schema Definition Dokumentation\API-Rueckgabe-Schemata\EricHoleFinanzamtsdaten.xsd. Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_NULL_PARAMETER: Parameter `bufaNr` ist NULL.
  - ERIC_GLOBAL_PRUEF_FEHLER: Die übergebene Bundesfinanzamtsnummer ist keine Ganzzahl.
  - ERIC_GLOBAL_KEINE_DATEN_VORHANDEN: Immer bei Testfinanzämtern.
  - ERIC_GLOBAL_COMMONDATA_NICHT_VERFUEGBAR
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

Siehe auch
  - EricMtHoleFinanzamtLandNummern()
  - EricMtHoleFinanzaemter()

## ◆ EricMtHoleTestfinanzaemter()

ERICAPI_IMPORT int EricMtHoleTestfinanzaemter | ( | EricInstanzHandle | instanz,
|  | EricRueckgabepufferHandle | rueckgabeXmlPuffer )

Die Testfinanzamtliste wird in `rueckgabeXmlPuffer` zurückgegeben.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [out] | rueckgabeXmlPuffer | Handle auf einen Rückgabepuffer, in den die Ergebnis XML-Daten geschrieben werden. Die XML-Daten folgen der XML Schema Definition Dokumentation\API-Rueckgabe-Schemata\EricHoleTestFinanzaemter.xsd. Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<EricHoleTestFinanzaemter xmlns="http://www.elster.de/EricXML/1.0/EricHoleTestFinanzaemter">
<Finanzamt>
<BuFaNummer>1096</BuFaNummer>
<Name>Testfinanzamt Saarland</Name>
</Finanzamt>
<Finanzamt>
<BuFaNummer>1097</BuFaNummer>
<Name>Finanzschule (Edenkoben)</Name>
</Finanzamt>
(...)
</EricHoleTestFinanzaemter>

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_COMMONDATA_NICHT_VERFUEGBAR
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

## ◆ EricMtHoleZertifikatEigenschaften()

ERICAPI_IMPORT int EricMtHoleZertifikatEigenschaften | ( | EricInstanzHandle | instanz,
|  | EricZertifikatHandle | hToken,
|  | const byteChar * | pin,
|  | EricRueckgabepufferHandle | rueckgabeXmlPuffer )

Die Eigenschaften des übergebenen Zertifikats werden im `rueckgabeXmlPuffer` zurückgegeben.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | hToken | Handle des Zertifikats, dessen Eigenschaften geholt werden sollen. Wird von der Funktion EricMtGetHandleToCertificate() zurückgeliefert.
  [in] | pin | PIN zum Öffnen des Zertifikats. Wird bei Software-Portalzertifikaten benötigt.
  [out] | rueckgabeXmlPuffer | Handle auf einen Rückgabepuffer, in den die Zertifikateigenschaften im XML-Format geschrieben werden. Das Format ist im XML Schema Dokumentation\API-Rueckgabe-Schemata\EricHoleZertifikatEigenschaften.xsd definiert. Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Zu beachten
  Bei einem ELSTER-Softwarezertifikat (.pfx) steht im Common Name (CN) die ID des ELSTER-Kontos, für das das Zertifikat ausgestellt wurde. Die Konto-ID kann beispielsweise dafür genutzt werden, bei einer Zertifikatsverlängerung das verlängerte Zertifikat dem alten Zertifikat zuzuordnen.

Beispiel:

<EricHoleZertifikatEigenschaften xmlns="http://www.elster.de/EricXML/2.0/EricHoleZertifikatEigenschaften">
<Signaturzertifikateigenschaften>
<AusgestelltAm>220817152116Z</AusgestelltAm>
<GueltigBis>230817152116Z</GueltigBis>
<Signaturalgorithmus>sha1WithRSAEncryption(1.2.840.113549.1.1.5)</Signaturalgorithmus>
<PublicKeyMD5>6b8b191936677957fe74103198e77f4e</PublicKeyMD5>
<PublicKeySHA1>884b0dfe2e10221a2aedd28c986cf34db0f1d932</PublicKeySHA1>
<PublicKeyBitLength>2048</PublicKeyBitLength>
<Issuer>
<Info><Name>CN</Name><Wert>ElsterSoftCA</Wert></Info>
<Info><Name>OU</Name><Wert>CA</Wert></Info>
(...)
</Issuer>
<Subjekt>
<Info><Name>CN</Name><Wert>1000872896</Wert></Info>
</Subjekt>
<Identifikationsmerkmaltyp>Steuernummer</Identifikationsmerkmaltyp>
<Registrierertyp>Person</Registrierertyp>
<Verifikationsart>Postweg</Verifikationsart>
<TokenTyp>Software</TokenTyp>
<Testzertifikat>true</Testzertifikat>
</Signaturzertifikateigenschaften>
<Verschluesselungszertifikateigenschaften>
(...)
</Verschluesselungszertifikateigenschaften>
</EricHoleZertifikatEigenschaften>

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN
  - ERIC_CRYPT_E_*: Ein Zertifikatsfehler aus dem Statuscodebereich von ERIC_CRYPT_E_INVALID_HANDLE = 610201101 bis 610201212

Siehe auch
  - ERiC-Entwicklerhandbuch.pdf, Kap. "Verwendung von EricHoleZertifikatEigenschaften()"
  - Dokumentation\API-Rueckgabe-Schemata\EricHoleZertifikatEigenschaften.xsd

## ◆ EricMtHoleZertifikatFingerabdruck()

ERICAPI_IMPORT int EricMtHoleZertifikatFingerabdruck | ( | EricInstanzHandle | instanz,
|  | const eric_verschluesselungs_parameter_t * | cryptoParameter,
|  | EricRueckgabepufferHandle | fingerabdruckPuffer,
|  | EricRueckgabepufferHandle | signaturPuffer )

Der Fingerabdruck und dessen Signatur wird für das übergebene Zertifikat zurückgegeben.

Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | cryptoParameter | Zertifikatsdaten, siehe eric_verschluesselungs_parameter_t. Das in der übergebenen Struktur referenzierte Zertifikat muss ein clientseitig erzeugtes Zertifikat (CEZ) sein.
  [out] | fingerabdruckPuffer | Handle auf einen Rückgabepuffer, in den der Fingerabdruck geschrieben wird, siehe EricRueckgabepufferHandle.
  [out] | signaturPuffer | Handle auf einen Rückgabepuffer, in den die Signatur des Fingerabdrucks geschrieben wird, siehe EricRueckgabepufferHandle.

Zu beachten
  Die Erzeugung eines Fingerabdrucks mit dieser Funktion ist nur in Zusammenhang mit clientseitig erzeugten Zertifikaten definiert.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_PUFFER_ZUGRIFFSKONFLIKT
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN
  - ERIC_CRYPT_E_P12_READ
  - ERIC_CRYPT_E_P12_DECODE
  - ERIC_CRYPT_E_PIN_WRONG
  - ERIC_CRYPT_E_P12_SIG_KEY
  - ERIC_CRYPT_E_P12_ENC_KEY
  - ERIC_CRYPT_ZERTIFIKAT
  - ERIC_CRYPT_EIDKARTE_NICHT_UNTERSTUETZT
  - ERIC_CRYPT_SIGNATUR
  - ERIC_CRYPT_CORRUPTED

## ◆ EricMtInstanzErzeugen()

ERICAPI_IMPORT EricInstanzHandle EricMtInstanzErzeugen | ( | const char * | pluginPfad,
|  | const char * | logPfad )

Erstellt und initialisiert eine neue ERiC-Instanz.

Der erzeugte EricInstanzHandle ist im Parameter `instanz` der Multithreading-API zu übergeben. Zum Beenden einer ERiC-Instanz ist EricMtInstanzFreigeben() aufzurufen.

Parameter

  [in] | pluginPfad | Pfad, in dem die Plugins rekursiv gesucht werden. Ist der Zeiger gleich NULL, wird der Pfad zur Bibliothek ericapi verwendet.
  [in] | logPfad | Optionaler Pfad zur Log-Datei eric.log. Ist der Wert gleich NULL, wird das betriebssystemspezifische Verzeichnis für temporäre Dateien verwendet.

Rückgabe
  - EricInstanzHandle != NULL: Zeiger auf die erzeugte ERiC-Instanz.
  - EricInstanzHandle == NULL: Fehler, Fehlerursache siehe Protokolldatei eric.log

Zu beachten

  Kann kein eric.log angelegt werden, wird eine entsprechende Fehlermeldung auf die Konsole (stderr) geschrieben und an den Windows-Ereignisdienst bzw. den syslogd-Dienst (Linux, AIX, macOS) geschickt.

  Für Linux, AIX und macOS ist zu beachten, dass der syslogd-Dienst gegebenenfalls erst noch zu aktivieren und für die Protokollierung von Meldungen der Facility "User" zu konfigurieren ist. Suchkriterien für ERiC-Meldungen in der Windows-Ereignisansicht sind "ERiC (Elster Rich Client)" als Quelle und "Anwendung" als Protokoll.

  Suchkriterien für ERiC-Meldungen in den Systemlogdateien unter Linux, AIX und macOS sind die Facility "User" und der Ident "ERiC (Elster Rich Client)".

Siehe auch
  - ERiC-Entwicklerhandbuch.pdf, Kap. "Hinweise zum optimierten Einsatz von ERiC-Instanzen und Plugins"
  - EricMtInstanzFreigeben()

## ◆ EricMtInstanzFreigeben()

ERICAPI_IMPORT int EricMtInstanzFreigeben | ( | EricInstanzHandle | instanz | ) |

Die übergebene ERiC-Instanz wird beendet und deren Speicher freigegeben.

Die freigegebene ERiC-Instanz kann nicht mehr verwendet werden. Andere ERiC-Instanzen bleiben von der Freigabe unberührt und können weiter verwendet werden.

Parameter

  [in] | instanz | ERiC-Instanz, die freigegeben werden soll.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_UNGUELTIGE_INSTANZ
  - ERIC_GLOBAL_UNGUELTIGER_PARAMETER
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

Siehe auch
  - EricMtInstanzErzeugen()

## ◆ EricMtMakeElsterEWAz()

ERICAPI_IMPORT int EricMtMakeElsterEWAz | ( | EricInstanzHandle | instanz,
|  | const byteChar * | ewAzBescheid,
|  | const byteChar * | landeskuerzel,
|  | EricRueckgabepufferHandle | ewAzElsterPuffer )

Konvertiert ein Einheitswert-Aktenzeichen in das ELSTER-Format.

Konvertiert ein gültiges Einheitswert-Aktenzeichen in einem landesspezifischen Bescheidformat (z.B. 208/035-3-03889.3) unter Angabe des Landeskürzels in ein Einheitswert-Aktenzeichen im ELSTER-Format (z.B. 520840353038893).

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | ewAzBescheid | Zeiger auf das Einheitswert-Aktenzeichen in einem landesspezifischen Bescheidformat.
  [in] | landeskuerzel | Zeiger auf das Landeskürzel (zum Beispiel BY für Bayern)
  [out] | ewAzElsterPuffer | Handle auf einen Rückgabepuffer, in den das erzeugte Einheitswert-Aktenzeichen im ELSTER-Format geschrieben wird.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_EWAZ_UNGUELTIG
  - ERIC_GLOBAL_EWAZ_LANDESKUERZEL_UNBEKANNT
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_UNGUELTIGER_PARAMETER
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

Siehe auch
  - Landeskürzel siehe ISO-3166-2

## ◆ EricMtMakeElsterStnr()

ERICAPI_IMPORT int EricMtMakeElsterStnr | ( | EricInstanzHandle | instanz,
|  | const byteChar * | steuernrBescheid,
|  | const byteChar | landesnr[2+1],
|  | const byteChar | bundesfinanzamtsnr[4+1],
|  | EricRueckgabepufferHandle | steuernrPuffer )

Es wird eine Steuernummer im ELSTER-Steuernummerformat erzeugt.

Die Funktion erzeugt aus einer angegebenen Steuernummer im Format des Steuerbescheides eine 13-stellige Steuernummer im ELSTER-Steuernummerformat.

Die sich ergebende 13-stellige Steuernummer im ELSTER-Steuernummerformat wird von der Funktion EricMtMakeElsterStnr() auch auf Gültigkeit geprüft.

Einer der beiden Parameter `landesnr` oder `bundesfinanzamtsnr` muss korrekt angegeben werden. Der jeweils andere Parameter darf NULL oder leer sein. Bei bayerischen und berliner Steuernummern im Format BBB/UUUUP ist die Angabe der Bundesfinanzamtsnummer zwingend erforderlich.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | steuernrBescheid | Format der Steuernummer wie auch auf amtlichen Schreiben angegeben.
  [in] | landesnr | 2-stellige Landesnummer (entspricht den ersten zwei Stellen der Bundesfinanzamtsnummer).
  [in] | bundesfinanzamtsnr | 4-stellige Bundesfinanzamtsnummer.
  [out] | steuernrPuffer | Handle auf einen Rückgabepuffer, in den die Steuernummer im ELSTER-Steuernummerformat geschrieben wird. Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_STEUERNUMMER_UNGUELTIG
  - ERIC_GLOBAL_LANDESNUMMER_UNBEKANNT
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_UNGUELTIGER_PARAMETER
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

## ◆ EricMtPruefeBIC()

ERICAPI_IMPORT int EricMtPruefeBIC | ( | EricInstanzHandle | instanz,
|  | const byteChar * | bic )

Die `bic` wird auf Gültigkeit überprüft.

Die Prüfung erfolgt in zwei Schritten:

1. Formale Prüfung auf gültige Zeichen und richtige Länge.
2. Prüfung, ob das Länderkennzeichen für BIC gültig ist.

Falls die BIC ungültig ist liefert die Funktion EricMtHoleFehlerText() den zugehörigen Fehlertext.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | bic | Zeiger auf eine NULL-terminierte Zeichenkette.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_BIC_FORMALER_FEHLER: Ungültige Zeichen, falsche Länge.
  - ERIC_GLOBAL_BIC_LAENDERCODE_FEHLER
  - ERIC_GLOBAL_NULL_PARAMETER: Parameter `bic` ist NULL.
  - ERIC_GLOBAL_COMMONDATA_NICHT_VERFUEGBAR
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

Siehe auch
  - ERiC-Entwicklerhandbuch.pdf, Kap. "BIC ISO-Ländercodes"
  - ERiC-Entwicklerhandbuch.pdf, Kap. "BIC-Prüfung"

## ◆ EricMtPruefeBuFaNummer()

ERICAPI_IMPORT int EricMtPruefeBuFaNummer | ( | EricInstanzHandle | instanz,
|  | const byteChar * | steuernummer )

Die Bundesfinanzamtsnummer wird überprüft.

Wird eine 13-stellige Steuernummer im ELSTER-Steuernummernformat angegeben, so wird nur die Bundesfinanzamtsnummer (= die ersten 4 Stellen der 13-stelligen Steuernummer) geprüft.

Eine Prüfung der Steuernummer selbst findet nicht statt (hierfür EricMtPruefeSteuernummer() verwenden).

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | steuernummer | 13-stellige Steuernummer im ELSTER Steuernummernformat bzw. 4-stellige Bundesfinanzamtsnummer.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_BUFANR_UNBEKANNT: Die Bundesfinanzamtsnummer ist unbekannt oder ungültig.
  - ERIC_GLOBAL_NULL_PARAMETER: Es wurde keine Bundesfinanzamtsnummer übergeben (Parameter ist NULL).
  - ERIC_GLOBAL_COMMONDATA_NICHT_VERFUEGBAR
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

Siehe auch
  - EricMtPruefeSteuernummer()
  - Pruefung_der_Steuer_und_Steueridentifikatsnummer.pdf, siehe Entwicklerbereich bei ELSTER.

## ◆ EricMtPruefeEWAz()

ERICAPI_IMPORT int EricMtPruefeEWAz | ( | EricInstanzHandle | instanz,
|  | const byteChar * | einheitswertAz )

Überprüft ein `Einheitswert-Aktenzeichen` im ELSTER-Format auf Gültigkeit.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | einheitswertAz | Zeiger auf ein Einheitswert-Aktenzeichen im ELSTER-Format

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_EWAZ_UNGUELTIG
  - ERIC_GLOBAL_COMMONDATA_NICHT_VERFUEGBAR
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

## ◆ EricMtPruefeIBAN()

ERICAPI_IMPORT int EricMtPruefeIBAN | ( | EricInstanzHandle | instanz,
|  | const byteChar * | iban )

Die `iban` wird auf Gültigkeit überprüft.

Die Prüfung erfolgt in vier Schritten:

1. Formale Prüfung auf gültige Zeichen und richtige Länge.
2. Prüfung, ob das Länderkennzeichen für IBAN gültig ist.
3. Prüfung, ob das länderspezifische Format gültig ist.
4. Prüfung, ob die Prüfziffer der IBAN gültig ist.

Falls die IBAN ungültig ist, liefert die Funktion EricMtHoleFehlerText() den zugehörigen Fehlertext.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | iban | Zeiger auf eine NULL-terminierte Zeichenkette.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_IBAN_FORMALER_FEHLER: Ungültige Zeichen, falsche Länge.
  - ERIC_GLOBAL_IBAN_LAENDERCODE_FEHLER
  - ERIC_GLOBAL_IBAN_LANDESFORMAT_FEHLER
  - ERIC_GLOBAL_IBAN_PRUEFZIFFER_FEHLER
  - ERIC_GLOBAL_NULL_PARAMETER: Parameter `iban` ist NULL.
  - ERIC_GLOBAL_COMMONDATA_NICHT_VERFUEGBAR
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

Siehe auch
  - ERiC-Entwicklerhandbuch.pdf, Kap. "IBAN - länderspezifische Formate"
  - ERiC-Entwicklerhandbuch.pdf, Kap. "IBAN-Prüfung"

## ◆ EricMtPruefeIdentifikationsMerkmal()

ERICAPI_IMPORT int EricMtPruefeIdentifikationsMerkmal | ( | EricInstanzHandle | instanz,
|  | const byteChar * | steuerId )

Die `steuerId` wird auf Gültigkeit überprüft.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | steuerId | Steuer-Identifikationsnummer (IdNr)

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_IDNUMMER_UNGUELTIG
  - ERIC_GLOBAL_COMMONDATA_NICHT_VERFUEGBAR
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

Siehe auch
  - EricMtPruefeSteuernummer()
  - ERiC-Entwicklerhandbuch.pdf, Kap. "Prüfung der Steueridentifikationsnummer (IdNr)"
  - ERiC-Entwicklerhandbuch.pdf, Kap. "Test-Steueridentifikationsnummer"

## ◆ EricMtPruefeSteuernummer()

ERICAPI_IMPORT int EricMtPruefeSteuernummer | ( | EricInstanzHandle | instanz,
|  | const byteChar * | steuernummer )

Die `steuernummer` wird einschließlich Bundesfinanzamtsnummer auf formale Richtigkeit geprüft.

Zur Prüfung der Bundesfinanzamtsnummer wird EricMtPruefeBuFaNummer() verwendet.

Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | steuernummer | NULL-terminierte 13-stellige Steuernummer im ELSTER-Steuernummernformat.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_STEUERNUMMER_UNGUELTIG
  - ERIC_GLOBAL_COMMONDATA_NICHT_VERFUEGBAR
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

Siehe auch
  - EricMtPruefeBuFaNummer()
  - Pruefung_der_Steuer_und_Steueridentifikatsnummer.pdf, siehe Entwicklerbereich bei ELSTER.

## ◆ EricMtPruefeWIdNr()

ERICAPI_IMPORT int EricMtPruefeWIdNr | ( | EricInstanzHandle | instanz,
|  | const byteChar * | wIdNr )

Die `Wirtschafts-Identifikationsnummer` (`W-IdNr`.) wird auf formale Gültigkeit überprüft.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | wIdNr | NULL-terminierte Wirtschafts-Identifikationsnummer mit oder ohne Unterscheidungsmerkmal.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_IDNUMMER_UNGUELTIG
  - ERIC_GLOBAL_COMMONDATA_NICHT_VERFUEGBAR
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

Siehe auch
  - ERiC-Entwicklerhandbuch.pdf, Kap. "Prüfung der Wirtschafts-Identifikationsnummer (W-IdNr.)"

## ◆ EricMtPruefeZertifikatPin()

ERICAPI_IMPORT int EricMtPruefeZertifikatPin | ( | EricInstanzHandle | instanz,
|  | const byteChar * | pathToKeystore,
|  | const byteChar * | pin,
|  | uint32_t | keyType )

Prüft, ob die `pin` zum Zertifikat `pathToKeystore` passt. Nicht anwendbar auf Ad Hoc-Zertifikate (AHZ), die für einen neuen Personalausweis (nPA) ausgestellt sind.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | pathToKeystore | Folgende Zertifikatstypen werden unterstützt: Clientseitig erzeugtes Zertifikat: Pfad zum Verzeichnis, in dem sich die Zertifikats-Datei (.cer) und die Datei mit dem privaten Schlüssel (.p12) befinden. Diese Kryptomittel wurden mit EricMtCreateKey() erzeugt. Der Pfad zum Verzeichnis ist bei clientseitig erzeugten Zertifikaten relativ zum aktuellen Arbeitsverzeichnis oder absolut anzugeben. Software-Portalzertifikat: Pfad zur Software-Zertifikatsdatei (i.d.R. mit der Endung .pfx). Der Pfad zur Datei ist bei Software-Zertifikaten relativ zum aktuellen Arbeitsverzeichnis oder absolut anzugeben. Sicherheitsstick: Pfad zur Treiberdatei, siehe (2). Bitte beachten, dass der Treiber betriebssystemabhängig sein kann. Weitere Informationen in der Anleitung zum Sicherheitsstick oder unter https://www.sicherheitsstick.de. Signaturkarte: Pfad zur Treiberdatei, welcher einen Zugriff auf die Signaturkarte ermöglicht, siehe (2). Weitere Informationen in der Anleitung zur Signaturkarte.
  [in] | pin | PIN für den Zugriff auf den privaten Schlüssel des Zertifikats.
  [in] | keyType | Mögliche Eingabewerte: 0: eSignatureKey: Schlüssel für die Signatur von Daten, siehe (1). 1: eEncryptionKey: Schlüssel für die Verschlüsselung von Daten, siehe (1).

(1) Bei einem Zertifikat wie dem mit EricMtCreateKey() clientseitig erzeugten Zertifikat (CEZ), das nur einen einzigen, gemeinsamen Schlüssel für Signatur und Verschlüsselung besitzt, sind beide Eingabewerte erlaubt. Die Werte beziehen sich dann beide auf denselben Schlüssel.

(2) Bei Sicherheitssticks und Signaturkarten ist bei der Angabe des Treibers der Suchmechanismus nach dynamischen Modulen des jeweiligen Betriebssystems zu berücksichtigen. Weitere Informationen sind z.B. unter Windows der Dokumentation der `LoadLibrary()` oder unter Linux und macOS der Dokumentation der `dlopen()` zu entnehmen.

Pfade müssen auf Windows in der für Datei-Funktionen benutzten ANSI-Codepage, auf Linux, AIX und Linux Power in der für das Dateisystem benutzten Locale und auf macOS in der "decomposed form" von UTF-8 übergeben werden. Bitte weitere Betriebssystemspezifika bzgl. nicht erlaubter Zeichen in Pfaden und Pfadtrennzeichen beachten.

Für Details zu Pfaden im ERiC siehe ERiC-Entwicklerhandbuch.pdf, Kapitel "Übergabe von Pfaden an ERiC API-Funktionen".

Es wird empfohlen, geöffnete Zertifikatshandle zu schließen, bevor mit der API-Funktion EricMtPruefeZertifikatPin() das gewünschte Zertifikat geprüft wird.

Zu beachten
  Eine falsche PIN-Eingabe erhöht bei Sicherheitsstick und Signaturkarte den Zähler für Fehlversuche. Welche Zertifikatstypen aufgrund von 3 Fehlversuchen gesperrt werden, ist im ERiC-Entwicklerhandbuch.pdf, Kap. "Das Portalzertifikat (POZ)" beschrieben.

Rückgabe
  - ERIC_OK
  - ERIC_CRYPT_E_PIN_WRONG
  - ERIC_CRYPT_NICHT_UNTERSTUETZTES_PSE_FORMAT
  - ERIC_CRYPT_EIDKARTE_NICHT_UNTERSTUETZT
  - ERIC_CRYPT_E_PSE_PATH
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

## ◆ EricMtRegistriereFortschrittCallback()

ERICAPI_IMPORT int EricMtRegistriereFortschrittCallback | ( | EricInstanzHandle | instanz,
|  | EricFortschrittCallback | funktion,
|  | void * | benutzerdaten )

Die `funktion` wird als Callback-Funktion für EricMtBearbeiteVorgang() registriert.

Die registrierte Callback-Funktion wird von der Funktion EricMtBearbeiteVorgang() aufgerufen, um bei der Verarbeitung den Fortschritt der einzelnen Arbeitsbereiche anzuzeigen.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | funktion | Zeiger auf die zu registrierende Funktion oder `NULL`
  [in] | benutzerdaten | Zeiger, der der registrierten Funktion immer mitgegeben wird. Die Anwendung kann diesen Parameter dazu verwenden, einen Zeiger auf eigene Daten oder Funktionen an die zu registrierende Funktion übergeben zu lassen.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_UNGUELTIGER_PARAMETER
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

Bemerkungen
  - Wenn eine zuvor registrierte Funktion nicht mehr aufgerufen werden soll, ist EricMtRegistriereFortschrittCallback() mit dem Wert `NULL` im Parameter `funktion` aufzurufen.
  - Es ist nicht erlaubt eine ERiC API-Funktion aus einer Callback-Funktion aufzurufen.
  - Die Verarbeitung im Callback findet synchron statt. Deshalb sollte der Callback sehr schnell ausgeführt werden.

Siehe auch
  - EricFortschrittCallback
  - EricMtBearbeiteVorgang()
  - ERiC-Entwicklerhandbuch.pdf, Kap. "Funktionen für Fortschrittcallbacks"

## ◆ EricMtRegistriereGlobalenFortschrittCallback()

ERICAPI_IMPORT int EricMtRegistriereGlobalenFortschrittCallback | ( | EricInstanzHandle | instanz,
|  | EricFortschrittCallback | funktion,
|  | void * | benutzerdaten )

Die registrierte `funktion` wird als Callback-Funktion von EricMtBearbeiteVorgang() aufgerufen und zeigt den Gesamtfortschritt der Verarbeitung an.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | funktion | Zeiger auf die zu registrierende Funktion oder `NULL`
  [in] | benutzerdaten | Zeiger, der der registrierten Funktion immer mitgegeben wird. Die Anwendung kann diesen Parameter dazu verwenden, einen Zeiger auf eigene Daten oder Funktionen an die zu registrierende Funktion übergeben zu lassen.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_UNGUELTIGER_PARAMETER
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

Bemerkungen
  - Wenn eine zuvor registrierte Funktion nicht mehr aufgerufen werden soll, ist EricMtRegistriereGlobalenFortschrittCallback() mit dem Wert `NULL` im Parameter `funktion` aufzurufen.
  - Es ist nicht erlaubt eine ERiC API-Funktion aus einer Callback-Funktion aufzurufen.
  - Die Verarbeitung im Callback findet synchron statt. Deshalb sollte der Callback sehr schnell ausgeführt werden.

Siehe auch
  - EricMtBearbeiteVorgang()
  - ERiC-Entwicklerhandbuch.pdf, Kap. "Funktionen für Fortschrittcallbacks"

## ◆ EricMtRegistriereLogCallback()

ERICAPI_IMPORT int EricMtRegistriereLogCallback | ( | EricInstanzHandle | instanz,
|  | EricLogCallback | funktion,
|  | uint32_t | schreibeEricLogDatei,
|  | void * | benutzerdaten )

Die registrierte `funktion` wird als Callback-Funktion für jede Lognachricht aufgerufen. Die Ausgabe entspricht einer Zeile im eric.log.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | funktion | Zeiger auf die zu registrierende Funktion oder NULL.
  [in] | schreibeEricLogDatei | Log-Nachrichten im eric.log: `1` Jede Log-Nachricht wird nach eric.log geschrieben. Der Parameter `funktion` kann auf eine Funktion zeigen oder `NULL` sein. `0` Falls `funktion` `!=` `NULL` werden keine Log-Nachrichten nach eric.log geschrieben, andernfalls werden die Log-Nachrichten nach eric.log geschrieben.
  [in] | benutzerdaten | Zeiger, welcher der registrierten Funktion immer mitgegeben wird. Die Anwendung kann diesen Parameter dazu verwenden, einen Zeiger auf eigene Daten oder Funktionen an die zu registrierende Funktion übergeben zu lassen.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_UNGUELTIGER_PARAMETER
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

Bemerkungen
  - Wenn eine zuvor registrierte Funktion nicht mehr aufgerufen werden soll, ist EricMtRegistriereLogCallback() mit dem Wert `NULL` im Parameter `funktion` aufzurufen (=Deregistrierung).
  - Vor dem Beenden der Steueranwendung ist eine registrierte Funktion zu deregistrieren, da es sonst zu einem Absturz kommen kann.
  - Es ist nicht erlaubt eine ERiC API-Funktion aus einer Callback-Funktion aufzurufen.
  - Die Verarbeitung im Callback findet synchron statt. Deshalb sollte der Callback sehr schnell ausgeführt werden.

## ◆ EricMtRueckgabepufferErzeugen()

ERICAPI_IMPORT EricRueckgabepufferHandle EricMtRueckgabepufferErzeugen | ( | EricInstanzHandle | instanz | ) |

Diese API-Funktion erzeugt einen Rückgabepuffer und gibt ein Handle darauf zurück.

Die von dieser Funktion erzeugten Rückgabepuffer werden verwendet, um die Ausgaben von ERiC-Funktionen (z.B. EricMtBearbeiteVorgang()) aufzunehmen. Dazu wird das Rückgabepuffer-Handle für den Schreibvorgang an die ausgebende Funktion übergeben.

Zum Auslesen des von den API-Funktionen beschriebenen Puffers wird das Rückgabepuffer-Handle an EricMtRueckgabepufferInhalt() übergeben. Ein einmal erzeugtes Rückgabepuffer-Handle kann für weitere nachfolgende Aufrufe von ERiC API-Funktionen wiederverwendet werden. Bei einer Wiederverwendung eines Handles werden frühere Inhalte überschrieben. Nach Verwendung muss jeder Rückgabepuffer mit EricMtRueckgabepufferFreigeben() freigegeben werden.

Rückgabepuffer sind der Singlethreading-API bzw. einer ERiC-Instanz der Multithreading-API fest zugeordnet. Die Funktionen der ERiC API, die einen Rückgabepuffer entgegennehmen, geben den Fehlercode ERIC_GLOBAL_PUFFER_UNGLEICHER_INSTANZ zurück, wenn der übergebene Rückgabepuffer:

- mit der Singlethreading-API erzeugt worden ist und dann mit der Multithreading-API verwendet wird.
- mit der Multithreading-API erzeugt worden ist und dann mit der Singlethreading-API verwendet wird.
- mit einer ERiC-Instanz erzeugt worden ist und dann mit einer anderen Instanz verwendet wird.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.

Rückgabe
  - EricRueckgabepufferHandle im Erfolgsfall.
  - NULL im Fehlerfall.

Siehe auch
  - EricMtRueckgabepufferLaenge()
  - EricMtRueckgabepufferInhalt()
  - EricMtRueckgabepufferFreigeben()

## ◆ EricMtRueckgabepufferFreigeben()

ERICAPI_IMPORT int EricMtRueckgabepufferFreigeben | ( | EricInstanzHandle | instanz,
|  | EricRueckgabepufferHandle | handle )

Der durch das `handle` bezeichnete Rückgabepuffer wird freigegeben.

Das Handle darf danach nicht weiter verwendet werden. Es wird daher empfohlen, Handle-Variablen nach der Freigabe explizit auf NULL zu setzen.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | handle | Handle auf einen mit EricMtRueckgabepufferErzeugen() angelegten Rückgabepuffer. Dieser Rückgabepuffer darf nicht bereits freigegeben worden sein.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_UNGUELTIGER_PARAMETER
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN

Siehe auch
  - EricMtRueckgabepufferErzeugen()
  - EricMtRueckgabepufferLaenge()
  - EricMtRueckgabepufferInhalt()

## ◆ EricMtRueckgabepufferInhalt()

ERICAPI_IMPORT const char * EricMtRueckgabepufferInhalt | ( | EricInstanzHandle | instanz,
|  | EricRueckgabepufferHandle | handle )

Der durch das `handle` bezeichnete Inhalt des Rückgabepuffers wird zurückgegeben.

Der zurückgegebene Zeiger verweist auf ein Byte-Array, das alle in den Rückgabepuffer geschriebenen Bytes sowie eine abschließende NULL-Terminierung enthält. Dieses Array existiert so lange im Speicher, bis der Rückgabepuffer entweder (bei einer Wiederverwendung des Handles) erneut beschrieben oder der Puffer explizit freigegeben wird.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | handle | Handle auf einen mit EricMtRueckgabepufferErzeugen() angelegten Rückgabepuffer. Dieser Rückgabepuffer darf nicht bereits freigegeben worden sein.

Rückgabe
  - Zeiger auf den NULL-terminierten Rückgabepufferinhalt, wenn ein gültiges Handle übergeben wird.
  - NULL: Bei Übergabe des ungültigen Handles NULL.

Siehe auch
  - EricMtRueckgabepufferErzeugen()
  - EricMtRueckgabepufferLaenge()
  - EricMtRueckgabepufferFreigeben()

## ◆ EricMtRueckgabepufferLaenge()

ERICAPI_IMPORT uint32_t EricMtRueckgabepufferLaenge | ( | EricInstanzHandle | instanz,
|  | EricRueckgabepufferHandle | handle )

Die Länge des Rückgabepufferinhalts wird zurückgegeben.

Die zurückgegebene Zahl entspricht der Anzahl von Bytes, die von einer zuvor aufgerufenen ERiC API-Funktion in den Rückgabepuffer geschrieben wurden. Die NULL-Terminierung, die bei Aufruf von EricMtRueckgabepufferInhalt() an das zurückgegebene Byte-Array angefügt wird, wird bei dieser Längenangabe nicht berücksichtigt.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [in] | handle | Handle auf einen mit EricMtRueckgabepufferErzeugen() angelegten Rückgabepuffer. Dieser Rückgabepuffer darf nicht bereits freigegeben worden sein.

Rückgabe
  - Anzahl der in den Rückgabepuffer geschriebenen Bytes, wenn ein gültiges Handle übergeben wird.
  - 0: Bei Übergabe des ungültigen Handles NULL.

Siehe auch
  - EricMtRueckgabepufferErzeugen()
  - EricMtRueckgabepufferInhalt()
  - EricMtRueckgabepufferFreigeben()

## ◆ EricMtSystemCheck()

ERICAPI_IMPORT int EricMtSystemCheck | ( | EricInstanzHandle | instanz | ) |

Es werden Plattform-, Betriebssystem- und ERiC-Informationen ausgegeben.

Diese Funktion liefert Informationen über die verwendeten ERiC-Bibliotheken, ERiC-Druckvorlagen, die eingesetzte Plattform, den Arbeitsspeicher und das verwendete Betriebssystem.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_UNGUELTIGER_PARAMETER
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - weitere, siehe eric_fehlercodes.h

Siehe auch
  - EricMtVersion()

## ◆ EricMtVersion()

ERICAPI_IMPORT int EricMtVersion | ( | EricInstanzHandle | instanz,
|  | EricRueckgabepufferHandle | rueckgabeXmlPuffer )

Es wird eine Liste sämtlicher Produkt- und Dateiversionen der verwendeten ERiC-Bibliotheken als XML-Daten zurückgegeben.

Diese Funktion kann bei auftretenden Fehlern die Fehlersuche beschleunigen und Supportfälle unterstützen.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll.
  [out] | rueckgabeXmlPuffer | Handle auf einen Rückgabepuffer, in den zu allen ERiC-Bibliotheken die Produkt- und Dateiversionen als XML-Daten nach XML Schema Definition Dokumentation\API-Rueckgabe-Schemata\EricVersion.xsd geschrieben werden. Zur Erzeugung, Verwendung und Freigabe von Rückgabepuffern siehe Dokumentation zu EricRueckgabepufferHandle.

Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<EricVersion xmlns="http://www.elster.de/EricXML/1.0/EricVersion">
<Bibliothek>
<Name>ericapi.dll</Name>
<Produktversion>99, 1, 2, 32767</Produktversion>
<Dateiversion>2008, 3, 5, 0</Dateiversion>
</Bibliothek>
<Bibliothek>
<Name>ericctrl.dll</Name>
<Produktversion>99, 1, 2, 32767</Produktversion>
<Dateiversion>2008, 3, 5, 0</Dateiversion>
</Bibliothek>
(...)
</EricVersion>

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - weitere, siehe eric_fehlercodes.h

Siehe auch
  - EricMtSystemCheck()

## ◆ EricMtZertifikatOeffnenAusBytes()

ERICAPI_IMPORT int EricMtZertifikatOeffnenAusBytes | ( | EricInstanzHandle | instanz,
|  | EricZertifikatHandle * | hToken,
|  | const byteChar * | pkcs12Container,
|  | uint32_t | containerGroesse,
|  | const byteChar * | pkcs12Passwort )

Für das im Speicher übergebene Zertifikat wird das Handle `hToken` zurückgeliefert.

Die ERiC API benötigt Zertifikat-Handles typischerweise bei kryptografischen Operationen.

Zertifikat-Handles sollten möglichst frühzeitig, d.h. wenn sie nicht mehr benötigt werden, mit EricMtCloseHandleToCertificate() freigegeben werden, spätestens jedoch zum Programmende bzw. vor dem Entladen der Bibliothek ericapi.

Parameter

  [in] | instanz | Die ERiC-Instanz, auf der diese Funktion ausgeführt werden soll
  [out] | hToken | Handle zu einem der folgenden Zertifikate: Portalzertifikat clientseitig erzeugtes Zertifikat
  [in] | pkcs12Container | Speicheradresse des Zertifikats im PKCS#12-Format. Es werden nur passwortgeschützte PKCS#12-Container akzeptiert.
  [in] | containerGroesse | Größe des PKCS#12-Containers in Bytes
  [in] | pkcs12Passwort | Das Passwort oder die PIN des PKCS#12-Containers. Dieser Parameter darf nicht NULL sein.

Rückgabe
  - ERIC_OK
  - ERIC_GLOBAL_NULL_PARAMETER
  - ERIC_GLOBAL_NICHT_GENUEGEND_ARBEITSSPEICHER
  - ERIC_GLOBAL_UNKNOWN
  - ERIC_CRYPT_NICHT_UNTERSTUETZTES_PSE_FORMAT
  - ERIC_CRYPT_E_MAX_SESSION
  - ERIC_CRYPT_E_PSE_PATH
  - ERIC_CRYPT_E_BUSY
  - ERIC_CRYPT_E_P11_SLOT_EMPTY
  - ERIC_CRYPT_E_NO_SIG_ENC_KEY
  - ERIC_CRYPT_E_PIN_WRONG
  - ERIC_CRYPT_E_LOAD_DLL
  - ERIC_CRYPT_E_NO_SERVICE
  - ERIC_CRYPT_E_ESICL_EXCEPTION

Siehe auch
  - EricMtCloseHandleToCertificate()
  - EricMtGetPinStatus()