tstools/DtsEdit/src/gpac/download.h

   1 /*\r
   2  *                      GPAC - Multimedia Framework C SDK\r
   3  *\r
   4  *                      Copyright (c) Jean Le Feuvre 2000-2005 \r
   5  *                                      All rights reserved\r
   6  *\r
   7  *  This file is part of GPAC / common tools sub-project\r
   8  *\r
   9  *  GPAC is free software; you can redistribute it and/or modify\r
  10  *  it under the terms of the GNU Lesser General Public License as published by\r
  11  *  the Free Software Foundation; either version 2, or (at your option)\r
  12  *  any later version.\r
  13  *   \r
  14  *  GPAC is distributed in the hope that it will be useful,\r
  15  *  but WITHOUT ANY WARRANTY; without even the implied warranty of\r
  16  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\r
  17  *  GNU Lesser General Public License for more details.\r
  18  *   \r
  19  *  You should have received a copy of the GNU Lesser General Public\r
  20  *  License along with this library; see the file COPYING.  If not, write to\r
  21  *  the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. \r
  22  *\r
  23  */\r
  24 \r
  25 #ifndef _GF_DOWNLOAD_H_\r
  26 #define _GF_DOWNLOAD_H_\r
  27 \r
  28 /*!\r
  29  *      \file <gpac/download.h>\r
  30  *      \brief Downloader functions.\r
  31  */\r
  32 \r
  33 /*!\r
  34  *      \addtogroup dld_grp downloader\r
  35  *      \ingroup utils_grp\r
  36  *      \brief File Downloader objects\r
  37  *\r
  38  *      This section documents the file downloading tools the GPAC framework. Currently HTTP is supported, HTTPS is under testing but may not be supported\r
  39  *depending on GPAC compilation options (HTTPS in GPAC needs OpenSSL installed on the system).\r
  40  *\r
  41  *      @{\r
  42  */\r
  43 \r
  44 \r
  45 #ifdef __cplusplus\r
  46 extern "C" {\r
  47 #endif\r
  48 \r
  49 #include <gpac/tools.h>\r
  50 #include <gpac/module.h>\r
  51 \r
  52 \r
  53 /*!the download manager object. This is usually not used by GPAC modules*/\r
  54 typedef struct __gf_download_manager GF_DownloadManager;\r
  55 /*!the download manager session.*/\r
  56 typedef struct __gf_download_session GF_DownloadSession;\r
  57 \r
  58 /*!\r
  59  *\brief download manager constructor\r
  60  *\r
  61  *Creates a new download manager object.\r
  62  *\param cfg optional configuration file. Currently the download manager needs a configuration file for cache location and \r
  63  *other options. The cache directory must be indicated in the section "General", key "CacheDirectory" of the configuration\r
  64  *file. If the cache directory is not found, the cache will be disabled but the downloader will still work.\r
  65  *\return the download manager object\r
  66 */\r
  67 GF_DownloadManager *gf_dm_new(GF_Config *cfg);\r
  68 /*\r
  69  *\brief download manager destructor\r
  70  *\r
  71  *Deletes the download manager. All running sessions are aborted\r
  72  *\param dm the download manager object\r
  73  */\r
  74 void gf_dm_del(GF_DownloadManager *dm);\r
  75 \r
  76 /*!\r
  77  *\brief callback function for authentication\r
  78  *\r
  79  * The gf_dm_get_usr_pass type is the type for the callback of the \ref gf_dm_set_auth_callback function used for password retrieval\r
  80  *\param usr_cbk opaque user data\r
  81  *\param site_url url of the site the user and password are requested for\r
  82  *\param usr_name the user name for this site. The allocated space for this buffer is 50 bytes. \note this varaibale may already be formatted.\r
  83  *\param password the password for this site and user. The allocated space for this buffer is 50 bytes.\r
  84  *\return 0 if user didn't fill in the information which will result in an authentication failure, 1 otherwise.\r
  85 */\r
  86 typedef Bool (*gf_dm_get_usr_pass)(void *usr_cbk, const char *site_url, char *usr_name, char *password);\r
  87 \r
  88 /*!\r
  89  *\brief password retrieval assignment\r
  90  *\r
  91  *Assigns the callback function used for user password retrieval. If no such function is assigned to the download manager, \r
  92  *all downloads requiring authentication will fail.\r
  93  *\param dm the download manager object\r
  94  *\param get_pass \ref gf_dm_get_usr_pass callback function for user and password retrieval. \r
  95  *\param usr_cbk opaque user data passed to callback function\r
  96  */\r
  97 void gf_dm_set_auth_callback(GF_DownloadManager *dm, gf_dm_get_usr_pass get_pass, void *usr_cbk);\r
  98 \r
  99 /*!downloader session message types*/\r
 100 enum\r
 101 {\r
 102         /*!signal that session is setup and waiting for connection request*/\r
 103         GF_NETIO_SETUP = 0,\r
 104         /*!signal that session connection is done*/\r
 105         GF_NETIO_CONNECTED,\r
 106         /*!request a protocol method from the user. Default value is "GET" for HTTP*/\r
 107         GF_NETIO_GET_METHOD,\r
 108         /*!request a header from the user. */\r
 109         GF_NETIO_GET_HEADER,\r
 110         /*!requesting content from the user, if any. Content is appended to the request*/\r
 111         GF_NETIO_GET_CONTENT,\r
 112         /*!signal that request is sent and waiting for server reply*/\r
 113         GF_NETIO_WAIT_FOR_REPLY,\r
 114         /*!signal a header to user. */\r
 115         GF_NETIO_PARSE_HEADER,\r
 116         /*!signal request reply to user. The reply is always sent after the headers*/\r
 117         GF_NETIO_PARSE_REPLY,\r
 118         /*!send data to the user*/\r
 119         GF_NETIO_DATA_EXCHANGE,\r
 120         /*!all data has been transfered*/\r
 121         GF_NETIO_DATA_TRANSFERED,\r
 122         /*!signal that the session has been deconnected*/\r
 123         GF_NETIO_DISCONNECTED,\r
 124         /*!downloader session failed (error code set) or done/destroyed (no error code)*/\r
 125         GF_NETIO_STATE_ERROR\r
 126 };\r
 127 \r
 128 /*!session download flags*/\r
 129 enum\r
 130 {\r
 131         /*!session is not threaded, the user must explicitely fetch the data */\r
 132         GF_NETIO_SESSION_NOT_THREADED   =       1,\r
 133         /*!session has no cache: data will be sent to the user if threaded mode (live streams like radios & co)*/\r
 134         GF_NETIO_SESSION_NOT_CACHED     =       1<<1,\r
 135 };\r
 136 \r
 137 \r
 138 /*!protocol I/O parameter*/\r
 139 typedef struct\r
 140 {\r
 141         /*!parameter message type*/\r
 142         u32 msg_type;\r
 143         /*error code if any. Valid for all message types.*/\r
 144         GF_Err error;\r
 145         /*!data received or data to send. Only valid for GF_NETIO_GET_CONTENT and GF_NETIO_DATA_EXCHANGE (when no cache is setup) messages*/\r
 146         char *data;\r
 147         /*!size of associated data. Only valid for GF_NETIO_GET_CONTENT and GF_NETIO_DATA_EXCHANGE messages*/\r
 148         u32 size;\r
 149         /*protocol header. Only valid for GF_NETIO_GET_HEADER, GF_NETIO_PARSE_HEADER and GF_NETIO_GET_METHOD*/\r
 150         char *name;\r
 151         /*protocol header value or server response. Only alid for GF_NETIO_GET_HEADER, GF_NETIO_PARSE_HEADER and GF_NETIO_PARSE_REPLY*/\r
 152         char *value;\r
 153         /*response code - only valid for GF_NETIO_PARSE_REPLY*/\r
 154         u32 reply;\r
 155 } GF_NETIO_Parameter;\r
 156 \r
 157 /*!\r
 158  *\brief callback function for data reception and state signaling\r
 159  *\r
 160  * The gf_dm_user_io type is the type for the data callback function of a download session\r
 161  *\param usr_cbk opaque user data\r
 162  *\param parameter the input/output parameter structure \r
 163 */\r
 164 typedef void (*gf_dm_user_io)(void *usr_cbk, GF_NETIO_Parameter *parameter);\r
 165 \r
 166 \r
 167 \r
 168 /*!\r
 169  *\brief download session constructor\r
 170  *\r
 171  *Creates a new download session\r
 172  *\param dm the download manager object\r
 173  *\param url file to retrieve (no PUT/POST yet, only downloading is supported)\r
 174  *\param dl_flags combination of session download flags\r
 175  *\param user_io \ref gf_dm_user_io callback function for data reception and service messages\r
 176  *\param usr_cbk opaque user data passed to callback function\r
 177  *\param error error for failure cases \r
 178  *\return the session object or NULL if error. If no error is indicated and a NULL session is returned, this means the file is local\r
 179  */\r
 180 GF_DownloadSession * gf_dm_sess_new(GF_DownloadManager *dm, char *url, u32 dl_flags,\r
 181                                                                           gf_dm_user_io user_io,\r
 182                                                                           void *usr_cbk,\r
 183                                                                           GF_Err *error);\r
 184 \r
 185 /*!\r
 186  *brief downloader session destructor\r
 187  *\r
 188  *Deletes the download session, cleaning the cache if indicated in the configuration file of the download manager (section "Downloader", key "CleanCache")\r
 189  *\param sess the download session\r
 190 */\r
 191 void gf_dm_sess_del(GF_DownloadSession * sess);\r
 192 /*!\r
 193  *\brief aborts downloading\r
 194  *\r
 195  *Aborts all operations in the session, regardless of its state. The session cannot be reused once this is called.\r
 196  *\param sess the download session\r
 197  */\r
 198 void gf_dm_sess_abort(GF_DownloadSession * sess);\r
 199 /*!\r
 200  *\brief sets private data\r
 201  *\r
 202  *associate private data with the session.\r
 203  *\param sess the download session\r
 204  *\param private_data the private data\r
 205  *\warning the private_data parameter is reserved for bandwidth statistics per service when used in the GPAC terminal.\r
 206  */\r
 207 void gf_dm_sess_set_private(GF_DownloadSession * sess, void *private_data);\r
 208 \r
 209 /*!\r
 210  *\brief gets private data\r
 211  *\r
 212  *Gets private data associated with the session.\r
 213  *\param sess the download session\r
 214  *\return the private data\r
 215  *\warning the private_data parameter is reserved for bandwidth statistics per service when used in the GPAC terminal.\r
 216  */\r
 217 void *gf_dm_sess_get_private(GF_DownloadSession * sess);\r
 218 /*!\r
 219  *\brief gets last session error \r
 220  *\r
 221  *Gets the last error that occured in the session\r
 222  *\param sess the download session\r
 223  *\return the last error\r
 224  */\r
 225 GF_Err gf_dm_sess_last_error(GF_DownloadSession *sess);\r
 226 \r
 227 /*!\r
 228  *\brief fetches data on session\r
 229  *\r
 230  *Fetches data from the server. This will also performs connections and all needed exchange with server.\r
 231  *\param sess the download session\r
 232  *\param buffer destination buffer\r
 233  *\param buffer_size destination buffer allocated size\r
 234  *\param read_size amount of data actually fetched\r
 235  *\note this can only be used when the session is not threaded\r
 236  */\r
 237 GF_Err gf_dm_sess_fetch_data(GF_DownloadSession * sess, char *buffer, u32 buffer_size, u32 *read_size);\r
 238 \r
 239 /*!\r
 240  *\brief get mime type \r
 241  *\r
 242  *Fetches the mime type of the URL this session is fetching\r
 243  *\param sess the download session\r
 244  *\return the mime type of the URL, or NULL if error. You should get the error with \ref gf_dm_sess_last_error\r
 245  */\r
 246 const char *gf_dm_sess_mime_type(GF_DownloadSession * sess);\r
 247 /*!\r
 248  *\brief get cache file name\r
 249  *\r
 250  *Gets the cache file name for the session.\r
 251  *\param sess the download session\r
 252  *\return the absolute path of the cache file, or NULL if the session is not cached*/\r
 253 const char *gf_dm_sess_get_cache_name(GF_DownloadSession * sess);\r
 254 /*!\r
 255  *\brief get statistics\r
 256  *\r
 257  *Gets download statistics for the session. All output parameters are optional and may be set to NULL.\r
 258  *\param sess the download session\r
 259  *\param server the remote server address\r
 260  *\param path the path on the remote server\r
 261  *\param total_size the total size in bytes the file fetched, 0 if unknown.\r
 262  *\param bytes_done the amount of bytes received from the server\r
 263  *\param bytes_per_sec the average data rate in bytes per seconds\r
 264  *\param net_status the session status\r
 265  */\r
 266 GF_Err gf_dm_sess_get_stats(GF_DownloadSession * sess, const char **server, const char **path, u32 *total_size, u32 *bytes_done, u32 *bytes_per_sec, u32 *net_status);\r
 267 \r
 268 \r
 269 /*! @} */\r
 270 \r
 271 #ifdef __cplusplus\r
 272 }\r
 273 #endif\r
 274 \r
 275 \r
 276 #endif          /*_GF_DOWNLOAD_H_*/\r
 277 \r