XR_ANDROID_google_cloud_auth

Name String

XR_ANDROID_google_cloud_auth

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

788

Revisione

1

Stato della ratifica

Non ratificato

Dipendenze di estensioni e versioni

XR_EXT_future

Data ultima modifica

2025-12-18

Stato IP

Nessuna rivendicazione di PI 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 credenziali di autenticazione per le API Google Cloud. 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 Debug Messenger e si verifica un errore potenzialmente risolvibile nel runtime durante l'invio di 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 Google 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 il messageId "GoogleCloudError".

Autenticazione

La struttura XrGoogleCloudAuthInfoBaseHeaderANDROID è definita come:

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:

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 Google Cloud pertinenti (specificate dalle estensioni dipendenti).
  • Se la chiave API ha delle restrizioni, queste devono consentire le API Google 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 agiranno come documentato per gli errori del cloud nell'estensione che definisce queste funzioni. Se una funzione può segnalare un errore e l'applicazione concatena 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 sarà stata convalidata per la formattazione e archiviata dal runtime.

Utilizzo valido (implicito)

La struttura XrGoogleCloudAuthInfoTokenANDROID è definita come:

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 Google 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 i claim 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 agiranno come documentato per gli errori del cloud nell'estensione che definisce queste funzioni. Se una funzione può segnalare un errore e l'applicazione concatena 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 token precedente. 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 archiviato dal runtime.

Utilizzo valido (implicito)

La struttura XrGoogleCloudAuthInfoKeylessANDROID è definita come:

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 Keyless non è configurata correttamente, il runtime potrebbe 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 Keyless sono state applicate correttamente. Se il risultato futuro è XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID , l'applicazione può riprovare in un secondo momento.

Utilizzo valido (implicito)

La funzione xrSetGoogleCloudAuthAsyncANDROID è definita come:

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 future 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 pronto del future. Quando il future è nello stato pronto, 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 e che estende XrGoogleCloudAuthInfoBaseHeaderANDROID (ad es. XrGoogleCloudAuthInfoApiKeyANDROID).

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

Utilizzo valido (implicito)

Codici di risposta

Operazione 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:

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

Descrizioni dei parametri

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

Codici di reso futuri

Valori di XrFutureCompletionEXT :: futureResult:

Operazione riuscita

  • XR_SUCCESS : le credenziali sono state applicate correttamente.

Errore

  • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID : autenticazione senza chiave non riuscita. L'applicazione può riprovare più tardi. L'applicazione o lo sviluppatore possono anche verificare determinate precondizioni per il successo (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 risposta

Operazione 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:

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 di un'API Google Cloud.

XR_GOOGLE_CLOUD_AUTH_ERROR_QUOTA_EXCEEDED_ANDROID

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

XR_GOOGLE_CLOUD_AUTH_ERROR_UNREACHABLE_ANDROID

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

XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID

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

La struttura XrGoogleCloudAuthErrorResultANDROID è definita come:

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'errore XrGoogleCloudAuthErrorANDROID che descrive in dettaglio le cause dell'errore di un'operazione di accesso a Google Cloud.

Se un'operazione non va a buon fine a causa dell'autenticazione di Google Cloud, questa struttura può essere concatenata alla struttura dei risultati operativi 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

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