Data Structures | Macros | Typedefs | Enumerations | Functions
Ecore URL Connection Functions

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

Data Structures

struct  _Ecore_Con_Event_Url_Data
 Used as the data param for the ECORE_CON_EVENT_URL_DATA event. More...
 
struct  _Ecore_Con_Event_Url_Complete
 Used as the data param for the ECORE_CON_EVENT_URL_COMPLETE event. More...
 
struct  _Ecore_Con_Event_Url_Progress
 Used as the data param for the ECORE_CON_EVENT_URL_PROGRESS event. More...
 

Macros

#define ECORE_CON_URL_CHECK_RETURN(u, ...)
 

Typedefs

typedef enum _Ecore_Con_Url_Time Ecore_Con_Url_Time
 
typedef enum _Ecore_Con_Url_Http_Version Ecore_Con_Url_Http_Version
 
typedef struct _Ecore_Con_Url Ecore_Con_Url
 Used to provide legacy API/ABI compatibility with non-Eo applications.
 
typedef struct _Ecore_Con_Event_Url_Data Ecore_Con_Event_Url_Data
 Used as the data param for the corresponding event.
 
typedef struct _Ecore_Con_Event_Url_Complete Ecore_Con_Event_Url_Complete
 Used as the data param for the corresponding event.
 
typedef struct _Ecore_Con_Event_Url_Progress Ecore_Con_Event_Url_Progress
 Used as the data param for the corresponding event.
 

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...
 
enum  _Ecore_Con_Url_Http_Version {
  ECORE_CON_URL_HTTP_VERSION_1_0 ,
  ECORE_CON_URL_HTTP_VERSION_1_1
}
 The http version to use. More...
 

Functions

ECORE_CON_API Eina_Bool ecore_con_url_http_version_set (Ecore_Con_Url *url_con, Ecore_Con_Url_Http_Version version)
 Changes the HTTP version used for the request. More...
 
ECORE_CON_API int ecore_con_url_init (void)
 Initializes the Ecore_Con_Url library. More...
 
ECORE_CON_API int ecore_con_url_shutdown (void)
 Shuts down the Ecore_Con_Url library. More...
 
ECORE_CON_API void ecore_con_url_pipeline_set (Eina_Bool enable)
 Enables or disable HTTP 1.1 pipelining. More...
 
ECORE_CON_API Eina_Bool ecore_con_url_pipeline_get (void)
 Is HTTP 1.1 pipelining enable ? More...
 
ECORE_CON_API Ecore_Con_Urlecore_con_url_new (const char *url)
 Creates and initializes a new Ecore_Con_Url connection object. More...
 
ECORE_CON_API Eina_Bool ecore_con_url_url_set (Ecore_Con_Url *url_con, const char *url)
 Change the URL assigned to this handle. More...
 
ECORE_CON_API const char * ecore_con_url_url_get (Ecore_Con_Url *url_con)
 Retrieve the URL assigned to this handle. More...
 
ECORE_CON_API Ecore_Con_Urlecore_con_url_custom_new (const char *url, const char *custom_request)
 Creates a custom connection object. More...
 
ECORE_CON_API void ecore_con_url_free (Ecore_Con_Url *url_con)
 Destroys an Ecore_Con_Url connection object. More...
 
ECORE_CON_API void ecore_con_url_data_set (Ecore_Con_Url *url_con, void *data)
 Associates data with a connection object. More...
 
ECORE_CON_API void * ecore_con_url_data_get (Ecore_Con_Url *url_con)
 Retrieves data associated with a Ecore_Con_Url connection object. More...
 
ECORE_CON_API 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. More...
 
ECORE_CON_API void ecore_con_url_additional_headers_clear (Ecore_Con_Url *url_con)
 Cleans additional headers. More...
 
ECORE_CON_API const Eina_Listecore_con_url_response_headers_get (Ecore_Con_Url *url_con)
 Retrieves headers from last request sent. More...
 
ECORE_CON_API void ecore_con_url_fd_set (Ecore_Con_Url *url_con, int fd)
 Sets up a file for receiving response data. More...
 
ECORE_CON_API int ecore_con_url_received_bytes_get (Ecore_Con_Url *url_con)
 Retrieves the number of bytes received. More...
 
ECORE_CON_API 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. More...
 
ECORE_CON_API Eina_Bool ecore_con_url_get (Ecore_Con_Url *url_con)
 Sends a get request. More...
 
ECORE_CON_API Eina_Bool ecore_con_url_head (Ecore_Con_Url *url_con)
 Sends a HEAD request. More...
 
ECORE_CON_API Eina_Bool ecore_con_url_post (Ecore_Con_Url *url_con, const void *data, long length, const char *content_type)
 Sends a post request. More...
 
ECORE_CON_API void ecore_con_url_time (Ecore_Con_Url *url_con, Ecore_Con_Url_Time time_condition, double timestamp)
 Sets whether HTTP requests should be conditional, dependent on modification time. More...
 
ECORE_CON_API 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. More...
 
ECORE_CON_API void ecore_con_url_verbose_set (Ecore_Con_Url *url_con, Eina_Bool verbose)
 Toggles libcurl's verbose output. More...
 
ECORE_CON_API void ecore_con_url_ftp_use_epsv_set (Ecore_Con_Url *url_con, Eina_Bool use_epsv)
 Enables or disables EPSV extension. More...
 
ECORE_CON_API void ecore_con_url_cookies_init (Ecore_Con_Url *url_con)
 Enables the cookie engine for subsequent HTTP requests. More...
 
ECORE_CON_API 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. More...
 
ECORE_CON_API void ecore_con_url_cookies_clear (Ecore_Con_Url *url_con)
 Clears currently loaded cookies. More...
 
ECORE_CON_API void ecore_con_url_cookies_session_clear (Ecore_Con_Url *url_con)
 Clears currently loaded session cookies. More...
 
ECORE_CON_API 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. More...
 
ECORE_CON_API 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. More...
 
ECORE_CON_API void ecore_con_url_cookies_jar_write (Ecore_Con_Url *url_con)
 Writes all current cookies to the cookie jar immediately. More...
 
ECORE_CON_API void ecore_con_url_ssl_verify_peer_set (Ecore_Con_Url *url_con, Eina_Bool verify)
 Toggle libcurl's verify peer's certificate option. More...
 
ECORE_CON_API int ecore_con_url_ssl_ca_set (Ecore_Con_Url *url_con, const char *ca_path)
 Set a custom CA to trust for SSL/TLS connections. More...
 
ECORE_CON_API Eina_Bool ecore_con_url_proxy_set (Ecore_Con_Url *url_con, const char *proxy)
 Sets HTTP proxy to use. More...
 
ECORE_CON_API Eina_Bool ecore_con_url_proxy_username_set (Ecore_Con_Url *url_con, const char *username)
 Sets zero terminated username to use for proxy. More...
 
ECORE_CON_API Eina_Bool ecore_con_url_proxy_password_set (Ecore_Con_Url *url_con, const char *password)
 Sets zero terminated password to use for proxy. More...
 
ECORE_CON_API void ecore_con_url_timeout_set (Ecore_Con_Url *url_con, double timeout)
 Sets timeout in seconds. More...
 
ECORE_CON_API int ecore_con_url_status_code_get (Ecore_Con_Url *url_con)
 Gets the returned HTTP STATUS code. More...
 
ECORE_CON_API void ecore_con_url_limit_upload_speed (Ecore_Con_Url *url_obj, off_t max_speed)
 Sets a maximum upload speed. More...
 
ECORE_CON_API void ecore_con_url_limit_download_speed (Ecore_Con_Url *url_obj, off_t max_speed)
 Sets a maximum download speed. More...
 
static void _ecore_con_url_dialer_close (Ecore_Con_Url *url_con)
 
static void _ecore_con_url_response_headers_free (Ecore_Con_Url *url_con)
 
static void _ecore_con_url_request_headers_free (Ecore_Con_Url *url_con)
 
static void _ecore_con_url_free_internal (Ecore_Con_Url *url_con)
 
static void _ecore_con_event_url_progress_free (void *data, void *event)
 
static void _ecore_con_event_url_progress_add (Ecore_Con_Url *url_con)
 
static void _ecore_con_event_url_complete_free (void *data, void *event)
 
static void _ecore_con_event_url_complete_add (Ecore_Con_Url *url_con, int status)
 
static void _ecore_con_url_dialer_error (void *data, const Efl_Event *event)
 
static void _ecore_con_event_url_data_free (void *data, void *event)
 
static void _ecore_con_url_dialer_can_read_changed (void *data, const Efl_Event *event)
 
static void _ecore_con_url_dialer_eos (void *data, const Efl_Event *event)
 
static void _ecore_con_url_dialer_headers_done (void *data, const Efl_Event *event)
 
 EFL_CALLBACKS_ARRAY_DEFINE (ecore_con_url_dialer_cbs, { EFL_IO_READER_EVENT_CAN_READ_CHANGED, _ecore_con_url_dialer_can_read_changed }, { EFL_IO_READER_EVENT_EOS, _ecore_con_url_dialer_eos }, { EFL_NET_DIALER_EVENT_DIALER_ERROR, _ecore_con_url_dialer_error }, { EFL_NET_DIALER_HTTP_EVENT_HEADERS_DONE, _ecore_con_url_dialer_headers_done })
 
static Eina_Bool _ecore_con_url_progress_animator_cb (void *data)
 
static char * _ecore_con_url_proxy_url_new (const Ecore_Con_Url *url_con)
 
static void _ecore_con_url_copier_done (void *data, const Efl_Event *event)
 
static void _ecore_con_url_copier_error (void *data, const Efl_Event *event)
 
 EFL_CALLBACKS_ARRAY_DEFINE (_ecore_con_url_copier_cbs, { EFL_IO_COPIER_EVENT_ERROR, _ecore_con_url_copier_error }, { EFL_IO_COPIER_EVENT_DONE, _ecore_con_url_copier_done })
 
static Eina_Bool _ecore_con_url_request_prepare (Ecore_Con_Url *url_con, const char *method)
 
static Eina_Bool _ecore_con_url_timeout_cb (void *data)
 

Detailed Description

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

These functions are a shortcut to make it easy to perform http requests (POST, GET, etc).

Brief usage:

  1. Create an Ecore_Con_Url object with ecore_con_url_new(url);
  2. Register to receive the ECORE_CON_EVENT_URL_COMPLETE event (and optionally the ECORE_CON_EVENT_URL_DATA and ECORE_CON_EVENT_URL_PROGRESS event to receive the response, e.g. for HTTP/FTP downloads)
  3. Perform the operation with ecore_con_url_get(...);

Note that it is good to reuse Ecore_Con_Url objects wherever possible, but bear in mind that each one can only perform one operation at a time. You need to wait for the ECORE_CON_EVENT_URL_COMPLETE event before re-using or destroying the object.

If it's necessary to change the Ecore_Con_Url object url, use ecore_con_url_url_set().

Simple Usage 1 (HTTP GET):

ecore_con_url_url_set(url_con, "http://www.google.com");
ECORE_CON_API Eina_Bool ecore_con_url_url_set(Ecore_Con_Url *url_con, const char *url)
Change the URL assigned to this handle.
Definition: ecore_con_url.c:845
ECORE_CON_API Eina_Bool ecore_con_url_get(Ecore_Con_Url *url_con)
Sends a get request.
Definition: ecore_con_url.c:862

Simple usage 2 (HTTP POST):

ecore_con_url_url_set(url_con, "http://www.example.com/post_handler.cgi");
ecore_con_url_post(url_con, data, data_length, "multipart/form-data");
ECORE_CON_API Eina_Bool ecore_con_url_post(Ecore_Con_Url *url_con, const void *data, long length, const char *content_type)
Sends a post request.
Definition: ecore_con_url.c:904

Simple Usage 3 (FTP download):

fd = creat(filename, 0644)
ecore_con_url_url_set(url_con, "ftp://ftp.example.com/pub/myfile");
ecore_con_url_fd_set(url_con, fd);
ECORE_CON_API void ecore_con_url_fd_set(Ecore_Con_Url *url_con, int fd)
Sets up a file for receiving response data.
Definition: ecore_con_url.c:1138

Simple Usage 4 (FTP upload as ftp://ftp.example.com/file):

ecore_con_url_url_set(url_con, "ftp://ftp.example.com");
ecore_con_url_ftp_upload(url_con, "/tmp/file", "user", "pass", NULL);
ECORE_CON_API 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.
Definition: ecore_con_url.c:1149

Simple Usage 5 (FTP upload as ftp://ftp.example.com/dir/file):

ecore_con_url_url_set(url_con, "ftp://ftp.example.com");
ecore_con_url_ftp_upload(url_con, "/tmp/file", "user", "pass","dir");

These are complete examples for the API:

Macro Definition Documentation

◆ ECORE_CON_URL_CHECK_RETURN

#define ECORE_CON_URL_CHECK_RETURN (   u,
  ... 
)
Value:
do \
{ \
if (!EINA_MAGIC_CHECK(u, ECORE_MAGIC_CON_URL)) \
{ \
ECORE_MAGIC_FAIL(u, ECORE_MAGIC_CON_URL, __func__); \
return __VA_ARGS__; \
} \
EINA_SAFETY_ON_TRUE_RETURN_VAL(u->delete_me, __VA_ARGS__); \
} \
while (0)
#define EINA_MAGIC_CHECK(d, m)
Definition to test if d is NULL or not, and if not NULL, if d->__eina_magic is equal to m.
Definition: eina_magic.h:247

Enumeration Type Documentation

◆ _Ecore_Con_Url_Time

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.

◆ _Ecore_Con_Url_Http_Version

The http version to use.

Since
1.2
Enumerator
ECORE_CON_URL_HTTP_VERSION_1_0 

HTTP version 1.0.

Since
1.2
ECORE_CON_URL_HTTP_VERSION_1_1 

HTTP version 1.1 (default)

Since
1.2

Function Documentation

◆ ecore_con_url_http_version_set()

ECORE_CON_API Eina_Bool ecore_con_url_http_version_set ( Ecore_Con_Url url_con,
Ecore_Con_Url_Http_Version  version 
)

Changes the HTTP version used for the request.

Parameters
url_conConnection object through which the request will be sent.
versionThe version to be used.
Returns
EINA_TRUE on success, EINA_FALSE on failure to change version.
Since
1.2
See also
ecore_con_url_pipeline_get()

◆ ecore_con_url_init()

ECORE_CON_API int ecore_con_url_init ( void  )

Initializes the Ecore_Con_Url library.

Returns
Number of times the library has been initialised without being shut down.
Note
This function doesn't call ecore_con_init(). You still need to call it explicitly before calling this one.
Examples
ecore_con_url_cookies_example.c, ecore_con_url_download_example.c, and ecore_con_url_headers_example.c.

References ECORE_CON_EVENT_URL_COMPLETE, ECORE_CON_EVENT_URL_DATA, ECORE_CON_EVENT_URL_PROGRESS, ecore_con_init(), ecore_con_shutdown(), ecore_event_type_new(), ecore_init(), ecore_shutdown(), emile_cipher_init(), emile_init(), and emile_shutdown().

Referenced by elm_quicklaunch_sub_init().

◆ ecore_con_url_shutdown()

ECORE_CON_API int ecore_con_url_shutdown ( void  )

Shuts down the Ecore_Con_Url library.

Returns
Number of calls that still uses Ecore_Con_Url
Note
This function doesn't call ecore_con_shutdown(). You still need to call it explicitly after calling this one.
Examples
ecore_con_url_cookies_example.c, ecore_con_url_download_example.c, and ecore_con_url_headers_example.c.

References ECORE_CON_EVENT_URL_COMPLETE, ECORE_CON_EVENT_URL_DATA, ECORE_CON_EVENT_URL_PROGRESS, ecore_con_shutdown(), ecore_con_url_free(), ecore_event_type_flush, ecore_shutdown(), EINA_LIST_FREE, and emile_shutdown().

Referenced by elm_quicklaunch_sub_shutdown().

◆ ecore_con_url_pipeline_set()

ECORE_CON_API void ecore_con_url_pipeline_set ( Eina_Bool  enable)

Enables or disable HTTP 1.1 pipelining.

Parameters
enableEINA_TRUE will turn it on, EINA_FALSE will disable it.

Pipelining allows to send one request after another one, without having to wait for the reply of the first request. The respective replies are received in the order that the requests were sent.

Enabling this feature will be valid for all requests done using ecore_con_url.

See http://en.wikipedia.org/wiki/HTTP_pipelining for more info.

See also
ecore_con_url_pipeline_get()
Examples
ecore_con_url_headers_example.c.

◆ ecore_con_url_pipeline_get()

ECORE_CON_API Eina_Bool ecore_con_url_pipeline_get ( void  )

Is HTTP 1.1 pipelining enable ?

Returns
EINA_TRUE if it is enable.
See also
ecore_con_url_pipeline_set()
Examples
ecore_con_url_headers_example.c.

◆ ecore_con_url_new()

ECORE_CON_API Ecore_Con_Url * ecore_con_url_new ( const char *  url)

Creates and initializes a new Ecore_Con_Url connection object.

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.

Create and initialize a new Ecore_Con_Url connection object that can be used for sending requests.

See also
ecore_con_url_custom_new()
ecore_con_url_url_set()
Examples
ecore_con_url_cookies_example.c, and ecore_con_url_download_example.c.

References eina_list_append(), EINA_MAGIC_SET, EINA_SAFETY_ON_NULL_RETURN_VAL, and eina_stringshare_add().

Referenced by ecore_con_url_custom_new().

◆ ecore_con_url_url_set()

ECORE_CON_API Eina_Bool ecore_con_url_url_set ( Ecore_Con_Url url_con,
const char *  url 
)

Change the URL assigned to this handle.

Parameters
url_conConnection object to change URL.
urlthe new URL.
Returns
EINA_TRUE on success, EINA_FALSE on errors.

◆ ecore_con_url_url_get()

ECORE_CON_API const char * ecore_con_url_url_get ( Ecore_Con_Url url_con)

Retrieve the URL assigned to this handle.

Parameters
url_conthe Connection object to retrieve URL.
Returns
NULL on error, read-only URL string on success.

◆ ecore_con_url_custom_new()

ECORE_CON_API Ecore_Con_Url * ecore_con_url_custom_new ( const char *  url,
const char *  custom_request 
)

Creates a custom connection object.

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.

Create and initialize 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().

See also
ecore_con_url_new()
ecore_con_url_url_set()
Examples
ecore_con_url_headers_example.c.

References ecore_con_url_new(), EINA_SAFETY_ON_NULL_RETURN_VAL, and eina_stringshare_add().

◆ ecore_con_url_free()

ECORE_CON_API void ecore_con_url_free ( Ecore_Con_Url url_con)

Destroys an Ecore_Con_Url connection object.

Parameters
url_conConnection object to free.
See also
ecore_con_url_new()
Examples
ecore_con_url_cookies_example.c, ecore_con_url_download_example.c, and ecore_con_url_headers_example.c.

Referenced by ecore_con_url_shutdown().

◆ ecore_con_url_data_set()

ECORE_CON_API void ecore_con_url_data_set ( Ecore_Con_Url url_con,
void *  data 
)

Associates data with a connection object.

Parameters
url_conConnection object to associate data.
dataData to be set.

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

See also
ecore_con_url_data_get()
Examples
ecore_con_url_download_example.c.

◆ ecore_con_url_data_get()

ECORE_CON_API void * ecore_con_url_data_get ( Ecore_Con_Url url_con)

Retrieves data associated with a Ecore_Con_Url connection object.

Parameters
url_conConnection object to retrieve data from.
Returns
Data associated with the given object.

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

See also
ecore_con_url_data_set()
Examples
ecore_con_url_download_example.c.

◆ ecore_con_url_additional_header_add()

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

Parameters
url_conConnection object
keyHeader key
valueHeader value

Add an additional header (User-Agent, Content-Type, etc.) to the request connection object. This addition will be valid for only one ecore_con_url_get() or ecore_con_url_post() call.

Some functions like ecore_con_url_time() also add headers to the request.

See also
ecore_con_url_get()
ecore_con_url_post()
ecore_con_url_additional_headers_clear()
Examples
ecore_con_url_cookies_example.c, and ecore_con_url_headers_example.c.

◆ ecore_con_url_additional_headers_clear()

ECORE_CON_API void ecore_con_url_additional_headers_clear ( Ecore_Con_Url url_con)

Cleans additional headers.

Parameters
url_conConnection object to clean additional headers.

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

See also
ecore_con_url_additional_header_add()
ecore_con_url_get()
ecore_con_url_post()

◆ ecore_con_url_response_headers_get()

ECORE_CON_API const Eina_List * ecore_con_url_response_headers_get ( Ecore_Con_Url url_con)

Retrieves headers from last request sent.

Parameters
url_conConnection object to retrieve response headers from.

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

Returns
List of response headers. This list must not be modified by the user.
Examples
ecore_con_url_cookies_example.c, and ecore_con_url_headers_example.c.

◆ ecore_con_url_fd_set()

ECORE_CON_API void ecore_con_url_fd_set ( Ecore_Con_Url url_con,
int  fd 
)

Sets up a file for receiving response data.

Parameters
url_conConnection object to set file
fdFile descriptor associated with the file. A negative value will unset any previously set fd.

Set up 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.

This call can be used to easily setup a file where the downloaded data will be saved.

Examples
ecore_con_url_download_example.c.

◆ ecore_con_url_received_bytes_get()

ECORE_CON_API int ecore_con_url_received_bytes_get ( Ecore_Con_Url url_con)

Retrieves the number of bytes received.

Retrieve 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()
Examples
ecore_con_url_download_example.c.

◆ ecore_con_url_httpauth_set()

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

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.
Attention
Require libcurl >= 7.19.1 to work, otherwise will always return 0.
Examples
ecore_con_url_headers_example.c.

◆ ecore_con_url_get()

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

The request is performed immediately, but you need to setup event handlers for ECORE_CON_EVENT_URL_DATA, ECORE_CON_EVENT_URL_COMPLETE or ECORE_CON_EVENT_URL_PROGRESS to get more information about its result.

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()
Examples
ecore_con_url_cookies_example.c, ecore_con_url_download_example.c, and ecore_con_url_headers_example.c.

◆ ecore_con_url_head()

ECORE_CON_API Eina_Bool ecore_con_url_head ( Ecore_Con_Url url_con)

Sends a HEAD request.

Parameters
url_conConnection object to perform a request on, previously created
Returns
EINA_TRUE on success, EINA_FALSE on error.

The request is performed immediately, but you need to setup event handlers for ECORE_CON_EVENT_URL_COMPLETE or ECORE_CON_EVENT_URL_PROGRESS to get more information about its result.

See also
ecore_con_url_custom_new()
ecore_con_url_additional_headers_clear()
ecore_con_url_additional_header_add()
ecore_con_url_response_headers_get()
ecore_con_url_time()
ecore_con_url_post()
Since
1.14

◆ ecore_con_url_post()

ECORE_CON_API 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). Can be NULL.
lengthPayload length. If -1, rely on automatic length calculation via strlen() on data.
content_typeContent type of the payload (e.g. text/xml). Can be NULL.
Returns
EINA_TRUE on success, EINA_FALSE on error.

The request starts immediately, but you need to setup event handlers for ECORE_CON_EVENT_URL_DATA, ECORE_CON_EVENT_URL_COMPLETE or ECORE_CON_EVENT_URL_PROGRESS to get more information about its result.

This call won't block your main loop.

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()
Examples
ecore_con_url_headers_example.c.

References _Eina_Rw_Slice::mem.

◆ ecore_con_url_time()

ECORE_CON_API void ecore_con_url_time ( Ecore_Con_Url url_con,
Ecore_Con_Url_Time  time_condition,
double  timestamp 
)

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

Parameters
url_conEcore_Con_Url to act upon.
time_conditionCondition to use for HTTP requests.
timestampTime since 1 Jan 1970 to use in the condition.

This function may set the header "If-Modified-Since" or "If-Unmodified-Since", depending on the value of time_condition, with the value timestamp.

See also
ecore_con_url_get()
ecore_con_url_post()
Examples
ecore_con_url_headers_example.c.

◆ ecore_con_url_ftp_upload()

ECORE_CON_API 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, EINA_FALSE otherwise.

Upload filename to an ftp server set in url_con using user and pass to directory upload_dir

◆ ecore_con_url_verbose_set()

ECORE_CON_API void ecore_con_url_verbose_set ( Ecore_Con_Url url_con,
Eina_Bool  verbose 
)

Toggles libcurl's verbose output.

Parameters
url_conEcore_Con_Url instance which will be acted upon.
verboseWhether or not to enable 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.

Examples
ecore_con_url_headers_example.c.

◆ ecore_con_url_ftp_use_epsv_set()

ECORE_CON_API void ecore_con_url_ftp_use_epsv_set ( Ecore_Con_Url url_con,
Eina_Bool  use_epsv 
)

Enables or disables EPSV extension.

Parameters
url_conThe Ecore_Con_Url instance which will be acted upon.
use_epsvBoolean to enable/disable the EPSV extension.

◆ ecore_con_url_cookies_init()

ECORE_CON_API void ecore_con_url_cookies_init ( Ecore_Con_Url url_con)

Enables the cookie engine for subsequent HTTP requests.

Parameters
url_conEcore_Con_Url instance which will be acted upon.

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.
Examples
ecore_con_url_cookies_example.c.

◆ ecore_con_url_cookies_ignore_old_session_set()

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

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.

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.

See also
ecore_con_url_cookies_file_add()
Examples
ecore_con_url_cookies_example.c.

◆ ecore_con_url_cookies_clear()

ECORE_CON_API void ecore_con_url_cookies_clear ( Ecore_Con_Url url_con)

Clears currently loaded cookies.

Parameters
url_conEcore_Con_Url instance which will be acted upon.

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.
The cookie files set by ecore_con_url_cookies_file_add() aren't loaded immediately, just when the request is started. Thus, if you ask to clear the cookies, but has a file already set by that function, the cookies will then be loaded and you will have old cookies set. In order to don't have any old cookie set, you need to don't call ecore_con_url_cookies_file_add() ever on the url_con handler, and call this function to clear any cookie set by a previous request on this handler.
See also
ecore_con_url_cookies_session_clear()
ecore_con_url_cookies_ignore_old_session_set()
Examples
ecore_con_url_cookies_example.c.

◆ ecore_con_url_cookies_session_clear()

ECORE_CON_API void ecore_con_url_cookies_session_clear ( Ecore_Con_Url url_con)

Clears currently loaded session cookies.

Parameters
url_conEcore_Con_Url instance which will be acted upon.

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.
The cookie files set by ecore_con_url_cookies_file_add() aren't loaded immediately, just when the request is started. Thus, if you ask to clear the session cookies, but has a file already set by that function, the session cookies will then be loaded and you will have old cookies set. In order to don't have any old session cookie set, you need to don't call ecore_con_url_cookies_file_add() ever on the url_con handler, and call this function to clear any session cookie set by a previous request on this handler. An easier way to don't use old session cookies is by using the function ecore_con_url_cookies_ignore_old_session_set().
See also
ecore_con_url_cookies_clear()
ecore_con_url_cookies_ignore_old_session_set()
Examples
ecore_con_url_cookies_example.c.

◆ ecore_con_url_cookies_file_add()

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

Parameters
url_conEcore_Con_Url instance which will be acted upon.
file_nameName of the file that will be added to the list.

Files must contain cookies defined according to two possible formats:

Cookies will only be read from this file. If you want to save cookies to a file, use ecore_con_url_cookies_jar_file_set(). Also notice that this function supports the both types of cookie file cited above, while ecore_con_url_cookies_jar_file_set() will save only in the Netscape/Mozilla's 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.
See also
ecore_con_url_cookies_ignore_old_session_set()
ecore_con_url_cookies_jar_file_set()
Examples
ecore_con_url_cookies_example.c.

◆ ecore_con_url_cookies_jar_file_set()

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

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.

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

Cookies will only be saved to this file. If you need to read cookies from a file, use ecore_con_url_cookies_file_add() instead.

Note
This function will initialize the cookie engine if it has not been initialized yet.
See also
ecore_con_url_cookies_jar_write()
Examples
ecore_con_url_cookies_example.c.

◆ ecore_con_url_cookies_jar_write()

ECORE_CON_API void ecore_con_url_cookies_jar_write ( Ecore_Con_Url url_con)

Writes all current cookies to the cookie jar immediately.

Parameters
url_conEcore_Con_Url instance which will be acted upon.

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.
See also
ecore_con_url_cookies_jar_file_set()
Examples
ecore_con_url_cookies_example.c.

◆ ecore_con_url_ssl_verify_peer_set()

ECORE_CON_API void ecore_con_url_ssl_verify_peer_set ( Ecore_Con_Url url_con,
Eina_Bool  verify 
)

Toggle libcurl's verify peer's certificate option.

If verify is EINA_TRUE, libcurl will verify the authenticity of the peer's certificate, otherwise it will not. Default behavior of libcurl is to check peer's certificate.

Parameters
url_conEcore_Con_Url instance which will be acted upon.
verifyWhether or not libcurl will check peer's certificate.
Since
1.1.0

◆ ecore_con_url_ssl_ca_set()

ECORE_CON_API int ecore_con_url_ssl_ca_set ( Ecore_Con_Url url_con,
const char *  ca_path 
)

Set a custom CA to trust for SSL/TLS connections.

Specify the path of a file (in PEM format) containing one or more CA certificate(s) to use for the validation of the server certificate.

This function can also disable CA validation if ca_path is NULL. However, the server certificate still needs to be valid for the connection to succeed (i.e., the certificate must concern the server the connection is made to).

Parameters
url_conConnection object that will use the custom CA.
ca_pathPath to a CA certificate(s) file or NULL to disable CA validation.
Returns
0 on success. When cURL is used, non-zero return values are equal to cURL error codes.

◆ ecore_con_url_proxy_set()

ECORE_CON_API Eina_Bool ecore_con_url_proxy_set ( Ecore_Con_Url url_con,
const char *  proxy 
)

Sets HTTP proxy to use.

The parameter should be a char * to a zero terminated string holding the host name or dotted IP address. To specify port number in this string, append :[port] to the end of the host name. The proxy string may be prefixed with [protocol]:// since any such prefix will be ignored. The proxy's port number may optionally be specified with the separate option. If not specified, libcurl will default to using port 1080 for proxies.

Parameters
url_conConnection object that will use the proxy.
proxyProxy string or NULL to disable
Returns
EINA_TRUE on success, EINA_FALSE on error.
Since
1.2

◆ ecore_con_url_proxy_username_set()

ECORE_CON_API Eina_Bool ecore_con_url_proxy_username_set ( Ecore_Con_Url url_con,
const char *  username 
)

Sets zero terminated username to use for proxy.

If socks protocol is used for proxy, protocol should be socks5 and above.

Parameters
url_conConnection object that will use the proxy.
usernameUsername string.
Returns
EINA_TRUE on success, EINA_FALSE on error.
See also
ecore_con_url_proxy_set()
Since
1.2

◆ ecore_con_url_proxy_password_set()

ECORE_CON_API Eina_Bool ecore_con_url_proxy_password_set ( Ecore_Con_Url url_con,
const char *  password 
)

Sets zero terminated password to use for proxy.

If socks protocol is used for proxy, protocol should be socks5 and above.

Parameters
url_conConnection object that will use the proxy.
passwordPassword string.
Returns
EINA_TRUE on success, EINA_FALSE on error.
See also
ecore_con_url_proxy_set()
Since
1.2

◆ ecore_con_url_timeout_set()

ECORE_CON_API void ecore_con_url_timeout_set ( Ecore_Con_Url url_con,
double  timeout 
)

Sets timeout in seconds.

The maximum time in seconds that you allow the ecore con url transfer operation to take. Normally, name lookups can take a considerable time and limiting operations to less than a few minutes risk aborting perfectly normal operations.

Parameters
url_conConnection object that will use the timeout.
timeouttime in seconds.
See also
ecore_con_url_cookies_jar_file_set()
Since
1.2

◆ ecore_con_url_status_code_get()

ECORE_CON_API int ecore_con_url_status_code_get ( Ecore_Con_Url url_con)

Gets the returned HTTP STATUS code.

This is used to, at any time, try to return the status code for a transmission.

Parameters
url_conConnection object
Returns
A valid HTTP STATUS code, or 0 on failure
Since
1.2
Examples
ecore_con_url_download_example.c.

◆ ecore_con_url_limit_upload_speed()

ECORE_CON_API void ecore_con_url_limit_upload_speed ( Ecore_Con_Url url_obj,
off_t  max_speed 
)

Sets a maximum upload speed.

Parameters
url_objConnection object
max_speedMaximum upload speed, in bytes per second

◆ ecore_con_url_limit_download_speed()

ECORE_CON_API void ecore_con_url_limit_download_speed ( Ecore_Con_Url url_obj,
off_t  max_speed 
)

Sets a maximum download speed.

Parameters
url_objConnection object
max_speedMaximum download speed, in bytes per second