agent/include/download-agent-interface.h

   1 /*
   2  * Copyright (c) 2012 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the License);
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef _Download_Agent_Interface_H
  18 #define _Download_Agent_Interface_H
  19
  20 #ifndef EXPORT_API
  21 #define EXPORT_API __attribute__((visibility("default")))
  22 #endif
  23
  24 #ifdef __cplusplus
  25 extern "C"
  26 {
  27 #endif
  28
  29 #include "download-agent-defs.h"
  30 #include <stdarg.h>
  31
  32 /**
  33  * @struct user_paused_info_t
  34  * @brief Download Agent will send its state through this structure.
  35  * @see da_paused_info_cb
  36  * @par
  37  *   This is used only by callback /a user_paused_info_t. \n
  38  */
  39 typedef struct {
  40         /// download request id for this notification
  41         int download_id;
  42 } user_paused_info_t;
  43
  44 /**
  45  * @struct user_progress_info_t
  46  * @brief Download Agent will send current downloading file's information through this structure.
  47  * @see da_progress_info_cb
  48  * @par
  49  *   This is used only by callback /a da_progress_info_cb. \n
  50  */
  51 typedef struct {
  52         /// download request id for this updated download information
  53         int download_id;
  54         /// received size of chunked data.
  55         unsigned long int received_size;
  56 } user_progress_info_t;
  57
  58 /**
  59  * @struct user_download_info_t
  60  * @brief Download Agent will send current download's information through this structure.
  61  * @see da_started_info_cb
  62  * @par
  63  *   This is used only by callback /a da_started_info_cb. \n
  64  */
  65 typedef struct {
  66         /// download request id for this updated download information
  67         int download_id;
  68         /// file's mime type from http header.
  69         char *file_type;
  70         /// file size from http header.
  71         unsigned long int file_size;
  72         /// This is temporary file path.
  73         char *tmp_saved_path;
  74         /// This is the file name for showing to user.
  75         char *content_name;
  76         /// etag string value for resume download,
  77         char *etag;
  78 } user_download_info_t;
  79
  80 typedef struct {
  81         /// download request id for this updated download information
  82         int download_id;
  83         /// This has only file name for now.
  84         char *saved_path;
  85         /// etag string value for resume download,
  86         /// This is returned when the download is failed and the etag is received from content server
  87         char *etag;
  88         /// convey error code if necessary, or it is zero.
  89         int err;
  90         /// http status code if necessary, or it is zero.
  91         int http_status;
  92 } user_finished_info_t;
  93
  94 typedef struct {
  95         const char **request_header;
  96         int request_header_count;
  97         const char *install_path;
  98         const char *file_name;
  99         const char *temp_file_path; /* For resume download, the "etag" value should be existed together */
 100         const char *etag; /* For resume download */
 101         void *user_data;
 102 } extension_data_t;
 103
 104 /**
 105  * @typedef da_paused_cb
 106  * @brief Download Agent will call this function to paused its state.
 107  *
 108  * This is user callback function registered on \a da_init. \n
 109  *
 110  * @remarks For the most of time, this state is just informative, so, user doesn't need to do any action back to Download Agent.
 111  *
 112  * @warning Download will be holding until getting user confirmation result through the function.
 113  *
 114  * @param[in]           state           state from Download Agent
 115  * @param[in]           user_param      user parameter which is set with \a DA_FEATURE_USER_DATA
 116  *
 117  * @see da_init
 118  * @see da_client_cb_t
 119  */
 120 typedef void (*da_paused_info_cb) (user_paused_info_t *paused_info, void *user_param);
 121
 122 /**
 123  * @brief Download Agent will call this function to update received size of download-requested file.
 124  *
 125  * This is user callback function registered on \a da_init. \n
 126  * This is informative, so, user doesn't need to do any action back to Download Agent.\n
 127  *
 128  * @param[in]           progress_info           updated downloading information
 129  * @param[in]           user_param      user parameter which is set with \a DA_FEATURE_USER_DATA
 130  *
 131  * @see da_init
 132  * @see da_client_cb_t
 133  */
 134 typedef void (*da_progress_info_cb) (user_progress_info_t *progress_info, void *user_param);
 135
 136 /**
 137  * @brief Download Agent will call this function to update mime type, temp file name, total file sizeand installed path.
 138  *
 139  * This is user callback function registered on \a da_init. \n
 140  * This is informative, so, user doesn't need to do any action back to Download Agent.\n
 141  *
 142  * @param[in]           download_info           updated download information
 143  * @param[in]           user_param      user parameter which is set with \a DA_FEATURE_USER_DATA
 144  *
 145  * @see da_init
 146  * @see da_client_cb_t
 147  */
 148 typedef void (*da_started_info_cb) (user_download_info_t *download_info, void *user_param);
 149
 150 typedef void (*da_finished_info_cb) (user_finished_info_t *finished_info, void *user_param);
 151  /**
 152   * @struct da_client_cb_t
 153   * @brief This structure convey User's callback functions for \a da_init
 154   * @see da_init
 155   */
 156 typedef struct {
 157         /// callback to convey download information
 158         da_started_info_cb update_dl_info_cb;
 159         /// callback to convey downloading information while downloading including received file size
 160         da_progress_info_cb update_progress_info_cb;
 161         /// callback to convey saved path
 162         da_finished_info_cb finished_info_cb;
 163         /// callback to convey etag value
 164         da_paused_info_cb paused_info_cb;
 165 } da_client_cb_t;
 166
 167 /**
 168  * @fn int da_init (da_client_cb_t *da_client_callback)
 169  * @brief This function initiates Download Agent and registers user callback functions.
 170  * @warning This should be called at once when client application is initialized before using other Download Agent APIs
 171  * @warning This function is paired with da_deinit function.
 172  *
 173  * @pre None.
 174  * @post None.
 175  *
 176  * @param[in]   da_client_callback      User callback function structure. The type is struct data pointer.
 177  * @return              DA_RESULT_OK for success, or DA_ERR_XXX for fail. DA_ERR_XXX is defined at download-agent-def.h.
 178  * @remarks             User MUST call this function first rather than any other DA APIs. \n
 179  *                              Please do not call UI code at callback function in direct. \n
 180  *                              It is better that it returns as soon as copying the data of callback functon. \n
 181  * @see da_deinit
 182  * @par Example
 183  * @code
 184  * #include <download-agent-interface.h>
 185  *
 186  * void da_started_info_cb(user_download_info_t *download_info,void *user_param);
 187  * void da_progress_info_cb(user_downloading_info_t *downloading_info,void *user_param);
 188  * void da_finished_cb(user_finished_info_t *complted_info, void *user_param);
 189  * void da_paused_info_cb(user_paused_info_t *paused_info, void *user_param);
 190  *
 191  * int download_initialize()
 192  * {
 193  *      int da_ret;
 194  *      da_client_cb_t da_cb = {0};
 195  *
 196  *      da_cb.update_dl_info_cb = &update_download_info_cb;
 197  *      da_cb.update_progress_info_cb = &progress_info_cb;
 198  *      da_cb.finished_info_cb = &finished_info_cb;
 199  *      da_cb.paused_info_cb = &paused_cb;
 200  *
 201  *      da_ret = da_init (&da_cb, 0);
 202  *      if (da_ret == DA_RESULT_OK) {
 203  *              // printf("successed\n");
 204  *              return true;
 205  *      } else {
 206  *              // printf("failed with error code %d\n", da_ret);
 207  *              return fail;
 208  *      }
 209  * }
 210  * @endcode
 211  */
 212 EXPORT_API int da_init(da_client_cb_t *da_client_callback);
 213
 214  /**
 215  * @fn int da_deinit ()
 216  * @brief This function deinitiates Download Agent.
 217  *
 218  * This function destroys all infomation for client manager.
 219  * When Download Agent is not used any more, please call this function.
 220  * Usually when client application is destructed, this is needed.
 221  *
 222  * @remarks This is paired with da_init. \n
 223  *                      The client Id should be the one from /a da_init(). \n
 224  *                      Otherwise, it cannot excute to deinitialize. \n
 225  *
 226  * @pre da_init() must be called in advance.
 227  * @post None.
 228  *
 229  * @return              DA_RESULT_OK for success, or DA_ERR_XXX for fail. DA_ERR_XXX is defined at download-agent-def.h.
 230  * @see da_init
 231  * @par Example
 232  * @code
 233  * #include <download-agent-interface.h>
 234  *
 235  *
 236  * int download_deinitialize()
 237  * {
 238  *      int da_ret;
 239  *      da_ret = da_deinit();
 240  *      if(da_ret == DA_RESULT_OK) {
 241  *              // printf("successed\n");
 242  *              return true;
 243  *      } else {
 244  *              // printf("failed with error code %d\n", da_ret);
 245  *              return fail;
 246  *      }
 247  * }
 248   @endcode
 249  */
 250 EXPORT_API int da_deinit();
 251
 252  /**
 253  * @fn int da_start_download(const char *url, int *download_id)
 254  * @brief This function starts to download a content on passed URL.
 255  *
 256  * Useful information and result are conveyed through following callbacks.
 257  * @li da_started_info_cb
 258  * @li da_progress_cb
 259  *
 260  * @pre da_init() must be called in advance.
 261  * @post None.
 262  * @remarks
 263   *     Downloaded file is automatically registered to system. (e.g. File DB) \n
 264  *      If there is another file has same name on registering directory, new one's name would have numbering postfix. \n
 265  *      (e.g. abc.mp3 to abc_1.mp3)
 266  *
 267  * @param[in]   url                             url to start download
 268  * @param[out]  download_id             assigned download request id for this URL
 269  * @return              DA_RESULT_OK for success, or DA_ERR_XXX for fail. DA_ERR_XXX is defined at download-agent-def.h.
 270  *
 271  * @see None.
 272  *
 273  * @par Example
 274  * @code
 275  * #include <download-agent-interface.h>
 276  *
 277  * int da_ret;
 278  * int download_id;
 279  * char *url = "http://www.test.com/sample.mp3";
 280  *
 281  * da_ret = da_start_download(url,&download_id);
 282  * if (da_ret == DA_RESULT_OK)
 283  *      printf("download requesting is successed\n");
 284  * else
 285  *      printf("download requesting is failed with error code %d\n", da_ret);
 286  * @endcode
 287  */
 288 EXPORT_API int da_start_download(const char *url, int *download_id);
 289
 290 /**
 291 * @fn int da_start_download_with_extension(const char *url, extension_data_t ext_data, int *download_id)
 292 * @brief This function starts to download a content on passed URL with passed extension.
 293 *
 294 * Useful information and result are conveyed through following callbacks.
 295 * @li da_started_info_cb
 296 * @li da_progress_cb
 297 *
 298 * @pre da_init() must be called in advance.
 299 * @post None.
 300 * @remarks This API operation is  exactly same with da_start_download(), except for input properties.   \n
 301 *
 302 * @param[in]    url     url to start download
 303 * @param[in]    ext_data extension data
 304 * @param[out]   download_id     assigned download request id for this URL
 305 * @return       DA_RESULT_OK for success, or DA_ERR_XXX for fail. DA_ERR_XXX is defined at download-agent-def.h.
 306 *
 307 *
 308 * @par Example
 309 * @code
 310   #include <download-agent-interface.h>
 311
 312         int da_ret;
 313         int download_id;
 314         extension_data_t ext_data = {0,};
 315         const char *url = "https://www.test.com/sample.mp3";
 316         const char *install_path = "/myFiles/music";
 317         const char *my_data = strdup("data");
 318         ext_data.install_path = install_path;
 319         ext_data.user_data = (void *)my_data;
 320
 321         da_ret = da_start_download_with_extension(url, &download_id, &ext_data);
 322         if (da_ret == DA_RESULT_OK)
 323             printf("download requesting is successed\n");
 324         else
 325             printf("download requesting is failed with error code %d\n", da_ret);
 326   @endcode
 327 */
 328 EXPORT_API int da_start_download_with_extension(const char *url,
 329         extension_data_t *ext_data,
 330         int *download_id
 331 );
 332
 333
 334 /**
 335  * @fn int da_cancel_download(int download_id)
 336  * @brief This function cancels a download for passed download_id.
 337  *
 338  * Client can use this function if user wants to cancel already requested download.
 339  *
 340  * @remarks Should check return value. \n
 341  *                      If return value is not DA_RESULT_OK, then previous requested download can be keep downloading.
 342  * @remarks After calling this function, all information for the download_id will be deleted. So, client cannot request anything for the download_id.
 343  *
 344  * @pre There should be exist ongoing or suspended download for download_id.
 345  * @post None.
 346  *
 347  * @param[in]           download_id             download request id
 348  * @return              DA_RESULT_OK for success, or DA_ERR_XXX for fail
 349  *
 350  * @see None.
 351  *
 352  * @par Example
 353  * @code
 354    #include <download-agent-interface.h>
 355
 356    int da_ret;
 357    int download_id;
 358
 359    da_ret = da_cancel_download(download_id);
 360    if(da_ret == DA_RESULT_OK) {
 361                 // printf("download with [%d] is successfully canceled.\n", download_id);
 362    }
 363    else {
 364                 // in this case, downloading with download_id is keep ongoing.
 365                 printf("failed to cancel with error code %d\n", da_ret);
 366    }
 367  @endcode
 368  */
 369 EXPORT_API int da_cancel_download(int download_id);
 370
 371
 372 /**
 373  * @fn int da_suspend_download(int download_id)
 374  * @brief This function suspends downloading for passed download_id.
 375  *
 376  * Client can use this function if user wants to suspend already requested download.
 377  *
 378  * @remarks Should check return value. \n
 379  *                      If return value is not DA_RESULT_OK, then previous requested download can be keep downloading.
 380  * @remarks After calling this function, all information for the download_id will be remained. So, client can request resume for the download_id.
 381  * @remarks Client should cancel or resume for this download_id, or all information for the download_id will be leaved forever.
 382  *
 383  * @pre There should be exist ongoing download for download_id.
 384  * @post None.
 385  *
 386  * @param[in]           download_id             download request id
 387  * @return              DA_RESULT_OK for success, or DA_ERR_XXX for fail
 388  *
 389  * @see da_resume_download()
 390  * @see da_cancel_download()
 391  *
 392  * @par Example
 393  * @code
 394    #include <download-agent-interface.h>
 395
 396    int da_ret;
 397    int download_id;
 398
 399    da_ret = da_suspend_download(download_id);
 400    if(da_ret == DA_RESULT_OK) {
 401                 // printf("download with [%d] is successfully suspended.\n", download_id);
 402    }
 403    else {
 404                 // in this case, downloading with download_id is keep ongoing.
 405                 printf("failed to suspend with error code %d\n", da_ret);
 406    }
 407  @endcode
 408  */
 409 EXPORT_API int da_suspend_download(int download_id);
 410
 411 EXPORT_API int da_suspend_download_without_update(int download_id);
 412 /**
 413  * @fn int da_resume_download(int download_id)
 414  * @brief This function resumes downloading for passed download_id.
 415  *
 416  * Client can use this function if user wants to resume suspended download.
 417  *
 418  * @remarks Should check return value. \n
 419  *                      If return value is not DA_RESULT_OK, then requested download can be not to resume.
 420  *
 421  * @pre There should be exist suspended download for download_id.
 422  * @post None.
 423  *
 424  * @param[in]           download_id             download request id
 425  * @return              DA_RESULT_OK for success, or DA_ERR_XXX for fail
 426  *
 427  * @see da_suspend_download()
 428  *
 429  * @par Example
 430  * @code
 431    #include <download-agent-interface.h>
 432
 433    int da_ret;
 434    int download_id;
 435
 436    da_ret = da_resume_download(download_id);
 437    if(da_ret == DA_RESULT_OK) {
 438                 // printf("download with [%d] is successfully resumed.\n", download_id);
 439    }
 440    else {
 441                 // in this case, downloading with download_id is keep suspended.
 442                 printf("failed to resume with error code %d\n", da_ret);
 443    }
 444  @endcode
 445  */
 446 EXPORT_API int da_resume_download(int download_id);
 447
 448 /**
 449  * @fn int da_is_valid_download_id(int download_id)
 450  * @brief This function return the download id is valid and the download thread is still alive.
 451  *
 452  * Client can use this function if user wants to resume download.
 453  * If the download id is vaild and the download thread is alive, it can resume download with using da_resume_download()
 454  * If the the download thread was already terminated due to restarting the process,
 455  *  it can resume download with using da_start_download_with_extension()
 456  *
 457  *
 458  *
 459  * @remarks Should check return value. \n
 460  *                      If return value is not DA_RESULT_OK, then requested download can be not to resume.
 461  *
 462  * @pre There should be exist suspended download for download_id.
 463  * @post None.
 464  *
 465  * @param[in]           download_id             download request id
 466  * @return              1 for success, or 0 for fail
 467   *
 468   */
 469 EXPORT_API int da_is_valid_download_id(int download_id);
 470
 471 #ifdef __cplusplus
 472 }
 473 #endif
 474
 475 #endif //_Download_Agent_Interface_H
 476
 477