XR_ANDROID_google_cloud_auth

Name String

XR_ANDROID_google_cloud_auth

Tipo de extensión

Extensión de instancia

Número de extensión registrado

788

Revisión

1

Estado de ratificación

No ratificado

Dependencias de extensiones y versiones

XR_EXT_future

Fecha de la última modificación

2025-12-18

Estado de la IP

No hay reclamos de IP conocidos.

Colaboradores

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

Descripción general

Esta extensión habilita el uso de extensiones basadas en Google Cloud, ya que permite que la aplicación proporcione credenciales de autenticación para las APIs de Google Cloud. El desarrollador debe usar la consola de Google Cloud ( https://console.cloud.google.com/) para crear un proyecto de Google Cloud para la aplicación. Esta extensión requiere la extensión XR_EXT_future .

Durante el desarrollo, la aplicación puede depurar problemas con su configuración de Google Cloud usando la extensión XR_EXT_debug_utils . Si la aplicación tiene un Debug Messenger y se produce un error potencialmente procesable en el entorno de ejecución cuando se envía una solicitud a Google Cloud en nombre de la aplicación, el entorno de ejecución invoca la devolución de llamada del mensajero con un mensaje de error. En este caso, el desarrollador debe consultar el mensaje de error y toda la documentación disponible, y, luego, asegurarse de que la aplicación y el proyecto de Google Cloud estén configurados correctamente para usar las APIs de Google Cloud. El entorno de ejecución debe usar el tipo de mensaje XR_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT, la gravedad XR_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT y el messageId “GoogleCloudError”.

Autenticación

La estructura XrGoogleCloudAuthInfoBaseHeaderANDROID se define de la siguiente manera:

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras.

Esta estructura no se usa directamente en la API, pero otras estructuras que pueden usarse con xrSetGoogleCloudAuthAsyncANDROID la extienden para proporcionar credenciales de autenticación.

Uso válido (implícito)

La estructura XrGoogleCloudAuthInfoApiKeyANDROID se define de la siguiente manera:

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras.
  • apiKey es un puntero a una cadena que representa la clave de API.

Cuando esta estructura se pasa a xrSetGoogleCloudAuthAsyncANDROID , el miembro apiKey debe ser una cadena ASCII no vacía sin espacios ni caracteres de control; de lo contrario, el entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE .

apiKey debe cumplir con las siguientes condiciones:

  • Debe ser una clave de API válida generada para tu proyecto de Google Cloud.
  • Tu proyecto de Google Cloud debe habilitar las APIs de Google Cloud pertinentes (especificadas por las extensiones dependientes).
  • Si la clave de API tiene restricciones, estas deben permitir las APIs de Google Cloud pertinentes y tu aplicación.

De lo contrario, la llamada a xrSetGoogleCloudAuthAsyncANDROID se realizará correctamente, pero todas las llamadas a funciones que dependan de la autorización de la nube actuarán como se documenta para las fallas de la nube en la extensión que define esas funciones. Si una función puede informar un error y la aplicación encadena XrGoogleCloudAuthErrorResultANDROID al parámetro de salida de esa función, el entorno de ejecución debe establecer XrGoogleCloudAuthErrorResultANDROID :: error en XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID para indicar este error.

La operación asíncrona se completará con XR_SUCCESS una vez que el entorno de ejecución valide el formato de la clave de API y la almacene.

Uso válido (implícito)

La estructura XrGoogleCloudAuthInfoTokenANDROID se define de la siguiente manera:

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras.
  • authToken es un puntero a una cadena que representa el token de autenticación.

Cuando esta estructura se pasa a xrSetGoogleCloudAuthAsyncANDROID , el miembro authToken debe ser una cadena ASCII no vacía sin espacios ni caracteres de control; de lo contrario, el entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE . authToken debe cumplir con las siguientes condiciones:

  • Debe ser una credencial válida y no vencida generada para tu proyecto de Google Cloud.
  • Tu proyecto de Google Cloud debe habilitar las APIs de Google Cloud pertinentes (especificadas por las extensiones dependientes).

  • La credencial debe ser una de las siguientes:

    • Un token de acceso de OAuth2 con los permisos pertinentes, generado cuando accedes a una Cuenta de Google con tu aplicación, O BIEN
    • Un token JWT firmado con las reclamaciones pertinentes, generado por una cuenta de servicio de tu proyecto de Google Cloud.

Los requisitos en cada caso se especifican según las extensiones dependientes. De lo contrario, la llamada a xrSetGoogleCloudAuthAsyncANDROID se realizará correctamente, pero todas las llamadas a funciones que dependan de la autorización de la nube actuarán como se documenta para las fallas de la nube en la extensión que define esas funciones. Si una función puede informar un error y la aplicación encadena XrGoogleCloudAuthErrorResultANDROID al parámetro de salida de esa función, el entorno de ejecución debe establecer XrGoogleCloudAuthErrorResultANDROID :: error en XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID para indicar este error.

La aplicación debe pasar de forma proactiva un token nuevo a través de xrSetGoogleCloudAuthAsyncANDROID antes de que venza el token anterior. El entorno de ejecución debe usar el token más reciente que pasó la aplicación cuando se inicia una nueva solicitud de red.

La operación asíncrona se completará con XR_SUCCESS una vez que se valide el formato del token y el entorno de ejecución lo almacene.

Uso válido (implícito)

La estructura XrGoogleCloudAuthInfoKeylessANDROID se define de la siguiente manera:

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras.

Cuando esta estructura se pasa a xrSetGoogleCloudAuthAsyncANDROID, el entorno de ejecución puede generar credenciales de forma dinámica (p.ej., en Android, el entorno de ejecución se comunica con los Servicios de Google Play desde el proceso de la aplicación). Si la autenticación sin claves no está configurada correctamente, el entorno de ejecución puede devolver XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID de forma síncrona.

La operación asíncrona realizará las solicitudes de red necesarias para recuperar las credenciales. El resultado de esta operación se devolverá en XrFutureCompletionEXT :: futureResult de xrSetGoogleCloudAuthCompleteANDROID . Si el resultado futuro es XR_SUCCESS , las credenciales de autenticación sin clave se aplicaron correctamente. Si el resultado futuro es XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID , la aplicación puede volver a intentarlo más tarde.

Uso válido (implícito)

La función xrSetGoogleCloudAuthAsyncANDROID se define de la siguiente manera:

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

Descripciones de los parámetros

  • session es la XrSession que usará las credenciales.
  • authInfo es un puntero a un struct que especifica el método y los parámetros de autenticación, con su campo XrGoogleCloudAuthInfoBaseHeaderANDROID :: type que indica el struct específico.
  • future es un puntero a un controlador XrFutureEXT en el que se devuelve el futuro creado, o XR_NULL_HANDLE si la función no devolvió XR_SUCCESS .

Establece las credenciales que se usan para autenticar con Google Cloud. Esta operación es asíncrona. Llama a xrPollFutureEXT para verificar el estado de preparación en el futuro. Una vez que el futuro esté en estado listo, llama a xrSetGoogleCloudAuthCompleteANDROID para recuperar el resultado.

El parámetro authInfo debe ser un puntero a un struct cuyo miembro XrGoogleCloudAuthInfoBaseHeaderANDROID :: type identifique el método de autenticación que se usará y que extienda XrGoogleCloudAuthInfoBaseHeaderANDROID (p.ej., XrGoogleCloudAuthInfoApiKeyANDROID).

Los requisitos, los comportamientos y las condiciones de error específicos (tanto síncronos como asíncronos) para cada método de autenticación se describen en la documentación de sus respectivas estructuras de datos.

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

  • 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 función xrSetGoogleCloudAuthCompleteANDROID se define de la siguiente manera:

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

Descripciones de los parámetros

  • session es la XrSession que se usa para iniciar la operación.
  • future es el XrFutureEXT que se debe completar.
  • completion es un puntero a un XrFutureCompletionEXT que completa el entorno de ejecución.

Códigos de devolución futuros

Valores de XrFutureCompletionEXT :: futureResult:

Listo

  • XR_SUCCESS : Las credenciales se aplicaron correctamente.

Falla

  • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID : Se produjo un error en la autenticación sin clave. La aplicación puede volver a intentarlo más tarde. La aplicación o el desarrollador pueden también verificar ciertas condiciones previas para el éxito (p.ej., en Android, el dispositivo debe tener una instalación actualizada de los Servicios de Google Play y estos servicios deben funcionar correctamente).

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

  • 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

Errores de autenticación de Google Cloud

La enumeración XrGoogleCloudAuthErrorANDROID se define de la siguiente manera:

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;

Los enumeradores tienen los siguientes valores:

Descripción de enum

XR_GOOGLE_CLOUD_AUTH_ERROR_NONE_ANDROID

No se produjo ningún error cuando se invocó una API de Google Cloud.

XR_GOOGLE_CLOUD_AUTH_ERROR_QUOTA_EXCEEDED_ANDROID

Se superó la cuota cuando se invocó una API de Google Cloud.

XR_GOOGLE_CLOUD_AUTH_ERROR_UNREACHABLE_ANDROID

No se pudo acceder a una API de Google Cloud, posiblemente debido a problemas de conectividad de red o disponibilidad del servidor.

XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID

Se produjo un error de autenticación cuando se invocó una API de Google Cloud.

La estructura XrGoogleCloudAuthErrorResultANDROID se define de la siguiente manera:

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras.
  • error es el XrGoogleCloudAuthErrorANDROID que detalla la causa del error de una operación que accede a Google Cloud.

Si una operación falla debido a la autenticación de Google Cloud, esta estructura puede encadenarse a la estructura de resultados operativos para proporcionar más información sobre el error.

Uso válido (implícito)

Ejemplo de código

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

Comandos nuevos

Estructuras nuevas

Enums nuevas

Nuevas constantes de enum

  • XR_ANDROID_GOOGLE_CLOUD_AUTH_EXTENSION_NAME
  • XR_ANDROID_google_cloud_auth_SPEC_VERSION

  • Extiende XrResult :

    • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID
    • XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID

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

Problemas

  • Revisión 1, 18 de diciembre de 2025 (Ben King)

    • Descripción inicial de la extensión.