XR_ANDROID_google_cloud_auth

Stringa del nome

XR_ANDROID_google_cloud_auth

Tipo di estensione

Estensione dell'istanza

Numero di estensione registrato

788

Revisione

1

Stato di ratifica

Non ratificato

Dipendenze di estensione e versione

XR_EXT_future

Data dell'ultima modifica

2025-12-18

Stato IP

Nessuna rivendicazione IP nota.

Collaboratori

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

Panoramica

Questa estensione consente l'utilizzo di estensioni basate su Google Cloud consentendo all'applicazione di fornire le credenziali di autenticazione per le API Cloud di Google. Lo sviluppatore deve utilizzare la console Google Cloud ( https://console.cloud.google.com/ ) per creare un progetto cloud per l'applicazione. Questa estensione richiede l'estensione XR_EXT_future .

Durante lo sviluppo, l'applicazione può eseguire il debug dei problemi relativi alla configurazione di Google Cloud utilizzando l'estensione XR_EXT_debug_utils . Se l'applicazione ha un messenger di debug e si verifica un errore potenzialmente utilizzabile durante l'esecuzione quando invia una richiesta a Google Cloud per conto dell'applicazione, il runtime richiama il callback del messenger con un messaggio di errore. In questo caso, lo sviluppatore deve consultare il messaggio di errore e tutta la documentazione disponibile, quindi assicurarsi che l'applicazione e il progetto Google Cloud siano configurati correttamente per utilizzare le API Cloud. Il runtime deve utilizzare il tipo di messaggio XR_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT , la gravità XR_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT e l'ID messaggio "GoogleCloudError".

Autenticazione

La struttura XrGoogleCloudAuthInfoBaseHeaderANDROID è definita come segue:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.

Questa struttura non viene utilizzata direttamente nell'API, ma viene estesa da altre strutture che possono essere utilizzate con xrSetGoogleCloudAuthAsyncANDROID per fornire le credenziali di autenticazione.

Utilizzo valido (implicito)

La struttura XrGoogleCloudAuthInfoApiKeyANDROID è definita come segue:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • apiKey è un puntatore a una stringa che rappresenta la chiave API.

Quando questa struttura viene passata a xrSetGoogleCloudAuthAsyncANDROID , il membro apiKey deve essere una stringa ASCII non vuota senza spazi o caratteri di controllo, altrimenti il runtime deve restituire XR_ERROR_VALIDATION_FAILURE .

apiKey deve inoltre soddisfare le seguenti condizioni:

  • Deve essere una chiave API valida generata per il tuo progetto Google Cloud.
  • Il tuo progetto Google Cloud deve abilitare le API Cloud pertinenti (specificate dalle estensioni dipendenti).
  • Se la chiave API ha limitazioni, queste devono consentire le API Cloud pertinenti e la tua applicazione.

In caso contrario, la chiamata a xrSetGoogleCloudAuthAsyncANDROID andrà a buon fine, ma tutte le chiamate alle funzioni che dipendono dall'autorizzazione cloud si comporteranno come documentato per gli errori cloud nell'estensione che definisce queste funzioni. Se una funzione può segnalare un errore e l'applicazione incatena XrGoogleCloudAuthErrorResultANDROID al parametro di output di quella funzione, il runtime deve impostare XrGoogleCloudAuthErrorResultANDROID :: error su XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID per indicare questo errore.

L'operazione asincrona verrà completata con XR_SUCCESS una volta che la chiave API è stata convalidata per la formattazione e memorizzata dal runtime.

Utilizzo valido (implicito)

La struttura XrGoogleCloudAuthInfoTokenANDROID è definita come segue:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • authToken è un puntatore a una stringa che rappresenta il token di autenticazione.

Quando questa struttura viene passata a xrSetGoogleCloudAuthAsyncANDROID , il membro authToken deve essere una stringa ASCII non vuota senza spazi o caratteri di controllo, altrimenti il runtime deve restituire XR_ERROR_VALIDATION_FAILURE . authToken deve inoltre soddisfare le seguenti condizioni:

  • Deve essere una credenziale valida e non scaduta generata per il tuo progetto Google Cloud.
  • Il tuo progetto Google Cloud deve abilitare le API Cloud pertinenti (specificate dalle estensioni dipendenti).

  • La credenziale deve essere una delle seguenti:

    • Un token di accesso OAuth2 con gli ambiti pertinenti, generato accedendo a un Account Google con la tua applicazione, OPPURE
    • Un token JWT firmato con le attestazioni pertinenti, generato da un service account del tuo progetto Google Cloud.

I requisiti in ogni caso sono specificati dalle estensioni dipendenti. In caso contrario, la chiamata a xrSetGoogleCloudAuthAsyncANDROID andrà a buon fine, ma tutte le chiamate alle funzioni che dipendono dall'autorizzazione cloud si comporteranno come documentato per gli errori cloud nell'estensione che definisce queste funzioni. Se una funzione può segnalare un errore e l'applicazione incatena XrGoogleCloudAuthErrorResultANDROID al parametro di output di quella funzione, il runtime deve impostare XrGoogleCloudAuthErrorResultANDROID :: error su XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID per indicare questo errore.

L'applicazione deve passare in modo proattivo un nuovo token tramite xrSetGoogleCloudAuthAsyncANDROID prima della scadenza del vecchio token. Il runtime deve utilizzare l'ultimo token passato dall'applicazione quando avvia una nuova richiesta di rete.

L'operazione asincrona verrà completata con XR_SUCCESS una volta che il token è stato convalidato per la formattazione e memorizzato dal runtime.

Utilizzo valido (implicito)

La struttura XrGoogleCloudAuthInfoKeylessANDROID è definita come segue:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.

Quando questa struttura viene passata a xrSetGoogleCloudAuthAsyncANDROID , il runtime può generare le credenziali in modo dinamico (ad es. su Android, il runtime comunica con Google Play Services dal processo dell'applicazione). Se l'autenticazione senza chiave non è configurata correttamente, il runtime può restituire XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID in modo sincrono.

L'operazione asincrona eseguirà le richieste di rete necessarie per recuperare le credenziali. Il risultato di questa operazione verrà restituito in XrFutureCompletionEXT :: futureResult da xrSetGoogleCloudAuthCompleteANDROID . Se il risultato futuro è XR_SUCCESS , le credenziali di autenticazione senza chiave sono state applicate correttamente. Se il risultato futuro è XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID , l'applicazione può riprovare più tardi.

Utilizzo valido (implicito)

La funzione xrSetGoogleCloudAuthAsyncANDROID è definita come segue:

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

Descrizioni dei parametri

  • session è l'XrSession che utilizzerà le credenziali.
  • authInfo è un puntatore a una struttura che specifica il metodo e i parametri di autenticazione, con il campo XrGoogleCloudAuthInfoBaseHeaderANDROID :: type che indica la struttura specifica.
  • future è un puntatore a un handle XrFutureEXT in cui viene restituito il futuro creato o XR_NULL_HANDLE se la funzione non ha restituito XR_SUCCESS .

Imposta le credenziali utilizzate per l'autenticazione con Google Cloud. Questa operazione è asincrona. Chiama xrPollFutureEXT per controllare lo stato di preparazione del futuro. Una volta che il futuro è nello stato di preparazione, chiama xrSetGoogleCloudAuthCompleteANDROID per recuperare il risultato.

Il parametro authInfo deve essere un puntatore a una struttura il cui membro XrGoogleCloudAuthInfoBaseHeaderANDROID :: type identifica il metodo di autenticazione da utilizzare ed estende XrGoogleCloudAuthInfoBaseHeaderANDROID (ad es. XrGoogleCloudAuthInfoApiKeyANDROID ).

I requisiti, i comportamenti e le condizioni di errore specifici (sia sincroni che asincroni) per ogni metodo di autenticazione sono descritti nella documentazione delle rispettive strutture di dati.

Utilizzo valido (implicito)

Codici di ritorno

Riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

La funzione xrSetGoogleCloudAuthCompleteANDROID è definita come segue:

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

Descrizioni dei parametri

  • session è l'XrSession utilizzato per avviare l'operazione.
  • future è l'XrFutureEXT da completare.
  • completion è un puntatore a un XrFutureCompletionEXT compilato dal runtime.

Codici di ritorno futuri

XrFutureCompletionEXT :: futureResult valori:

Riuscita

  • XR_SUCCESS : le credenziali sono state applicate correttamente.

Errore

  • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID : l'autenticazione senza chiave non è riuscita. L'applicazione può riprovare più tardi. L'applicazione o lo sviluppatore possono anche controllare alcune precondizioni per la riuscita (ad es. su Android, il dispositivo deve avere un'installazione aggiornata di Google Play Services e questi servizi devono funzionare correttamente).

Utilizzo valido (implicito)

Codici di ritorno

Riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

Errori di autenticazione di Google Cloud

L'enumerazione XrGoogleCloudAuthErrorANDROID è definita come segue:

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;

Gli enumeratori hanno i seguenti valori:

Descrizione enum

XR_GOOGLE_CLOUD_AUTH_ERROR_NONE_ANDROID

Non si è verificato alcun errore durante la chiamata a un'API Google Cloud.

XR_GOOGLE_CLOUD_AUTH_ERROR_QUOTA_EXCEEDED_ANDROID

Quota superata durante la chiamata a un'API Google Cloud.

XR_GOOGLE_CLOUD_AUTH_ERROR_UNREACHABLE_ANDROID

Impossibile raggiungere un'API Google Cloud, probabilmente a causa di problemi di connettività di rete o di disponibilità del server.

XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID

Si è verificato un errore di autenticazione durante la chiamata a un'API Google Cloud.

La struttura XrGoogleCloudAuthErrorResultANDROID è definita come segue:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • error è l'XrGoogleCloudAuthErrorANDROID che descrive la causa dell'errore di un'operazione di accesso a Google Cloud.

Se un'operazione non riesce a causa dell'autenticazione di Google Cloud, questa struttura può essere concatenata alla struttura del risultato operativo per fornire ulteriori informazioni sull'errore.

Utilizzo valido (implicito)

Esempio di codice

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

Nuovi comandi

Nuove strutture

Nuove enum

Nuove costanti enum

  • XR_ANDROID_GOOGLE_CLOUD_AUTH_EXTENSION_NAME
  • XR_ANDROID_google_cloud_auth_SPEC_VERSION

  • Estensione di XrResult :

    • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID
    • XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID

  • Estensione di 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

Problemi

  • Revisione 1, 18/12/2025 (Ben King)

    • Descrizione iniziale dell'estensione.