XR_ANDROID_google_cloud_auth

Ciąg znaków nazwy

XR_ANDROID_google_cloud_auth

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

788

Wersja

1

Stan ratyfikacji

Nie ratyfikowano

Zależności rozszerzeń i wersji

XR_EXT_future

Data ostatniej modyfikacji

2025-12-18

Stan adresu IP

Brak znanych roszczeń dotyczących własności intelektualnej.

Twórcy

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

Omówienie

To rozszerzenie umożliwia korzystanie z rozszerzeń opartych na Google Cloud, ponieważ pozwala aplikacji udostępniać dane logowania do interfejsów API Google Cloud. Deweloper musi użyć konsoli Google Cloud ( https://console.cloud.google.com/ ), aby utworzyć projekt w chmurze Google dla aplikacji. To rozszerzenie wymaga rozszerzenia XR_EXT_future .

Podczas tworzenia aplikacji możesz debugować problemy z konfiguracją Google Cloud za pomocą rozszerzenia XR_EXT_debug_utils . Jeśli aplikacja ma Debug Messenger, a podczas wysyłania żądania do Google Cloud w jej imieniu wystąpi błąd, który może wymagać podjęcia działania, środowisko wykonawcze wywoła funkcję zwrotną posłańca z komunikatem o błędzie. W takim przypadku deweloper powinien zapoznać się z komunikatem o błędzie i całą dostępną dokumentacją, a następnie upewnić się, że aplikacja i projekt Google Cloud są prawidłowo skonfigurowane do korzystania z Cloud APIs Google Cloud. Środowisko wykonawcze musi używać typu wiadomości XR_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT, poziomu ważności XR_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT i identyfikatora wiadomości „GoogleCloudError”.

Uwierzytelnianie

Struktura XrGoogleCloudAuthInfoBaseHeaderANDROID jest zdefiniowana w ten sposób:

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.

Ta struktura nie jest używana bezpośrednio w interfejsie API, ale jest rozszerzana przez inne struktury, które mogą być używane z funkcją xrSetGoogleCloudAuthAsyncANDROID do podawania danych logowania.

Prawidłowe użycie (domyślne)

Struktura XrGoogleCloudAuthInfoApiKeyANDROID jest zdefiniowana w ten sposób:

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • apiKey to wskaźnik ciągu znaków reprezentujący klucz interfejsu API.

Gdy ta struktura jest przekazywana do funkcji xrSetGoogleCloudAuthAsyncANDROID, element apiKey musi być niepustym ciągiem znaków ASCII bez spacji i znaków sterujących. W przeciwnym razie środowisko wykonawcze musi zwrócić wartość XR_ERROR_VALIDATION_FAILURE.

apiKey musi spełniać te warunki:

  • Musi to być prawidłowy klucz interfejsu API wygenerowany dla Twojego projektu w chmurze Google.
  • W projekcie Google Cloud muszą być włączone odpowiednie interfejsy Google Cloud API (określone przez rozszerzenia zależne).
  • Jeśli klucz interfejsu API ma ograniczenia, muszą one zezwalać na odpowiednie interfejsy Cloud API i Twoją aplikację.

W przeciwnym razie wywołanie funkcji xrSetGoogleCloudAuthAsyncANDROID zakończy się powodzeniem, ale wszystkie wywołania funkcji, które zależą od autoryzacji w chmurze, będą działać zgodnie z dokumentacją dotyczącą błędów w chmurze w rozszerzeniu, które definiuje te funkcje. Jeśli funkcja może zgłosić błąd, a aplikacja łączy XrGoogleCloudAuthErrorResultANDROID z parametrem wyjściowym tej funkcji, środowisko wykonawcze musi ustawić XrGoogleCloudAuthErrorResultANDROID :: error na XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID, aby wskazać ten błąd.

Operacja asynchroniczna zakończy się wartością XR_SUCCESS, gdy klucz interfejsu API zostanie zweryfikowany pod kątem formatowania i zapisany przez środowisko wykonawcze.

Prawidłowe użycie (domyślne)

Struktura XrGoogleCloudAuthInfoTokenANDROID jest zdefiniowana w ten sposób:

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • authToken to wskaźnik ciągu znaków reprezentującego token uwierzytelniania.

Gdy ta struktura jest przekazywana do funkcji xrSetGoogleCloudAuthAsyncANDROID, element authToken musi być niepustym ciągiem znaków ASCII bez spacji i znaków sterujących. W przeciwnym razie środowisko wykonawcze musi zwrócić wartość XR_ERROR_VALIDATION_FAILURE. authToken musi spełniać te warunki:

  • Musi to być prawidłowe i nieprzeterminowane dane logowania wygenerowane dla Twojego projektu Google Cloud.
  • W projekcie Google Cloud muszą być włączone odpowiednie interfejsy Google Cloud API (określone przez rozszerzenia zależne).

  • Dokument musi być jednym z tych dokumentów:

    • token dostępu OAuth2 z odpowiednimi zakresami wygenerowany przez zalogowanie się na konto Google w aplikacji LUB
    • Podpisany token JWT z odpowiednimi deklaracjami wygenerowany przez konto usługi z Twojego projektu w chmurze Google.

Wymagania w każdym przypadku są określone przez rozszerzenia, od których zależy. W przeciwnym razie wywołanie funkcji xrSetGoogleCloudAuthAsyncANDROID zakończy się powodzeniem, ale wszystkie wywołania funkcji, które zależą od autoryzacji w chmurze, będą działać zgodnie z dokumentacją dotyczącą błędów w chmurze w rozszerzeniu, które definiuje te funkcje. Jeśli funkcja może zgłosić błąd, a aplikacja łączy XrGoogleCloudAuthErrorResultANDROID z parametrem wyjściowym tej funkcji, środowisko wykonawcze musi ustawić XrGoogleCloudAuthErrorResultANDROID :: error na XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID, aby wskazać ten błąd.

Zanim stary token wygaśnie, aplikacja musi aktywnie przekazać nowy token za pomocą funkcji xrSetGoogleCloudAuthAsyncANDROID. Środowisko wykonawcze musi używać najnowszego tokena przekazanego przez aplikację podczas rozpoczynania nowego żądania sieciowego.

Operacja asynchroniczna zakończy się z wartością XR_SUCCESS, gdy token zostanie zweryfikowany pod kątem formatowania i zapisany przez środowisko wykonawcze.

Prawidłowe użycie (domyślne)

Struktura XrGoogleCloudAuthInfoKeylessANDROID jest zdefiniowana w ten sposób:

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.

Gdy ta struktura zostanie przekazana do funkcji xrSetGoogleCloudAuthAsyncANDROID, środowisko wykonawcze może dynamicznie generować dane logowania (np. na Androidzie środowisko wykonawcze komunikuje się z Usługami Google Play z procesu aplikacji). Jeśli uwierzytelnianie bezkluczowe nie jest prawidłowo skonfigurowane, środowisko wykonawcze może zwrócić wartość XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID synchronicznie.

Operacja asynchroniczna wykona niezbędne żądania sieciowe, aby pobrać dane logowania. Wynik tej operacji zostanie zwrócony w XrFutureCompletionEXT :: futureResult z funkcji xrSetGoogleCloudAuthCompleteANDROID . Jeśli przyszły wynik to XR_SUCCESS , dane logowania uwierzytelniania bezkluczykowego zostały zastosowane. Jeśli przyszły wynik to XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID , aplikacja może spróbować ponownie później.

Prawidłowe użycie (domyślne)

Funkcja xrSetGoogleCloudAuthAsyncANDROID jest zdefiniowana w ten sposób:

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

Opisy parametrów

  • session to XrSession, która będzie używać danych logowania.
  • authInfo to wskaźnik struktury określającej metodę uwierzytelniania i parametry, a pole XrGoogleCloudAuthInfoBaseHeaderANDROID :: type wskazuje konkretną strukturę.
  • future to wskaźnik do uchwytu XrFutureEXT, w którym zwracana jest utworzona przyszłość, lub XR_NULL_HANDLE, jeśli funkcja nie zwróciła wartości XR_SUCCESS .

Ustaw dane logowania używane do uwierzytelniania w Google Cloud. Ta operacja jest asynchroniczna. Wywołaj funkcję xrPollFutureEXT, aby sprawdzić stan gotowości przyszłego obiektu. Gdy przyszłość będzie w stanie gotowości, wywołaj funkcję xrSetGoogleCloudAuthCompleteANDROID, aby pobrać wynik.

Parametr authInfo musi być wskaźnikiem do struktury, której element XrGoogleCloudAuthInfoBaseHeaderANDROID :: type określa metodę uwierzytelniania, która ma być używana, i która rozszerza XrGoogleCloudAuthInfoBaseHeaderANDROID (np. XrGoogleCloudAuthInfoApiKeyANDROID).

Szczegółowe wymagania, zachowania i warunki błędów (synchroniczne i asynchroniczne) dla każdej metody uwierzytelniania są opisane w dokumentacji odpowiednich struktur danych.

Prawidłowe użycie (domyślne)

Kody zwrotne

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • 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

Funkcja xrSetGoogleCloudAuthCompleteANDROID jest zdefiniowana w ten sposób:

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

Opisy parametrów

  • session to XrSession użyta do rozpoczęcia operacji.
  • future to XrFutureEXT do ukończenia.
  • completion to wskaźnik do struktury XrFutureCompletionEXT wypełnionej przez środowisko wykonawcze.

Kody zwrotu w przyszłości

XrFutureCompletionEXT :: futureResult wartości:

Sukces

  • XR_SUCCESS : dane logowania zostały zastosowane.

Błąd

  • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID : Nie udało się uwierzytelnianie bez klucza. Aplikacja może spróbować jeszcze raz później. Aplikacja lub deweloper może też sprawdzać pewne warunki wstępne (np. na Androidzie urządzenie musi mieć aktualną instalację Usług Google Play, a te usługi muszą działać prawidłowo).

Prawidłowe użycie (domyślne)

Kody zwrotne

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • 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

Błędy uwierzytelniania w Google Cloud

Wyliczenie XrGoogleCloudAuthErrorANDROID jest zdefiniowane w ten sposób:

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;

Wartości wyliczeniowe są następujące:

Opis typu wyliczeniowego

XR_GOOGLE_CLOUD_AUTH_ERROR_NONE_ANDROID

Podczas wywoływania interfejsu Google Cloud API nie wystąpił żaden błąd.

XR_GOOGLE_CLOUD_AUTH_ERROR_QUOTA_EXCEEDED_ANDROID

Limit został przekroczony podczas wywoływania interfejsu API Google Cloud.

XR_GOOGLE_CLOUD_AUTH_ERROR_UNREACHABLE_ANDROID

Nie udało się połączyć z interfejsem Google Cloud API, prawdopodobnie z powodu problemów z łącznością sieciową lub dostępnością serwera.

XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID

Podczas wywoływania interfejsu Google Cloud API wystąpił błąd autoryzacji.

Struktura XrGoogleCloudAuthErrorResultANDROID jest zdefiniowana w ten sposób:

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • error to XrGoogleCloudAuthErrorANDROID, który zawiera szczegółowe informacje o przyczynie błędu operacji uzyskiwania dostępu do Google Cloud.

Jeśli operacja nie powiedzie się z powodu uwierzytelniania w Google Cloud, ta struktura może być połączona ze strukturą wyniku operacji, aby dostarczyć więcej informacji o błędzie.

Prawidłowe użycie (domyślne)

Przykładowy kod

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.
  }
}

Nowe polecenia

Nowe struktury

Nowe wartości w polu enum

Nowe stałe wyliczeniowe

  • XR_ANDROID_GOOGLE_CLOUD_AUTH_EXTENSION_NAME
  • XR_ANDROID_google_cloud_auth_SPEC_VERSION

  • Rozszerzanie XrResult :

    • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID
    • XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID

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

Problemy

  • Wersja 1, 18 grudnia 2025 r. (Ben King)

    • Początkowy opis rozszerzenia.