XR_ANDROID_google_cloud_auth

Cadena de nombre

XR_ANDROID_google_cloud_auth

Tipo de extensión

Extensión de la instancia

Número de extensión registrado

788

Revisión

1

Estado de ratificación

No se ratificó

Dependencias de extensiones y versiones

XR_EXT_future

Fecha de la última modificación

2025-12-18

Estado de la IP

No hay reclamos conocidos por IP.

Colaboradores

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

Descripción general

Esta extensión permite el uso de extensiones basadas en Google Cloud, ya que permite que la aplicación proporcione credenciales de autenticación para las APIs de Cloud de Google. 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 tiempo de ejecución cuando se envía una solicitud a Google Cloud en nombre de la aplicación, el tiempo 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 Cloud. El tiempo 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, sino que se extiende con otras estructuras que se pueden usar con xrSetGoogleCloudAuthAsyncANDROID 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 tiempo 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 Cloud pertinentes (especificadas por las extensiones dependientes).
  • Si la clave de API tiene restricciones, estas deben permitir las APIs de Cloud de Google 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 en la nube se comportarán como se documenta para las fallas en la nube en la extensión que define esas funciones. Si una función puede informar una falla y la aplicación encadena XrGoogleCloudAuthErrorResultANDROID al parámetro de salida de esa función, el tiempo 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 autorizació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 tiempo 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 Cloud pertinentes (especificadas por las extensiones dependientes).

  • La credencial debe ser una de las siguientes:

    • Un token de acceso de OAuth2 con los alcances pertinentes, generado cuando se accede a una Cuenta de Google con tu aplicación
    • Es un token de JWT firmado con los reclamos pertinentes, generado por una cuenta de servicio de tu proyecto de Google Cloud.

Los requisitos en cada caso se especifican en 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 en la nube se comportarán como se documenta para las fallas en la nube en la extensión que define esas funciones. Si una función puede informar una falla y la aplicación encadena XrGoogleCloudAuthErrorResultANDROID al parámetro de salida de esa función, el tiempo 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 caduque el token anterior. El tiempo 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 el tiempo de ejecución valide el formato del token y 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 tiempo de ejecución puede generar credenciales de forma dinámica (p.ej., en Android, el tiempo de ejecución se comunica con los Servicios de Google Play desde el proceso de la aplicación). Si la autenticación sin llave no está configurada correctamente, es posible que el tiempo de ejecución devuelva 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 desde 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 el 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 identificador de 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 la autenticación 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 el estado listo, llama a xrSetGoogleCloudAuthCompleteANDROID para recuperar el resultado.

El parámetro authInfo debe ser un puntero a una estructura cuyo miembro XrGoogleCloudAuthInfoBaseHeaderANDROID :: type identifica el método de autenticación que se usará y que extiende 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 respectivos structs 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 el 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 tiempo de ejecución.

Códigos de devolución futuros

XrFutureCompletionEXT :: Valores de futureResult:

Listo

  • XR_SUCCESS : Las credenciales se aplicaron correctamente.

Falla

  • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID : Falló la autenticación sin llave. La aplicación puede volver a intentarlo más tarde. La aplicación o el desarrollador también pueden 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 enumerantes tienen los siguientes valores:

Descripción de la enumeración

XR_GOOGLE_CLOUD_AUTH_ERROR_NONE_ANDROID

No se produjo ningún error al invocar una API de Google Cloud.

XR_GOOGLE_CLOUD_AUTH_ERROR_QUOTA_EXCEEDED_ANDROID

Se excedió 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 resultado operativo 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

Nuevas estructuras

Nuevas enumeraciones

Nuevas constantes de enumeración

  • XR_ANDROID_GOOGLE_CLOUD_AUTH_EXTENSION_NAME
  • XR_ANDROID_google_cloud_auth_SPEC_VERSION

  • Extensión de XrResult :

    • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID
    • XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID

  • Extensión 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

Problemas

  • Revisión 1, 2025-12-18 (Ben King)

    • Es la descripción inicial de la extensión.