Funktionen in einer HIDL-Schnittstelle werden Methoden in der automatisch generierten IFoo
C++-Klassendeklaration zugeordnet. Der Name jeder Funktion bleibt in C++ gleich; In den folgenden Abschnitten wird beschrieben, wie HIDL-Argumente und Rückgabewerte in C++ übersetzt werden.
Funktionsparameter
Die in der .hal
Datei aufgeführten Argumente sind C++-Datentypen zugeordnet. Argumente, die keinem primitiven C++-Typ zugeordnet werden können, werden per Konstantenverweis übergeben.
Für jede HIDL-Funktion, die einen Rückgabewert hat (eine generates
Anweisung hat), verfügt die C++-Parameterliste für diese Funktion über ein zusätzliches Argument: eine Rückruffunktion, die mit den Rückgabewerten der HIDL-Funktion aufgerufen wird. Es gibt eine Ausnahme : Wenn die generates
Klausel einen einzelnen Parameter enthält, der direkt einem C++-Grundelement zugeordnet ist, wird die Callback- Elision verwendet (der Callback wird entfernt und der Rückgabewert wird von der Funktion über eine normale return
Anweisung zurückgegeben).
Funktionsrückgabewerte
Die folgenden Funktionen haben Rückgabewerte.
Transportfehler und Rückgabetyp
Die generates
Anweisung kann zu drei Arten von Funktionssignaturen führen:
- Für nur einen Rückgabewert, der ein C++-Grundelement ist, wird der
generates
Rückgabewert als Wert von der Funktion in einemReturn<T>
-Objekt zurückgegeben. - In komplizierteren Fällen werden die
generates
Rückgabewerte über den Rückrufparameter zurückgegeben, der mit dem Funktionsaufruf selbst bereitgestellt wird, und die Funktion gibtReturn<void>
zurück. - Wenn keine
generates
Anweisung vorhanden ist, gibt die FunktionReturn<void>
zurück.
Bei RPC-Aufrufen können gelegentlich Transportfehler auftreten, z. B. wenn der Server ausfällt, wenn die Transportressourcen nicht ausreichen, um den Aufruf abzuschließen, oder wenn die übergebenen Parameter den Abschluss des Aufrufs nicht zulassen (z. B. wenn eine erforderliche Rückruffunktion fehlt). Return
speichern Transportfehleranzeigen sowie einen T
Wert (außer Return<void>
).
Da die clientseitigen und serverseitigen Funktionen dieselbe Signatur haben, muss die serverseitige Funktion einen Return
zurückgeben, auch wenn ihre Implementierung keine Transportfehler signalisiert. Return<T>
-Objekte werden mit Return(myTValue)
erstellt (oder können implizit aus mTValue
erstellt werden, z. B. in return
Anweisungen) und Return<void>
-Objekte werden mit Void()
erstellt.
Return<T>
-Objekte verfügen über eine implizite Konvertierung in und von ihrem T
Wert. Das Return
Objekt kann durch Aufruf seiner isOk()
Methode auf Transportfehler überprüft werden. Diese Prüfung ist nicht erforderlich; Wenn jedoch ein Fehler auftritt und nicht überprüft wird, bis das Return
Objekt zerstört wird oder eine T
Wert-Konvertierung versucht wird, wird der Clientprozess abgebrochen und ein Fehler protokolliert. Wenn isOk()
einen Transportfehler oder einen Aufruffehler aufgrund eines Logikfehlers im Entwicklercode anzeigt (z. B. die Übergabe von nullptr
als synchroner Rückruf), kann description()
für das Return-Objekt aufgerufen werden, um eine für die Protokollierung geeignete Zeichenfolge zurückzugeben. In solchen Fällen gibt es keine Möglichkeit festzustellen, wie viel Code aufgrund des fehlgeschlagenen Aufrufs möglicherweise auf dem Server ausgeführt wurde. Die Methode isDeadObject()
wird ebenfalls bereitgestellt. Diese Methode gibt an, dass !isOk()
darauf zurückzuführen ist, dass das Remote-Objekt abgestürzt ist oder nicht mehr existiert. isDeadObject()
impliziert immer !isOk()
.
Rückgabe nach Wert
Wenn die generates
Anweisung einem einzelnen C++-Grundelement zugeordnet ist, befindet sich kein Rückrufparameter in der Parameterliste. Stattdessen stellt eine Implementierung den Rückgabewert T
in einem Return<T>
-Objekt bereit, das implizit aus dem primitiven Typ T
generiert werden kann. Zum Beispiel:
Return<uint32_t> someMethod() { uint32_t return_data = ...; // Compute return_data return return_data; };
Die Methode Return<*>::withDefault
wird ebenfalls bereitgestellt. Diese Methode stellt einen Wert bereit, wenn der Rückgabewert !isOk()
ist. Diese Methode markiert auch automatisch das Rückgabeobjekt als in Ordnung, sodass der Clientprozess nicht beendet wird.
Rückkehr mit Callback-Parameter
Ein Rückruf kann den Rückgabewert der HIDL-Funktion an den Aufrufer zurückgeben. Der Prototyp des Rückrufs ist ein std::function
Objekt mit Parametern (aus der generates
Anweisung übernommen), die C++-Typen zugeordnet sind. Sein Rückgabewert ist void – der Rückruf selbst gibt keinen Wert zurück.
Der Rückgabewert einer C++-Funktion mit einem Rückrufparameter hat den Typ Return<void>
. Die Serverimplementierung ist nur für die Bereitstellung des Rückgabewerts verantwortlich. Da die Rückgabewerte bereits über den Callback übergeben werden, ist der T
Template-Parameter void
:
Return<void> someMethod(someMethod_cb _cb);
Von ihrer C++-Implementierung aus sollten Serverimplementierungen Void()
zurückgeben, eine statische Inline-Funktion, die ein Return<void>
-Objekt zurückgibt. Beispiel einer typischen Servermethodenimplementierung mit einem Callback-Parameter:
Return<void> someMethod(someMethod_cb _cb) { // Do some processing, then call callback with return data hidl_vec<uint32_t> vec = ... _cb(vec); return Void(); };
Funktionen ohne Rückgabewerte
Die C++-Signatur einer Funktion ohne generates
Anweisung weist keinen Callback-Parameter in der Parameterliste auf. Der Rückgabetyp ist Return<void>.
Oneway-Funktionen
Mit dem Schlüsselwort oneway
gekennzeichnete Funktionen sind asynchrone Funktionen (Clients blockieren ihre Ausführung nicht) und haben keine Rückgabewerte. Die C++-Signatur einer oneway
Funktion verfügt über keinen Callback-Parameter in der Parameterliste und ihr C++-Rückgabewert ist Return<void>
.