libgpac
Documentation of the core library of GPAC. For more information, check out http://gpac.wp.mines-telecom.fr
|
File Cache Downloader objects. More...
Data Structures | |
struct | GF_URL_Info |
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 Bool(* | gf_dm_get_usr_pass) (void *usr_cbk, const char *site_url, char *usr_name, char *password) |
callback function for authentication More... | |
typedef void(* | gf_dm_user_io) (void *usr_cbk, GF_NETIO_Parameter *parameter) |
callback function for data reception and state signaling More... | |
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).
struct GF_URL_Info |
Data Fields | ||
---|---|---|
const char * | protocol | |
char * | server_name | |
char * | remotePath | |
char * | canonicalRepresentation | |
char * | userName | |
char * | password | |
u16 | port |
struct GF_NETIO_Parameter |
protocol I/O parameter
Data Fields | ||
---|---|---|
GF_NetIOStatus | msg_type |
parameter message type |
GF_Err | error | |
const char * | data |
data received or data to send. Only valid for GF_NETIO_GET_CONTENT and GF_NETIO_DATA_EXCHANGE (when no cache is setup) messages |
u32 | size |
size of associated data. Only valid for GF_NETIO_GET_CONTENT and GF_NETIO_DATA_EXCHANGE messages |
const char * | name | |
char * | value | |
u32 | reply | |
GF_DownloadSession * | sess |
typedef struct __DownloadedCacheEntryStruct* DownloadedCacheEntry |
Handle for Cache Entries. You can use the gf_cache_get_* functions to get the cache properties
typedef struct __CacheReaderStruct* GF_CacheReader |
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
usr_cbk | opaque user data |
site_url | url of the site the user and password are requested for |
usr_name | the user name for this site. The allocated space for this buffer is 50 bytes. |
password | the password for this site and user. The allocated space for this buffer is 50 bytes. |
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
usr_cbk | opaque user data |
parameter | the input/output parameter structure |
enum GF_NetIOStatus |
downloader session message types
enum GF_NetIOFlags |
session download flags
GF_Err gf_cache_delete_entry | ( | const DownloadedCacheEntry | entry | ) |
Free The DownloadedCacheEntry handle
entry | The entry to delete |
const char* gf_cache_get_etag_on_server | ( | const DownloadedCacheEntry | entry | ) |
Get the ETag associated with this cache entry if any
entry | The entry |
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.
entry | The entry |
eTag | The eTag to set |
const char* gf_cache_get_etag_on_disk | ( | const DownloadedCacheEntry | entry | ) |
Get the ETag associated with this cache entry if any
entry | The entry |
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.
entry | The entry |
eTag | The eTag to set |
const char* gf_cache_get_mime_type | ( | const DownloadedCacheEntry | entry | ) |
Get the Mime-Type associated with this cache entry.
entry | The entry |
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.
entry | The entry |
mime_type | The mime-type to set |
const char* gf_cache_get_url | ( | const DownloadedCacheEntry | entry | ) |
Get the URL associated with this cache entry.
entry | The entry |
const char* gf_cache_get_hash | ( | const DownloadedCacheEntry | entry | ) |
Get the Hash Key associated with this cache entry.
entry | The entry |
Bool gf_cache_can_be_cached | ( | const DownloadedCacheEntry | entry | ) |
Tells whether a cache entry should be cached safely (no
entry | The entry |
const char* gf_cache_get_last_modified_on_disk | ( | const DownloadedCacheEntry | entry | ) |
Get the Last-Modified information associated with this cache entry.
entry | The entry |
const char* gf_cache_get_last_modified_on_server | ( | const DownloadedCacheEntry | entry | ) |
Get the Last-Modified information associated with this cache entry.
entry | The entry |
GF_Err gf_cache_set_last_modified_on_disk | ( | const DownloadedCacheEntry | entry, |
const char * | newLastModified | ||
) |
Set the Last-Modified header for this cache entry
entry | The entry |
newLastModified | The new value to set, will be duplicated |
GF_Err gf_cache_set_last_modified_on_server | ( | const DownloadedCacheEntry | entry, |
const char * | newLastModified | ||
) |
Set the Last-Modified header for this cache entry
entry | The entry |
newLastModified | The new value to set, will be duplicated |
const char* gf_cache_get_cache_filename | ( | const DownloadedCacheEntry | entry | ) |
Get the file name of cache associated with this cache entry.
entry | The entry |
u32 gf_cache_get_cache_filesize | ( | const DownloadedCacheEntry | entry | ) |
Get the real file size of the cache entry
entry | The entry |
GF_Err gf_cache_flush_disk_cache | ( | const DownloadedCacheEntry | entry | ) |
Flushes The disk cache for this entry (by persisting the property file
entry | The entry |
GF_Err gf_cache_set_content_length | ( | const DownloadedCacheEntry | entry, |
u32 | length | ||
) |
u32 gf_cache_get_content_length | ( | const DownloadedCacheEntry | entry | ) |
GF_Err gf_cache_append_http_headers | ( | const DownloadedCacheEntry | entry, |
char * | httpRequest | ||
) |
entry | The entry of cache to use |
httpRequest | The HTTP GET request to populate. The request must have been allocated enough to handle the cache arguments |
GF_Err gf_cache_delete_all_cached_files | ( | const char * | directory | ) |
Delete all cached files in given directory starting with startpattern
directory | to clean up |
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 | ) |
Bool gf_cache_are_headers_processed | ( | const DownloadedCacheEntry | entry | ) |
GF_Err gf_cache_set_headers_processed | ( | const DownloadedCacheEntry | entry | ) |
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.
url | The URL to fill |
info | This structure will be initialized properly and filled with the data |
baseURL | The baseURL to use if any (can be null) |
void gf_dm_url_info_init | ( | GF_URL_Info * | info | ) |
Init the GF_URL_Info structure before it can be used
info | The structure to initialize |
void gf_dm_url_info_del | ( | GF_URL_Info * | info | ) |
Frees the inner structures of a GF_URL_Info_Struct
info | The info to free |
GF_DownloadManager* gf_dm_new | ( | GF_Config * | cfg | ) |
Creates a new download manager object.
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. |
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 | ||
) |
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.
dm | the download manager object |
get_pass | gf_dm_get_usr_pass callback function for user and password retrieval. |
usr_cbk | opaque 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
dm | the download manager object |
url | file to retrieve (no PUT/POST yet, only downloading is supported) |
dl_flags | combination of session download flags |
user_io | gf_dm_user_io callback function for data reception and service messages |
usr_cbk | opaque user data passed to callback function |
error | error for failure cases |
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
dm | The download manager used to create the download session |
url | file to retrieve (no PUT/POST yet, only downloading is supported) |
dl_flags | combination of session download flags |
user_io | gf_dm_user_io callback function for data reception and service messages |
usr_cbk | opaque user data passed to callback function |
e | error for failure cases |
void gf_dm_sess_del | ( | GF_DownloadSession * | sess | ) |
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")
sess | the download session |
void gf_dm_sess_abort | ( | GF_DownloadSession * | sess | ) |
Aborts all operations in the session, regardless of its state. The session cannot be reused once this is called.
sess | the download session |
void gf_dm_sess_set_private | ( | GF_DownloadSession * | sess, |
void * | private_data | ||
) |
associate private data with the session.
sess | the download session |
private_data | the private data |
void* gf_dm_sess_get_private | ( | GF_DownloadSession * | sess | ) |
Gets private data associated with the session.
sess | the download session |
GF_Err gf_dm_sess_last_error | ( | GF_DownloadSession * | sess | ) |
Gets the last error that occured in the session
sess | the download session |
Bool gf_dm_is_thread_dead | ( | GF_DownloadSession * | sess | ) |
Indicates whether the thread has ended
sess | the 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.
sess | the download session |
buffer | destination buffer |
buffer_size | destination buffer allocated size |
read_size | amount of data actually fetched |
const char* gf_dm_sess_mime_type | ( | GF_DownloadSession * | sess | ) |
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
sess | the download session |
GF_Err gf_dm_sess_set_range | ( | GF_DownloadSession * | sess, |
u64 | start_range, | ||
u64 | end_range, | ||
Bool | discontinue_cache | ||
) |
Sets the session byte range. This shll be called before processing the session.
sess | the download session |
start_range | HTTP download start range in byte |
end_range | HTTP download end range in byte |
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 |
const char* gf_dm_sess_get_cache_name | ( | GF_DownloadSession * | sess | ) |
Gets the cache file name for the session.
sess | the download session |
void gf_dm_delete_cached_file_entry | ( | const GF_DownloadManager * | dm, |
const char * | url | ||
) |
dm | the download manager |
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 | ||
) |
Convenience function
sess | the download session |
url | The URL associate to the cache entry to be deleted |
const char* gf_cache_get_cache_filename_range | ( | const GF_DownloadSession * | sess, |
u64 | startOffset, | ||
u64 | endOffset | ||
) |
Get a range of a cache entry file
sess | The session |
startOffset | The first byte of the request to get |
endOffset | The last byte of request to get |
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 | ||
) |
Gets download statistics for the session. All output parameters are optional and may be set to NULL.
sess | the download session |
server | the remote server address |
path | the path on the remote server |
total_size | the total size in bytes the file fetched, 0 if unknown. |
bytes_done | the amount of bytes received from the server |
bytes_per_sec | the average data rate in bytes per seconds |
net_status | the session status |
u64 gf_dm_sess_get_utc_start | ( | GF_DownloadSession * | sess | ) |
Gets session start time in UTC. If chunk-transfer is used, the start time is reset at each chunk start
sess | the download session |
GF_Err gf_dm_sess_process | ( | GF_DownloadSession * | sess | ) |
Fetches the session object (process all headers and data transfer). This is only usable if the session is not threaded
sess | the download session |
GF_Err gf_dm_sess_process_headers | ( | GF_DownloadSession * | sess | ) |
Fetch the session object headers and stops after that. This is only usable if the session is not threaded
sess | the download session |
u32 gf_dm_sess_get_status | ( | GF_DownloadSession * | sess | ) |
Fetch the session current status
sess | the download session |
const char* gf_dm_sess_get_resource_name | ( | GF_DownloadSession * | sess | ) |
Returns the original resource URL associated with the session
sess | the download session |
const char* gf_dm_sess_get_original_resource_name | ( | GF_DownloadSession * | sess | ) |
Returns the original resource URL before any redirection associated with the session
sess | the download session |
GF_Err gf_dm_wget_with_cache | ( | GF_DownloadManager * | dm, |
const char * | url, | ||
const char * | filename, | ||
u64 | start_range, | ||
u64 | end_range, | ||
char ** | redirected_url | ||
) |
dm | The download manager to use, function will use all associated cache ressources |
url | The url to download |
filename | The filename to download |
start_range | start position of a byte range |
end_range | end position of a byte range |
redirected_url | If not NULL, will be allocated and filled with the URL after redirection. Caller takes ownership |
GF_Err gf_dm_wget | ( | const char * | url, |
const char * | filename, | ||
u64 | start_range, | ||
u64 | end_range, | ||
char ** | redirected_url | ||
) |
url | The url to download |
filename | The filename to download |
start_range | start position of a byte range |
end_range | end position of a byte range |
redirected_url | If not NULL, will be allocated and filled with the URL after redirection. Caller takes ownership |
GF_Err gf_dm_sess_reset | ( | GF_DownloadSession * | sess | ) |
Resets the session for new processing of the same url
sess | the download session |
DownloadedCacheEntry gf_dm_refresh_cache_entry | ( | GF_DownloadSession * | sess | ) |
sess | The session |
Bool gf_dm_sess_can_be_cached_on_disk | ( | const 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
sess | The session |
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.
sess | The session |
flags | The new flags for the session - if flags is 0xFFFFFFFF, existing flags are not modified |
user_io | The new callback function |
cbk | The new user data to ba used in the callback function |
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 GF_NETIO_SESSION_PERSISTENT flag set. This is only possible if the session is not threaded.
sess | The session |
url | The new url for the session |
const char* gf_dm_sess_get_header | ( | GF_DownloadSession * | sess, |
const char * | name | ||
) |
void gf_dm_set_data_rate | ( | GF_DownloadManager * | dm, |
u32 | rate_in_bits_per_sec | ||
) |
u32 gf_dm_get_data_rate | ( | GF_DownloadManager * | dm | ) |
u32 gf_dm_get_global_rate | ( | GF_DownloadManager * | dm | ) |
GF_Err gf_dm_get_file_memory | ( | const char * | url, |
char ** | out_data, | ||
u32 * | out_size, | ||
char ** | out_mime | ||
) |