XR_ANDROID_google_cloud_auth

Chaîne de nom

XR_ANDROID_google_cloud_auth

Type d'extension

Extension d'instance

Numéro d'extension enregistré

788

Révision

1

État de ratification

Non ratifié

Dépendances d'extension et de version

XR_EXT_future

Date de dernière modification

2025-12-18

État de la propriété intellectuelle

Aucune revendication de propriété intellectuelle connue.

Contributeurs

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 autorisant l'application à 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 débogueur et qu'une erreur potentiellement exploitable se produit lors de l'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 débogueur 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;

Description des membres

  • type correspond au 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;

Description des membres

  • type correspond au 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 répondre aux 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 pertinentes (spécifiées par les extensions dépendantes).
  • Si la clé API comporte des restrictions, celles-ci doivent autoriser les API Google Cloud pertinentes et votre application.

Sinon, l'appel à xrSetGoogleCloudAuthAsyncANDROID réussira, mais tous les appels aux fonctions qui dépendent de l'autorisation cloud se comporteront 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 enchaîne 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 terminera par XR_SUCCESS une fois que la clé API aura été 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;

Description des membres

  • type correspond au 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 répondre aux 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 pertinentes (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 pertinents, 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 dans chaque cas sont spécifiées par les extensions dépendantes. Sinon, l'appel à xrSetGoogleCloudAuthAsyncANDROID réussira, mais tous les appels aux fonctions qui dépendent de l'autorisation cloud se comporteront 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 enchaîne 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 jeton aura été validé pour le formatage et 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;

Description des membres

  • type correspond au 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 d'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 effectue les requêtes réseau nécessaires pour récupérer les identifiants. Le résultat de cette opération sera renvoyé dans le XrFutureCompletionEXT :: futureResult à partir de xrSetGoogleCloudAuthCompleteANDROID . Si le résultat futur est XR_SUCCESS , les identifiants d'authentification sans clé ont été appliqués. Si le résultat futur est XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID , l'application peut réessayer ultérieurement.

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 correspond au XrSession qui utilisera les identifiants.
  • authInfo est un pointeur vers une structure spécifiant la méthode et les paramètres d'authentification, avec son champ XrGoogleCloudAuthInfoBaseHeaderANDROID :: type indiquant la structure spécifique.
  • future est un pointeur vers un handle XrFutureEXT dans lequel l'avenir créé est renvoyé, ou XR_NULL_HANDLE si la fonction n'a pas renvoyé XR_SUCCESS .

Définissez les identifiants utilisés pour l'authentification auprès de Google Cloud. Cette opération est asynchrone. Appelez xrPollFutureEXT pour vérifier l'état prêt de l'avenir. Une fois que l'avenir est 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, les comportements et les 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

L'é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 correspond au XrSession utilisé pour démarrer l'opération.
  • future correspond au XrFutureEXT à terminer.
  • completion est un pointeur vers un XrFutureCompletionEXT rempli par l'environnement d'exécution.

Codes renvoyés futurs

XrFutureCompletionEXT :: futureResult valeurs :

Opération réussie

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

L'échec

  • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID : l'authentification sans clé a échoué. L'application peut réessayer ultérieurement. L'application ou le développeur peut é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

L'é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;

Description des membres

  • type correspond au XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
  • error correspond au 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 enchaîné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

Nouveaux enums

Nouvelles constantes d'enum

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