XR_ANDROID_google_cloud_auth

Name String

XR_ANDROID_google_cloud_auth

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahl

788

Revision

1

Ratification Status

Nicht ratifiziert

Erweiterungs- und Versionsabhängigkeiten

XR_EXT_future

Datum der letzten Änderung

2025-12-18

IP-Status

Keine bekannten Ansprüche auf geistiges Eigentum.

Mitwirkende

John Ullman, Google
Ben King, Google
Nihav Jain, Google
Jared Finder, Google

Übersicht

Diese Erweiterung ermöglicht die Verwendung von Google Cloud-basierten Erweiterungen, indem die Anwendung Authentifizierungsdaten für Google Cloud APIs bereitstellen kann. Der Entwickler muss die Google Cloud Console ( https://console.cloud.google.com/) verwenden, um ein Google Cloud-Projekt für die Anwendung zu erstellen. Für diese Erweiterung ist die Erweiterung XR_EXT_future erforderlich.

Während der Entwicklung kann die Anwendung Probleme mit der Google Cloud-Einrichtung mithilfe der Erweiterung XR_EXT_debug_utils beheben. Wenn die Anwendung einen Debug Messenger hat und in der Laufzeit ein potenziell behebbarer Fehler auftritt, während im Namen der Anwendung eine Anfrage an Google Cloud gesendet wird, ruft die Laufzeit den Callback des Messengers mit einer Fehlermeldung auf. In diesem Fall sollte der Entwickler die Fehlermeldung und alle verfügbaren Dokumentationen lesen und dann dafür sorgen, dass die Anwendung und das Google Cloud-Projekt ordnungsgemäß für die Verwendung von Google Cloud APIs eingerichtet sind. Die Laufzeit muss den Nachrichtentyp XR_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT, den Schweregrad XR_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT und die messageId „GoogleCloudError“ verwenden.

Authentifizierung

Die Struktur XrGoogleCloudAuthInfoBaseHeaderANDROID ist so definiert:

typedef struct XrGoogleCloudAuthInfoBaseHeaderANDROID {
    XrStructureType    type;
    const void*        next;
} XrGoogleCloudAuthInfoBaseHeaderANDROID;

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.

Diese Struktur wird nicht direkt in der API verwendet, sondern von anderen Strukturen erweitert, die mit xrSetGoogleCloudAuthAsyncANDROID verwendet werden können, um Authentifizierungsdaten bereitzustellen.

Gültige Verwendung (implizit)

Die Struktur XrGoogleCloudAuthInfoApiKeyANDROID ist so definiert:

typedef struct XrGoogleCloudAuthInfoApiKeyANDROID {
    XrStructureType    type;
    const void*        next;
    const char*        apiKey;
} XrGoogleCloudAuthInfoApiKeyANDROID;

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • apiKey ist ein Verweis auf einen String, der den API-Schlüssel darstellt.

Wenn diese Struktur an xrSetGoogleCloudAuthAsyncANDROID übergeben wird, muss das apiKey-Mitglied ein nicht leerer ASCII-String ohne Leerzeichen oder Steuerzeichen sein. Andernfalls muss die Laufzeit XR_ERROR_VALIDATION_FAILURE zurückgeben.

apiKey muss außerdem die folgenden Bedingungen erfüllen:

  • Es muss ein gültiger API-Schlüssel sein, der für Ihr Google Cloud-Projekt generiert wurde.
  • In Ihrem Google Cloud-Projekt müssen die relevanten Google Cloud APIs aktiviert sein (wie von den abhängigen Erweiterungen angegeben).
  • Wenn der API-Schlüssel Einschränkungen hat, müssen die Einschränkungen die relevanten Google Cloud APIs und Ihre Anwendung zulassen.

Andernfalls ist der Aufruf von xrSetGoogleCloudAuthAsyncANDROID erfolgreich, aber alle Aufrufe von Funktionen, die von der Cloud-Autorisierung abhängen, verhalten sich wie in der Erweiterung, die diese Funktionen definiert, für Cloud-Fehler dokumentiert. Wenn eine Funktion einen Fehler melden kann und die Anwendung XrGoogleCloudAuthErrorResultANDROID mit dem Ausgabeparameter dieser Funktion verkettet, muss die Laufzeit XrGoogleCloudAuthErrorResultANDROID :: error auf XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID setzen, um diesen Fehler anzuzeigen.

Der asynchrone Vorgang wird mit XR_SUCCESS abgeschlossen, sobald der API-Schlüssel auf Formatierung geprüft und von der Laufzeit gespeichert wurde.

Gültige Verwendung (implizit)

Die Struktur XrGoogleCloudAuthInfoTokenANDROID ist so definiert:

typedef struct XrGoogleCloudAuthInfoTokenANDROID {
    XrStructureType    type;
    const void*        next;
    const char*        authToken;
} XrGoogleCloudAuthInfoTokenANDROID;

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • authToken ist ein Verweis auf einen String, der das Authentifizierungstoken darstellt.

Wenn diese Struktur an xrSetGoogleCloudAuthAsyncANDROID übergeben wird, muss das authToken-Mitglied ein nicht leerer ASCII-String ohne Leerzeichen oder Steuerzeichen sein. Andernfalls muss die Laufzeit XR_ERROR_VALIDATION_FAILURE zurückgeben. authToken muss außerdem die folgenden Bedingungen erfüllen:

  • Es muss sich um gültige und nicht abgelaufene Anmeldedaten handeln, die für Ihr Google Cloud-Projekt generiert wurden.
  • In Ihrem Google Cloud-Projekt müssen die relevanten Google Cloud APIs aktiviert sein (wie von den abhängigen Erweiterungen angegeben).

  • Die Anmeldedaten müssen einer der folgenden Typen sein:

    • Ein OAuth2-Zugriffstoken mit den relevanten Bereichen, das durch die Anmeldung bei einem Google-Konto mit Ihrer Anwendung generiert wurde, ODER
    • Ein signiertes JWT-Token mit den relevanten Anforderungen, das von einem Dienstkonto aus Ihrem Google Cloud-Projekt generiert wurde.

Die Anforderungen werden jeweils durch die abhängigen Erweiterungen festgelegt. Andernfalls ist der Aufruf von xrSetGoogleCloudAuthAsyncANDROID erfolgreich, aber alle Aufrufe von Funktionen, die von der Cloud-Autorisierung abhängen, verhalten sich wie in der Erweiterung, die diese Funktionen definiert, für Cloud-Fehler dokumentiert. Wenn eine Funktion einen Fehler melden kann und die Anwendung XrGoogleCloudAuthErrorResultANDROID mit dem Ausgabeparameter dieser Funktion verkettet, muss die Laufzeit XrGoogleCloudAuthErrorResultANDROID :: error auf XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID setzen, um diesen Fehler anzuzeigen.

Die Anwendung muss proaktiv ein neues Token über xrSetGoogleCloudAuthAsyncANDROID übergeben, bevor das alte Token abläuft. Die Laufzeit muss das neueste Token verwenden, das von der Anwendung beim Starten einer neuen Netzwerkanfrage übergeben wurde.

Der asynchrone Vorgang wird mit XR_SUCCESS abgeschlossen, sobald das Token auf Formatierung geprüft und von der Laufzeit gespeichert wurde.

Gültige Verwendung (implizit)

Die Struktur XrGoogleCloudAuthInfoKeylessANDROID ist so definiert:

typedef struct XrGoogleCloudAuthInfoKeylessANDROID {
    XrStructureType    type;
    const void*        next;
} XrGoogleCloudAuthInfoKeylessANDROID;

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.

Wenn diese Struktur an xrSetGoogleCloudAuthAsyncANDROID übergeben wird, kann die Laufzeitumgebung Anmeldedaten dynamisch generieren. Unter Android kommuniziert die Laufzeitumgebung beispielsweise über den Anwendungsprozess mit den Google Play-Diensten. Wenn die schlüssellose Authentifizierung nicht richtig eingerichtet ist, kann die Laufzeit XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID synchron zurückgeben.

Der asynchrone Vorgang führt die erforderlichen Netzwerkanfragen aus, um Anmeldedaten abzurufen. Das Ergebnis dieses Vorgangs wird in XrFutureCompletionEXT :: futureResult von xrSetGoogleCloudAuthCompleteANDROID zurückgegeben. Wenn das zukünftige Ergebnis XR_SUCCESS ist, wurden die Anmeldedaten für die schlüssellose Authentifizierung erfolgreich angewendet. Wenn das zukünftige Ergebnis XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID ist, kann die Anwendung es später noch einmal versuchen.

Gültige Verwendung (implizit)

Die Funktion xrSetGoogleCloudAuthAsyncANDROID ist so definiert:

XrResult xrSetGoogleCloudAuthAsyncANDROID(
    XrSession                                   session,
    const XrGoogleCloudAuthInfoBaseHeaderANDROID* authInfo,
    XrFutureEXT*                                future);

Parameterbeschreibungen

  • session ist die XrSession, die die Anmeldedaten verwendet.
  • authInfo ist ein Zeiger auf eine Struktur, die die Authentifizierungsmethode und die Parameter angibt. Das Feld XrGoogleCloudAuthInfoBaseHeaderANDROID :: type gibt die spezifische Struktur an.
  • future ist ein Zeiger auf ein XrFutureEXT-Handle, in dem das erstellte Future zurückgegeben wird, oder XR_NULL_HANDLE, wenn die Funktion nicht XR_SUCCESS zurückgegeben hat.

Legen Sie die Anmeldedaten fest, die für die Authentifizierung bei Google Cloud verwendet werden. Dieser Vorgang ist asynchron. Rufen Sie xrPollFutureEXT auf, um den Bereitschaftsstatus des Future zu prüfen. Sobald das Future den Status „Bereit“ hat, rufen Sie xrSetGoogleCloudAuthCompleteANDROID auf, um das Ergebnis abzurufen.

Der Parameter authInfo muss ein Zeiger auf eine Struktur sein, deren XrGoogleCloudAuthInfoBaseHeaderANDROID :: type-Mitglied die zu verwendende Authentifizierungsmethode identifiziert und die XrGoogleCloudAuthInfoBaseHeaderANDROID erweitert (z.B. XrGoogleCloudAuthInfoApiKeyANDROID).

Die spezifischen Anforderungen, Verhaltensweisen und Fehlerbedingungen (sowohl synchron als auch asynchron) für jede Authentifizierungsmethode werden in der Dokumentation für die jeweiligen Datenstrukturen beschrieben.

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Die Funktion xrSetGoogleCloudAuthCompleteANDROID ist so definiert:

XrResult xrSetGoogleCloudAuthCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrFutureCompletionEXT*                      completion);

Parameterbeschreibungen

  • session ist die XrSession, die zum Starten des Vorgangs verwendet wird.
  • future ist die XrFutureEXT, die abgeschlossen werden muss.
  • completion ist ein Zeiger auf ein XrFutureCompletionEXT, das von der Laufzeit ausgefüllt wird.

Zukünftige Rückgabecodes

XrFutureCompletionEXT :: futureResult-Werte:

Erfolg

  • XR_SUCCESS : Die Anmeldedaten wurden erfolgreich angewendet.

Fehler

  • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID : Die schlüssellose Authentifizierung ist fehlgeschlagen. Die Anwendung kann es später noch einmal versuchen. Die Anwendung oder der Entwickler kann auch bestimmte Voraussetzungen für den Erfolg prüfen (z.B. muss auf dem Android-Gerät eine aktuelle Installation der Google Play-Dienste vorhanden sein und diese Dienste müssen ordnungsgemäß funktionieren).

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Google Cloud-Authentifizierungsfehler

Die Aufzählung XrGoogleCloudAuthErrorANDROID ist so definiert:

typedef enum XrGoogleCloudAuthErrorANDROID {
    XR_GOOGLE_CLOUD_AUTH_ERROR_NONE_ANDROID = 0,
    XR_GOOGLE_CLOUD_AUTH_ERROR_QUOTA_EXCEEDED_ANDROID = -1,
    XR_GOOGLE_CLOUD_AUTH_ERROR_UNREACHABLE_ANDROID = -2,
    XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID = -3,
    XR_GOOGLE_CLOUD_AUTH_ERROR_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrGoogleCloudAuthErrorANDROID;

Die Enumeranten haben die folgenden Werte:

Enum-Beschreibung

XR_GOOGLE_CLOUD_AUTH_ERROR_NONE_ANDROID

Beim Aufrufen einer Google Cloud API ist kein Fehler aufgetreten.

XR_GOOGLE_CLOUD_AUTH_ERROR_QUOTA_EXCEEDED_ANDROID

Kontingent beim Aufrufen einer Google Cloud API überschritten.

XR_GOOGLE_CLOUD_AUTH_ERROR_UNREACHABLE_ANDROID

Eine Google Cloud API konnte nicht erreicht werden, möglicherweise aufgrund von Problemen mit der Netzwerkverbindung oder der Serververfügbarkeit.

XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID

Beim Aufrufen einer Google Cloud API ist ein Authentifizierungsfehler aufgetreten.

Die Struktur XrGoogleCloudAuthErrorResultANDROID ist so definiert:

typedef struct XrGoogleCloudAuthErrorResultANDROID {
    XrStructureType                  type;
    void*                            next;
    XrGoogleCloudAuthErrorANDROID    error;
} XrGoogleCloudAuthErrorResultANDROID;

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • error ist der XrGoogleCloudAuthErrorANDROID, der die Ursache des Fehlers eines Vorgangs beschreibt, der auf Google Cloud zugreift.

Wenn ein Vorgang aufgrund der Google Cloud-Authentifizierung fehlschlägt, kann diese Struktur mit der Struktur des Vorgangsergebnisses verkettet werden, um weitere Informationen zum Fehler bereitzustellen.

Gültige Verwendung (implizit)

Beispielcode

XrSession session; // previously initialized
XrInstance instance; // previously initialized
XrFutureEXT future = XR_NULL_HANDLE;

// The function pointers are previously initialized using
// xrGetInstanceProcAddr.
PFN_xrPollFutureEXT xrPollFutureEXT; // previously initialized
PFN_xrSetGoogleCloudAuthAsyncANDROID xrSetGoogleCloudAuthAsyncANDROID; // previously initialized
PFN_xrSetGoogleCloudAuthCompleteANDROID xrSetGoogleCloudAuthCompleteANDROID; // previously initialized

auto waitUntilReady = [&](XrFutureEXT future) {
  XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
  XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
  pollInfo.future = future;
  do {
    // sleep(1);
    xrPollFutureEXT(instance, &pollInfo, &pollResult);
  } while (pollResult.state != XR_FUTURE_STATE_READY_EXT);
};

// Set Google Cloud auth via API key.
XrGoogleCloudAuthInfoApiKeyANDROID authApiKey{XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_API_KEY_ANDROID};
authApiKey.apiKey = "MYAPIKEY";
XrResult result = xrSetGoogleCloudAuthAsyncANDROID(
    session, reinterpret_cast<XrGoogleCloudAuthInfoBaseHeaderANDROID*>(&authApiKey), &future);

// Or, set Google Cloud auth via auth token:
XrGoogleCloudAuthInfoTokenANDROID authToken{XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_TOKEN_ANDROID};
authToken.authToken = "MYAUTHTOKEN";
result = xrSetGoogleCloudAuthAsyncANDROID(
    session, reinterpret_cast<XrGoogleCloudAuthInfoBaseHeaderANDROID*>(&authToken), &future);

// Or, set Google Cloud auth via keyless auth:
XrGoogleCloudAuthInfoKeylessANDROID authKeyless{XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_KEYLESS_ANDROID};
result = xrSetGoogleCloudAuthAsyncANDROID(
    session, reinterpret_cast<XrGoogleCloudAuthInfoBaseHeaderANDROID*>(&authKeyless),
    &future);

// Check the result of the auth setup.
if (result == XR_ERROR_VALIDATION_FAILURE) {
  // The credentials were invalid.
} else if (result == XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID) {
  // Keyless auth was not properly setup.
} else if (result == XR_SUCCESS) {
  waitUntilReady(future);
  XrFutureCompletionEXT completion{XR_TYPE_FUTURE_COMPLETION_EXT};
  xrSetGoogleCloudAuthCompleteANDROID(session, future, &completion);

  if (completion.futureResult == XR_SUCCESS) {
    // Credentials were successfully applied.
  } else if (completion.futureResult == XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID) {
    // An error occurred when setting keyless auth credentials. This error may be retried.
  }
}

Neue Befehle

Neue Gebäude

Neue Enums

Neue Enum-Konstanten

  • XR_ANDROID_GOOGLE_CLOUD_AUTH_EXTENSION_NAME
  • XR_ANDROID_google_cloud_auth_SPEC_VERSION

  • Erweiterung von XrResult :

    • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID
    • XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID

  • Erweiterung von XrStructureType :

    • XR_TYPE_GOOGLE_CLOUD_AUTH_ERROR_RESULT_ANDROID
    • XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_API_KEY_ANDROID
    • XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_KEYLESS_ANDROID
    • XR_TYPE_GOOGLE_CLOUD_AUTH_INFO_TOKEN_ANDROID

Probleme

  • Version 1, 18.12.2025 (Ben King)

    • Erste Beschreibung der Erweiterung.