التحقّق من توفّر VPS في الموقع الحالي للجهاز

تستخدم واجهة برمجة التطبيقات الجغرافية المكانية مزيجًا من بيانات VPS وبيانات نظام تحديد المواقع العالمي (GPS) لإنشاء أوضاع جيوفضائية عالية الدقة. يمكن استخدام واجهة برمجة التطبيقات في أي مكان يتمكّن فيه الجهاز من تحديد موقعه الجغرافي:

  • وفي المناطق ذات الدقة المنخفضة لنظام تحديد المواقع العالمي (GPS)، مثل المساحات الداخلية والبيئات الحضرية الكثيفة، ستعتمد واجهة برمجة التطبيقات على تغطية VPS لإنشاء أوضاع عالية الدقة.
  • في البيئات الخارجية التي تتضمن عوائق قليلة أو لا تحتوي على أي عوائق علوية، قد تتمكن واجهة برمجة التطبيقات Geospatial API من استخدام بيانات الموقع الجغرافي المتوفرة لنظام تحديد المواقع العالمي (GPS) لإنشاء وضعيات جيوفضائية بدقة عالية.

يمكنك تحديد مدى توفّر VPS في موضع أفقي معيّن قبل بدء جلسة الواقع المعزّز واستخدامه لإنشاء تجارب أكثر تحديدًا، على سبيل المثال، عرض زر "Enter AR" (إدخال زر الواقع المعزّز) فقط عند توفُّر VPS.

تفعيل ARCore API

يجب أن يفعِّل تطبيقك ARCore API للتحقّق من مدى توفُّر VPS.

بعد تفعيل ARCore API، يمكنك التحقّق من مدى توفّر VPS بدون:

التحقّق من مدى توفّر VPS في تطبيقك

ويمكن استخدام واجهة برمجة التطبيقات الجغرافية المكانية في أي مكان يمكن للجهاز فيه تحديد موقعه. إذا كانت تجربة الواقع المعزّز تعتمد على تغطية VPS، يمكنك استخدام ArSession_checkVpsAvailabilityAsync() للحصول على ArVpsAvailabilityFuture، وهي مهمة غير متزامنة تتحقّق من مدى توفّر VPS في موضع أفقي معيّن. بعد الحصول على ArVpsAvailabilityFuture، يمكنك الحصول على نتيجته من خلال إجراء استطلاع رأي أو من خلال معاودة الاتصال.

استطلاع رأي النتيجة

يمكنك استخدام ArFuture_getState() للحصول على حالة ArFuture. هناك ثلاث حالات مختلفة:

يمكنك مواصلة التحقّق من ArFuture_getState() إلى أن تكتمل المهمة.

// Obtain a ArVpsAvailabilityFuture and store it somewhere.
ArVpsAvailabilityFuture* future = NULL;
CHECK(ArSession_checkVpsAvailabilityAsync(ar_session, latitude, longitude,
                                          NULL, NULL, &future) == AR_SUCCESS);

// Poll ArVpsAvailabilityFuture later, for example, in a render loop.
ArFutureState future_state = AR_FUTURE_STATE_PENDING;
ArFuture_getState(ar_session, (ArFuture*)future, &future_state);
if (future_state == AR_FUTURE_STATE_DONE) {
  ArVpsAvailability vps_availability = AR_VPS_AVAILABILITY_UNKNOWN;
  ArVpsAvailabilityFuture_getResult(ar_session, future, &vps_availability);
  switch (vps_availability) {
    case AR_VPS_AVAILABILITY_AVAILABLE:
      // VPS is available at this location.
      break;
    case AR_VPS_AVAILABILITY_UNAVAILABLE:
      // VPS is unavailable at this location.
      break;
    case AR_VPS_AVAILABILITY_ERROR_NETWORK_CONNECTION:
      // The external service could not be reached due to a network connection
      // error.
      break;

      // Handle other error states, e.g.
      // AR_VPS_AVAILABILITY_ERROR_RESOURCE_EXHAUSTED,
      // AR_VPS_AVAILABILITY_ERROR_INTERNAL, ...
  }
  ArFuture_release((ArFuture*)future);
}

احصل على النتيجة من خلال معاودة الاتصال.

يمكنك أيضًا الحصول على نتيجة ArFuture من خلال معاودة الاتصال. استخدِم ArSession_checkVpsAvailabilityAsync() وقدِّم callback. سيتم استدعاء callback في سلسلة التعليمات الرئيسية بعد وقت قصير من تغيير حالة ArFuture إلى AR_FUTURE_STATE_DONE.

void vps_availability_callback(void* context, ArVpsAvailability availability) {
  // Callback is called on the Main thread.

  // Handle the ArVpsAvailability result as shown above.
  // For example, show UI that enables your AR view.

  // It is a best practice to free `context` memory at the end of the callback.
  free(context);
}

void check_availability_with_callback(ArSession* ar_session, double latitude,
                                      double longitude) {
  ArVpsAvailabilityFuture* future = NULL;
  void* context = NULL;
  CHECK(ArSession_checkVpsAvailabilityAsync(
      ar_session, latitude, longitude, context, vps_availability_callback,
      &future) == AR_SUCCESS);
}

إلغاء ArFuture

استخدِم ArFuture_cancel() لمحاولة إلغاء ArFuture. بسبب التوازي مع سلسلة المحادثات، قد لا تنجح محاولة الإلغاء التي تجريها. وتعرض ArFuture_cancel() القيمة 1 إذا نجحت هذه المحاولة، وتعرض 0 خلاف ذلك.

استخدام واجهة برمجة التطبيقات Geospatial API بدون تغطية VPS

يمكن أيضًا استخدام واجهة برمجة التطبيقات Geospatial API في المناطق التي لا تتوفر بها تغطية VPS. في البيئات الخارجية التي لا تحتوي على حواجز علوية أو بدونها، قد يكون نظام تحديد المواقع العالمي (GPS) كافيًا لإنشاء وضعية بدقة عالية.

الخطوات التالية