2.1. Serververbindung

Um auf die RPC-Schnittstelle des GREYHOUND Servers zugreifen zu können, wird die Basisklasse GhRpcClient verwendet. Diese stellt das zentrale Verbindungsobjekt zum Server dar und wird von den einzelnen Diensten der RPC-Schnittstelle verwendet. Es enthält die Zugangsdaten zum GREYHOUND Server und regelt die technischen Aspekte der Kommunikation mit dem Server.

Das folgende Beispiel zeigt, wie ein Client-Objekt erzeugt wird, welches den GREYHOUND Server mit dem Hostnamen "localhost" auf dem Port 80 anspricht. Die Verbindung wird im Beispiel nicht verschlüsselt (kein SSL) und die Verbindung wird über den Benutzernamen "tester" mit dem Kennwort "test123" authentifiziert:

Erstellen des Client-Objekts mit Zugangsdaten:

1
2
3
4


<?php
require_once 'ghrpc/ghrpc.php';

$client = new GhRpcClient('localhost', 80, false, 'tester', 'test123');

Alle Funktionen, die über dieses Client-Objekt aufgerufen werden, verwenden diese Zugangsdaten. Das bedeutet insbesondere, dass über die RPC Schnittstelle mit den Berechtigungen des im Client-Objekt angegebenen Benutzers gearbeitet wird. Hat dieser Benutzer beispielsweise nicht die Berechtigung, eine bestimmte Gruppe einzusehen, so wird der Versuch, über die RPC Schnittstelle E-Mails aus dieser Gruppe abzurufen, mit einer entsprechenden Fehlermeldung fehlschlagen (mehr dazu im Abschnitt Fehlerbehandlung). Dies bedeutet letztlich auch, dass sich die Web-Anwendung nicht um das Einhalten der Berechtigungen kümmern muss, da dies auf Serverseite bereits garantiert wird.

Jede Verbindung zum GREYHOUND Server wird anhand einer eindeutigen Client ID identifiziert. Zur gleichen Zeit kann unter derselben eindeutigen ID nur ein Benutzer angemeldet sein, so wie auch in einer GREYHOUND Client Instanz immer nur ein Benutzer angemeldet ist. Diese eindeutige ID sollte auch solange erhalten bleiben, wie die Anwendung aktiv ist, d. h. bei Web-Anwendungen sollte diese eindeutige ID vom ersten Zugriff auf den GREYHOUND Server an bis zum Schließen des Browsers erhalten bleiben. Dies lässt sich beispielsweise über Cookies oder Sessions realisieren. Um dies zu vereinfachen, bietet die Klasse GhRpcClient eine Methode setUniqueClientIdCookieName() an, mit der der Name eines Cookies festgelegt werden kann, in dem diese eindeutige ID für die Dauer der Browser-Session gespeichert wird. Jede Web-Anwendung, die diesen Mechanismus nutzt, sollte hier einen Cookie-Namen wählen, der nicht mit denen anderer Web-Anwendungen kollidiert. Im folgenden Beispiel wurde "ghrpcexample1" als Name für den Cookie gewählt.

Erstellen des Client-Objekts mit Speichern der eindeutigen Client ID im Cookie:

1
2
3
4
5


<?php
require_once 'ghrpc/ghrpc.php';

$client = new GhRpcClient('localhost', 80, false, 'tester', 'test123');
$client->setUniqueClientIdCookieName('ghrpcexample1');

Kümmert sich die Web-Anwendung selbst um das Speichern der eindeutigen Client ID (über die Methode setUniqueClientId() in der Klasse GhRpcClient, beispielsweise, indem die eindeutige ID in der PHP Session gespeichert wird, so braucht der Name für den Cookie nicht festgelegt werden, da die ID dann nicht im Cookie gespeichert werden muss.

Wenn Inhalte des GREYHOUND Servers auf einer Webseite dargestellt werden, so ist darauf zu achten, dass die richtige Zeichencodierung verwendet wird, da sonst Sonderzeichen wie Umlaute oder das Euro-Währungssymbol nicht korrekt angezeigt werden. Die RPC Schnittstelle verwendet als Vorgabe die UTF-8 Zeichencodierung. Verwendet die Webseite nicht UTF-8 als Zeichencodierung, so kann im Client-Objekt die Zeichencodierung der Webseite angegeben werden. Alle Textdaten, die über die RPC Schnittstelle ausgeliefert werden, werden dann in diese Zeichencodierung umgewandelt bzw. beim Senden an den Server aus dieser Zeichencodierung in UTF-8 umgewandelt.

Eine Besonderheit sind Serverinhalte, die vollständige HTML-Seiten beinhalten können, beispielsweise die Inhalte von E-Mails, Notizen, Telefonnotizen, Aufgaben, Briefen, Textblöcken, Vorlagen oder Signaturen. Aus Gründen der Abwärtskompatibilität werden diese Inhalte im GREYHOUND Server mit der ANSI-Zeichencodierung windows-1252 gespeichert. Eingehende Nachrichten, die in einer anderen Zeichencodierung vorliegen, wandelt der GREYHOUND Server beim Empfang in windows-1252 um (und ändert ggf. die Angabe der Zeichencodierung im Meta-Tag Content-Type). Diese Inhalte werden vom Server über die RPC Schnittstelle immer in der windows-1252 Zeichencodierung ausgeliefert, unabhängig von der Zeichencodierung, die im Client-Objekt eingestellt ist (die Daten werden nicht als Textdaten übertragen, sondern binär).

In der praktischen Nutzung ist dies für die meisten Web-Anwendungen nicht relevant, da solche Inhalte vollständige Webseiten darstellen und diese vom Browser auch korrekt angezeigt werden (beispielsweise, wenn sie in einem eigenen Fenster oder einem IFrame angezeigt werden). Werden jedoch Teile dieser Inhalte oder reine Textinhalte innerhalb einer Webseite ausgegeben, die eine andere Zeichencodierung (beispielsweise UTF-8 verwendet), so müssen die Inhalte zuvor von windows-1252 in die betreffende Codierung umgewandelt werden (beispielsweise mit Hilfe der PHP Funktion iconv). Ebenso gilt dies, wenn solche Inhalte auf dem Server gespeichert werden sollen, beispielsweise beim Ändern des Inhalts eines Objekts oder beim Erzeugen eines neuen Objekts. Hier muss sichergestellt sein, dass der Inhalt in der Zeichencodierung windows-1252 vorliegt.

Das folgende Beispiel demonstriert, wie eine UTF-8-codierte Webseite den Betreff und den Inhalt einer Notiz mit einer Eingabe aus einem Formular überschreibt (die Datenobjekte und Funktionen für RPC Aufrufe werden im Abschnitt RPC Aufrufe beschrieben):

Zeichencodierung von Inhalten:

1
2
3
4
5
6
7
8
9
10
11
12
13
14


<?php
require_once 'ghrpc/ghrpc.php';

$client = new GhRpcClient('localhost', 80, false, 'tester', 'test123');
$client->setCharset('UTF-8'); // Zeichencodierung setzen

$noteId = 23;  // Die Notiz soll im Beispiel die ID 23 auf dem Server besitzen
$note = rpc_itemslib::newRpcItems($client)->Get($noteId, false);

$subject = $_POST['note_subject'];
$content = $_POST['note_content'];

$note->Subject = $subject; // Zeichencodierung wird von der Schnittstelle erledigt
$note->Properties->Note->EditorData = iconv('UTF-8', 'windows-1252//IGNORE//TRANSLIT'); // Inhalt muss in windows-1252 umgewandelt werden

Im Beispiel wird davon ausgegangen, dass der Betreff und der Inhalt für die E-Mail über ein HTML Formular abgeschickt wurden und in den POST-Variablen "note_subject" bzw. "note_content" enthalten sind. Das Setzen der von der Webseite verwendeten Zeichencodierung auf UTF-8 ist streng genommen nicht notwendig, da UTF-8 ohnehin die Vorgabe für die RPC Schnittstelle ist (die Angabe schadet aber selbstverständlich nicht). Der Betreff (die Eigenschaft "Subject") wird direkt gesetzt. Hier würde die PHP RPC Bibliothek selbstständig die Umwandlung der Zeichencodierung vornehmen, da der Betreff als normaler String übermittelt wird. In diesem Beispiel wird nicht umgewandelt, da die Zeichencodierung mit der der RPC Schnittstelle übereinstimmen. Der Inhalt (die Eigenschaft "Properties->Note->EditorData") hingegen muss explizit in die windows-1252 Zeichencodierung gebracht werden, da der Inhalt der Notiz (die Eigenschaft "EditorData") binär übertragen wird und keine automatische Zeichencodierung erhält. Werden hier HTML Inhalte gesetzt, so sollte dort auch das Meta-Tag "Content-Type" mit Angabe der Zeichencodierung "windows-1252" eingefügt werden.