Add iOS background downloading harness to Context (#1447)

Context allows to inform iOS network implementation
that the app is going to switch background-foreground.
And it allows to store background session completion
handlers.

Relates-To: OLPEDGE-2847

Signed-off-by: Rustam Gamidov <[email protected]>

Author: rustam-gamidov-here

olp-cpp-sdk-core/CMakeLists.txt

@@ -293,6 +293,12 @@ set(OLP_SDK_HTTP_SOURCES
     ./src/http/NetworkUtils.cpp
 )
 
+set(OLP_SDK_PLATFORM_SOURCES
+    ./src/context/Context.cpp
+    ./src/context/ContextInternal.cpp
+    ./src/context/ContextInternal.h
+)
+
 if (ANDROID)
     # http network Android implementation:
     set(OLP_SDK_HTTP_ANDROID_SOURCES
@@ -314,6 +320,8 @@ endif()
 
 if (IOS)
     set(OLP_SDK_HTTP_SOURCES ${OLP_SDK_HTTP_SOURCES} ${OLP_SDK_HTTP_IOS_SOURCES})
+    set(OLP_SDK_PLATFORM_HEADERS ${OLP_SDK_PLATFORM_HEADERS} ${OLP_SDK_PLATFORM_IOS_HEADERS})
+    set(OLP_SDK_PLATFORM_SOURCES ${OLP_SDK_PLATFORM_SOURCES} ${OLP_SDK_PLATFORM_IOS_SOURCES})
 
     set(OLP_SDK_DEFAULT_NETWORK_DEFINITION OLP_SDK_NETWORK_HAS_IOS)
 endif()
@@ -328,10 +336,6 @@ if (WIN32)
     endif()
 endif()
 
-set(OLP_SDK_PLATFORM_SOURCES
-    ./src/context/Context.cpp
-)
-
 set(OLP_SDK_UTILS_SOURCES
     ./src/utils/Base64.cpp
     ./src/utils/BoostExceptionHandle.cpp

olp-cpp-sdk-core/cmake/ios.cmake

@@ -28,7 +28,16 @@ if(IOS)
         "${CMAKE_CURRENT_LIST_DIR}/../src/http/ios/OLPHttpClient.h"
     )
 
+    set(OLP_SDK_PLATFORM_IOS_HEADERS
+        "${CMAKE_CURRENT_LIST_DIR}/../include/olp/core/context/EnterBackgroundSubscriber.h"
+    )
+    set(OLP_SDK_PLATFORM_IOS_SOURCES
+        "${CMAKE_CURRENT_LIST_DIR}/../src/context/ios/ContextInternal.mm"
+    )
+
     add_definitions(-DOLP_SDK_NETWORK_HAS_IOS)
 else()
+    set(OLP_SDK_PLATFORM_IOS_HEADERS)
+    set(OLP_SDK_PLATFORM_IOS_SOURCES)
     set(OLP_SDK_HTTP_IOS_SOURCES)
 endif()

olp-cpp-sdk-core/include/olp/core/context/Context.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2019-2021 HERE Europe B.V.
+ * Copyright (C) 2019-2023 HERE Europe B.V.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -170,7 +170,39 @@ class CORE_API Context {
    * @return The `android.content.Context` instance.
    */
   static jobject getAndroidContext();
-#endif
+#elif defined(__APPLE__)
+  /**
+   * @brief Inform subscribers to enter background mode.
+   *
+   * @note Use it only after you initialize the `Context` class.
+   */
+  static void EnterBackground();
+
+  /**
+   * @brief Inform subscribers to exit background mode.
+   *
+   * @note Use it only after you initialize the `Context` class.
+   */
+  static void ExitBackground();
+
+  /**
+   * @brief Store background sessions completion handler to call it
+   * when the session is done. Received from the OS by the application delegate.
+   * See iOS downloading files in the background documentation for more details.
+   *
+   * @param session_name Name of the background session to store completion
+   * handler for.
+   * @param completion_handler A completion handler recieved from iOS
+   * by the application delegate to be called when the background activity
+   * related to a session is done.
+   *
+   * @note Use it only after you initialize the `Context` class.
+   */
+  static void StoreBackgroundSessionCompletionHandler(
+      const std::string& session_name,
+      std::function<void(void)> completion_handler);
+
+#endif  // __APPLE__
 };
 
 }  // namespace context

olp-cpp-sdk-core/include/olp/core/context/EnterBackgroundSubscriber.h

@@ -0,0 +1,43 @@
+/*
+ * Copyright (C) 2023 HERE Europe B.V.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ * License-Filename: LICENSE
+ */
+
+#pragma once
+
+namespace olp {
+namespace context {
+
+/**
+ * @brief Used only for the iOS environment to be informed that the application
+ * is entering or exiting background.
+ */
+class EnterBackgroundSubscriber {
+ public:
+  /**
+   * @brief Called when `Context` is entering background mode.
+   */
+  virtual void OnEnterBackground() = 0;
+
+  /**
+   * @brief Called when `Context` is exiting background mode.
+   */
+  virtual void OnExitBackground() = 0;
+};
+
+}  // namespace context
+}  // namespace olp

olp-cpp-sdk-core/src/context/Context.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2019 HERE Europe B.V.
+ * Copyright (C) 2019-2023 HERE Europe B.V.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -33,51 +33,30 @@
 #include <jni.h>
 #endif
 
+#include "ContextInternal.h"
+
 namespace {
 std::atomic_flag gDeInitializing = ATOMIC_FLAG_INIT;
 }
 
 namespace olp {
 namespace context {
-// Because of static initializer orders, we need to have this on the heap.
-struct ContextData {
-  std::vector<olp::context::Context::InitializedCallback> initVector;
-  std::vector<olp::context::Context::DeinitializedCallback> deinitVector;
-
-  std::mutex contextMutex;
-  size_t contextInstanceCounter = 0;
-#ifdef ANDROID
-  JavaVM* javaVM = nullptr;
-  jobject context = nullptr;
-#endif
-};
-
-#define LOGTAG "Context"
-
-std::shared_ptr<ContextData> instance() {
-  // Static initialization is thread safe.
-  // Shared pointer allows to extend the life of ContextData
-  // until all Scope objects are destroyed.
-  static std::shared_ptr<ContextData> gSetupVectors =
-      std::make_shared<ContextData>();
-  return gSetupVectors;
-}
 
 void initialize() {
-  const auto data = instance();
+  const auto data = Instance();
 
   // Fire all initializations.
-  for (const olp::context::Context::InitializedCallback& cb : data->initVector)
+  for (const olp::context::Context::InitializedCallback& cb : data->init_vector)
     cb();
 }
 
 void deinitialize() {
   if (!atomic_flag_test_and_set(&gDeInitializing)) {
-    const auto data = instance();
+    const auto data = Instance();
 
     // Fire all deinitializeds.
     for (const olp::context::Context::DeinitializedCallback& cb :
-         data->deinitVector)
+         data->deinit_vector)
       cb();
 
     atomic_flag_clear(&gDeInitializing);
@@ -86,16 +65,16 @@ void deinitialize() {
 
 void Context::addInitializeCallbacks(InitializedCallback initCallback,
                                      DeinitializedCallback deinitCalback) {
-  auto cd = instance();
+  auto cd = Instance();
 
-  cd->initVector.emplace_back(std::move(initCallback));
-  cd->deinitVector.emplace_back(std::move(deinitCalback));
+  cd->init_vector.emplace_back(std::move(initCallback));
+  cd->deinit_vector.emplace_back(std::move(deinitCalback));
 }
 
 void Context::init() {
-  auto cd = instance();
+  auto cd = Instance();
 #ifdef ANDROID
-  cd->javaVM = nullptr;
+  cd->java_vm = nullptr;
 #else
   (void)cd;
 #endif
@@ -104,16 +83,16 @@ void Context::init() {
 
 void Context::deinit() {
 #ifdef ANDROID
-  auto cd = instance();
+  auto cd = Instance();
   // Release the global reference of Context.
   // Technically not needed if we took the application context,
   // but good to release just in case.
-  if (cd->javaVM) {
+  if (cd->java_vm) {
     JNIEnv* env = nullptr;
     bool attached = false;
-    if (cd->javaVM->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION_1_6) !=
+    if (cd->java_vm->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION_1_6) !=
         JNI_OK) {
-      if (cd->javaVM->AttachCurrentThread(&env, nullptr) != JNI_OK) {
+      if (cd->java_vm->AttachCurrentThread(&env, nullptr) != JNI_OK) {
         env = nullptr;
       } else {
         attached = true;
@@ -122,20 +101,20 @@ void Context::deinit() {
     if (env) {
       env->DeleteGlobalRef(cd->context);
       if (attached) {
-        cd->javaVM->DetachCurrentThread();
+        cd->java_vm->DetachCurrentThread();
       }
     }
   }
 
-  cd->javaVM = nullptr;
+  cd->java_vm = nullptr;
 #endif
   deinitialize();
 }
 
 #if defined(ANDROID)
 void Context::init(JavaVM* vm, jobject context) {
-  auto cd = instance();
-  cd->javaVM = vm;
+  auto cd = Instance();
+  cd->java_vm = vm;
 
   JNIEnv* env = nullptr;
   if (vm->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION_1_6) != JNI_OK) {
@@ -148,46 +127,84 @@ void Context::init(JavaVM* vm, jobject context) {
 }
 
 JavaVM* Context::getJavaVM() {
-  auto cd = instance();
-  if (!cd->javaVM) {
+  auto cd = Instance();
+  if (!cd->java_vm) {
     assert(false);
   }
 
-  return cd->javaVM;
+  return cd->java_vm;
 }
 
 jobject Context::getAndroidContext() {
-  auto cd = instance();
+  auto cd = Instance();
   if (!cd->context) {
     assert(false);
   }
   return cd->context;
 }
-#endif
+#elif defined(__APPLE__)
+void Context::EnterBackground() {
+  auto cd = Instance();
+  std::lock_guard<std::mutex> lock(cd->context_mutex);
+
+  auto& clients = cd->enter_background_subscibers;
+  std::for_each(clients.begin(), clients.end(),
+                [&](std::weak_ptr<EnterBackgroundSubscriber> weak) {
+                  auto strong = weak.lock();
+                  if (strong) {
+                    strong->OnEnterBackground();
+                  }
+                });
+}
+
+void Context::ExitBackground() {
+  auto cd = Instance();
+  std::lock_guard<std::mutex> lock(cd->context_mutex);
+
+  auto& clients = cd->enter_background_subscibers;
+  std::for_each(clients.begin(), clients.end(),
+                [&](std::weak_ptr<EnterBackgroundSubscriber> weak) {
+                  auto strong = weak.lock();
+                  if (strong) {
+                    strong->OnExitBackground();
+                  }
+                });
+}
+
+void Context::StoreBackgroundSessionCompletionHandler(
+    const std::string& session_name,
+    std::function<void(void)> completion_handler) {
+  auto cd = Instance();
+  std::lock_guard<std::mutex> lock(cd->context_mutex);
+
+  auto& completion_handlers = cd->completion_handlers;
+  completion_handlers.emplace(session_name, std::move(completion_handler));
+}
+#endif  // __APPLE__
 
-Context::Scope::Scope() : m_cd(instance()) {
-  std::lock_guard<std::mutex> lock(m_cd->contextMutex);
-  assert(m_cd->contextInstanceCounter != std::numeric_limits<size_t>::max());
-  if (m_cd->contextInstanceCounter++ == 0) {
+Context::Scope::Scope() : m_cd(Instance()) {
+  std::lock_guard<std::mutex> lock(m_cd->context_mutex);
+  assert(m_cd->context_instance_counter != std::numeric_limits<size_t>::max());
+  if (m_cd->context_instance_counter++ == 0) {
     Context::init();
   }
 }
 #ifdef ANDROID
 /// see Context::init()
-Context::Scope::Scope(JavaVM* vm, jobject application) : m_cd(instance()) {
-  std::lock_guard<std::mutex> lock(m_cd->contextMutex);
-  assert(m_cd->contextInstanceCounter != std::numeric_limits<size_t>::max());
-  if (m_cd->contextInstanceCounter++ == 0) {
+Context::Scope::Scope(JavaVM* vm, jobject application) : m_cd(Instance()) {
+  std::lock_guard<std::mutex> lock(m_cd->context_mutex);
+  assert(m_cd->context_instance_counter != std::numeric_limits<size_t>::max());
+  if (m_cd->context_instance_counter++ == 0) {
     Context::init(vm, application);
   }
 }
 #endif
 
 /// see Context::deinit()
 Context::Scope::~Scope() {
-  std::lock_guard<std::mutex> lock(m_cd->contextMutex);
-  assert(m_cd->contextInstanceCounter != std::numeric_limits<size_t>::min());
-  if (--m_cd->contextInstanceCounter == 0) {
+  std::lock_guard<std::mutex> lock(m_cd->context_mutex);
+  assert(m_cd->context_instance_counter != std::numeric_limits<size_t>::min());
+  if (--m_cd->context_instance_counter == 0) {
     Context::deinit();
   }
 }