XR_ANDROID_google_cloud_auth

رشته نام

XR_ANDROID_google_cloud_auth

نوع افزونه

افزونه نمونه

شماره داخلی ثبت‌شده

788

بازبینی

1

وضعیت تصویب

تصویب‌نشده

وابستگی‌های افزونه و نسخه

XR_EXT_future

تاریخ آخرین تغییر

2025-12-18

وضعیت IP

هیچ ادعای مالکیت فکری شناخته‌شده‌ای وجود ندارد.

همیاران

John Ullman،‏ Google
Ben King،‏ Google
Nihav Jain،‏ Google
Jared Finder،‏ Google

نمای کلی

این افزونه با فراهم کردن امکان ارائه اطلاعات کاربری اصالت‌سنجی برای میاناهای برنامه‌سازی کاربردی Google Cloud توسط برنامه، استفاده از افزونه‌های مبتنی بر Google Cloud را ممکن می‌کند. توسعه‌دهنده باید از «کنسول Google Cloud» ( https://console.cloud.google.com/ ) برای ایجاد پروژه Google Cloud برای برنامه استفاده کند. این افزونه به افزونه XR_EXT_future نیاز دارد.

درحین توسعه، برنامه می‌تواند بااستفاده از افزونه XR_EXT_debug_utils مشکلات راه‌اندازی Google Cloud را اشکال‌زدایی کند. اگر برنامه دارای «پیام‌رسان اشکال‌زدایی» باشد و هنگام ارسال درخواست به Google Cloud ازطرف برنامه، خطای بالقوه قابل‌اقدامی در زمان اجرا رخ دهد، زمان اجرا با پیام خطا، فراخوان پیام‌رسان را فراخوانی می‌کند. در این حالت، توسعه‌دهنده باید پیام خطا و همه اسناد دردسترس را بررسی کند و سپس مطمئن شود که برنامه و پروژه Google Cloud به‌درستی برای استفاده از Google Cloud API راه‌اندازی شده‌اند. زمان اجرا باید از نوع پیام XR_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT، شدت XR_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT، و شناسه پیام «GoogleCloudError» استفاده کند.

اصالت‌سنجی

ساختار XrGoogleCloudAuthInfoBaseHeaderANDROID به‌صورت زیر تعریف می‌شود:

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

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.

این ساختار مستقیماً در میانای برنامه‌سازی کاربردی استفاده نمی‌شود اما توسط ساختارهای دیگری که می‌توانند با xrSetGoogleCloudAuthAsyncANDROID برای ارائه اعتبارنامه‌های اصالت‌سنجی استفاده شوند گسترش می‌یابد.

استفاده معتبر (ضمنی)

ساختار XrGoogleCloudAuthInfoApiKeyANDROID به‌صورت زیر تعریف می‌شود:

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

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • ‫apiKey اشاره‌گری به رشته‌ای است که کلید میانای برنامه‌سازی کاربردی را نشان می‌دهد.

وقتی این ساختار به xrSetGoogleCloudAuthAsyncANDROID منتقل می‌شود، عضو apiKey باید یک رشته ASCII غیرخالی بدون فاصله یا نویسه کنترلی باشد، درغیراین‌صورت زمان اجرا باید XR_ERROR_VALIDATION_FAILURE را برگرداند.

apiKey باید شرایط زیر را نیز برآورده کند:

  • این کلید باید کلید میانای برنامه‌سازی کاربردی معتبری باشد که برای پروژه Google Cloud شما تولید شده است.
  • پروژه Google Cloud شما باید Google Cloud API مربوطه را (که توسط افزونه‌های وابسته مشخص شده است) فعال کند.
  • اگر «کلید میانای برنامه‌سازی کاربردی» محدودیت‌هایی دارد، این محدودیت‌ها باید به میاناهای برنامه‌سازی کاربردی Google Cloud مربوطه و برنامه شما اجازه دسترسی بدهند.

درغیراین‌صورت، فراخوانی xrSetGoogleCloudAuthAsyncANDROID موفقیت‌آمیز خواهد بود اما همه فراخوانی‌های توابعی که به مجوز ابری وابسته هستند، طبق آنچه برای خرابی‌های ابری در افزونه‌ای که آن توابع را تعریف می‌کند مستند شده است عمل خواهند کرد. اگر تابعی بتواند خرابی را گزارش کند و برنامه XrGoogleCloudAuthErrorResultANDROID را به پارامتر خروجی آن تابع زنجیر کند، زمان اجرا باید XrGoogleCloudAuthErrorResultANDROID :: error را روی XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID تنظیم کند تا این خطا را نشان دهد.

وقتی کلید میانای برنامه‌سازی کاربردی ازنظر قالب‌بندی اعتبارسنجی شد و توسط زمان اجرا ذخیره شد، عملیات ناهمگام با XR_SUCCESS تکمیل خواهد شد.

استفاده معتبر (ضمنی)

ساختار XrGoogleCloudAuthInfoTokenANDROID به‌صورت زیر تعریف می‌شود:

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

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • authToken اشاره‌گری به رشته‌ای است که نشان‌دهنده کد اصالت‌سنجی است.

وقتی این ساختار به xrSetGoogleCloudAuthAsyncANDROID منتقل می‌شود، عضو authToken باید یک رشته ASCII غیرخالی بدون فاصله یا نویسه کنترلی باشد، درغیراین‌صورت زمان اجرا باید XR_ERROR_VALIDATION_FAILURE را برگرداند. authToken باید شرایط زیر را نیز برآورده کند:

  • این اعتبارنامه باید معتبر و منقضی‌نشده باشد و برای پروژه Google Cloud شما تولید شده باشد.
  • پروژه Google Cloud شما باید Google Cloud API مربوطه را (که توسط افزونه‌های وابسته مشخص شده است) فعال کند.

  • اعتبارنامه باید یکی از موارد زیر باشد:

    • یک کد دسترسی OAuth2 با دامنه‌های مربوطه، که با ورود به سیستم حساب Google با برنامه شما تولید شده است، یا
    • یک توکن JWT امضاشده با ادعاهای مربوطه که توسط «حساب خدمات» از پروژه Google Cloud شما تولید شده است.

الزامات هر مورد توسط افزونه‌های وابسته مشخص می‌شود. درغیراین‌صورت، فراخوانی xrSetGoogleCloudAuthAsyncANDROID موفقیت‌آمیز خواهد بود اما همه فراخوانی‌های توابعی که به مجوز ابری وابسته هستند، طبق آنچه برای خرابی‌های ابری در افزونه‌ای که آن توابع را تعریف می‌کند مستند شده است عمل خواهند کرد. اگر تابعی بتواند خرابی را گزارش کند و برنامه XrGoogleCloudAuthErrorResultANDROID را به پارامتر خروجی آن تابع زنجیر کند، زمان اجرا باید XrGoogleCloudAuthErrorResultANDROID :: error را روی XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID تنظیم کند تا این خطا را نشان دهد.

برنامه باید پیش‌از منقضی شدن کلید قدیمی، کلید جدیدی را ازطریق xrSetGoogleCloudAuthAsyncANDROID به‌طور پیش‌گیرانه ارسال کند. زمان اجرا باید از جدیدترین کد ارسالی برنامه هنگام شروع درخواست شبکه جدید استفاده کند.

پس‌از اینکه قالب‌بندی کد درستی‌سنجی شد و زمان اجرا آن را ذخیره کرد، عملیات ناهمگام با XR_SUCCESS تکمیل خواهد شد.

استفاده معتبر (ضمنی)

ساختار XrGoogleCloudAuthInfoKeylessANDROID به‌صورت زیر تعریف می‌شود:

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

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.

وقتی این ساختار به xrSetGoogleCloudAuthAsyncANDROID منتقل می‌شود، زمان اجرا ممکن است اعتبارنامه‌ها را به‌طور پویا تولید کند (مثلاً در Android، زمان اجرا با «خدمات Google Play» از فرایند برنامه ارتباط برقرار می‌کند). اگر «احراز هویت بدون کلید» به‌درستی راه‌اندازی نشده باشد، زمان اجرا ممکن است XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID را به‌صورت هم‌زمان برگرداند.

عملیات ناهمگام درخواست‌های شبکه لازم را برای واکشی اطلاعات کاربری انجام خواهد داد. نتیجه این عملیات در XrFutureCompletionEXT :: futureResult از xrSetGoogleCloudAuthCompleteANDROID برگردانده خواهد شد. اگر نتیجه آتی XR_SUCCESS باشد، اطلاعات اعتباری «احراز هویت بدون کلید» باموفقیت اعمال شده است. اگر نتیجه آتی XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID باشد، برنامه ممکن است بعداً دوباره امتحان کند.

استفاده معتبر (ضمنی)

تابع xrSetGoogleCloudAuthAsyncANDROID به‌صورت زیر تعریف می‌شود:

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

شرح پارامترها

  • session XrSession است که از اعتبارنامه استفاده خواهد کرد.
  • ‫authInfo اشاره‌گری به یک ساختار است که روش و پارامترهای اصالت‌سنجی را مشخص می‌کند و فیلد XrGoogleCloudAuthInfoBaseHeaderANDROID :: type آن ساختار خاص را نشان می‌دهد.
  • future اشاره‌گری به دسته XrFutureEXT است که در آن آینده ایجادشده برگردانده می‌شود، یا XR_NULL_HANDLE اگر تابع XR_SUCCESS را برنگرداند.

اعتبارنامه‌های مورداستفاده برای اصالت‌سنجی با Google Cloud را تنظیم کنید. این عملیات ناهمگام است. برای بررسی وضعیت آماده بودن در آینده، xrPollFutureEXT را فراخوانی کنید. وقتی آینده در وضعیت آماده قرار گرفت، xrSetGoogleCloudAuthCompleteANDROID را فراخوانی کنید تا نتیجه را بازیابی کنید.

پارامتر authInfo باید اشاره‌گری به ساختاری باشد که عضو XrGoogleCloudAuthInfoBaseHeaderANDROID :: type آن روش اصالت‌سنجی مورداستفاده را شناسایی می‌کند و XrGoogleCloudAuthInfoBaseHeaderANDROID را گسترش می‌دهد (برای مثال XrGoogleCloudAuthInfoApiKeyANDROID ).

الزامات، رفتارها، و شرایط خطای خاص (هم همگام و هم ناهمگام) برای هر روش اصالت‌سنجی در مستندات مربوط به ساختارهای داده مربوطه آن‌ها شرح داده شده است.

استفاده معتبر (ضمنی)

کدهای برگشتی

موفقیت‌آمیز بود

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ناموفق

  • 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

تابع xrSetGoogleCloudAuthCompleteANDROID به‌صورت زیر تعریف می‌شود:

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

شرح پارامترها

  • ‫session همان XrSession است که برای شروع عملیات استفاده می‌شود.
  • future XrFutureEXT برای تکمیل است.
  • ‫completion اشاره‌گری به XrFutureCompletionEXT است که توسط زمان اجرا پر شده است.

کدهای برگشتی آتی

XrFutureCompletionEXT :: futureResult مقدار:

موفقیت‌آمیز بود

  • XR_SUCCESS : اطلاعات کاربری باموفقیت اعمال شد.

ناموفق

  • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID : اصالت‌سنجی بدون کلید ناموفق بود. برنامه می‌تواند بعداً دوباره امتحان کند. همچنین، برنامه یا توسعه‌دهنده ممکن است پیش‌شرط‌های خاصی را برای موفقیت بررسی کند (برای مثال، در Android، دستگاه باید نسخه به‌روز «خدمات Google Play» را نصب کرده باشد و این خدمات باید به‌درستی کار کنند).

استفاده معتبر (ضمنی)

کدهای برگشتی

موفقیت‌آمیز بود

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ناموفق

  • 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

خطاهای اصالت‌سنجی Google Cloud

شمارش XrGoogleCloudAuthErrorANDROID به‌صورت زیر تعریف می‌شود:

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;

مقادیر شمارشی دارای مقادیر زیر هستند:

شرح شمارشی

XR_GOOGLE_CLOUD_AUTH_ERROR_NONE_ANDROID

هنگام فراخوانی Google Cloud API خطایی رخ نداد.

XR_GOOGLE_CLOUD_AUTH_ERROR_QUOTA_EXCEEDED_ANDROID

هنگام فراخوانی Google Cloud API، از سهمیه فراتر رفته‌اید.

XR_GOOGLE_CLOUD_AUTH_ERROR_UNREACHABLE_ANDROID

دسترسی به Google Cloud API ممکن نشد، احتمالاً به‌دلیل مشکلات اتصال شبکه یا دردسترس بودن سرور.

XR_GOOGLE_CLOUD_AUTH_ERROR_ANDROID

هنگام فراخوانی Google Cloud API، خطای اصالت‌سنجی رخ داد.

ساختار XrGoogleCloudAuthErrorResultANDROID به‌صورت زیر تعریف می‌شود:

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

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • error XrGoogleCloudAuthErrorANDROID است که علت خطای عملیات دسترسی به Google Cloud را شرح می‌دهد.

اگر عملیاتی به‌دلیل «اصالت‌سنجی Google Cloud» ناموفق باشد، این ساختار ممکن است به ساختار نتیجه عملیاتی زنجیر شود تا اطلاعات بیشتری درباره خطا ارائه دهد.

استفاده معتبر (ضمنی)

کد نمونه

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

فرمان‌های جدید

سازه‌های جدید

Enums جدید

ثابت‌های شمارشی جدید

  • XR_ANDROID_GOOGLE_CLOUD_AUTH_EXTENSION_NAME
  • XR_ANDROID_google_cloud_auth_SPEC_VERSION

  • درحال گسترش دادن XrResult :

    • XR_ERROR_KEYLESS_AUTH_FAILED_ANDROID
    • XR_ERROR_KEYLESS_AUTH_NOT_SETUP_ANDROID

  • درحال گسترش دادن 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

مشکلات

  • بازبینی ۱، ‎۲۰۲۵-۱۲-۱۸ (بن کینگ)

    • توضیحات اولیه افزونه.