src/agent/include/download-agent-defs.h

   1 /**
   2  * Download Agent
   3  *
   4  * Copyright (c) 2000 - 2012 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Jungki Kwak <jungki.kwak@samsung.com>, Keunsoon Lee <keunsoon.lee@samsung.com>
   7  *
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  *     http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  *
  20  * @file                download-agent-defs.h
  21  * @brief               including types and defines for Download Agent
  22  * @author              Keunsoon Lee(keunsoon.lee@samsung.com)
  23  * @author              Jungki Kwak(jungki.kwak@samsung.com)
  24  */
  25
  26 #ifndef _Download_Agent_Defs_H
  27 #define _Download_Agent_Defs_H
  28
  29 /**
  30  * @{
  31  */
  32 #ifndef DEPRECATED
  33 #define DEPRECATED __attribute__((deprecated))
  34 #endif
  35
  36 /**
  37  * @ingroup Reference
  38  */
  39 typedef int da_handle_t;
  40
  41 /**
  42  * @ingroup Reference
  43  * Max count to download files simultaneously. \n
  44  * Main reason for this restriction is because of Network bandwidth.
  45  */
  46 #define DA_MAX_DOWNLOAD_REQ_AT_ONCE     5
  47
  48 /**
  49  * @ingroup Reference
  50  */
  51 #define DA_RESULT_OK    0
  52
  53 #define DA_TRUE         1
  54 #define DA_FALSE                0
  55 #define DA_NULL                 0
  56 #define DA_INVALID_ID   -1
  57
  58 /**
  59  * @ingroup Reference
  60  * special \c dl_req_id to indicate all \c dl_req_id on current status \n\n
  61  * If client wants to do something (cancel/suspend/resume) for all \c dl_req_id, simply use this. \n
  62  * This sends a command to all downloading threads on current status without any changes on state notification. \n
  63  * That is, it is same with calling each dl_req_id separately.
  64  * @see DA_DOWNLOAD_REQ_ID_FOR_ALL_ITEMS_WITH_UNIFIED_NOTI
  65  */
  66 #define DA_DOWNLOAD_REQ_ID_FOR_ALL_ITEMS -1
  67 /**
  68  * @ingroup Reference
  69  * This is also indicates all \c dl_req_id, but it will not send state notification for each \c dl_req_id. \n
  70  * Instead, DA_STATE_XXX_ALL will be sent.
  71  * @see DA_DOWNLOAD_REQ_ID_FOR_ALL_ITEMS
  72  */
  73 #define DA_DOWNLOAD_REQ_ID_FOR_ALL_ITEMS_WITH_UNIFIED_NOTI -2
  74 /**
  75  * @}
  76  */
  77
  78 /**
  79  * @ingroup Reference
  80  * @addtogroup ExtensionFeatures Extension features
  81  * @{
  82  * @brief Download Agent's extension features using by da_start_download_with_extension()
  83  *
  84  * When calling \a da_start_download_with_extension function, use these defines for property name. \n
  85  *
  86 */
  87 /**
  88  * @fn DA_FEATURE_REQUEST_HEADER
  89  * @brief receiving reqeust header for requesting URL on \a da_start_download_with_extension.
  90  * @remarks
  91  *      property value type for this is 'char**'.
  92  *  value is valid if it has the string array which consist the name of http header field and the value of http header.
  93  *  ex) Cookie: SID=1234
  94  * @see da_start_download_with_extension
  95  */
  96 #define DA_FEATURE_REQUEST_HEADER "request_header"
  97
  98 /**
  99  * @def DA_FEATURE_USER_DATA
 100  * @brief receiving user data for requesting URL on \a da_start_download_with_extension.
 101  * @remarks
 102  *      property value type for this is 'void*'.
 103  * @details
 104  *      Every client callback will convey this value.
 105  * @see da_start_download_with_extension
 106  */
 107 #define DA_FEATURE_USER_DATA    "user_data"
 108
 109 /**
 110  * @def DA_FEATURE_INSTALL_PATH
 111  * @brief Downloaded file will be installed on designated path.
 112  * @remarks
 113  *      property value type for this is 'char*'.
 114  * @warning
 115  *      If the path is invalid, DA_ERR_INVALID_INSTALL_PATH will be returned. \n
 116  *      No file name accepts, but only path does.
 117  * @see da_start_download_with_extension
 118  */
 119 #define DA_FEATURE_INSTALL_PATH "install_path"
 120
 121 /**
 122  * @def DA_FEATURE_FILE_NAME
 123  * @brief Downloaded file will be stored with the designated name.
 124  * @remarks
 125  *      property value type for this is 'char*'.
 126  * @warning
 127  *      No path accepts, but only file name dose. \n\n
 128  *      If the designated file name does not include extension, DA will extract an extension automatically and use it. \n
 129  *      If the designated file name includes extension, DA will use the extension without any check. \n\n
 130  *      <b>It is not guaranteed to play or execute the stored file if client designates wrong extension. </b><br>
 131  *      <b>If you are not confident of extension, DO NOT designate extension, but send just pure file name. </b><br><br>
 132  *      <b>Client MUST check \a saved_path of \a user_download_info_t. </b><br>
 133  *      <b>Because really decided file name can be different from the designated one. </b><br>
 134  *      For example, actual file name can have numbering postfix if another file has same name is exist on storing directory. \n
 135  *      (e.g. abc.mp3 to abc_1.mp3) \n\n
 136  *      This feature is ignored in case of OMA/Midlet download. \n
 137  * @see da_start_download_with_extension
 138  * @see user_download_info_t
 139  */
 140 #define DA_FEATURE_FILE_NAME    "file_name"
 141 /**
 142 *@}
 143 */
 144
 145 /**
 146  * @ingroup Reference
 147  * DA_DOWNLOAD_MANAGING_METHOD_MANUAL means that DA pass chunked packetes and response header data to the client in direct.
 148  * This is only availalbe in case of A link download (HTTP)
 149  * Please refer to sample code (da-test/md-sample.c)
 150  */
 151 typedef enum {
 152         DA_DOWNLOAD_MANAGING_METHOD_AUTO = 0,   // DA handle all download progress including install a content. Support A link(HTTP) / OMA / MIDP download.
 153         DA_DOWNLOAD_MANAGING_METHOD_MANUAL,             // DA pass only chuncked packets, response header data, state and error code to the client. Support only A link (HTTP) download
 154         DA_DOWNLOAD_MANAGING_METHOD_MAX
 155 } da_download_managing_method;
 156
 157 /**
 158  * @warning depricated
 159  */
 160 typedef enum {
 161         DA_INSTALL_FAIL_REASON_OK = 0,                          // install is succeed
 162         DA_INSTALL_FAIL_REASON_INSUFFICIENT_MEMORY,     // There is no sufficient memory on target
 163         DA_INSTALL_FAIL_REASON_USER_CANCELED,           // user canceled installation
 164         DA_INSTALL_FAIL_REASON_MAX
 165 } da_install_fail_reason;
 166
 167
 168 /**
 169  * @ingroup Reference
 170  * Download Agent notifies these states to client with \a da_notify_cb, when it is changed. \n
 171  * Most of these value are informative, except for DA_STATE_WAITING_USER_CONFIRM. \n
 172  * @remark Guarantee that one of following state is the final one.
 173  *      @li DA_STATE_FINISHED
 174  *      @li DA_STATE_CANCELED
 175  *      @li DA_STATE_FAILED
 176  * @see user_notify_info_t
 177  * @see da_notify_cb
 178  * @par
 179         @li For default download
 180         \n DA_STATE_DOWNLOAD_STARTED,
 181         DA_STATE_DOWNLOADING,
 182         DA_STATE_DOWNLOAD_COMPLETE,
 183
 184         @li For cancel, suspend, resume
 185         \n DA_STATE_CANCELED,
 186         DA_STATE_SUSPENDED,
 187         DA_STATE_RESUMED,
 188
 189         @li Last notification for all case
 190         \n DA_STATE_FINISHED,
 191         DA_STATE_FAILED,
 192  */
 193 typedef enum {
 194         DA_STATE_WAITING = 0,
 195         /// Requested download to Web server for designated URL
 196         DA_STATE_DOWNLOAD_STARTED,              //      1
 197         /// Started to receiving HTTP body data
 198         DA_STATE_DOWNLOADING,                   //      2
 199         /// Completed to download from Web server. Not yet registered to system.
 200         DA_STATE_DOWNLOAD_COMPLETE,             //      3
 201         /// Suspended download
 202         DA_STATE_SUSPENDED,                     //      4
 203         /// Suspended all download. Emitted only if receiving DA_DOWNLOAD_REQ_ID_FOR_ALL_ITEMS_WITH_UNIFIED_NOTI.
 204         DA_STATE_SUSPENDED_ALL,         // 5
 205         /// Resumed download which was suspended
 206         DA_STATE_RESUMED,                       //      6
 207         /// Resumed all download. Emitted only if receiving DA_DOWNLOAD_REQ_ID_FOR_ALL_ITEMS_WITH_UNIFIED_NOTI.
 208         DA_STATE_RESUMED_ALL,           // 7
 209         /// Finished all process to download.
 210         DA_STATE_FINISHED,                      //      8
 211         /// Canceled download
 212         DA_STATE_CANCELED,                      //      9
 213         /// Canceled all download. Emitted only if receiving DA_DOWNLOAD_REQ_ID_FOR_ALL_ITEMS_WITH_UNIFIED_NOTI.
 214         DA_STATE_CANCELED_ALL,          // 10
 215         /// Failed to download
 216         DA_STATE_FAILED                 //      11
 217 } da_state;
 218
 219
 220 /**
 221  * @ingroup Reference
 222  * @addtogroup ErrorCodes Error codes
 223  * @{
 224  */
 225
 226 /**
 227  * @{
 228  */
 229 // InputError Input error (-100 ~ -199)
 230 // Client passed wrong parameter
 231 #define DA_ERR_INVALID_ARGUMENT         -100
 232 #define DA_ERR_INVALID_DL_REQ_ID        -101
 233 #define DA_ERR_INVALID_CLIENT           -102
 234 #define DA_ERR_INVALID_DD               -103
 235 #define DA_ERR_INVALID_URL              -104
 236 #define DA_ERR_INVALID_HANDLE           -105
 237 #define DA_ERR_INVALID_INSTALL_PATH     -106
 238 #define DA_ERR_INVALID_MIME_TYPE        -107
 239
 240 // Client passed correct parameter, but Download Agent rejects the request because of internal policy.
 241 #define DA_ERR_MISMATCH_CLIENT_DD       -150
 242 #define DA_ERR_ALREADY_CANCELED         -160
 243 #define DA_ERR_ALREADY_SUSPENDED        -161
 244 #define DA_ERR_ALREADY_RESUMED          -162
 245 #define DA_ERR_CANNOT_SUSPEND           -170
 246 #define DA_ERR_CANNOT_RESUME            -171
 247 #define DA_ERR_WAITING_USER_CONFIRM     -180
 248 #define DA_ERR_WAITING_INSTALL_RESULT   -181
 249 #define DA_ERR_INVALID_STATE            -190
 250 #define DA_ERR_ALREADY_MAX_DOWNLOAD     -191
 251 #define DA_ERR_UNSUPPORTED_PROTOCAL     -192
 252 #define DA_ERR_CLIENT_IS_ALREADY_REGISTERED     -193
 253 /**
 254  * @}
 255  */
 256
 257 /**
 258  * @{
 259  */
 260 // System error (-200 ~ -299)
 261 #define DA_ERR_FAIL_TO_MEMALLOC         -200
 262 #define DA_ERR_FAIL_TO_CREATE_THREAD            -210
 263 #define DA_ERR_FAIL_TO_OBTAIN_MUTEX             -220
 264 #define DA_ERR_FAIL_TO_ACCESS_FILE      -230
 265 #define DA_ERR_DISK_FULL        -240
 266 /**
 267  * @}
 268  */
 269
 270 /**
 271  * @{
 272  */
 273 // Platform error (-300 ~ -399)
 274 #define DA_ERR_FAIL_TO_GET_CONF_VALUE           -300
 275 #define DA_ERR_FAIL_TO_ACCESS_STORAGE   -310
 276 #define DA_ERR_DLOPEN_FAIL              -330
 277 /**
 278  * @}
 279  */
 280
 281 /**
 282  * @{
 283  */
 284 // Network error (-400 ~ -499)
 285 #define DA_ERR_NETWORK_FAIL             -400
 286 #define DA_ERR_UNREACHABLE_SERVER               -410
 287 #define DA_ERR_HTTP_TIMEOUT             -420
 288 #define DA_ERR_SSL_FAIL                 -430
 289 /**
 290  * @}
 291  */
 292
 293 /**
 294  * @{
 295  */
 296 // HTTP error - not conforming with HTTP spec (-500 ~ -599)
 297 #define DA_ERR_MISMATCH_CONTENT_TYPE    -500
 298 #define DA_ERR_MISMATCH_CONTENT_SIZE    -501
 299 #define DA_ERR_SERVER_RESPOND_BUT_SEND_NO_CONTENT       -502
 300 /**
 301  * @}
 302  */
 303
 304
 305 /**
 306  * @{
 307  */
 308 // DRM error - not conforming with DRM spec (-700 ~ -799)
 309 #define DA_ERR_DRM_FAIL                 -700
 310 #define DA_ERR_DRM_FILE_FAIL    -710
 311 /**
 312  * @}
 313  */
 314
 315 /**
 316  * @{
 317  */
 318 // install error (-800 ~ -899)
 319 #define DA_ERR_FAIL_TO_INSTALL_FILE     -800
 320 /**
 321 *@}
 322 */
 323
 324 /**
 325 *@}
 326 */
 327 #endif
 328