~ubuntu-branches/debian/experimental/gpac/experimental : contents of include/gpac/download.h at revision 9

~ubuntu-branches/debian/experimental/gpac/experimental : (revision 9)
/*
 *			GPAC - Multimedia Framework C SDK
 *
 *			Authors: Jean Le Feuvre 
 *			Copyright (c) Telecom ParisTech 2000-2012
 *					All rights reserved
 *
 *  This file is part of GPAC / common tools sub-project
 *
 *  GPAC is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU Lesser General Public License as published by
 *  the Free Software Foundation; either version 2, or (at your option)
 *  any later version.
 *
 *  GPAC is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; see the file COPYING.  If not, write to
 *  the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 *
 */

#ifndef _GF_DOWNLOAD_H_
#define _GF_DOWNLOAD_H_

/*!
 *	\file <gpac/download.h>
 *	\brief Downloader functions.
 */

/*!
 *	\addtogroup dld_grp downloader
 *	\ingroup utils_grp
 *	\brief File Downloader objects
 *
 *	This section documents the file downloading tools the GPAC framework. Currently HTTP is supported, HTTPS is under testing but may not be supported
 *depending on GPAC compilation options (HTTPS in GPAC needs OpenSSL installed on the system).
 *
 *	@{
 */


#ifdef __cplusplus
extern "C" {
#endif

#include <gpac/tools.h>
#include <gpac/config_file.h>
#include <gpac/cache.h>


	/*!the download manager object. This is usually not used by GPAC modules*/
    typedef struct __gf_download_manager GF_DownloadManager;
    /*!the download manager session.*/
    typedef struct __gf_download_session GF_DownloadSession;

    typedef struct GF_URL_Info_Struct {
        const char * protocol;
        char * server_name;
        char * remotePath;
        char * canonicalRepresentation;
        char * userName;
        char * password;
        u16 port;
    } GF_URL_Info;

	/*!
     * Extracts the information from an URL. A call to gf_dm_url_info_init() must have been issue before calling this method.
     * \param url The URL to fill
     * \param info This structure will be initialized properly and filled with the data
     * \param baseURL The baseURL to use if any (can be null)
     * \return GF_OK if URL is well formed and supported by GPAC
     */
    GF_Err gf_dm_get_url_info(const char * url, GF_URL_Info * info, const char * baseURL);

    /**
     * Init the GF_URL_Info structure before it can be used
     * \param info The structure to initialize
     */
    void gf_dm_url_info_init(GF_URL_Info * info);

    /*!
     * Frees the inner structures of a GF_URL_Info_Struct
     * \param info The info to free
     */
    void gf_dm_url_info_del(GF_URL_Info * info);

    /*!
     *\brief download manager constructor
     *
     *Creates a new download manager object.
     *\param cfg optional configuration file. Currently the download manager needs a configuration file for cache location and
     *other options. The cache directory must be indicated in the section "General", key "CacheDirectory" of the configuration
     *file. If the cache directory is not found, the cache will be disabled but the downloader will still work.
     *\return the download manager object
    */
    GF_DownloadManager *gf_dm_new(GF_Config *cfg);
    /*
     *\brief download manager destructor
     *
     *Deletes the download manager. All running sessions are aborted
     *\param dm the download manager object
     */
    void gf_dm_del(GF_DownloadManager *dm);

    /*!
     *\brief callback function for authentication
     *
     * 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
     *\param usr_cbk opaque user data
     *\param site_url url of the site the user and password are requested for
     *\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.
     *\param password the password for this site and user. The allocated space for this buffer is 50 bytes.
     *\return 0 if user didn't fill in the information which will result in an authentication failure, 1 otherwise.
    */
    typedef Bool (*gf_dm_get_usr_pass)(void *usr_cbk, const char *site_url, char *usr_name, char *password);

    /*!
     *\brief password retrieval assignment
     *
     *Assigns the callback function used for user password retrieval. If no such function is assigned to the download manager,
     *all downloads requiring authentication will fail.
     *\param dm the download manager object
     *\param get_pass \ref gf_dm_get_usr_pass callback function for user and password retrieval.
     *\param usr_cbk opaque user data passed to callback function
     */
    void gf_dm_set_auth_callback(GF_DownloadManager *dm, gf_dm_get_usr_pass get_pass, void *usr_cbk);

    /*!downloader session message types*/
    typedef enum
    {
        /*!signal that session is setup and waiting for connection request*/
        GF_NETIO_SETUP = 0,
        /*!signal that session connection is done*/
        GF_NETIO_CONNECTED,
        /*!request a protocol method from the user. Default value is "GET" for HTTP*/
        GF_NETIO_GET_METHOD,
        /*!request a header from the user. */
        GF_NETIO_GET_HEADER,
        /*!requesting content from the user, if any. Content is appended to the request*/
        GF_NETIO_GET_CONTENT,
        /*!signal that request is sent and waiting for server reply*/
        GF_NETIO_WAIT_FOR_REPLY,
        /*!signal a header to user. */
        GF_NETIO_PARSE_HEADER,
        /*!signal request reply to user. The reply is always sent after the headers*/
        GF_NETIO_PARSE_REPLY,
        /*!send data to the user*/
        GF_NETIO_DATA_EXCHANGE,
        /*!all data has been transfered*/
        GF_NETIO_DATA_TRANSFERED,
        /*!signal that the session has been deconnected*/
        GF_NETIO_DISCONNECTED,
        /*!downloader session failed (error code set) or done/destroyed (no error code)*/
        GF_NETIO_STATE_ERROR
    } GF_NetIOStatus;

    /*!session download flags*/
    enum
    {
        /*!session is not threaded, the user must explicitely fetch the data , either with the function gf_dm_sess_fetch_data 
		or the function gf_dm_sess_process- if the session is threaded, the user must call gf_dm_sess_process to start the session*/
        GF_NETIO_SESSION_NOT_THREADED	=	1,
        /*! session data is live, e.g. data will be sent to the user if threaded mode (live streams like radios & co)
				Whether the data is cached or not to disk cannot be controlled by the user at the current time.
		*/
        GF_NETIO_SESSION_NOT_CACHED	=	1<<1,
		/*indicates that the connection to the server should be kept once the download is successfully completed*/
        GF_NETIO_SESSION_PERSISTENT =	1<<2,
		/*file is stored in memory, and the cache name is set to gpac://%u@%p, where %d is the size in bytes and %d is the the pointer to the memory.
		Memory cached files are destroyed upon downloader destruction*/
        GF_NETIO_SESSION_MEMORY_CACHE	=	1<<3,
    };


    /*!protocol I/O parameter*/
    typedef struct
    {
        /*!parameter message type*/
        u32 msg_type;
        /*error code if any. Valid for all message types.*/
        GF_Err error;
        /*!data received or data to send. Only valid for GF_NETIO_GET_CONTENT and GF_NETIO_DATA_EXCHANGE (when no cache is setup) messages*/
        const char *data;
        /*!size of associated data. Only valid for GF_NETIO_GET_CONTENT and GF_NETIO_DATA_EXCHANGE messages*/
        u32 size;
        /*protocol header. Only valid for GF_NETIO_GET_HEADER, GF_NETIO_PARSE_HEADER and GF_NETIO_GET_METHOD*/
        const char *name;
        /*protocol header value or server response. Only alid for GF_NETIO_GET_HEADER, GF_NETIO_PARSE_HEADER and GF_NETIO_PARSE_REPLY*/
        char *value;
        /*message-dependend
			for GF_NETIO_PARSE_REPLY, response code
			for GF_NETIO_DATA_EXCHANGE 
				Set to 1 in to indicate end of chunk transfer
				Set to 2 in GF_NETIO_DATA_EXCHANGE to indicate complete file is already received (replay of events from cache)
			for all other, usage is reserved
		*/
        u32 reply;
        /*download session for which the message is being sent*/
		GF_DownloadSession *sess;
    } GF_NETIO_Parameter;

    /*!
     *\brief callback function for data reception and state signaling
     *
     * The gf_dm_user_io type is the type for the data callback function of a download session
     *\param usr_cbk opaque user data
     *\param parameter the input/output parameter structure
    */
    typedef void (*gf_dm_user_io)(void *usr_cbk, GF_NETIO_Parameter *parameter);



    /*!
     *\brief download session constructor
     *
     *Creates a new download session
     *\param dm the download manager object
     *\param url file to retrieve (no PUT/POST yet, only downloading is supported)
     *\param dl_flags combination of session download flags
     *\param user_io \ref gf_dm_user_io callback function for data reception and service messages
     *\param usr_cbk opaque user data passed to callback function
     *\param error error for failure cases
     *\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
     */
    GF_DownloadSession * gf_dm_sess_new(GF_DownloadManager *dm, const char *url, u32 dl_flags,
                                        gf_dm_user_io user_io,
                                        void *usr_cbk,
                                        GF_Err *error);

    /*!
     *\brief download session simple constructor
     *
     *Creates a new download session
     *\param dm The download manager used to create the download session
     *\param url file to retrieve (no PUT/POST yet, only downloading is supported)
     *\param dl_flags combination of session download flags
     *\param user_io \ref gf_dm_user_io callback function for data reception and service messages
     *\param usr_cbk opaque user data passed to callback function
     *\param e error for failure cases
     *\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
     */
    GF_DownloadSession *gf_dm_sess_new_simple(GF_DownloadManager * dm, const char *url, u32 dl_flags,
            gf_dm_user_io user_io,
            void *usr_cbk,
            GF_Err *e);

    /*!
     *brief downloader session destructor
     *
     *Deletes the download session, cleaning the cache if indicated in the configuration file of the download manager (section "Downloader", key "CleanCache")
     *\param sess the download session
    */
    void gf_dm_sess_del(GF_DownloadSession * sess);

	/*!
     *\brief aborts downloading
     *
     *Aborts all operations in the session, regardless of its state. The session cannot be reused once this is called.
     *\param sess the download session
     */
    void gf_dm_sess_abort(GF_DownloadSession * sess);

	/*!
     *\brief sets private data
     *
     *associate private data with the session.
     *\param sess the download session
     *\param private_data the private data
     *\warning the private_data parameter is reserved for bandwidth statistics per service when used in the GPAC terminal.
     */
    void gf_dm_sess_set_private(GF_DownloadSession * sess, void *private_data);

    /*!
     *\brief gets private data
     *
     *Gets private data associated with the session.
     *\param sess the download session
     *\return the private data
     *\warning the private_data parameter is reserved for bandwidth statistics per service when used in the GPAC terminal.
     */
    void *gf_dm_sess_get_private(GF_DownloadSession * sess);

	/*!
     *\brief gets last session error
     *
     *Gets the last error that occured in the session
     *\param sess the download session
     *\return the last error
     */
    GF_Err gf_dm_sess_last_error(GF_DownloadSession *sess);

    /*!
     *\brief is download manager thread dead?
     *
     *Indicates whether the thread has ended
	 *\param sess the download session
     */
	Bool gf_dm_is_thread_dead(GF_DownloadSession *sess);

    /*!
     *\brief fetches data on session
     *
     *Fetches data from the server. This will also performs connections and all needed exchange with server.
     *\param sess the download session
     *\param buffer destination buffer
     *\param buffer_size destination buffer allocated size
     *\param read_size amount of data actually fetched
     *\note this can only be used when the session is not threaded
     */
    GF_Err gf_dm_sess_fetch_data(GF_DownloadSession * sess, char *buffer, u32 buffer_size, u32 *read_size);

    /*!
     *\brief get mime type as lower case
     *
     *Fetches the mime type of the URL this session is fetching, value will be returned lower case, so application/x-mpegURL will be returned as application/x-mpegurl
     *\param sess the download session
     *\return the mime type of the URL, or NULL if error. You should get the error with \ref gf_dm_sess_last_error
     */
    const char *gf_dm_sess_mime_type(GF_DownloadSession * sess);

    /*!
     *\brief sets session range
     *
     *Sets the session byte range. This shll be called before processing the session.
     *\param sess the download session
     *\param start_range HTTP download start range in byte 
     *\param end_range HTTP download end range in byte 
     *\param discontinue_cache If set, forces a new cache entry if byte range are not continuous. Otherwise a single cache entry is used to reconstruct the file
     *\note this can only be used when the session is not threaded
     */
	GF_Err gf_dm_sess_set_range(GF_DownloadSession *sess, u64 start_range, u64 end_range, Bool discontinue_cache);
    /*!
     *\brief get cache file name
     *
     * Gets the cache file name for the session.
     *\param sess the download session
     *\return the absolute path of the cache file, or NULL if the session is not cached*/
    const char *gf_dm_sess_get_cache_name(GF_DownloadSession * sess);

    /*!
     * \brief Marks the cache file to be deleted once the file is not used anymore by any session
     * \param dm the download manager
     * \param url The URL associate to the cache entry to be deleted
     */
    void gf_dm_delete_cached_file_entry(const GF_DownloadManager * dm, const char * url);

    /*!
     * Convenience function
     * \see gf_dm_delete_cached_file_entry
     *\param sess the download session
     * \param url The URL associate to the cache entry to be deleted
     */
    void gf_dm_delete_cached_file_entry_session(const GF_DownloadSession * sess, const char * url);

    /*!
     * Get a range of a cache entry file
     * \param sess The session
     * \param startOffset The first byte of the request to get
     * \param endOffset The last byte of request to get
     * \return The temporary name for the file created to have a range of the file
     */
    const char * gf_cache_get_cache_filename_range( const GF_DownloadSession * sess, u64 startOffset, u64 endOffset );

    /*!
     *\brief get statistics
     *
     *Gets download statistics for the session. All output parameters are optional and may be set to NULL.
     *\param sess the download session
     *\param server the remote server address
     *\param path the path on the remote server
     *\param total_size the total size in bytes the file fetched, 0 if unknown.
     *\param bytes_done the amount of bytes received from the server
     *\param bytes_per_sec the average data rate in bytes per seconds
     *\param net_status the session status
     */
    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, GF_NetIOStatus *net_status);

    /*!
     *\brief get start time
     *
     *Gets session start time in UTC. If chunk-transfer is used, the start time is reset at each chunk start
     *\param sess the download session
     *\return UTC start time
     */
    u64 gf_dm_sess_get_utc_start(GF_DownloadSession *sess);


    /*!
     *\brief fetch session object
     *
     *Fetch the session object (process all headers and data transfer). This is only usable if the session is not threaded
     *\param sess the download session
     *\return the last error in the session or 0 if none*/
    GF_Err gf_dm_sess_process(GF_DownloadSession * sess);

    /*!
     *\brief fetch session object headers
     *
     *Fetch the session object headers and stops after that. This is only usable if the session is not threaded
     *\param sess the download session
     *\return the last error in the session or 0 if none*/
    GF_Err gf_dm_sess_process_headers(GF_DownloadSession * sess);

    /*!
     *\brief fetch session status
     *
     *Fetch the session current status
     *\param sess the download session
     *\return the session status*/
	u32 gf_dm_sess_get_status(GF_DownloadSession * sess);
	/*!
     *\brief Get session resource url
     *
     *Returns the original resource URL associated with the session
     *\param sess the download session
     *\return the associated URL
     */
    const char *gf_dm_sess_get_resource_name(GF_DownloadSession *sess);
    /*!
     *\brief Get session original resource url
     *
     *Returns the original resource URL before any redirection associated with the session
     *\param sess the download session
     *\return the associated URL
     */
    const char *gf_dm_sess_get_original_resource_name(GF_DownloadSession *sess);
	

    /*!
     * \brief Download a file over the network using a download manager
     * \param dm The downlaod manager to use, function will use all associated cache ressources
     * \param url The url to download
     * \param filename The filename to download
     * \param start_range start position of a byte range
     * \param end_range end position of a byte range
     * \return GF_OK if everything went fine, an error otherwise
     */
    GF_Err gf_dm_wget_with_cache(GF_DownloadManager * dm,
                                const char *url, const char *filename, u64 start_range, u64 end_range);

    /*!
     * \brief Same as gf_dm_wget_with_cache, but initializes the GF_DownloadManager by itself.
     * This function is deprecated, please use gf_dm_wget_with_cache instead
     * \param url The url to download
     * \param filename The filename to download
     * \param start_range start position of a byte range
     * \param end_range end position of a byte range
     * \return GF_OK if everything went fine, an error otherwise
     */
    GF_Err gf_dm_wget(const char *url, const char *filename, u64 start_range, u64 end_range);

    /*!
     *\brief Reset session
     *
     *Resets the session for new processing of the same url
     *\param sess the download session
     *\return error code if any
     */
    GF_Err gf_dm_sess_reset(GF_DownloadSession *sess);

    /*!
     * \brief forces the refresh of a cache entry
     * The entry is still allocated in the session.
     * \param sess The session
     * \return a pointer to the entry of session refreshed
     */
    DownloadedCacheEntry gf_dm_refresh_cache_entry(GF_DownloadSession *sess);
    
    /*!
     * Tells whether session can be cached on disk.
     * Typically, when request has no content length, it deserves being streamed an cannot be cached
     * (ICY or MPEG-streamed content
     * \param sess The session
     * \return True if a cache can be created
     */
    Bool gf_dm_sess_can_be_cached_on_disk(const GF_DownloadSession *sess);


    /*!
     * Reassigns session flags and callbacks. This is only possible if the session is not threaded.
	 * \param sess The session
	 * \param flags The new flags for the session - if flags is 0xFFFFFFFF, existing flags are not modified
	 * \param user_io The new callback function
	 * \param cbk The new user data to ba used in the callback function
     * \return GF_OK or error
     */
	GF_Err gf_dm_sess_reassign(GF_DownloadSession *sess, u32 flags, gf_dm_user_io user_io, void *cbk);

    /*!
     * Re-setup an existing, completed session to download a new URL. If same server/port/protocol is used, the same socket will be reused if the session
	 * has the GF_NETIO_SESSION_PERSISTENT flag set. This is only possible if the session is not threaded.
	 * \param sess The session
	 * \param url The new url for the session 
     * \return GF_OK or error
     */
	GF_Err gf_dm_sess_setup_from_url(GF_DownloadSession *sess, const char *url);

    /*
     *\retrieves the HTTP header value for the given name
     *
     *Retrieves the HTTP header value for the given header name.
     *\param sess the current session
     *\param name the target header name
     * \return header value or NULL if not found
	 */
	const char *gf_dm_sess_get_header(GF_DownloadSession *sess, const char *name);

    /*
     *\brief sets download manager max rate per session
     *
     *Sets the maximum rate (per session only at the current time). 
     *\param dm the download manager object
     *\param rate_in_bits_per_sec the new rate in bits per sec. If 0, HTTP rate will not be limited
     */
    void gf_dm_set_data_rate(GF_DownloadManager *dm, u32 rate_in_bits_per_sec);

    /*
     *\brief gets download manager max rate per session
     *
     *Sets the maximum rate (per session only at the current time). 
     *\param dm the download manager object
     *\return the rate in bits per sec. If 0, HTTP rate is not limited
     */
    u32 gf_dm_get_data_rate(GF_DownloadManager *dm);


    /*
     *\brief fetches remote file in memory
     *
     *Fetches remote file in memory . 
     *\param url the data to fetch 
     *\param out_data output data (allocated by function)
     *\param out_size output data size
     *\param out_mime if not NULL, pointer will contain the mime type (allocated by function)
     *\return error code if any
     */
	GF_Err gf_dm_get_file_memory(const char *url, char **out_data, u32 *out_size, char **out_mime);
	/*! @} */

#ifdef __cplusplus
}
#endif


#endif		/*_GF_DOWNLOAD_H_*/
