XR_ANDROID_google_cloud_auth

Name String

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 IP

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

Twórcy

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

Przegląd

To rozszerzenie umożliwia korzystanie z rozszerzeń działających w chmurze Google, umożliwiając aplikacji podawanie danych uwierzytelniających do Cloud APIs Google. 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 programowania aplikacja może 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ć działania, środowisko wykonawcze wywołuje wywołanie zwrotne komunikatora 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 interfejsów Google Cloud API. Ś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 messageId „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 xrSetGoogleCloudAuthAsyncANDROID do podawania danych uwierzytelniających.

Prawidłowe użycie (pośrednie)

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 do ciągu znaków reprezentującego klucz interfejsu API.

Gdy ta struktura jest przekazywana do 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ć XR_ERROR_VALIDATION_FAILURE.

apiKey musi dodatkowo 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 zależne rozszerzenia).
  • Jeśli klucz interfejsu API ma ograniczenia, muszą one zezwalać na odpowiednie interfejsy Cloud APIs i Twoją aplikację.

W przeciwnym razie wywołanie funkcji xrSetGoogleCloudAuthAsyncANDROID powiedzie się, 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ę z wynikiem XR_SUCCESS, gdy klucz interfejsu API zostanie zweryfikowany pod kątem formatowania i zapisany przez środowisko wykonawcze.

Prawidłowe użycie (pośrednie)

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 do ciągu znaków reprezentującego token uwierzytelniania.

Gdy ta struktura jest przekazywana do 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ć XR_ERROR_VALIDATION_FAILURE. authToken musi dodatkowo spełniać te warunki:

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

  • Dane logowania muszą być jednym z tych typów:

    • token dostępu OAuth2 z odpowiednimi zakresami, wygenerowany przez zalogowanie się na konto Google za pomocą aplikacji;
    • Podpisany token JWT z odpowiednimi deklaracjami, wygenerowany przez konto usługi z projektu w chmurze Google.

Wymagania w każdym przypadku są określone przez rozszerzenia zależne. W przeciwnym razie wywołanie funkcji xrSetGoogleCloudAuthAsyncANDROID powiedzie się, 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.

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

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

Prawidłowe użycie (pośrednie)

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 jest przekazywana do funkcji xrSetGoogleCloudAuthAsyncANDROID, środowisko wykonawcze może dynamicznie generować dane logowania (np. na Androidzie środowisko wykonawcze komunikuje się z Usługami Google Play z poziomu procesu aplikacji). Jeśli uwierzytelnianie bez klucza nie jest prawidłowo skonfigurowane, środowisko wykonawcze może zwrócić 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 xrSetGoogleCloudAuthCompleteANDROID . Jeśli przyszły wynik to XR_SUCCESS , dane uwierzytelniające uwierzytelniania bez klucza 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 (pośrednie)

Funkcja xrSetGoogleCloudAuthAsyncANDROID jest zdefiniowana w ten sposób:

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

Opisy parametrów

  • session to XrSession, który będzie używać danych logowania.
  • authInfo to wskaźnik do struktury określającej metodę i parametry uwierzytelniania, a pole XrGoogleCloudAuthInfoBaseHeaderANDROID :: type wskazuje konkretną strukturę.
  • future to wskaźnik do uchwytu XrFutureEXT, w którym zwracany jest utworzony obiekt Future, lub XR_NULL_HANDLE, jeśli funkcja nie zwróciła 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 obiektu future. Gdy obiekt future 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 identyfikuje metodę uwierzytelniania, która ma być używana, i która rozszerza XrGoogleCloudAuthInfoBaseHeaderANDROID (np. XrGoogleCloudAuthInfoApiKeyANDROID).

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

Prawidłowe użycie (pośrednie)

Kody zwrotu

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żywany do rozpoczęcia operacji.
  • future to XrFutureEXT, który należy ukończyć.
  • completion to wskaźnik do XrFutureCompletionEXT wypełnionego przez środowisko wykonawcze.

Kody zwrotu w przyszłości

Wartości XrFutureCompletionEXT :: futureResult:

Sukces

  • XR_SUCCESS : dane logowania zostały zastosowane.

Błąd

  • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID : uwierzytelnianie bez klucza nie powiodło się. Aplikacja może spróbować ponownie później. Aplikacja lub deweloper mogą też sprawdzić, czy spełnione są pewne warunki wstępne (np. na Androidzie urządzenie musi mieć aktualną instalację Usług Google Play, a usługi te muszą działać prawidłowo).

Prawidłowe użycie (pośrednie)

Kody zwrotu

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 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;

Elementy wyliczenia mają te wartości:

Opis typu wyliczeniowego

XR_GOOGLE_CLOUD_AUTH_ERROR_NONE_ANDROID

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

XR_GOOGLE_CLOUD_AUTH_ERROR_QUOTA_EXCEEDED_ANDROID

Przekroczono limit podczas wywoływania interfejsu Google Cloud API.

XR_GOOGLE_CLOUD_AUTH_ERROR_UNREACHABLE_ANDROID

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

XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID

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

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 szczegółowo opisuje przyczynę błędu operacji uzyskującej dostęp do Google Cloud.

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

Prawidłowe użycie (pośrednie)

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 domy

Nowe wartości w polu enum

Nowe stałe typu wyliczeniowego

  • XR_ANDROID_GOOGLE_CLOUD_AUTH_EXTENSION_NAME
  • XR_ANDROID_google_cloud_auth_SPEC_VERSION

  • Rozszerzenie 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.