XR_ANDROID_google_cloud_auth

Name String

XR_ANDROID_google_cloud_auth

Type d'extension

Extension d'instance

Numéro d'extension enregistré

788

Révision

1

État de la ratification

Non ratifié

Dépendances d'extension et de version

XR_EXT_future

Date de dernière modification

2025-12-18

État de l'adresse IP

Aucune réclamation de propriété intellectuelle connue.

Participants

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

Présentation

Cette extension permet d'utiliser des extensions basées sur Google Cloud en permettant à l'application de fournir des identifiants d'authentification pour les API Google Cloud. Le développeur doit utiliser la console Google Cloud ( https://console.cloud.google.com/) pour créer un projet Google Cloud pour l'application. Cette extension nécessite l'extension XR_EXT_future .

Pendant le développement, l'application peut déboguer les problèmes liés à sa configuration Google Cloud à l'aide de l'extension XR_EXT_debug_utils . Si l'application dispose d'un Debug Messenger et qu'une erreur potentiellement exploitable se produit dans l'environnement d'exécution lors de l'envoi d'une requête à Google Cloud au nom de l'application, l'environnement d'exécution appelle le rappel du messager avec un message d'erreur. Dans ce cas, le développeur doit consulter le message d'erreur et toute la documentation disponible, puis s'assurer que l'application et le projet Google Cloud sont correctement configurés pour utiliser les API Google Cloud. L'environnement d'exécution doit utiliser le type de message XR_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT, la gravité XR_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT et l'ID de message "GoogleCloudError".

Authentification

La structure XrGoogleCloudAuthInfoBaseHeaderANDROID est définie comme suit :

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

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.

Cette structure n'est pas directement utilisée dans l'API, mais elle est étendue par d'autres structures qui peuvent être utilisées avec xrSetGoogleCloudAuthAsyncANDROID pour fournir des identifiants d'authentification.

Utilisation valide (implicite)

La structure XrGoogleCloudAuthInfoApiKeyANDROID est définie comme suit :

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

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
  • apiKey est un pointeur vers une chaîne représentant la clé API.

Lorsque cette structure est transmise à xrSetGoogleCloudAuthAsyncANDROID , le membre apiKey doit être une chaîne ASCII non vide sans espaces ni caractères de contrôle. Sinon, l'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE.

apiKey doit également remplir les conditions suivantes :

  • Il doit s'agir d'une clé API valide générée pour votre projet Google Cloud.
  • Votre projet Google Cloud doit activer les API Google Cloud appropriées (spécifiées par les extensions dépendantes).
  • Si la clé API est soumise à des restrictions, celles-ci doivent autoriser les API Google Cloud concernées et votre application.

Sinon, l'appel de xrSetGoogleCloudAuthAsyncANDROID aboutira, mais tous les appels de fonctions qui dépendent de l'autorisation cloud agiront comme indiqué pour les échecs cloud dans l'extension qui définit ces fonctions. Si une fonction peut signaler un échec et que l'application associe XrGoogleCloudAuthErrorResultANDROID au paramètre de sortie de cette fonction, l'environnement d'exécution doit définir XrGoogleCloudAuthErrorResultANDROID :: error sur XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID pour indiquer cette erreur.

L'opération asynchrone se termine par XR_SUCCESS une fois que la clé API est validée pour le formatage et stockée par l'environnement d'exécution.

Utilisation valide (implicite)

La structure XrGoogleCloudAuthInfoTokenANDROID est définie comme suit :

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

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
  • authToken est un pointeur vers une chaîne représentant le jeton d'authentification.

Lorsque cette structure est transmise à xrSetGoogleCloudAuthAsyncANDROID , le membre authToken doit être une chaîne ASCII non vide sans espaces ni caractères de contrôle. Sinon, l'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE. authToken doit également remplir les conditions suivantes :

  • Il doit s'agir d'un identifiant valide et non expiré généré pour votre projet Google Cloud.
  • Votre projet Google Cloud doit activer les API Google Cloud appropriées (spécifiées par les extensions dépendantes).

  • L'identifiant doit être l'un des suivants :

    • Un jeton d'accès OAuth2 avec les champs d'application appropriés, généré en vous connectant à un compte Google avec votre application, OU
    • Un jeton JWT signé avec les revendications pertinentes, généré par un compte de service de votre projet Google Cloud.

Les exigences de chaque cas sont spécifiées par les extensions dépendantes. Sinon, l'appel de xrSetGoogleCloudAuthAsyncANDROID aboutira, mais tous les appels de fonctions qui dépendent de l'autorisation cloud agiront comme indiqué pour les échecs cloud dans l'extension qui définit ces fonctions. Si une fonction peut signaler un échec et que l'application associe XrGoogleCloudAuthErrorResultANDROID au paramètre de sortie de cette fonction, l'environnement d'exécution doit définir XrGoogleCloudAuthErrorResultANDROID :: error sur XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID pour indiquer cette erreur.

L'application doit transmettre de manière proactive un nouveau jeton via xrSetGoogleCloudAuthAsyncANDROID avant l'expiration de l'ancien jeton. L'environnement d'exécution doit utiliser le dernier jeton transmis par l'application lors du démarrage d'une nouvelle requête réseau.

L'opération asynchrone se terminera par XR_SUCCESS une fois que le format du jeton aura été validé et que le jeton aura été stocké par l'environnement d'exécution.

Utilisation valide (implicite)

La structure XrGoogleCloudAuthInfoKeylessANDROID est définie comme suit :

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

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.

Lorsque cette structure est transmise à xrSetGoogleCloudAuthAsyncANDROID, l'environnement d'exécution peut générer des identifiants de manière dynamique (par exemple, sur Android, l'environnement d'exécution communique avec les services Google Play à partir du processus de l'application). Si l'authentification sans clé n'est pas correctement configurée, l'environnement d'exécution peut renvoyer XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID de manière synchrone.

L'opération asynchrone effectuera les requêtes réseau nécessaires pour récupérer les identifiants. Le résultat de cette opération sera renvoyé dans XrFutureCompletionEXT :: futureResult à partir de xrSetGoogleCloudAuthCompleteANDROID . Si le résultat futur est XR_SUCCESS , les identifiants d'authentification sans clé ont bien été appliqués. Si le résultat futur est XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID , l'application peut réessayer plus tard.

Utilisation valide (implicite)

La fonction xrSetGoogleCloudAuthAsyncANDROID est définie comme suit :

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

Description des paramètres

  • session est la XrSession qui utilisera les identifiants.
  • authInfo est un pointeur vers une structure spécifiant la méthode d'authentification et les paramètres, avec son champ XrGoogleCloudAuthInfoBaseHeaderANDROID :: type indiquant la structure spécifique.
  • future est un pointeur vers un handle XrFutureEXT dans lequel l'objet Future créé est renvoyé, ou XR_NULL_HANDLE si la fonction n'a pas renvoyé XR_SUCCESS .

Définissez les identifiants utilisés pour vous authentifier auprès de Google Cloud. Cette opération est asynchrone. Appelez xrPollFutureEXT pour vérifier l'état de préparation de l'objet Future. Une fois que l'objet Future est à l'état prêt, appelez xrSetGoogleCloudAuthCompleteANDROID pour récupérer le résultat.

Le paramètre authInfo doit être un pointeur vers une structure dont le membre XrGoogleCloudAuthInfoBaseHeaderANDROID :: type identifie la méthode d'authentification à utiliser et qui étend XrGoogleCloudAuthInfoBaseHeaderANDROID (par exemple, XrGoogleCloudAuthInfoApiKeyANDROID).

Les exigences, comportements et conditions d'erreur spécifiques (synchrones et asynchrones) pour chaque méthode d'authentification sont décrits dans la documentation de leurs structures de données respectives.

Utilisation valide (implicite)

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • 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 fonction xrSetGoogleCloudAuthCompleteANDROID est définie comme suit :

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

Description des paramètres

  • session est l'XrSession utilisée pour démarrer l'opération.
  • future est le XrFutureEXT à terminer.
  • completion est un pointeur vers un XrFutureCompletionEXT renseigné par l'environnement d'exécution.

Codes de retour futurs

XrFutureCompletionEXT :: valeurs futureResult :

Opération réussie

  • XR_SUCCESS : les identifiants ont bien été appliqués.

Échec

  • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID : échec de l'authentification sans clé. L'application peut réessayer plus tard. L'application ou le développeur peuvent également vérifier certaines conditions préalables à la réussite (par exemple, sur Android, l'appareil doit disposer d'une installation à jour des services Google Play, et ces services doivent fonctionner correctement).

Utilisation valide (implicite)

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • 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

Erreurs d'authentification Google Cloud

L'énumération XrGoogleCloudAuthErrorANDROID est définie comme suit :

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;

Les énumérants ont les valeurs suivantes :

Description de l'enum

XR_GOOGLE_CLOUD_AUTH_ERROR_NONE_ANDROID

Aucune erreur ne s'est produite lors de l'appel d'une API Google Cloud.

XR_GOOGLE_CLOUD_AUTH_ERROR_QUOTA_EXCEEDED_ANDROID

Quota dépassé lors de l'appel d'une API Google Cloud.

XR_GOOGLE_CLOUD_AUTH_ERROR_UNREACHABLE_ANDROID

Échec de l'accès à une API Google Cloud, peut-être en raison de problèmes de connectivité réseau ou de disponibilité du serveur.

XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID

Une erreur d'authentification s'est produite lors de l'appel d'une API Google Cloud.

La structure XrGoogleCloudAuthErrorResultANDROID est définie comme suit :

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

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
  • error est l'erreur XrGoogleCloudAuthErrorANDROID détaillant la cause de l'erreur d'une opération accédant à Google Cloud.

Si une opération échoue en raison de l'authentification Google Cloud, cette structure peut être associée à la structure de résultat opérationnel pour fournir plus d'informations sur l'erreur.

Utilisation valide (implicite)

Exemple de code

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

Nouvelles commandes

Nouvelles structures

Nouvelles énumérations

Nouvelles constantes d'énumération

  • XR_ANDROID_GOOGLE_CLOUD_AUTH_EXTENSION_NAME
  • XR_ANDROID_google_cloud_auth_SPEC_VERSION

  • Extension de XrResult :

    • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID
    • XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID

  • Extension de 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

Problèmes

  • Révision 1, 18/12/2025 (Ben King)

    • Description initiale de l'extension.