API-Dokumentation
der XML-RPC - Schnittstelle
XML-RPC (Extensible Markup Language Remote Procedure Call) ist ein Protokoll, mit dem Methoden auf entfernten Servern ausgeführt werden können. Damit der Omnichat an nahezu jede Software angebunden werden kann, haben wir uns als Schnittstelle für XML-RPC entschieden. Für ausgewählte Software stellen wir bereits fertige XML-RPC-Server - die sogenannten Konnektoren bereit.
Damit eine Software den Omnichat nutzen kann, muss sie folgende Methoden bereitstellen:
- status.get
- user.login
- user.info
- user.invite (optional)
- buddies.list (optional)
Exceptions
Tritt ein Fehler bei der Ausführung einer Methode auf, muss eine XLM/RPC-Exception zurückgegeben werden. Jede XML/RPC-Exception enthält eine Fehlernummer, sowie eine Fehlerbeschreibung. Die Fehlernummern sind für den Omnichat wie folgt festgelegt:
| Fehlernummer | Beschreibung |
|---|---|
| 200 | Benutzer nicht gefunden |
| 210 | Login aufgrund ungültiger Session-ID fehlgeschlagen |
status.get
Diese Methode wird bei der Initialisierung des Chats aufgerufen, um die Erreichbarkeit des Connectors sicherzustellen.
Argumente
keine
Rückgabe
[struct] mit folgenden Elementen:
- [string] apiVersion
- Version der Omnichat-API (1.0)
- [string] softwareName
- Name der Software (z.b. phpBB)
- [string] softwareVersion
- Version der Software (z.b. 2.1.18)
user.login
Möchte ein User den Chat betreten, übermittel der Omnichat-Server seinen Benutzernamen sowie seine Session-ID an den Connector.
Argumente
- [string] Benutzername
- [string] Session-ID
Rückgabe
Bei Erfolg wird der Benutzernamen des Benutzers zurückgeliefert.
[string] Benutzername
user.info
Fragt Informationen über einen Benutzer ab.
Argumente
- [string] Benutzername
Rückgabe
[struct] mit folgenden Elementen:
- [string] username
- Benutzername
- [boolean] vip (optional)
- Gibt an, ob der Benutzer VIP-Rechte im Chat haben soll
- [string] id (optional)
- Datenbank-Interne ID des Benutzers
user.invite
Ein User (im Chat) lädt einen anderen User (der sich nicht im Chat befindet) in seinen Raum ein. Für die Benachrichtigung des einzuladenden Users ist die Software der Community verantwortlich.
Argumente
- [string] einladender Benutzer
- [string] einzuladender Benutzer
- [string] Raumname
Rückgabe
[boolean] true, wenn dem User die Einladung zugestellt werden konnte, ansonsten false.
buddies.list
Gibt eine Liste mit den Freunden des übergebenen Users zurück. Aus dieser Liste werden vom Omnichat alle User angezeit, die gerade im Chat sind.
Argumente
- [string] Benutzername
Rückgabe
[array] mit den 0, 1 oder mehreren Elementen:
- [string] username
- Name eines Freundes