2.2. RPC Aufrufe
Die Abbildung der RPC Funktionen und Daten des GREYHOUND Servers auf Klassen und Methoden der PHP RPC Bibliothek unterteilt sich in Unit-Klassen, Datenklassen und Diensteklassen. Die einzelnen Klassen-Typen und ihr Zusammenspiel werden im Folgenden beschrieben.
Die einzelnen Funktionsbereiche des Servers sind in sogenannte Units unterteilt, die jeweils Datenobjekte, Konstanten und Funktionen eines zusammenhängenden Bereichs umfassen. So sind beispielsweise alle Klassen und Funktionen, die Benutzer betreffen, in der Unit rpc_userslib enthalten.
Das Konzept der Units gibt es in dieser Form nicht in der Programmiersprache PHP, die naheliegendste Entsprechung wären die mit PHP 5.3 eingeführten Namespaces, auf die jedoch in der PHP API aus Gründen der Abwärtskompatibilität verzichtet wurde, damit die PHP API auch auf Systemen verwendet werden kann, die nur PHP 5.2 bereitstellen.
Die PHP API stellt jede Unit durch eine PHP Klasse dar, welche die Konstanten der jeweiligen Unit als statische Klassenkonstanten enthält. Diese Unit-Klassen sind genauso benannt wie die jeweilige Unit in der originalen RPC Schnittstelle, beispielsweise "rpc_userslib" für die Unit, die die Klassen und Funktionen der Benutzerverwaltung im Server enthält. Eine Übersicht der verfügbaren Units befindet sich im Abschnitt PHP-RPC-Units.
Da in der originalen RPC Schnittstelle des Servers einige gleichnamige Klassen in unterschiedlichen Units enthalten sind, in PHP jedoch Klassennamen eindeutig sein müssen, wurden die Namen der Daten- und Diensteklassen der RPC Schnittstelle in der PHP API durch Voranstellung eines Prefixes eindeutig gemacht. Dieser Prefix beginnt mit "GhRpc" für alle Klassen der PHP RPC Bibliothek, gefolgt vom Namen der Unit (ohne das vorangehende "rpc_" und beginnend mit einem Großbuchstaben).
Zusammengesetzt ergibt dies z.B. für die Klasse "RpcDetailedItem der originalen RPC Schnittstelle aus der Unit "rpc_itemslib" den PHP Klassennamen "GhRpcItemslibRpcDetailedItem".
Um diese umständliche Schreibweise der Klassennamen zu vereinfachen, enthält jede Unit-Klasse statische Methoden, mit denen die in der Unit enthaltenen Daten- und Diensteklassen erzeugt werden können. Die Namen dieser Methoden beginnen jeweils mit "new", gefolgt vom Klassennamen aus der originalen RPC Schnittstelle. Die folgenden beiden Schreibweisen sind daher gleichwertig:
Vereinfachende Objekterzeugung über statische Unit-Methoden:
1
2
3
2
3
<?php
$item = new GhRpcItemslibRpcDetailedItem();
$item = rpc_itemslib::newRpcDetailedItem();
Die zweite Schreibweise bietet für Datenobjekte zusätzlich einen optionalen Parameter (für Diensteobjekte hat diese Methode einen Pflichtparameter mit anderer Bedeutung, s.u.). Wird die statische Methode mit dem Parameter "true" aufgerufen, so werden alle Objekteigenschaften des zurück gelieferten Objekts, die Arrays darstellen, mit einem leeren Array, und alle Objekteigenschaften, die Datenobjekte (s.u.) darstellen, mit einem "leeren" Datenobjekt initialisiert (in diesen Datenobjekten sind ebenfalls alle Arrays und Datenobjekte entsprechend vorinitialisiert).
Dies nimmt dem Entwickler die Arbeit ab, alle untergeordneten Datenobjekte zu initialisieren, wie das folgende Beispiel zeigt (hier wird der Inhalt einer neuen E-Mail gesetzt):
Erzeugung von vorinitialisierten Datenobjekten:
1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
<?php
// Explizite Objekterzeugung:
$item = new GhRpcItemslibRpcDetailedItem();
$item->Properties = new GhRpcItemslibRpcItemProperties();
$item->Properties->Email = new GhRpcItemslibRpcEmailProperties();
$item->Properties->Email->EditorData = 'Hallo Welt!';
// Vereinfachte, vorinitialisierte Objekterzeugung:
$item = rpc_itemslib::newRpcDetailedItem(true);
$item->Properties->Email->EditorData = 'Hallo Welt!';
Der Großteil der Klassen der PHP RPC Bibliothek sind Datenklassen, die die Eigenschaften von Datenobjekten im GREYHOUND Server abbilden. Die eigentlichen Daten liegen in Objekteigenschaften vor. Die Namensgebung dieser Eigenschaften ist identisch zu denen im Server, was insbesondere bedeutet, dass sie entgegen der für PHP üblichen Konvention mit Großbuchstaben beginnen. Enthält eine Objekteigenschaft wiederum komplexe Daten, so werden diese ebenfalls als Datenobjekt in der Objekteigenschaft vorgehalten.
Das Objekt, dass beispielsweise E-Mails, Notizen, Briefe usw. im Server repräsentiert (GhRpcItemslibRpcDetailedItem) enthält beispielsweise eine Objekteigenschaft "Subject", in der der Betreff des Objekts als String steht, eine Objekteigenschaft "From", in der die Absenderadressdaten in Form eines Objekts (GhRpcItemslibRpcAddressItem) enthalten sind und eine Objekteigenschaft "Recipients", in der ein Array mehrere solcher Adressdaten-Objekte (ebenfalls GhRpcItemslibRpcAddressItem) für die Adressaten des Objekts vorhält.
Eigenständige Objekte im Server verfügen jeweils über eine eindeutige Kennzahl, über die sie identifizierbar sind. Diese ID wird verwendet, um einzelne Objekte als Datenobjekt vom Server abzurufen, sie findet aber auch innerhalb der Datenobjekte Verwendung, wenn Bezug auf andere Objekte genommen wird. So wird beispielsweise das Thema, dem ein Objekt angehört, über die Themen-ID verknüpft. Objekteigenschaften, in denen IDs anderer Objekte gespeichert werden, enden in der Regel auf die Endung "Ref" (für "Referenz"). So enthält beispielsweise die Objekteigenschaft "TopicRef" der Klasse GhRpcItemslibRpcDetailedItem das Thema, dem das Objekt angehört und die Objekteigenschaft "GroupRef" die Gruppe, in der das Objekt eingeordnet ist.
Werden mehrere IDs in einer Objekteigenschaft gespeichert, so endet die Objekteigenschaft in der Regel auf den Plural "Refs", z.B. die Objekteigenschaft "CategoryRefs" in der Klasse GhRpcTopicslibRpcTopic, die die IDs der Benutzergruppen, die das Thema verwenden können, als Array enthält.
Einige Objekteigenschaften der Datenobjekte enthalten Werte, die von der PHP RPC Bibliothek als Konstanten bereitgestellt werden, damit nicht ständig die Zahlenwerte nachgeschlagen werden müssen. Diese Konstanten befinden sich (als statische Klassenkonstanten) in der jeweiligen Unit-Klasse. Die Namen der Konstanten entsprechen denen der "Enum"-Werte der originalen RPC Schnittstelle, die folgende Konvention vorgibt: die Konstante beginnt mit einigen Kleinbuchstaben, die eine Abkürzung ihres Verwendungszwecks darstellen, gefolgt von der Bedeutung der Konstante, bei der jedes Wort mit einem Großbuchstaben beginnt ("upper camel-case"). Die Konstanten, die den Typ von Objekten ("item type") angeben, heißen beispielsweise "ikEmail", "ikNote", "ikLetter" und befinden sich in der Unit-Klasse "rpc_itemslib", wie das folgende Beispiel zeigt:
Konstanten als Werte in Datenobjekten:
1
2
3
2
3
<?php
$email = new GhRpcItemslibRpcDetailedItem();
$email->Kind = rpc_itemslib::ikEmail; // Objekt vom Typ "E-Mail"
Manche Objekteigenschaften stellen eine Kombination aus einer oder mehrerer Optionen dar. In der originalen RPC Schnittstelle wird dies als "Set" bezeichnet, die einzelnen Optionen als "Enums". Technisch wird dies durch einen Integer-Wert repräsentiert, bei dem die einzelnen Optionen jeweils ein Bit darstellen. Um diese Bitoperationen zu vereinfachen, stellt die PHP RPC Klasse GhRpcUtils einige statische Methoden bereit:
Sets als Werte in Datenobjekten:
1
2
3
4
5
2
3
4
5
<?php
$email = new GhRpcItemslibRpcDetailedItem();
$email->Flags = GhRpcUtils::newSet(rpc_itemslib::ifUnsent, rpc_itemslib::ifRead); // Ungesendet und gelesen
$email->Flags = GhRpcUtils::addToSet($email->Flags, rpc_itemslib::ifUseHtml); // zusätzlich HTML-Format verwenden
$email->Flags = GhRpcUtils::removeFromSet($email->Flags, rpc_itemslib::ifRead); // doch nicht als gelesen markieren
Die Methode GhRpcUtils::newSet() kombiniert eine oder mehrere Optionen (in der Regel Konstanten aus der entsprechenden Unit) zu einem Set. Die Methode GhRpcUtils::addToSet()
fügt zu einem bestehenden Set Optionen hinzu, und die Methode GhRpcUtils::removeFromSet() entfernt Optionen aus einem Set.
Die Klasse GhRpcUtils stellt zudem eine Konstante "GhRpcUtils::SET_ALL" zur Verfügung, die ein Set darstellt, bei dem alle Optionen gesetzt sind. Die Unit-Klassen enhalten ebenfalls eine solche Konstante (z.B. "rpc_itemslib::SET_ALL"), die identisch sind. Diese Konstante kann der Einfachheit halber verwendet werden, wenn in einem Set alle Optionen gesetzt werden sollen, ohne sämtliche Optionen einzeln angeben zu müssen.
Die RPC Schnittstelle des GREYHOUND Servers bündelt alle ihre Funktionen in Diensten, die in der PHP RPC Bibliothek als Diensteklassen dargestellt werden. Da Diensteobjekte bei RPC Funktionsaufrufen Daten an den Server senden, benötigen sie Zugriff auf das Client-Objekt, das die Verbindung zum Server repräsentiert (siehe Abschnitt Serververbindung). Das Client-Objekt muss dem Diensteobjekt daher im Konstruktor übergeben werden, oder in der oben beschriebenen vereinfachten Schreibweise als Parameter an die statische Unit-Methode:
Erzeugung eines Dienstes:
1
2
3
4
5
2
3
4
5
<?php
$client = new GhRpcClient('localhost', 80, false, 'tester', 'test123');
$itemService = new GhRpcItemslibRpcItems($client);
$itemService = rpc_itemslib::newRpcItems($client);
Das Diensteobjekt bietet dann Funktionen zum Abrufen und Senden von Datenobjekten vom bzw. an den Server. Das folgende Beispiel zeigt, wie der Dienst für Themen verwendet wird, um eine Liste der Themen vom Server abzurufen und anzuzeigen:
Abruf der Themenliste vom Server:
1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
<?php
require_once 'ghrpc/ghrpc.php';
$client = new GhRpcClient('localhost', 80, false, 'tester', 'test123'); // Client erzeugen
$client->setUniqueClientIdCookieName('ghrpcexample1'); // Cookie-Namen setzen
$topicService = rpc_topicslib::newRpcTopics($client); // Dienst für Themen erzeugen
$topicsList = $topicService->GetList(false); // Themen-Liste vom Server abrufen
// Themen-Liste ausgeben:
foreach($topicsList as $topic)
echo 'Thema "' . htmlspecialchars($topic->Name) . '" (ID: ' . $topic->ID . ', Pfad: ' . htmlspecialchars($topic->Path) . ')<br>';