2 * Copyright (c) 2012 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 #ifndef _Download_Agent_Interface_H
18 #define _Download_Agent_Interface_H
21 #define EXPORT_API __attribute__((visibility("default")))
29 #include "download-agent-defs.h"
33 * @struct user_paused_info_t
34 * @brief Download Agent will send its state through this structure.
35 * @see da_paused_info_cb
37 * This is used only by callback /a user_paused_info_t. \n
40 /// download request id for this notification
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
49 * This is used only by callback /a da_progress_info_cb. \n
52 /// download request id for this updated download information
54 /// received size of chunked data.
55 unsigned long int received_size;
56 } user_progress_info_t;
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
63 * This is used only by callback /a da_started_info_cb. \n
66 /// download request id for this updated download information
68 /// file's mime type from http header.
70 /// file size from http header.
71 unsigned long int file_size;
72 /// This is temporary file path.
74 /// This is the file name for showing to user.
76 /// etag string value for resume download,
78 } user_download_info_t;
81 /// download request id for this updated download information
83 /// This has only file name for now.
85 /// etag string value for resume download,
86 /// This is returned when the download is failed and the etag is received from content server
88 /// convey error code if necessary, or it is zero.
90 /// http status code if necessary, or it is zero.
92 } user_finished_info_t;
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 */
105 * @typedef da_paused_cb
106 * @brief Download Agent will call this function to paused its state.
108 * This is user callback function registered on \a da_init. \n
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.
112 * @warning Download will be holding until getting user confirmation result through the function.
114 * @param[in] state state from Download Agent
115 * @param[in] user_param user parameter which is set with \a DA_FEATURE_USER_DATA
118 * @see da_client_cb_t
120 typedef void (*da_paused_info_cb) (user_paused_info_t *paused_info, void *user_param);
123 * @brief Download Agent will call this function to update received size of download-requested file.
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
128 * @param[in] progress_info updated downloading information
129 * @param[in] user_param user parameter which is set with \a DA_FEATURE_USER_DATA
132 * @see da_client_cb_t
134 typedef void (*da_progress_info_cb) (user_progress_info_t *progress_info, void *user_param);
137 * @brief Download Agent will call this function to update mime type, temp file name, total file sizeand installed path.
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
142 * @param[in] download_info updated download information
143 * @param[in] user_param user parameter which is set with \a DA_FEATURE_USER_DATA
146 * @see da_client_cb_t
148 typedef void (*da_started_info_cb) (user_download_info_t *download_info, void *user_param);
150 typedef void (*da_finished_info_cb) (user_finished_info_t *finished_info, void *user_param);
152 * @struct da_client_cb_t
153 * @brief This structure convey User's callback functions for \a da_init
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;
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.
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
184 * #include <download-agent-interface.h>
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);
191 * int download_initialize()
194 * da_client_cb_t da_cb = {0};
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;
201 * da_ret = da_init (&da_cb, 0);
202 * if (da_ret == DA_RESULT_OK) {
203 * // printf("successed\n");
206 * // printf("failed with error code %d\n", da_ret);
212 EXPORT_API int da_init(da_client_cb_t *da_client_callback);
215 * @fn int da_deinit ()
216 * @brief This function deinitiates Download Agent.
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.
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
226 * @pre da_init() must be called in advance.
229 * @return DA_RESULT_OK for success, or DA_ERR_XXX for fail. DA_ERR_XXX is defined at download-agent-def.h.
233 * #include <download-agent-interface.h>
236 * int download_deinitialize()
239 * da_ret = da_deinit();
240 * if(da_ret == DA_RESULT_OK) {
241 * // printf("successed\n");
244 * // printf("failed with error code %d\n", da_ret);
250 EXPORT_API int da_deinit();
253 * @fn int da_start_download(const char *url, int *download_id)
254 * @brief This function starts to download a content on passed URL.
256 * Useful information and result are conveyed through following callbacks.
257 * @li da_started_info_cb
260 * @pre da_init() must be called in advance.
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)
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.
275 * #include <download-agent-interface.h>
279 * char *url = "http://www.test.com/sample.mp3";
281 * da_ret = da_start_download(url,&download_id);
282 * if (da_ret == DA_RESULT_OK)
283 * printf("download requesting is successed\n");
285 * printf("download requesting is failed with error code %d\n", da_ret);
288 EXPORT_API int da_start_download(const char *url, int *download_id);
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.
294 * Useful information and result are conveyed through following callbacks.
295 * @li da_started_info_cb
298 * @pre da_init() must be called in advance.
300 * @remarks This API operation is exactly same with da_start_download(), except for input properties. \n
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.
310 #include <download-agent-interface.h>
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;
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");
325 printf("download requesting is failed with error code %d\n", da_ret);
328 EXPORT_API int da_start_download_with_extension(const char *url,
329 extension_data_t *ext_data,
335 * @fn int da_cancel_download(int download_id)
336 * @brief This function cancels a download for passed download_id.
338 * Client can use this function if user wants to cancel already requested download.
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.
344 * @pre There should be exist ongoing or suspended download for download_id.
347 * @param[in] download_id download request id
348 * @return DA_RESULT_OK for success, or DA_ERR_XXX for fail
354 #include <download-agent-interface.h>
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);
364 // in this case, downloading with download_id is keep ongoing.
365 printf("failed to cancel with error code %d\n", da_ret);
369 EXPORT_API int da_cancel_download(int download_id);
373 * @fn int da_suspend_download(int download_id)
374 * @brief This function suspends downloading for passed download_id.
376 * Client can use this function if user wants to suspend already requested download.
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.
383 * @pre There should be exist ongoing download for download_id.
386 * @param[in] download_id download request id
387 * @return DA_RESULT_OK for success, or DA_ERR_XXX for fail
389 * @see da_resume_download()
390 * @see da_cancel_download()
394 #include <download-agent-interface.h>
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);
404 // in this case, downloading with download_id is keep ongoing.
405 printf("failed to suspend with error code %d\n", da_ret);
409 EXPORT_API int da_suspend_download(int download_id);
411 EXPORT_API int da_suspend_download_without_update(int download_id);
413 * @fn int da_resume_download(int download_id)
414 * @brief This function resumes downloading for passed download_id.
416 * Client can use this function if user wants to resume suspended download.
418 * @remarks Should check return value. \n
419 * If return value is not DA_RESULT_OK, then requested download can be not to resume.
421 * @pre There should be exist suspended download for download_id.
424 * @param[in] download_id download request id
425 * @return DA_RESULT_OK for success, or DA_ERR_XXX for fail
427 * @see da_suspend_download()
431 #include <download-agent-interface.h>
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);
441 // in this case, downloading with download_id is keep suspended.
442 printf("failed to resume with error code %d\n", da_ret);
446 EXPORT_API int da_resume_download(int download_id);
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.
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()
459 * @remarks Should check return value. \n
460 * If return value is not DA_RESULT_OK, then requested download can be not to resume.
462 * @pre There should be exist suspended download for download_id.
465 * @param[in] download_id download request id
466 * @return 1 for success, or 0 for fail
469 EXPORT_API int da_is_valid_download_id(int download_id);
475 #endif //_Download_Agent_Interface_H