XR_ANDROID_google_cloud_auth

String de nome

XR_ANDROID_google_cloud_auth

Tipo de extensão

Extensão de instância

Número da extensão registrada

788

Revisão

1

Status de ratificação

Não ratificado

Dependências de extensão e versão

XR_EXT_future

Data da última modificação

2025-12-18

Status do IP

Não há reivindicações de IP conhecidas.

Colaboradores

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

Visão geral

Essa extensão permite o uso de extensões baseadas no Google Cloud, permitindo que o aplicativo forneça credenciais de autenticação para as APIs do Cloud. O desenvolvedor precisa usar o console do Google Cloud ( https://console.cloud.google.com/ ) para criar um projeto na nuvem para o aplicativo. Essa extensão requer a extensão XR_EXT_future .

Durante o desenvolvimento, o aplicativo pode depurar problemas com a configuração do Google Cloud usando a extensão XR_EXT_debug_utils . Se o aplicativo tiver um Debug Messenger e ocorrer um erro potencialmente acionável no tempo de execução ao enviar uma solicitação ao Google Cloud em nome do aplicativo, o tempo de execução vai invocar o callback do messenger com uma mensagem de erro. Nesse caso, o desenvolvedor precisa consultar a mensagem de erro e toda a documentação disponível e garantir que o aplicativo e o projeto do Google Cloud estejam configurados corretamente para usar as APIs do Cloud. O tempo de execução precisa usar o tipo de mensagem XR_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT, a gravidade XR_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT e o messageId "GoogleCloudError".

Autenticação

A estrutura XrGoogleCloudAuthInfoBaseHeaderANDROID é definida da seguinte forma:

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

Descrições de membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.

Essa estrutura não é usada diretamente na API, mas é estendida por outras estruturas que podem ser usadas com xrSetGoogleCloudAuthAsyncANDROID para fornecer credenciais de autenticação.

Uso válido (implícito)

A estrutura XrGoogleCloudAuthInfoApiKeyANDROID é definida como:

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

Descrições de membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • apiKey é um ponteiro para uma string que representa a chave de API.

Quando essa estrutura é transmitida para xrSetGoogleCloudAuthAsyncANDROID , o membro apiKey precisa ser uma string ASCII não vazia sem espaços ou caracteres de controle. Caso contrário, o tempo de execução precisa retornar XR_ERROR_VALIDATION_FAILURE.

apiKey precisa atender às seguintes condições:

  • Ela precisa ser uma chave de API válida gerada para seu projeto na nuvem do Google Cloud.
  • Seu projeto do Google Cloud precisa ativar as APIs do Cloud relevantes (especificadas pelas extensões dependentes).
  • Se a chave de API tiver restrições, elas precisam permitir as APIs do Cloud relevantes do Google Cloud e seu aplicativo.

Caso contrário, a chamada para xrSetGoogleCloudAuthAsyncANDROID será bem-sucedida, mas todas as chamadas para funções que dependem da autorização na nuvem vão agir conforme documentado para falhas na nuvem na extensão que define essas funções. Se uma função puder informar uma falha e o aplicativo encadear XrGoogleCloudAuthErrorResultANDROID ao parâmetro de saída dessa função, o tempo de execução deverá definir XrGoogleCloudAuthErrorResultANDROID :: error como XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID para indicar esse erro.

A operação assíncrona será concluída com XR_SUCCESS assim que a chave de API for validada para formatação e armazenada pelo tempo de execução.

Uso válido (implícito)

A estrutura XrGoogleCloudAuthInfoTokenANDROID é definida como:

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

Descrições de membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • authToken é um ponteiro para uma string que representa o token de autenticação.

Quando essa estrutura é transmitida para xrSetGoogleCloudAuthAsyncANDROID , o membro authToken precisa ser uma string ASCII não vazia sem espaços ou caracteres de controle. Caso contrário, o tempo de execução precisa retornar XR_ERROR_VALIDATION_FAILURE. authToken precisa atender às seguintes condições:

  • Ela precisa ser uma credencial válida e não expirada gerada para seu projeto do Google Cloud.
  • Seu projeto do Google Cloud precisa ativar as APIs do Cloud relevantes (especificadas pelas extensões dependentes).

  • A credencial precisa ser uma das seguintes opções:

    • Um token de acesso OAuth2 com os escopos relevantes, gerado ao fazer login em uma Conta do Google com seu aplicativo, OU
    • Um token JWT assinado com as declarações relevantes, gerado por uma conta de serviço do seu projeto na nuvem do Google.

Os requisitos em cada caso são especificados pelas extensões dependentes. Caso contrário, a chamada para xrSetGoogleCloudAuthAsyncANDROID será bem-sucedida, mas todas as chamadas para funções que dependem da autorização na nuvem vão agir conforme documentado para falhas na nuvem na extensão que define essas funções. Se uma função puder informar uma falha e o aplicativo encadear XrGoogleCloudAuthErrorResultANDROID ao parâmetro de saída dessa função, o tempo de execução deverá definir XrGoogleCloudAuthErrorResultANDROID :: error como XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID para indicar esse erro.

O aplicativo precisa transmitir proativamente um novo token usando xrSetGoogleCloudAuthAsyncANDROID antes que o token antigo expire. O ambiente de execução precisa usar o token mais recente transmitido pelo aplicativo ao iniciar uma nova solicitação de rede.

A operação assíncrona será concluída com XR_SUCCESS assim que o token for validado para formatação e armazenado pelo tempo de execução.

Uso válido (implícito)

A estrutura XrGoogleCloudAuthInfoKeylessANDROID é definida como:

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

Descrições de membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.

Quando essa estrutura é transmitida para xrSetGoogleCloudAuthAsyncANDROID, o tempo de execução pode gerar credenciais dinamicamente (por exemplo, no Android, o tempo de execução se comunica com o Google Play Services no processo do aplicativo). Se a autenticação sem chave não estiver configurada corretamente, o tempo de execução poderá retornar XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID de forma síncrona.

A operação assíncrona vai fazer as solicitações de rede necessárias para buscar as credenciais. O resultado dessa operação será retornado em XrFutureCompletionEXT :: futureResult de xrSetGoogleCloudAuthCompleteANDROID . Se o resultado futuro for XR_SUCCESS , as credenciais de autenticação sem chave foram aplicadas com sucesso. Se o resultado futuro for XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID , o aplicativo poderá tentar novamente mais tarde.

Uso válido (implícito)

A função xrSetGoogleCloudAuthAsyncANDROID é definida como:

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

Descrições dos parâmetros

  • session é a XrSession que vai usar as credenciais.
  • authInfo é um ponteiro para uma struct que especifica o método e os parâmetros de autenticação, com o campo XrGoogleCloudAuthInfoBaseHeaderANDROID :: type indicando a struct específica.
  • future é um ponteiro para um identificador XrFutureEXT em que o futuro criado é retornado ou XR_NULL_HANDLE se a função não retornar XR_SUCCESS .

Defina as credenciais usadas para autenticação com o Google Cloud. Essa operação é assíncrona. Chame xrPollFutureEXT para verificar o estado pronto no futuro. Quando o futuro estiver no estado pronto, chame xrSetGoogleCloudAuthCompleteANDROID para recuperar o resultado.

O parâmetro authInfo precisa ser um ponteiro para uma struct em que o membro XrGoogleCloudAuthInfoBaseHeaderANDROID :: type identifica o método de autenticação a ser usado e que estende XrGoogleCloudAuthInfoBaseHeaderANDROID (por exemplo, XrGoogleCloudAuthInfoApiKeyANDROID).

Os requisitos, comportamentos e condições de erro específicos (síncronos e assíncronos) de cada método de autenticação são descritos na documentação das respectivas estruturas de dados.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • 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

A função xrSetGoogleCloudAuthCompleteANDROID é definida como:

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

Descrições dos parâmetros

  • session é a XrSession usada para iniciar a operação.
  • future é o XrFutureEXT a ser concluído.
  • completion é um ponteiro para um XrFutureCompletionEXT preenchido pelo tempo de execução.

Códigos de retorno futuros

XrFutureCompletionEXT :: valores futureResult:

Sucesso

  • XR_SUCCESS : as credenciais foram aplicadas.

Falha

  • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID : falha na autenticação sem chave. O aplicativo pode tentar novamente mais tarde. O aplicativo ou desenvolvedor também pode verificar algumas pré-condições para o sucesso. Por exemplo, no Android, o dispositivo precisa ter uma instalação atualizada do Google Play Services, e esses serviços precisam estar funcionando corretamente.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • 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

Erros de autenticação do Google Cloud

A enumeração XrGoogleCloudAuthErrorANDROID é definida como:

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;

Os enumeradores têm os seguintes valores:

Descrição da enumeração

XR_GOOGLE_CLOUD_AUTH_ERROR_NONE_ANDROID

Nenhum erro ocorreu ao invocar uma API do Google Cloud.

XR_GOOGLE_CLOUD_AUTH_ERROR_QUOTA_EXCEEDED_ANDROID

A cota foi excedida ao invocar uma API do Google Cloud.

XR_GOOGLE_CLOUD_AUTH_ERROR_UNREACHABLE_ANDROID

Não foi possível acessar uma API do Google Cloud, possivelmente devido a problemas de conectividade de rede ou disponibilidade do servidor.

XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID

Ocorreu um erro de autenticação ao invocar uma API do Google Cloud.

A estrutura XrGoogleCloudAuthErrorResultANDROID é definida como:

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

Descrições de membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • error é o XrGoogleCloudAuthErrorANDROID que detalha a causa do erro de uma operação que acessa o Google Cloud.

Se uma operação falhar devido à autenticação do Google Cloud, essa struct poderá ser encadeada à struct de resultado operacional para fornecer mais informações sobre o erro.

Uso válido (implícito)

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

Novos comandos

Novas estruturas

Novos tipos enumerados

Novas constantes de enumeração

  • XR_ANDROID_GOOGLE_CLOUD_AUTH_EXTENSION_NAME
  • XR_ANDROID_google_cloud_auth_SPEC_VERSION

  • Extensão de XrResult :

    • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID
    • XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID

  • Extensão 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

  • Revisão 1, 18/12/2025 (Ben King)

    • Descrição inicial da extensão.