Ecore URL Connection Functions

Utility functions that set up, use and shut down the Ecore URL Connection library. More...

Typedefs

typedef struct _Ecore_Con_Url Ecore_Con_Url
 A handle to an http upload/download object.

Enumerations

enum  _Ecore_Con_Url_Time {
  ECORE_CON_URL_TIME_NONE = 0,
  ECORE_CON_URL_TIME_IFMODSINCE,
  ECORE_CON_URL_TIME_IFUNMODSINCE
}
 The type of condition to use when making an HTTP request dependent on time, so that headers such as "If-Modified-Since" are used. More...

Functions

EAPI int ecore_con_url_init (void)
 Initialises the Ecore_Con_Url library.
EAPI int ecore_con_url_shutdown (void)
 Shuts down the Ecore_Con_Url library.
EAPI Ecore_Con_Urlecore_con_url_new (const char *url)
 Creates and initializes a new Ecore_Con_Url connection object.
EAPI Ecore_Con_Urlecore_con_url_custom_new (const char *url, const char *custom_request)
 Creates a custom connection object.
EAPI void ecore_con_url_free (Ecore_Con_Url *url_con)
 Destroys a Ecore_Con_Url connection object.
EAPI Eina_Bool ecore_con_url_url_set (Ecore_Con_Url *url_con, const char *url)
 Sets the URL to send the request to.
EAPI void ecore_con_url_data_set (Ecore_Con_Url *url_con, void *data)
 Associates data with a connection object.
EAPI void * ecore_con_url_data_get (Ecore_Con_Url *url_con)
 Retrieves data associated with a Ecore_Con_Url connection object.
EAPI void ecore_con_url_additional_header_add (Ecore_Con_Url *url_con, const char *key, const char *value)
 Adds an additional header to the request connection object.
EAPI void ecore_con_url_additional_headers_clear (Ecore_Con_Url *url_con)
 Cleans additional headers.
EAPI const Eina_List * ecore_con_url_response_headers_get (Ecore_Con_Url *url_con)
 Retrieves headers from last request sent.
EAPI void ecore_con_url_fd_set (Ecore_Con_Url *url_con, int fd)
 Setup a file for receiving request data.
EAPI int ecore_con_url_received_bytes_get (Ecore_Con_Url *url_con)
 Retrieves the number of bytes received.
EAPI Eina_Bool ecore_con_url_httpauth_set (Ecore_Con_Url *url_con, const char *username, const char *password, Eina_Bool safe)
 Sets url_con to use http auth, with given username and password, "safely" or not.
EINA_DEPRECATED EAPI Eina_Bool ecore_con_url_send (Ecore_Con_Url *url_con, const void *data, long length, const char *content_type)
 Sends a request.
EAPI Eina_Bool ecore_con_url_get (Ecore_Con_Url *url_con)
 Sends a get request.
EAPI Eina_Bool ecore_con_url_post (Ecore_Con_Url *url_con, const void *data, long length, const char *content_type)
 Sends a post request.
EAPI void ecore_con_url_time (Ecore_Con_Url *url_con, Ecore_Con_Url_Time condition, double timestamp)
 Sets whether HTTP requests should be conditional, dependent on modification time.
EAPI Eina_Bool ecore_con_url_ftp_upload (Ecore_Con_Url *url_con, const char *filename, const char *user, const char *pass, const char *upload_dir)
 Uploads a file to an ftp site.
EAPI void ecore_con_url_verbose_set (Ecore_Con_Url *url_con, Eina_Bool verbose)
 Toggle libcurl's verbose output.
EAPI void ecore_con_url_ftp_use_epsv_set (Ecore_Con_Url *url_con, Eina_Bool use_epsv)
 Enable or disable EPSV extension.
EAPI void ecore_con_url_cookies_init (Ecore_Con_Url *url_con)
 Enables the cookie engine for subsequent HTTP requests.
EAPI void ecore_con_url_cookies_ignore_old_session_set (Ecore_Con_Url *url_con, Eina_Bool ignore)
 Controls whether session cookies from previous sessions shall be loaded.
EAPI void ecore_con_url_cookies_clear (Ecore_Con_Url *url_con)
 Clears currently loaded cookies.
EAPI void ecore_con_url_cookies_session_clear (Ecore_Con_Url *url_con)
 Clears currently loaded session cookies.
EAPI void ecore_con_url_cookies_file_add (Ecore_Con_Url *url_con, const char *const file_name)
 Adds a file to the list of files from which to load cookies.
EAPI Eina_Bool ecore_con_url_cookies_jar_file_set (Ecore_Con_Url *url_con, const char *const cookiejar_file)
 Sets the name of the file to which all current cookies will be written when either cookies are flushed or Ecore_Con is shut down.
EAPI void ecore_con_url_cookies_jar_write (Ecore_Con_Url *url_con)
 Writes all current cookies to the cookie jar immediately.

Detailed Description

Utility functions that set up, use and shut down the Ecore URL Connection library.

Todo:
write detailed description of Ecore_Con_Url

Enumeration Type Documentation

The type of condition to use when making an HTTP request dependent on time, so that headers such as "If-Modified-Since" are used.

Enumerator:
ECORE_CON_URL_TIME_NONE 

Do not place time restrictions on the HTTP requests.

ECORE_CON_URL_TIME_IFMODSINCE 

Add the "If-Modified-Since" HTTP header, so that the request is performed by the server only if the target has been modified since the time value passed to it in the request.

ECORE_CON_URL_TIME_IFUNMODSINCE 

Add the "If-Unmodified-Since" HTTP header, so that the request is performed by the server only if the target has NOT been modified since the time value passed to it in the request.


Function Documentation

EAPI void ecore_con_url_additional_header_add ( Ecore_Con_Url url_con,
const char *  key,
const char *  value 
)

Adds an additional header to the request connection object.

Adds an additional header to the request connection object. This addition will be valid for only one ecore_con_url_get() or ecore_con_url_post() call.

Parameters:
url_conConnection object
keyHeader key
valueHeader value
See also:
ecore_con_url_get()
ecore_con_url_post()
ecore_con_url_additional_headers_clear()

Cleans additional headers.

Cleans additional headers associated with a connection object (previously added with ecore_con_url_additional_header_add()).

Parameters:
url_conConnection object to clean additional headers.
See also:
ecore_con_url_additional_header_add()
ecore_con_url_get()
ecore_con_url_post()
EAPI void ecore_con_url_cookies_clear ( Ecore_Con_Url url_con)

Clears currently loaded cookies.

The cleared cookies are removed and will not be sent in subsequent HTTP requests, nor will they be written to the cookiejar file set via ecore_con_url_cookies_jar_file_set().

Note:
This function will initialize the cookie engine if it has not been initialized yet.
Parameters:
url_conEcore_Con_Url instance which will be acted upon.
See also:
ecore_con_url_cookies_session_clear()
ecore_con_url_cookies_ignore_old_session_set()
EAPI void ecore_con_url_cookies_file_add ( Ecore_Con_Url url_con,
const char *const  file_name 
)

Adds a file to the list of files from which to load cookies.

Files must contain cookies defined according to two possible formats:

  • HTTP-style header ("Set-Cookie: ...").
  • Netscape/Mozilla cookie data format.

Please notice that the file will not be read immediately, but rather added to a list of files that will be loaded and parsed at a later time.

Note:
This function will initialize the cookie engine if it has not been initialized yet.
Parameters:
url_conEcore_Con_Url instance which will be acted upon.
file_nameName of the file that will be added to the list.
See also:
ecore_con_url_cookies_ignore_old_session_set()
EAPI void ecore_con_url_cookies_ignore_old_session_set ( Ecore_Con_Url url_con,
Eina_Bool  ignore 
)

Controls whether session cookies from previous sessions shall be loaded.

Session cookies are cookies with no expire date set, which usually means they are removed after the current session is closed.

By default, when Ecore_Con_Url loads cookies from a file, all cookies are loaded, including session cookies, which, most of the time, were supposed to be loaded and valid only for that session.

If ignore is set to EINA_TRUE, when Ecore_Con_Url loads cookies from the files passed to ecore_con_url_cookies_file_add(), session cookies will not be loaded.

Parameters:
url_conEcore_Con_Url instance which will be acted upon.
ignoreIf EINA_TRUE, ignore session cookies when loading cookies from files. If EINA_FALSE, all cookies will be loaded.
See also:
ecore_con_url_cookies_file_add()
EAPI void ecore_con_url_cookies_init ( Ecore_Con_Url url_con)

Enables the cookie engine for subsequent HTTP requests.

After this function is called, cookies set by the server in HTTP responses will be parsed and stored, as well as sent back to the server in new HTTP requests.

Note:
Even though this function is called ecore_con_url_cookies_init(), there is no symmetrical shutdown operation.
Parameters:
url_conEcore_Con_Url instance which will be acted upon.
EAPI Eina_Bool ecore_con_url_cookies_jar_file_set ( Ecore_Con_Url url_con,
const char *const  cookiejar_file 
)

Sets the name of the file to which all current cookies will be written when either cookies are flushed or Ecore_Con is shut down.

Cookies are written following Netscape/Mozilla's data format, also known as cookie-jar.

Note:
This function will initialize the cookie engine if it has not been initialized yet.
Parameters:
url_conEcore_Con_Url instance which will be acted upon.
cookiejar_fileFile to which the cookies will be written.
Returns:
EINA_TRUE is the file name has been set successfully, EINA_FALSE otherwise.
See also:
ecore_con_url_cookies_jar_write()

Writes all current cookies to the cookie jar immediately.

A cookie-jar file must have been previously set by ecore_con_url_jar_file_set, otherwise nothing will be done.

Note:
This function will initialize the cookie engine if it has not been initialized yet.
Parameters:
url_conEcore_Con_Url instance which will be acted upon.
See also:
ecore_con_url_cookies_jar_file_set()

Clears currently loaded session cookies.

Session cookies are cookies with no expire date set, which usually means they are removed after the current session is closed.

The cleared cookies are removed and will not be sent in subsequent HTTP requests, nor will they be written to the cookiejar file set via ecore_con_url_cookies_jar_file_set().

Note:
This function will initialize the cookie engine if it has not been initialized yet.
Parameters:
url_conEcore_Con_Url instance which will be acted upon.
See also:
ecore_con_url_cookies_clear()
ecore_con_url_cookies_ignore_old_session_set()
EAPI Ecore_Con_Url * ecore_con_url_custom_new ( const char *  url,
const char *  custom_request 
)

Creates a custom connection object.

Creates and initializes a new Ecore_Con_Url for a custom request (e.g. HEAD, SUBSCRIBE and other obscure HTTP requests). This object should be used like one created with ecore_con_url_new().

Parameters:
urlURL that will receive requests
custom_requestCustom request (e.g. GET, POST, HEAD, PUT, etc)
Returns:
NULL on error, a new Ecore_Con_Url on success.
See also:
ecore_con_url_new()
ecore_con_url_url_set()

References ecore_con_url_free(), and ecore_con_url_new().

EAPI void * ecore_con_url_data_get ( Ecore_Con_Url url_con)

Retrieves data associated with a Ecore_Con_Url connection object.

Retrieves data associated with a Ecore_Con_Url connection object (previously set with ecore_con_url_data_set()).

Parameters:
url_conConnection object to retrieve data from.
Returns:
Data associated with the given object.
See also:
ecore_con_url_data_set()

Referenced by ecore_file_download_abort().

EAPI void ecore_con_url_data_set ( Ecore_Con_Url url_con,
void *  data 
)

Associates data with a connection object.

Associates data with a connection object, which can be retrieved later with ecore_con_url_data_get()).

Parameters:
url_conConnection object to associate data.
dataData to be set.
See also:
ecore_con_url_data_get()
EAPI void ecore_con_url_fd_set ( Ecore_Con_Url url_con,
int  fd 
)

Setup a file for receiving request data.

Setups a file to have response data written into. Note that ECORE_CON_EVENT_URL_DATA events will not be emitted if a file has been set to receive the response data.

Parameters:
url_conConnection object to set file
fdFile descriptor associated with the file
EAPI void ecore_con_url_free ( Ecore_Con_Url url_con)

Destroys a Ecore_Con_Url connection object.

Parameters:
url_conConnection object to free.
See also:
ecore_con_url_new()

References ecore_main_fd_handler_del().

Referenced by ecore_con_url_custom_new(), ecore_con_url_init(), ecore_con_url_new(), ecore_con_url_shutdown(), and ecore_file_download_abort().

EAPI Eina_Bool ecore_con_url_ftp_upload ( Ecore_Con_Url url_con,
const char *  filename,
const char *  user,
const char *  pass,
const char *  upload_dir 
)

Uploads a file to an ftp site.

Parameters:
url_conThe Ecore_Con_Url object to send with
filenameThe path to the file to send
userThe username to log in with
passThe password to log in with
upload_dirThe directory to which the file should be uploaded
Returns:
#EINA_TRUE on success, else #EINA_FALSE. Upload filename to an ftp server set in url_con using user and pass to directory upload_dir

References ecore_con_url_url_set().

EAPI void ecore_con_url_ftp_use_epsv_set ( Ecore_Con_Url url_con,
Eina_Bool  use_epsv 
)

Enable or disable EPSV extension.

Returns:
FIXME: To be more documented.
EAPI Eina_Bool ecore_con_url_get ( Ecore_Con_Url url_con)

Sends a get request.

Parameters:
url_conConnection object to perform a request on, previously created
Returns:
#EINA_TRUE on success, #EINA_FALSE on error.
See also:
ecore_con_url_custom_new()
ecore_con_url_additional_headers_clear()
ecore_con_url_additional_header_add()
ecore_con_url_data_set()
ecore_con_url_data_get()
ecore_con_url_response_headers_get()
ecore_con_url_time()
ecore_con_url_post()
EAPI Eina_Bool ecore_con_url_httpauth_set ( Ecore_Con_Url url_con,
const char *  username,
const char *  password,
Eina_Bool  safe 
)

Sets url_con to use http auth, with given username and password, "safely" or not.

ATTENTION: requires libcurl >= 7.19.1 to work, otherwise will always return 0.

Parameters:
url_conConnection object to perform a request on, previously created with ecore_con_url_new() or ecore_con_url_custom_new().
usernameUsername to use in authentication
passwordPassword to use in authentication
safeWhether to use "safer" methods (eg, NOT http basic auth)
Returns:
#EINA_TRUE on success, #EINA_FALSE on error.
EAPI int ecore_con_url_init ( void  )

Initialises the Ecore_Con_Url library.

Returns:
Number of times the library has been initialised without being shut down.

References ECORE_CON_EVENT_URL_COMPLETE, ECORE_CON_EVENT_URL_DATA, ECORE_CON_EVENT_URL_PROGRESS, ecore_con_url_free(), ecore_event_type_new(), and ecore_timer_add().

EAPI Ecore_Con_Url * ecore_con_url_new ( const char *  url)

Creates and initializes a new Ecore_Con_Url connection object.

Creates and initializes a new Ecore_Con_Url connection object that can be uesd for sending requests.

Parameters:
urlURL that will receive requests. Can be changed using ecore_con_url_url_set.
Returns:
NULL on error, a new Ecore_Con_Url on success.
See also:
ecore_con_url_custom_new()
ecore_con_url_url_set()

References ecore_con_url_free(), and ecore_con_url_url_set().

Referenced by ecore_con_url_custom_new().

EAPI Eina_Bool ecore_con_url_post ( Ecore_Con_Url url_con,
const void *  data,
long  length,
const char *  content_type 
)

Sends a post request.

Parameters:
url_conConnection object to perform a request on, previously created with ecore_con_url_new() or ecore_con_url_custom_new().
dataPayload (data sent on the request)
lengthPayload length. If -1, rely on automatic length calculation via strlen() on data.
content_typeContent type of the payload (e.g. text/xml)
Returns:
#EINA_TRUE on success, #EINA_FALSE on error.
See also:
ecore_con_url_custom_new()
ecore_con_url_additional_headers_clear()
ecore_con_url_additional_header_add()
ecore_con_url_data_set()
ecore_con_url_data_get()
ecore_con_url_response_headers_get()
ecore_con_url_time()
ecore_con_url_get()

Retrieves the number of bytes received.

Retrieves the number of bytes received on the last request of the given connection object.

Parameters:
url_conConnection object which the request was sent on.
Returns:
Number of bytes received on request.
See also:
ecore_con_url_get()
ecore_con_url_post()
EAPI const Eina_List * ecore_con_url_response_headers_get ( Ecore_Con_Url url_con)

Retrieves headers from last request sent.

Retrieves a list containing the response headers. This function should be used after an ECORE_CON_EVENT_URL_COMPLETE event (headers should normally be ready at that time).

Parameters:
url_conConnection object to retrieve response headers from.
Returns:
List of response headers. This list must not be modified by the user.
EINA_DEPRECATED EAPI Eina_Bool ecore_con_url_send ( Ecore_Con_Url url_con,
const void *  data,
long  length,
const char *  content_type 
)

Sends a request.

Parameters:
url_conConnection object to perform a request on, previously created with ecore_con_url_new() or ecore_con_url_custom_new().
dataPayload (data sent on the request)
lengthPayload length. If -1, rely on automatic length calculation via strlen() on data.
content_typeContent type of the payload (e.g. text/xml)
Returns:
#EINA_TRUE on success, #EINA_FALSE on error.
See also:
ecore_con_url_custom_new()
ecore_con_url_additional_headers_clear()
ecore_con_url_additional_header_add()
ecore_con_url_data_set()
ecore_con_url_data_get()
ecore_con_url_response_headers_get()
ecore_con_url_time()
ecore_con_url_get()
ecore_con_url_post()
EAPI int ecore_con_url_shutdown ( void  )

Shuts down the Ecore_Con_Url library.

Returns:
Number of calls that still uses Ecore_Con_Url

References ecore_con_url_free(), ecore_idler_del(), and ecore_timer_del().

EAPI void ecore_con_url_time ( Ecore_Con_Url url_con,
Ecore_Con_Url_Time  condition,
double  timestamp 
)

Sets whether HTTP requests should be conditional, dependent on modification time.

Parameters:
url_conEcore_Con_Url to act upon.
conditionCondition to use for HTTP requests.
timestampTime since 1 Jan 1970 to use in the condition.
See also:
ecore_con_url_get()
ecore_con_url_post()
EAPI Eina_Bool ecore_con_url_url_set ( Ecore_Con_Url url_con,
const char *  url 
)

Sets the URL to send the request to.

Parameters:
url_conConnection object through which the request will be sent.
urlURL that will receive the request
Returns:
EINA_TRUE on success, EINA_FALSE on error.

Referenced by ecore_con_url_ftp_upload(), and ecore_con_url_new().

EAPI void ecore_con_url_verbose_set ( Ecore_Con_Url url_con,
Eina_Bool  verbose 
)

Toggle libcurl's verbose output.

If verbose is EINA_TRUE, libcurl will output a lot of verbose information about its operations, which is useful for debugging. The verbose information will be sent to stderr.

Parameters:
url_conEcore_Con_Url instance which will be acted upon.
verboseWhether or not to enable libcurl's verbose output.