downloader
[utils]

File Downloader objects. More...

Classes

struct  GF_NETIO_Parameter

Typedefs

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
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 }

Functions

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, char *url, u32 dl_flags, gf_dm_user_io user_io, void *usr_cbk, GF_Err *error)
 download session 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
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
const char * gf_dm_sess_get_cache_name (GF_DownloadSession *sess)
 get cache file name
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

Detailed Description

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 __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_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.
Note:
this varaibale may already be formatted.
Parameters:
password the 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_cbk opaque user data
parameter the 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 has no cache: data will be sent to the user if threaded mode (live streams like radios & co)


Function Documentation

GF_DownloadManager* gf_dm_new ( GF_Config *  cfg  ) 

Creates a new download manager object.

Parameters:
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.
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:
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,
char *  url,
u32  dl_flags,
gf_dm_user_io  user_io,
void *  usr_cbk,
GF_Err error 
)

Creates a new download session

Parameters:
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
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

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

Parameters:
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.

Parameters:
sess the download session

void gf_dm_sess_set_private ( GF_DownloadSession sess,
void *  private_data 
)

associate private data with the session.

Parameters:
sess the download session
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_get_private ( GF_DownloadSession sess  ) 

Gets private data associated with the session.

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

GF_Err gf_dm_sess_last_error ( GF_DownloadSession sess  ) 

Gets the last error that occured in the session

Parameters:
sess the download session
Returns:
the last error

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:
sess the download session
buffer destination buffer
buffer_size destination buffer allocated size
read_size amount 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:
sess the download session
Returns:
the mime type of the URL, or NULL if error. You should get the error with gf_dm_sess_last_error

const char* gf_dm_sess_get_cache_name ( GF_DownloadSession sess  ) 

Gets the cache file name for the session.

Parameters:
sess the download session
Returns:
the absolute path of the cache file, or NULL if the session is not cached

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:
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


Generated on Mon Sep 8 18:11:26 2008 for libgpac by  doxygen 1.5.6