XR_ANDROID_google_cloud_auth

Name String

XR_ANDROID_google_cloud_auth

Erweiterungstyp

Instanzerweiterung

Registrierte Erweiterungsnummer

788

Revision

1

Ratifizierungsstatus

Nicht ratifiziert

Abhängigkeiten von Erweiterungen und Versionen

XR_EXT_future

Datum der letzten Änderung

2025-12-18

IP-Status

Keine bekannten IP-Ansprüche.

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 bereitstellt. Der Entwickler muss in der Google Cloud Console ( https://console.cloud.google.com/ ) ein Google Cloud-Projekt für die Anwendung 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 während der Laufzeit ein potenziell umsetzbarer Fehler auftritt, wenn 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 die gesamte verfügbare Dokumentation 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 Nachricht-ID „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 verwendet werden können mit xrSetGoogleCloudAuthAsyncANDROID , 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 Zeiger auf einen String, der den API-Schlüssel darstellt.

Wenn diese Struktur an xrSetGoogleCloudAuthAsyncANDROID übergeben wird, apiKey das Mitglied muss 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 (angegeben durch die abhängigen Erweiterungen).
  • Wenn der API-Schlüssel Einschränkungen hat, müssen diese 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 so, wie in der Erweiterung, die diese Funktionen definiert, für Cloud-Fehler dokumentiert. Wenn eine Funktion einen Fehler melden kann und die Anwendung XrGoogleCloudAuthErrorResultANDROID an den Ausgabeparameter dieser Funktion verkettet, muss die Laufzeit XrGoogleCloudAuthErrorResultANDROID :: error auf XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID setzen, um diesen Fehler anzugeben.

Der asynchrone Vorgang wird mit XR_SUCCESS abgeschlossen, sobald der API-Schlüssel auf Formatierung validiert 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 Zeiger auf einen String, der das Authentifizierungstoken darstellt.

Wenn diese Struktur an xrSetGoogleCloudAuthAsyncANDROID übergeben wird, authToken das Mitglied muss 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 ein gültiges und nicht abgelaufenes Authentifizierungstoken sein, das für Ihr Google Cloud-Projekt generiert wurde.
  • In Ihrem Google Cloud-Projekt müssen die relevanten Google Cloud APIs aktiviert sein (angegeben durch die abhängigen Erweiterungen).

  • Das Authentifizierungstoken muss eines der folgenden sein:

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

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

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 übergeben wurde, wenn eine neue Netzwerkanfrage gestartet wird.

Der asynchrone Vorgang wird mit XR_SUCCESS abgeschlossen, sobald das Token auf Formatierung validiert 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 Laufzeit Anmeldedaten dynamisch generieren (z.B. kommuniziert die Laufzeit unter Android aus dem Anwendungsprozess mit den Google Play-Diensten). Wenn die schlüssellose Authentifizierung nicht ordnungsgemäß 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 der 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 die erstellte Zukunft 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 Status „Bereit“ für die Zukunft zu prüfen. Sobald die Zukunft bereit ist, rufen Sie xrSetGoogleCloudAuthCompleteANDROID auf, um das Ergebnis abzurufen.

Der authInfo Parameter 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 wurde.
  • future ist die XrFutureEXT, die abgeschlossen werden soll.
  • completion ist ein Zeiger auf eine XrFutureCompletionEXT, die von der Laufzeit ausgefüllt wird.

Zukünftige Rückgabecodes

XrFutureCompletionEXT :: futureResult Werte:

Erfolg

  • XR_SUCCESS : 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 Android-Geräten 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 XrGoogleCloudAuthErrorANDROID Enumeration 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 Enumeratoren 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

Beim Aufrufen einer Google Cloud API wurde das Kontingent ü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 bei einem Vorgang angibt, der auf Google Cloud zugreift.

Wenn ein Vorgang aufgrund der Google Cloud-Authentifizierung fehlschlägt, kann diese Struktur an die Struktur des Vorgangsergebnisses angehängt werden, um weitere Informationen zum Fehler zu liefern.

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 Strukturen

Neue Enums

Neue Enum-Konstanten

  • XR_ANDROID_GOOGLE_CLOUD_AUTH_EXTENSION_NAME
  • XR_ANDROID_google_cloud_auth_SPEC_VERSION

  • Erweitern von XrResult :

    • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID
    • XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID

  • Erweitern 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

  • Revision 1, 18.12.2025 (Ben King)

    • Erste Beschreibung der Erweiterung.