# Package at.chipkarte.client.gina.soap

Interface und Klassen des GINA-Service (GINA).

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  IGinaService | Dieses Service stellt GINA-spezifische Funktionen zur Verfügung.

- Class Summary
  Class | Description
  --- | ---
  CardReader | Enthält Informationen zu einen Kartenleser.
  DialogsInfo | Liefert Informationen über die Anzahl der am Ordinationsclient zurzeit aufgebauten Dialoge beziehungsweise über die maximale Anzahl der aufbaubaren Dialoge.
  GinaInfo | Enthält GINA-Informationen.
  GinaVersion | Enthält Informationen zur GINA-Softwareversion und dem GINA-Typ.
  ServiceStatusInformation | Enthält Statusinformationen und gegebenenfalls Hinweise für ein Service.
  StatusInformationen | Enthält GINA-Informationen und Verfügbarkeitsinformationen zu den auf der GINA installierten Services.

## Package at.chipkarte.client.gina.soap Description

Interface und Klassen des GINA-Service (GINA). Enthält den SOAP Endpoint `IGinaService` sowie die dazu notwendigen Klassen.
Inhalt der GINA package-Beschreibung:

- Allgemein

- Inhalt
- GINA-Typ
- Rechte

- Funktionalität des GINA-Service

- Freie Dialoge
- Kartenleser

- Zugriff auf den Kartenleser
- Lesen von Kartendaten
- Kartenleser abfragen
- Kartenleser setzen
- Kartenleserstatus abfragen
- Kartenleser freigeben für Multihost-Systeme

- Informationen des Ordinationsclient abfragen
- Ordinationsclient testen (Funktionstest)

# Allgemein

## Inhalt

Das GINA-Service beinhaltet Funktionen die nur auf dem Ordinationsclient (der GINA) ausfgeführt werden.
Diese Funktionen werden mit Abschluss der Umstellung auf GINAaaS nicht mehr benötigt.
Die Funktionen zur Abfrage der Kartenleser, zum Setzen eines Kartenlesers in einem Dialog, sowie zur Freigabe eines Kartenlesers werden zwecks Kompatibilität zu den noch nicht umgestellen Services weiterhin angeboten!
Das Lesen von Kartendaten wird nicht mehr explizit angeboten. Diese Informationen sind durch die VPSW mittels zur Verfügung gesellter REST Schnittstelle vom LANCCR abzufragen.
Die Dokumentation des REST-Services zur Kommunikation mit dem Kartenleser ist zu finden unter:Swagger Doku LANCCR.

## GINA-Typ

Man unterscheidet zwei Arten von GINAs:

- WIRK-GINA (PRODUKTIV-GINA)
- VPSWH-GINA

Vertragspartnersoftware-Hersteller (VPSWH) können sich mit ihrer / ihren Vertragspartnernummer(n), respektive ihren Pseudo-o-cards, nur auf VPSWH-GINAs anmelden.
Äquivalent können Vertragspartner (VP) sich mit ihrer / ihren Vertragspartnernummer(n), respektive ihren o-cards, nur auf WIRK-GINAs anmelden.
Welchen GINA-Typ die verwendete GINA besitzt, kann abgefragt werden. Siehe hierzu Informationen des Ordinationsclient abfragen.

## Rechte

Für die Funktionen des GINA-Service werden keine bestimmten Rechte benötigt.

# Funktionalität des GINA-Service

## Freie Dialoge

Die Anzahl der Dialoge auf einem Ordinationsclient ist beschränkt. Die maximale Anzahl wird durch das System vorgegeben und kann nicht über die Vertragspartnersoftware-Schnittstelle geändert werden. Die aktuelle Konfiguration und die Anzahl der bereits aufgebauten Dialoge kann über die Funktion getFreeDialogs() abgefragt werden.
Die Nutzung dieser Funktion ist nur noch zeitlich begrenzt möglich.

## Kartenleser

### Kartenleser abfragen

Mit der Funktion getCardReaders() kann man die am Ordinationsclient angeschlossenen Kartenleser abfragen.
Die Funktion retourniert für jeden Kartenleser ein Objekt vom Typ CardReader, welches die Kartenleser-ID (Id) enthält. Die Kartenleser-ID entspricht dabei dem Anzeigenamen des Kartenlesers und dient der eindeutigen Referenzierung des Kartenlesers in allen weiteren Funktionen des eCS (z.B. CardReaderId in setCardReader()).
Die Nutzung dieser Funktion ist nur noch zeitlich begrenzt möglich. Die Ermittlung der Kartenleser ist umzustellen auf das CRS Service.

### Kartenleser setzen

Mit der Funktion setCardReader() kann man einem Dialog einen Kartenleser zuordnen.
Requests mit Kartenleserzugriff bieten des Weiteren die Möglichkeit einen Kartenleser ohne vorherigen Aufruf der Funktion setCardReader() zuzuordnen, indem bei dem Request die Kartenleser-ID (CardReaderId) mitübergeben wird. Der übergebene Kartenleser ist dabei nicht nur für den aktuellen Request gültig, sondern solange dem Dialog zugeordnet bis ein anderer Kartenleser zugeordnet wird.
Die Nutzung dieser Funktion ist nur noch zeitlich begrenzt möglich. Da an der SS12 die Karteninformationen nur noch mittels CardToken angegeben werden, ist ein explizites Setzen des Kartenlesers nicht mehr notwendig.

### Kartenleser freigeben für Multihost-System

Multihostfähige LAN-CCR können maximal vier Hosts (z.B. GINAs) zugeordnet werden, wodurch jeder dieser Hosts in der Lage ist mit dem LAN-CCR zu kommunizieren.
Durch den Aufruf einer Funktion mit Kartenzugriff, wird der Kartenleser dem aufrufenden Host zur Benutzung zugewiesen. Andere Hosts können während dieser Zeit den Kartenleser (und die darin gesteckte Karte) nicht nutzen und erhalten eine Fehlermeldung, dass der Kartenleser gerade in Verwendung ist.
Erst wenn der, den Kartenleser gerade nutzende Host den Kartenleser freigibt oder die Karte gezogen wird, kann ein anderer Host den Kartenleser für sich beanspruchen.

##### Bsp.: Zugriff von zwei Hosts

Soll von verschiedenen Hosts auf denselben Kartenleser (und somit dieselbe gesteckte Karte) zugegriffen werden, empfiehlt es sich am Ende einer Transaktion mit Kartenzugriff und vor der nächsten Transaktion mit Kartenzugriff die Karte freizugeben. Auch im Fehlerfall sollte die Karte freigegeben werden um eine eventuelle Sperre für einen anderen Host zu vermeiden.

##### Szenario 4 - Kartenleser freigeben:

### Zugriff auf den Kartenleser

Die direkte Kommunikation mit dem LANCCR ist nur mittels REST-Schnittstelle möglich.
Die Kommunikation per REST erfolgt aktuell über die GINA. Mit einer späteren Release wird dies umgestellt, sodass die Kommunikation direkt mit dem Kartenleser erfolgt (neue Kartenlesergeneration - GINO).
Hinweis: Durch die spätere Umstellung der Kommuniktation direkt mit dem Kartenleser ändert sich nur die Aufruf-URL (Host).
Die Dokumentation des REST-Services zur Kommunikation mit dem Kartenleser ist zu finden unter: Swagger Doku LANCCR

## Informationen des Ordinationsclient abfragen

Mittels der Funktion getGinsSoftwareVersion() können die Software-Version der GINA sowie der GINA-Typ abgefragt werden. Der GINA-Typ gibt die zulässige Benutzergruppe der abgefragten GINA vor. Man unterscheidet hierbei zwischen Vertragspartner-GINAs (WIRK-GINAs) und Vertragspartnersoftware-Hersteller-GINAs (VPSWH-GINAs).
Siehe hierzu auch die Package-Beschreibung des TSV-Service.

## Ordinationsclient testen (Funktionstest)

Um zu testen, ob der Ordinationsclient ordnungsgemäß läuft, gibt es folgende Funktionstests:

- die Abfragemöglichkeit von GINA- und Service-Verfügbarkeitsinformationen und
- einen Test von Chipkarten durch das Lesen der Karten mittels Chipkartenleser