libgpac  0.4.5
Classes | Typedefs | Enumerations | Functions
downloader
utils

File Cache Downloader objects. More...

Classes

struct  GF_URL_Info_Struct
struct  GF_NETIO_Parameter

Typedefs

typedef struct
__DownloadedCacheEntryStruct * 
DownloadedCacheEntry
typedef struct
__CacheReaderStruct * 
GF_CacheReader
typedef struct
__gf_download_manager 
GF_DownloadManager
typedef struct
__gf_download_session 
GF_DownloadSession
typedef struct GF_URL_Info_Struct GF_URL_Info
typedef Bool(* gf_dm_get_usr_pass )(void *usr_cbk, const char *site_url, char *usr_name, char *password)
 callback function for authentication
typedef void(* gf_dm_user_io )(void *usr_cbk, GF_NETIO_Parameter *parameter)
 callback function for data reception and state signaling

Enumerations

enum  {
  GF_NETIO_SETUP = 0, GF_NETIO_CONNECTED, GF_NETIO_GET_METHOD, GF_NETIO_GET_HEADER,
  GF_NETIO_GET_CONTENT, GF_NETIO_WAIT_FOR_REPLY, GF_NETIO_PARSE_HEADER, GF_NETIO_PARSE_REPLY,
  GF_NETIO_DATA_EXCHANGE, GF_NETIO_DATA_TRANSFERED, GF_NETIO_DISCONNECTED, GF_NETIO_STATE_ERROR
}
enum  { GF_NETIO_SESSION_NOT_THREADED = 1, GF_NETIO_SESSION_NOT_CACHED = 1<<1, GF_NETIO_SESSION_PERSISTENT = 1<<2 }

Functions

GF_Err gf_cache_delete_entry (const DownloadedCacheEntry entry)
const char * gf_cache_get_etag_on_server (const DownloadedCacheEntry entry)
GF_Err gf_cache_set_etag_on_disk (const DownloadedCacheEntry entry, const char *eTag)
const char * gf_cache_get_etag_on_disk (const DownloadedCacheEntry entry)
GF_Err gf_cache_set_etag_on_server (const DownloadedCacheEntry entry, const char *eTag)
const char * gf_cache_get_mime_type (const DownloadedCacheEntry entry)
GF_Err gf_cache_set_mime_type (const DownloadedCacheEntry entry, const char *mime_type)
const char * gf_cache_get_url (const DownloadedCacheEntry entry)
const char * gf_cache_get_hash (const DownloadedCacheEntry entry)
Bool gf_cache_can_be_cached (const DownloadedCacheEntry entry)
const char * gf_cache_get_last_modified_on_disk (const DownloadedCacheEntry entry)
const char * gf_cache_get_last_modified_on_server (const DownloadedCacheEntry entry)
GF_Err gf_cache_set_last_modified_on_disk (const DownloadedCacheEntry entry, const char *newLastModified)
GF_Err gf_cache_set_last_modified_on_server (const DownloadedCacheEntry entry, const char *newLastModified)
const char * gf_cache_get_cache_filename (const DownloadedCacheEntry entry)
u32 gf_cache_get_cache_filesize (const DownloadedCacheEntry entry)
GF_Err gf_cache_flush_disk_cache (const DownloadedCacheEntry entry)
GF_Err gf_cache_set_content_length (const DownloadedCacheEntry entry, u32 length)
u32 gf_cache_get_content_length (const DownloadedCacheEntry entry)
GF_Err appendHttpCacheHeaders (const DownloadedCacheEntry entry, char *httpRequest)
 append cache directives to an HTTP GET request
GF_Err gf_cache_delete_all_cached_files (const char *directory)
GF_CacheReader gf_cache_reader_new (const DownloadedCacheEntry entry)
GF_Err gf_cache_reader_del (GF_CacheReader handle)
s64 gf_cache_reader_seek_at (GF_CacheReader reader, u64 seekPosition)
s64 gf_cache_reader_get_position (const GF_CacheReader reader)
s64 gf_cache_reader_get_currentSize (GF_CacheReader reader)
s64 gf_cache_reader_get_full_size (GF_CacheReader reader)
s32 gf_cache_reader_read (GF_CacheReader reader, char *buff, s32 length)
Bool gf_cache_check_if_cache_file_is_corrupted (const DownloadedCacheEntry entry)
void gf_cache_entry_set_delete_files_when_deleted (const DownloadedCacheEntry entry)
Bool gf_cache_entry_is_delete_files_when_deleted (const DownloadedCacheEntry entry)
u32 gf_cache_get_sessions_count_for_cache_entry (const DownloadedCacheEntry entry)
u64 gf_cache_get_start_range (const DownloadedCacheEntry entry)
u64 gf_cache_get_end_range (const DownloadedCacheEntry entry)
GF_Err gf_dm_get_url_info (const char *url, GF_URL_Info *info, const char *baseURL)
void gf_dm_url_info_init (GF_URL_Info *info)
void gf_dm_url_info_del (GF_URL_Info *info)
GF_DownloadManagergf_dm_new (GF_Config *cfg)
 download manager constructor
void gf_dm_del (GF_DownloadManager *dm)
void gf_dm_set_auth_callback (GF_DownloadManager *dm, gf_dm_get_usr_pass get_pass, void *usr_cbk)
 password retrieval assignment
GF_DownloadSessiongf_dm_sess_new (GF_DownloadManager *dm, const char *url, u32 dl_flags, gf_dm_user_io user_io, void *usr_cbk, GF_Err *error)
 download session constructor
GF_DownloadSessiongf_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)
 download session simple constructor
void gf_dm_sess_del (GF_DownloadSession *sess)
void gf_dm_sess_abort (GF_DownloadSession *sess)
 aborts downloading
void gf_dm_sess_set_private (GF_DownloadSession *sess, void *private_data)
 sets private data
void * gf_dm_sess_get_private (GF_DownloadSession *sess)
 gets private data
GF_Err gf_dm_sess_last_error (GF_DownloadSession *sess)
 gets last session error
Bool gf_dm_is_thread_dead (GF_DownloadSession *sess)
 is download manager thread dead?
GF_Err gf_dm_sess_fetch_data (GF_DownloadSession *sess, char *buffer, u32 buffer_size, u32 *read_size)
 fetches data on session
const char * gf_dm_sess_mime_type (GF_DownloadSession *sess)
 get mime type
GF_Err gf_dm_sess_set_range (GF_DownloadSession *sess, u64 start_range, u64 end_range)
 sets session range
const char * gf_dm_sess_get_cache_name (GF_DownloadSession *sess)
 get cache file name
void gf_dm_delete_cached_file_entry (const GF_DownloadManager *dm, const char *url)
 Marks the cache file to be deleted once the file is not used anymore by any session.
void gf_dm_delete_cached_file_entry_session (const GF_DownloadSession *dm, const char *url)
const char * gf_cache_get_cache_filename_range (const GF_DownloadSession *sess, u64 startOffset, u64 endOffset)
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)
 get statistics
GF_Err gf_dm_sess_process (GF_DownloadSession *sess)
 fetch session object
GF_Err gf_dm_sess_process_headers (GF_DownloadSession *sess)
 fetch session object headers
u32 gf_dm_sess_get_status (GF_DownloadSession *sess)
 fetch session status
const char * gf_dm_sess_get_resource_name (GF_DownloadSession *dnload)
 Get session resource url.
const char * gf_dm_sess_get_original_resource_name (GF_DownloadSession *dnload)
 Get session original resource url.
GF_Err gf_dm_wget_with_cache (GF_DownloadManager *dm, const char *url, const char *filename)
 Download a file over the network using a download manager.
GF_Err gf_dm_wget (const char *url, const char *filename)
 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.
GF_Err gf_dm_sess_reset (GF_DownloadSession *sess)
 Reset session.
DownloadedCacheEntry gf_dm_refresh_cache_entry (GF_DownloadSession *sess)
 forces the refresh of a cache entry The entry is still allocated in the session.
Bool gf_dm_sess_can_be_cached_on_disk (const GF_DownloadSession *sess)
GF_Err gf_dm_sess_reassign (GF_DownloadSession *sess, u32 flags, gf_dm_user_io user_io, void *cbk)
GF_Err gf_dm_sess_setup_from_url (GF_DownloadSession *sess, const char *url)
void gf_dm_set_data_rate (GF_DownloadManager *dm, u32 rate_in_byte_per_sec)
u32 gf_dm_get_data_rate (GF_DownloadManager *dm)
GF_Err gf_dm_get_file_memory (const char *url, char **out_data, u32 *out_size, char **out_mime)

Detailed Description

File Downloader objects.

This section documents the file caching tools the GPAC framework.

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).


Typedef Documentation

typedef struct __DownloadedCacheEntryStruct* DownloadedCacheEntry

Handle for Cache Entries. You can use the gf_cache_get_* functions to get the cache properties

typedef struct __gf_download_manager GF_DownloadManager

the download manager object. This is usually not used by GPAC modules

typedef struct __gf_download_session GF_DownloadSession

the download manager session.

typedef Bool(* gf_dm_get_usr_pass)(void *usr_cbk, const char *site_url, char *usr_name, char *password)

The gf_dm_get_usr_pass type is the type for the callback of the gf_dm_set_auth_callback function used for password retrieval

Parameters:
usr_cbkopaque user data
site_urlurl of the site the user and password are requested for
usr_namethe user name for this site. The allocated space for this buffer is 50 bytes.
Note:
this varaibale may already be formatted.
Parameters:
passwordthe password for this site and user. The allocated space for this buffer is 50 bytes.
Returns:
0 if user didn't fill in the information which will result in an authentication failure, 1 otherwise.
typedef void(* gf_dm_user_io)(void *usr_cbk, GF_NETIO_Parameter *parameter)

The gf_dm_user_io type is the type for the data callback function of a download session

Parameters:
usr_cbkopaque user data
parameterthe input/output parameter structure

Enumeration Type Documentation

anonymous enum

downloader session message types

Enumerator:
GF_NETIO_SETUP 

signal that session is setup and waiting for connection request

GF_NETIO_CONNECTED 

signal that session connection is done

GF_NETIO_GET_METHOD 

request a protocol method from the user. Default value is "GET" for HTTP

GF_NETIO_GET_HEADER 

request a header from the user.

GF_NETIO_GET_CONTENT 

requesting content from the user, if any. Content is appended to the request

GF_NETIO_WAIT_FOR_REPLY 

signal that request is sent and waiting for server reply

GF_NETIO_PARSE_HEADER 

signal a header to user.

GF_NETIO_PARSE_REPLY 

signal request reply to user. The reply is always sent after the headers

GF_NETIO_DATA_EXCHANGE 

send data to the user

GF_NETIO_DATA_TRANSFERED 

all data has been transfered

GF_NETIO_DISCONNECTED 

signal that the session has been deconnected

GF_NETIO_STATE_ERROR 

downloader session failed (error code set) or done/destroyed (no error code)

anonymous enum

session download flags

Enumerator:
GF_NETIO_SESSION_NOT_THREADED 

session is not threaded, the user must explicitely fetch the data

GF_NETIO_SESSION_NOT_CACHED 

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.


Function Documentation

Free The DownloadedCacheEntry handle

Parameters:
entryThe entry to delete
Returns:
GF_OK
const char* gf_cache_get_etag_on_server ( const DownloadedCacheEntry  entry)

Get the ETag associated with this cache entry if any

Parameters:
entryThe entry
Returns:
The ETag if any was defined, NULL otherwise
GF_Err gf_cache_set_etag_on_disk ( const DownloadedCacheEntry  entry,
const char *  eTag 
)

Set the eTag in the cache. Data is duplicated, so original string can be freed by caller.

Parameters:
entryThe entry
eTagThe eTag to set
Returns:
GF_OK if entry and eTag are valid, GF_BAD_PARAM otherwise
const char* gf_cache_get_etag_on_disk ( const DownloadedCacheEntry  entry)

Get the ETag associated with this cache entry if any

Parameters:
entryThe entry
Returns:
The ETag if any was defined, NULL otherwise
GF_Err gf_cache_set_etag_on_server ( const DownloadedCacheEntry  entry,
const char *  eTag 
)

Set the eTag in the cache. Data is duplicated, so original string can be freed by caller.

Parameters:
entryThe entry
eTagThe eTag to set
Returns:
GF_OK if entry and eTag are valid, GF_BAD_PARAM otherwise
const char* gf_cache_get_mime_type ( const DownloadedCacheEntry  entry)

Get the Mime-Type associated with this cache entry.

Parameters:
entryThe entry
Returns:
The Mime-Type (never NULL if entry is valid)
GF_Err gf_cache_set_mime_type ( const DownloadedCacheEntry  entry,
const char *  mime_type 
)

Set the Mime-Type in the cache. Data is duplicated, so original string can be freed by caller.

Parameters:
entryThe entry
eTagThe mime-type to set
Returns:
GF_OK if entry and mime-type are valid, GF_BAD_PARAM otherwise
const char* gf_cache_get_url ( const DownloadedCacheEntry  entry)

Get the URL associated with this cache entry.

Parameters:
entryThe entry
Returns:
The Hash key (never NULL if entry is valid)
const char* gf_cache_get_hash ( const DownloadedCacheEntry  entry)

Get the Hash Key associated with this cache entry.

Parameters:
entryThe entry
Returns:
The Hash key (never NULL if entry is valid)

Tells whether a cache entry should be cached safely (no

Parameters:
entryThe entry
Returns:
1 if entry should be cached

Get the Last-Modified information associated with this cache entry.

Parameters:
entryThe entry
Returns:
The Last-Modified header (can be NULL)

Get the Last-Modified information associated with this cache entry.

Parameters:
entryThe entry
Returns:
The Last-Modified header (can be NULL)
GF_Err gf_cache_set_last_modified_on_disk ( const DownloadedCacheEntry  entry,
const char *  newLastModified 
)

Set the Last-Modified header for this cache entry

Parameters:
entryThe entry
newLastModifiedThe new value to set, will be duplicated
Returns:
GF_OK if everything went alright, GF_BAD_PARAM if entry is NULL
GF_Err gf_cache_set_last_modified_on_server ( const DownloadedCacheEntry  entry,
const char *  newLastModified 
)

Set the Last-Modified header for this cache entry

Parameters:
entryThe entry
newLastModifiedThe new value to set, will be duplicated
Returns:
GF_OK if everything went alright, GF_BAD_PARAM if entry is NULL
const char* gf_cache_get_cache_filename ( const DownloadedCacheEntry  entry)

Get the file name of cache associated with this cache entry.

Parameters:
entryThe entry
Returns:
The Cache file (never NULL if entry is valid)

Get the real file size of the cache entry

Parameters:
entryThe entry
Returns:
the file size

Flushes The disk cache for this entry (by persisting the property file

Parameters:
entryThe entry
GF_Err appendHttpCacheHeaders ( const DownloadedCacheEntry  entry,
char *  httpRequest 
)
Parameters:
entryThe entry of cache to use
httpRequestThe HTTP GET request to populate. The request must have been allocated enough to handle the cache arguments
Returns:
GF_OK if everything went fine, GF_BAD_PARAM if parameters are wrong
GF_Err gf_cache_delete_all_cached_files ( const char *  directory)

Delete all cached files in given directory starting with startpattern

Parameters:
directoryto clean up
Returns:
GF_OK if everything went fine
GF_Err gf_dm_get_url_info ( const char *  url,
GF_URL_Info info,
const char *  baseURL 
)

Extracts the information from an URL. A call to gf_dm_url_info_init() must have been issue before calling this method.

Parameters:
urlThe URL to fill
infoThis structure will be initialized properly and filled with the data
baseURLThe baseURL to use if any (can be null)
Returns:
GF_OK if URL is well formed and supported by GPAC
void gf_dm_url_info_init ( GF_URL_Info info)

Init the GF_URL_Info structure before it can be used

Parameters:
infoThe structure to initialize
void gf_dm_url_info_del ( GF_URL_Info info)

Frees the inner structures of a GF_URL_Info_Struct

Parameters:
infoThe info to free
GF_DownloadManager* gf_dm_new ( GF_Config *  cfg)

Creates a new download manager object.

Parameters:
cfgoptional 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.
Returns:
the download manager object
void gf_dm_set_auth_callback ( GF_DownloadManager dm,
gf_dm_get_usr_pass  get_pass,
void *  usr_cbk 
)

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.

Parameters:
dmthe download manager object
get_passgf_dm_get_usr_pass callback function for user and password retrieval.
usr_cbkopaque user data passed to callback function
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 
)

Creates a new download session

Parameters:
dmthe download manager object
urlfile to retrieve (no PUT/POST yet, only downloading is supported)
dl_flagscombination of session download flags
user_iogf_dm_user_io callback function for data reception and service messages
usr_cbkopaque user data passed to callback function
errorerror for failure cases
Returns:
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 
)

Creates a new download session

Parameters:
urlfile to retrieve (no PUT/POST yet, only downloading is supported)
dl_flagscombination of session download flags
user_iogf_dm_user_io callback function for data reception and service messages
usr_cbkopaque user data passed to callback function
cache_namecache name
errorerror for failure cases
Returns:
the session object or NULL if error. If no error is indicated and a NULL session is returned, this means the file is local

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")

Parameters:
sessthe download session

Aborts all operations in the session, regardless of its state. The session cannot be reused once this is called.

Parameters:
sessthe download session
void gf_dm_sess_set_private ( GF_DownloadSession sess,
void *  private_data 
)

associate private data with the session.

Parameters:
sessthe download session
private_datathe private data
Warning:
the private_data parameter is reserved for bandwidth statistics per service when used in the GPAC terminal.

Gets private data associated with the session.

Parameters:
sessthe download session
Returns:
the private data
Warning:
the private_data parameter is reserved for bandwidth statistics per service when used in the GPAC terminal.

Gets the last error that occured in the session

Parameters:
sessthe download session
Returns:
the last error

Indicates whether the thread has ended

Parameters:
sessthe download session
GF_Err gf_dm_sess_fetch_data ( GF_DownloadSession sess,
char *  buffer,
u32  buffer_size,
u32 *  read_size 
)

Fetches data from the server. This will also performs connections and all needed exchange with server.

Parameters:
sessthe download session
bufferdestination buffer
buffer_sizedestination buffer allocated size
read_sizeamount of data actually fetched
Note:
this can only be used when the session is not threaded
const char* gf_dm_sess_mime_type ( GF_DownloadSession sess)

Fetches the mime type of the URL this session is fetching

Parameters:
sessthe download session
Returns:
the mime type of the URL, or NULL if error. You should get the error with gf_dm_sess_last_error
GF_Err gf_dm_sess_set_range ( GF_DownloadSession sess,
u64  start_range,
u64  end_range 
)

Sets the session byte range. This shll be called before processing the session.

Parameters:
sessthe download session
start_rangeHTTP download start range in byte
end_rangeHTTP download end range in byte
Note:
this can only be used when the session is not threaded

Gets the cache file name for the session.

Parameters:
sessthe download session
Returns:
the absolute path of the cache file, or NULL if the session is not cached
void gf_dm_delete_cached_file_entry ( const GF_DownloadManager dm,
const char *  url 
)
Parameters:
entryThe cache entry to delete
void gf_dm_delete_cached_file_entry_session ( const GF_DownloadSession dm,
const char *  url 
)

Convenience function

See also:
gf_dm_delete_cached_file_entry
const char* gf_cache_get_cache_filename_range ( const GF_DownloadSession sess,
u64  startOffset,
u64  endOffset 
)

Get a range of a cache entry file

Parameters:
entryThe session
startOffsetThe first byte of the request to get
endOffsetThe last byte of request to get
Returns:
The temporary name for the file created to have a range of the file
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 
)

Gets download statistics for the session. All output parameters are optional and may be set to NULL.

Parameters:
sessthe download session
serverthe remote server address
paththe path on the remote server
total_sizethe total size in bytes the file fetched, 0 if unknown.
bytes_donethe amount of bytes received from the server
bytes_per_secthe average data rate in bytes per seconds
net_statusthe session status

Fetch the session object (process all headers and data transfer). This is only usable if the session is not threaded

Parameters:
sessthe download session
Returns:
the last error in the session or 0 if none

Fetch the session object headers and stops after that. This is only usable if the session is not threaded

Parameters:
sessthe download session
Returns:
the last error in the session or 0 if none

Fetch the session current status

Parameters:
sessthe download session
Returns:
the session status

Returns the original resource URL associated with the session

Parameters:
sessthe download session
Returns:
the associated URL

Returns the original resource URL before any redirection associated with the session

Parameters:
sessthe download session
Returns:
the associated URL
GF_Err gf_dm_wget_with_cache ( GF_DownloadManager dm,
const char *  url,
const char *  filename 
)
Parameters:
dmThe downlaod manager to use, function will use all associated cache ressources
urlThe url to download
filenameThe filename to download
Returns:
GF_OK if everything went fine, an error otherwise
GF_Err gf_dm_wget ( const char *  url,
const char *  filename 
)
Parameters:
urlThe url to download
filenameThe filename to download
Returns:
GF_OK if everything went fine, an error otherwise

Resets the session for new processing of the same url

Parameters:
sessthe download session
Returns:
error code if any
Parameters:
sessThe session
Returns:
a pointer to the entry of session refreshed

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

Parameters:
sessThe session
Returns:
True if a cache can be created
GF_Err gf_dm_sess_reassign ( GF_DownloadSession sess,
u32  flags,
gf_dm_user_io  user_io,
void *  cbk 
)

Reassigns session flags and callbacks. This is only possible if the session is not threaded.

Parameters:
sessThe session
flagsThe new flags for the session
user_ioThe new callback function
cbkThe new user data to ba used in the callback function
Returns:
GF_OK or error
GF_Err gf_dm_sess_setup_from_url ( GF_DownloadSession sess,
const char *  url 
)

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 flag set. This is only possible if the session is not threaded.

Parameters:
sessThe session
urlThe new url for the session
Returns:
GF_OK or error