Service Adaptor: Working with Plugins

This tutorial demonstrates how you can use adaptors to work with plugins.

This feature is supported in mobile applications only.

Warm-up

Become familiar with the Service Adaptor API basics:

• Initializing the Service Adaptor

  Obtain the Service adaptor handle and initialize the plugins.

• Retrieving the File List

  Get a list of files in the storage.

• Uploading Files

  Upload a file to the storage.

• Downloading Files

  Download a file from the storage

• Removing Files

  Remove a file from the storage

Initializing the Service Adaptor

To use the service adaptor plugins in your application, you must learn to obtain a service adaptor handle and a list of the available plugins:

1. Obtain a service adaptor handle:

   static service_adaptor_h service_adaptor;
   
   void 
   service_adaptor_init()
   {
      int ret = service_adaptor_create(&service_adaptor);
   
      if (SERVICE_ADAPTOR_ERROR_NONE != ret)
      {
         // Error handling
      }
   }
   

2. Use a data structure to store the obtained plugin handles:

   struct 
   plugin_list_item_s
   {
      service_plugin_h plugin;
      struct plugin_list_item_s *next;
   };
   
   typedef struct plugin_list_item_s plugin_list_item_t;
   typedef plugin_list_item_t plugin_list_t;
   typedef plugin_list_item_t* plugin_list_item_h;
   typedef plugin_list_t* plugin_list_h;
   
   extern void 
   plugin_list_item_add(plugin_list_h plugins, plugin_list_item_h plugin_item);
   

3. Obtain a list of available service adaptor plugins:

   static plugin_list_t plugins;
   
   static bool 
   _plugin_iterator_cb(char *plugin_uri, int service_mask, void *user_data)
   {
      plugin_list_item_h plugin_item = (plugin_list_item_h)calloc(1, sizeof(plugin_list_item_t));
   
      // Add plugin to the list
      plugin_list_item_add(&plugins, plugin_item);
   
      // Create plugin handle
      service_adaptor_create_plugin(service_adaptor, plugin_uri, &plugin_item->plugin);
   
      // Set plugin properties
      service_plugin_add_property(plugin_item->plugin, SERVICE_PLUGIN_PROPERTY_APP_KEY, "app_key");
      service_plugin_add_property(plugin_item->plugin, SERVICE_PLUGIN_PROPERTY_APP_SECRET, "app_secret");
   
      // Initialize plugin
      service_plugin_start(plugin_item->plugin, service_mask);
   
      return true;
   }
   
   void 
   plugin_lookup()
   {
      // Iterate over plugin list
      int ret = service_adaptor_foreach_plugin(service_adaptor, _plugin_iterator_cb, &plugins);
   
      if (SERVICE_ADAPTOR_ERROR_NO_DATA == ret)
      {
         // Handle no plugins
      }
      else if (SERVICE_ADAPTOR_ERROR_NONE != ret)
      {
         // Error handling
      }
   }
   

Retrieving the File List

To list the files in the storage, use the obtained plugin handle:

static bool 
_file_iterator_cb(service_storage_file_h file, void *user_data)
{
   char *name = NULL;
   unsigned long long size = 0;
   bool is_dir = false;

   // Fetch basic file info
   service_storage_file_is_dir(file, &is_dir);
   service_storage_file_get_size(file, &size);
   service_storage_file_get_logical_path(file, &name);

   return true;
}

static void 
_service_storage_result_cb(int result, service_storage_file_list_h list, void *user_data)
{
   // Iterate over file list
   service_storage_file_list_foreach_file(list, _file_iterator_cb, NULL);
}

void 
plugin_get_file_list(service_plugin_h plugin)
{
   service_storage_get_file_list(plugin, "/", _service_storage_result_cb, NULL);
}

Uploading Files

To upload a file to the storage:

1. Define callbacks:

   static void 
   task_progress_cb(unsigned long long progress, unsigned long long total, void *user_data)
   {
      // Handle the task progress
   }
   
   static void 
   task_state_cb(service_storage_task_state_e state, void *user_data)
   {
      // Handle task states
      switch (state)
      {
         case SERVICE_STORAGE_TASK_IN_PROGRESS:
            break;
         case SERVICE_STORAGE_TASK_COMPLETED:
            break;
         case SERVICE_STORAGE_TASK_CANCELED:
            break;
         case SERVICE_STORAGE_TASK_FAILED:
            break;
      }
   }

2. Create an upload task:

   static int 
   create_upload_task(service_plugin_h plugin, const char *local_path, const char *storage_path, service_storage_task_h *task)
   {
      return service_storage_create_upload_task(plugin, local_path, storage_path, task);
   }
   
   void 
   plugin_upload_file(service_plugin_h plugin, const char *local_path, const char *storage_path)
   {
      service_storage_task_h task;
   
      // Upload a local file to the storage
      if (SERVICE_ADAPTOR_ERROR_NONE != create_upload_task(plugin, storage_path, local_path, &task))
      {
         // Error handling
   
         return;
      }
   

3. Register callbacks to monitor the upload progress and task state changes:

      // Task progress change callback
      if (SERVICE_ADAPTOR_ERROR_NONE != service_storage_set_task_progress_cb(task, task_progress_cb, NULL))
      {
         // Error handling
   
         return;
      }
   
      // Task state change callback
      if (SERVICE_ADAPTOR_ERROR_NONE != service_storage_set_task_state_changed_cb(task, task_state_cb, NULL))
      {
         // Error handling
   
         return;
      }
   

4. Start the upload task:

      if (SERVICE_ADAPTOR_ERROR_NONE != service_storage_start_task(task))
      {
         // Error handling
   
         return;
      }
   }
   

Downloading Files

To download a file from the storage:

1. Create a download task:

   static int 
   create_download_task(service_plugin_h plugin, const char *storage_path, const char *local_path, service_storage_task_h *task)
   {
      return service_storage_create_download_task(plugin, storage_path, local_path, task);
   }
   
   void 
   plugin_download_file(service_plugin_h plugin, const char *storage_path, const char *local_path)
   {
      service_storage_task_h task;
   
      // Download file from the storage to a local directory
      if (SERVICE_ADAPTOR_ERROR_NONE != create_download_task(plugin, storage_path, local_path, &task))
      {
         // Error handling
   
         return;
      }
   

2. Register callbacks to monitor the download progress and task state changes:

      // Task progress change callback
      if (SERVICE_ADAPTOR_ERROR_NONE != service_storage_set_task_progress_cb(task, task_progress_cb, NULL))
      {
         // Error handling
   
         return;
      }
   
      // Task state change callback
      if (SERVICE_ADAPTOR_ERROR_NONE != service_storage_set_task_state_changed_cb(task, task_state_cb, NULL))
      {
         // Error handling
   
         return;
      }
   

3. Start the download task:

      if (SERVICE_ADAPTOR_ERROR_NONE != service_storage_start_task(task))
      {
         // Error handling
   
         return;
      }
   }
   

Removing Files

To remove a file from the storage, use the service_storage_remove() function:

static void 
file_remove_cb(int result, void *user_data)
{
   if (SERVICE_ADAPTOR_ERROR_NONE != result)
   {
      // Error handling
   }
}

void 
plugin_remove_file(service_plugin_h plugin, const char *file)
{
   const int ret = service_storage_remove(plugin, file, file_remove_cb, NULL);

   if (SERVICE_ADAPTOR_ERROR_NONE == ret)
   {
      // Error handling
   }
}