![]() |
libgpac
Documentation of the core library of GPAC
|
HTTP Downloader. More...
Modules | |
DownloaderCache | |
HTTP Downloader Cache. | |
Data Structures | |
struct | GF_URL_Info_Struct |
struct | GF_NETIO_Parameter |
Typedefs | |
typedef struct __gf_download_manager | GF_DownloadManager |
typedef struct __gf_download_session | GF_DownloadSession |
typedef struct __gf_filter_session | GF_DownloadFilterSession |
typedef void(* | gf_dm_on_usr_pass) (void *usr_cbk, const char *usr_name, const char *password, Bool store_info) |
callback function for authentication More... | |
typedef Bool(* | gf_dm_get_usr_pass) (void *usr_cbk, const char *site_url, char *usr_name, char *password, gf_dm_on_usr_pass async_pass, void *async_udta) |
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... | |
Enumerations | |
enum | GF_NetIOStatus { 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, GF_NETIO_REQUEST_SESSION, GF_NETIO_CANCEL_STREAM } |
enum | GF_NetIOFlags { GF_NETIO_SESSION_NOT_THREADED = 1, GF_NETIO_SESSION_NOT_CACHED = 1<<1, GF_NETIO_SESSION_NOTIFY_DATA = 1<<2, GF_NETIO_SESSION_PERSISTENT = 1<<3, GF_NETIO_SESSION_MEMORY_CACHE = 1<<4, GF_NETIO_SESSION_KEEP_CACHE = 1<<5, GF_NETIO_SESSION_KEEP_FIRST_CACHE = 1<<6 } |
enum | { GF_HTTP_UNKNOWN = 0, GF_HTTP_GET, GF_HTTP_HEAD, GF_HTTP_OPTIONS, GF_HTTP_CONNECT, GF_HTTP_TRACE, GF_HTTP_PUT, GF_HTTP_POST, GF_HTTP_DELETE } |
Functions | |
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_DownloadManager * | gf_dm_new (GF_DownloadFilterSession *fsess) |
download manager constructor More... | |
void | gf_dm_del (GF_DownloadManager *dm) |
download manager destructor More... | |
void | gf_dm_set_auth_callback (GF_DownloadManager *dm, gf_dm_get_usr_pass get_pass, void *usr_cbk) |
password retrieval assignment More... | |
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) |
download session constructor More... | |
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) |
download session simple constructor More... | |
void | gf_dm_sess_del (GF_DownloadSession *sess) |
downloader session destructor More... | |
void | gf_dm_sess_abort (GF_DownloadSession *sess) |
aborts downloading More... | |
GF_Err | gf_dm_sess_last_error (GF_DownloadSession *sess) |
gets last session error More... | |
GF_Err | gf_dm_sess_fetch_data (GF_DownloadSession *sess, char *buffer, u32 buffer_size, u32 *read_size) |
fetches data on session More... | |
const char * | gf_dm_sess_mime_type (GF_DownloadSession *sess) |
get mime type as lower case More... | |
GF_Err | gf_dm_sess_set_range (GF_DownloadSession *sess, u64 start_range, u64 end_range, Bool discontinue_cache) |
sets session range More... | |
const char * | gf_dm_sess_get_cache_name (GF_DownloadSession *sess) |
get cache file name More... | |
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. More... | |
void | gf_dm_delete_cached_file_entry_session (const GF_DownloadSession *sess, const char *url) |
GF_Err | gf_dm_sess_get_stats (GF_DownloadSession *sess, const char **server, const char **path, u64 *total_size, u64 *bytes_done, u32 *bytes_per_sec, GF_NetIOStatus *net_status) |
get statistics More... | |
u64 | gf_dm_sess_get_utc_start (GF_DownloadSession *sess) |
get start time More... | |
GF_Err | gf_dm_sess_process (GF_DownloadSession *sess) |
fetch session object More... | |
GF_Err | gf_dm_sess_process_headers (GF_DownloadSession *sess) |
fetch session object headers More... | |
const char * | gf_dm_sess_get_resource_name (GF_DownloadSession *sess) |
Get session resource url. More... | |
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) |
GF_Err | gf_dm_wget (const char *url, const char *filename, u64 start_range, u64 end_range, char **redirected_url) |
Same as gf_dm_wget_with_cache, but initializes the GF_DownloadManager by itself. More... | |
GF_Err | gf_dm_sess_setup_from_url (GF_DownloadSession *sess, const char *url, Bool allow_direct_reuse) |
const char * | gf_dm_sess_get_header (GF_DownloadSession *sess, const char *name) |
retrieves the HTTP header value for the given name More... | |
GF_Err | gf_dm_sess_enum_headers (GF_DownloadSession *sess, u32 *idx, const char **hdr_name, const char **hdr_val) |
enumerates the HTTP headers for a session More... | |
void | gf_dm_set_data_rate (GF_DownloadManager *dm, u32 rate_in_bits_per_sec) |
sets download manager max rate per session More... | |
u32 | gf_dm_get_data_rate (GF_DownloadManager *dm) |
gets download manager max rate per session More... | |
u32 | gf_dm_get_global_rate (GF_DownloadManager *dm) |
gets cumultaed download rate for all sessions More... | |
GF_Err | gf_dm_sess_get_header_sizes_and_times (GF_DownloadSession *sess, u32 *req_hdr_size, u32 *rsp_hdr_size, u32 *connect_time, u32 *reply_time, u32 *download_time) |
Get header sizes and times stats for the session. More... | |
void | gf_dm_sess_force_memory_mode (GF_DownloadSession *sess, u32 force_cache_type) |
Forces session to use memory storage. More... | |
GF_Err | gf_dm_set_localcache_provider (GF_DownloadManager *dm, Bool(*local_cache_url_provider_cbk)(void *udta, char *url, Bool is_cache_destroy), void *lc_udta) |
DownloadedCacheEntry | gf_dm_add_cache_entry (GF_DownloadManager *dm, const char *szURL, GF_Blob *blob, u64 start_range, u64 end_range, const char *mime, Bool clone_memory, u32 download_time_ms) |
GF_Err | gf_dm_force_headers (GF_DownloadManager *dm, const DownloadedCacheEntry entry, const char *headers) |
This section documents the file downloading tools the GPAC framework. Currently HTTP and HTTPS are supported. HTTPS may not be supported depending on GPAC compilation options (HTTPS in GPAC needs OpenSSL installed on the system).
struct GF_URL_Info_Struct |
URL information object
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 u8 * | 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 __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 struct __gf_filter_session GF_DownloadFilterSession |
the optional filter session.
typedef void(* gf_dm_on_usr_pass) (void *usr_cbk, const char *usr_name, const char *password, Bool store_info) |
This function is called back after user and password has been entered
usr_cbk | opaque user data passed by download manager |
usr_name | the user name for the desired site, or NULL if the authentication was canceled |
password | the password for the desired site and user, or NULL if the authentication was canceled |
store_info | if TRUE, credentials will be stored in gpac config |
typedef Bool(* gf_dm_get_usr_pass) (void *usr_cbk, const char *site_url, char *usr_name, char *password, gf_dm_on_usr_pass async_pass, void *async_udta) |
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. |
async_pass | async function to call back when user and pass have been entered. If NULL, sync call will be performed |
async_udta | async user data to pass back to the async function. If NULL, sync call will be performed |
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
anonymous enum |
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 | ) |
Inits 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_DownloadFilterSession * | fsess | ) |
Creates a new download manager object.
fsess | optional filter session. If not NULL, the filter session will be used for async downloads. Otherwise, threads will be created |
void gf_dm_del | ( | GF_DownloadManager * | dm | ) |
Deletes the download manager. All running sessions are aborted
dm | 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.
dm | the download manager object |
get_pass | specifies 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 | specifies 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 | specifies 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 | ) |
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 |
GF_Err gf_dm_sess_last_error | ( | GF_DownloadSession * | sess | ) |
Gets the last error that occured in the session
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 | ||
) |
Marks the cache file for this session to be deleted once the file is not used anymore by any session
sess | the download session |
url | The URL associate to the cache entry to be deleted |
GF_Err gf_dm_sess_get_stats | ( | GF_DownloadSession * | sess, |
const char ** | server, | ||
const char ** | path, | ||
u64 * | total_size, | ||
u64 * | 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 |
const char* gf_dm_sess_get_resource_name | ( | GF_DownloadSession * | sess | ) |
Returns the original resource URL 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 | ||
) |
Downloads a file over the network using a download manager
dm | The download manager to use, function will use all associated cache resources |
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, redirected_url 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 | ||
) |
This function is deprecated, please use gf_dm_wget_with_cache instead
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, redirected_url will be allocated and filled with the URL after redirection. Caller takes ownership |
GF_Err gf_dm_sess_setup_from_url | ( | GF_DownloadSession * | sess, |
const char * | url, | ||
Bool | allow_direct_reuse | ||
) |
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 |
allow_direct_reuse | Allow reuse of cache entry without checking cache directives |
const char* gf_dm_sess_get_header | ( | GF_DownloadSession * | sess, |
const char * | name | ||
) |
Retrieves the HTTP header value for the given header name.
sess | the current session |
name | the target header name |
GF_Err gf_dm_sess_enum_headers | ( | GF_DownloadSession * | sess, |
u32 * | idx, | ||
const char ** | hdr_name, | ||
const char ** | hdr_val | ||
) |
Retrieves the HTTP header name and value for the given header index.
sess | the current session |
idx | index for the enumeration, must be initialized to 0 for the first call |
hdr_name | where name of header is stored - do not free |
hdr_val | where value of header is stored - do not free |
void gf_dm_set_data_rate | ( | GF_DownloadManager * | dm, |
u32 | rate_in_bits_per_sec | ||
) |
Sets the maximum rate (per session only at the current time).
dm | the download manager object |
rate_in_bits_per_sec | the new rate in bits per sec. If 0, HTTP rate will not be limited |
u32 gf_dm_get_data_rate | ( | GF_DownloadManager * | dm | ) |
Sets the maximum rate (per session only at the current time).
dm | the download manager object |
u32 gf_dm_get_global_rate | ( | GF_DownloadManager * | dm | ) |
Gets the cumultated bitrate in of all active sessions.
dm | the download manager object |
GF_Err gf_dm_sess_get_header_sizes_and_times | ( | GF_DownloadSession * | sess, |
u32 * | req_hdr_size, | ||
u32 * | rsp_hdr_size, | ||
u32 * | connect_time, | ||
u32 * | reply_time, | ||
u32 * | download_time | ||
) |
Get header sizes and times stats for the session
sess | the current session |
req_hdr_size | request header size in bytes. May be NULL. |
rsp_hdr_size | response header size in bytes. May be NULL. |
connect_time | connection time in micro seconds. May be NULL. |
reply_time | elapsed time between request sent and response header received, in micro seconds. May be NULL. |
download_time | download time since request sent, in micro seconds. May be NULL. |
void gf_dm_sess_force_memory_mode | ( | GF_DownloadSession * | sess, |
u32 | force_cache_type | ||
) |
Forces session to use memory storage for future downloads
sess | the current session |
force_cache_type | if 1, cache will be kept even if session is reassigned. If 2, cache will ne kept for next resource downloaded, then no caching for subsequent resources (used for init segments) |
GF_Err gf_dm_set_localcache_provider | ( | GF_DownloadManager * | dm, |
Bool(*)(void *udta, char *url, Bool is_cache_destroy) | local_cache_url_provider_cbk, | ||
void * | lc_udta | ||
) |
Registers a local cache provider (bypassing the http session), used when populating cache from input data (ROUTE for example)
dm | the download manager |
local_cache_url_provider_cbk | callback function to the cache provider. The callback function shall return GF_TRUE if the requested URL is provided by this local cache |
lc_udta | opaque pointer passed to the callback function |
DownloadedCacheEntry gf_dm_add_cache_entry | ( | GF_DownloadManager * | dm, |
const char * | szURL, | ||
GF_Blob * | blob, | ||
u64 | start_range, | ||
u64 | end_range, | ||
const char * | mime, | ||
Bool | clone_memory, | ||
u32 | download_time_ms | ||
) |
Adds a local entry in the cache
dm | the download manager |
szURL | the URL this resource is caching |
blob | blob object holding the data of the resource |
start_range | start range of the data in the resource |
end_range | start range of the data in the resource. If both start_range and end_range are 0, the data is the complete resource |
mime | associated MIME type if any |
clone_memory | indicates that the data shall be cloned in the cache because the caller will discard it |
download_time_ms | indicates the download time of the associated resource, if known, 0 otherwise. |
GF_Err gf_dm_force_headers | ( | GF_DownloadManager * | dm, |
const DownloadedCacheEntry | entry, | ||
const char * | headers | ||
) |
Forces HTTP headers for a given cache entry
dm | the download manager |
entry | the cache entry to update |
headers | the header string, including CRLF delimiters, to force |