Funktionen

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 einem Return<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 gibt Return<void> zurück.
  • Wenn keine generates Anweisung vorhanden ist, gibt die Funktion Return<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> .