You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

2424 lines
88 KiB

#ifndef _ECORE_CON_H
#define _ECORE_CON_H
#include <time.h>
#include <libgen.h>
#ifdef _WIN32
# include <ws2tcpip.h>
#else
# include <netdb.h>
#endif
#include <Eina.h>
#include <Eo.h>
#ifdef EFL_BETA_API_SUPPORT
#include "Efl_Net.h"
#endif
#ifdef EAPI
# undef EAPI
#endif
#ifdef _WIN32
# ifdef EFL_BUILD
# ifdef DLL_EXPORT
# define EAPI __declspec(dllexport)
# else
# define EAPI
# endif
# else
# define EAPI __declspec(dllimport)
# endif
#else
# ifdef __GNUC__
# if __GNUC__ >= 4
# define EAPI __attribute__ ((visibility("default")))
# else
# define EAPI
# endif
# else
# define EAPI
# endif
#endif
/**
* @defgroup Ecore_Con_Group Ecore_Con - Connection functions
* @ingroup Ecore
*
* The Ecore Connection Library ( @c Ecore_Con ) provides simple mechanisms
* for communications between programs using reliable sockets. It saves
* the programmer from having to worry about file descriptors and waiting
* for incoming connections.
*
* There are two main objects in the @c Ecore_Con library: the @c
* Ecore_Con_Server and the @c Ecore_Con_Client.
*
* The @c Ecore_Con_Server represents a server that can be connected to.
* It is used regardless of whether the program is acting as a server or
* client itself.
*
* To create a listening server call @c ecore_con_server_add(), optionally using
* an ECORE_CON_USE_* encryption type OR'ed with the type for encryption.
*
* To connect to a server, call @c ecore_con_server_connect(). Data can
* then be sent to the server using the @c ecore_con_server_send().
*
* Functions are described in the following groupings:
* @li @ref Ecore_Con_Lib_Group
* @li @ref Ecore_Con_Server_Group
* @li @ref Ecore_Con_Client_Group
* @li @ref Ecore_Con_Url_Group
*
* Events are described in @ref Ecore_Con_Events_Group.
*/
/**
* @defgroup Ecore_Con_Events_Group Ecore Connection Events Functions
* @ingroup Ecore_Con_Group
*
* The Ecore Con events can be categorized into Server side events
* and Client side events.
* Server side events:
* @li ECORE_CON_CLIENT_ADD: Whenever a client connection is made to an
* @c Ecore_Con_Server, an event of this type is emitted, allowing the
* retrieval of the client's ip with @ref ecore_con_client_ip_get and
* associating data with the client using ecore_con_client_data_set.
* @li ECORE_CON_EVENT_CLIENT_DEL: Whenever a client connection to an
* @c Ecore_Con_Server is destroyed, an event of this type is emitted. The contents of
* the data with this event are variable, but if the client object in the data
* is non-null, it must be freed with @ref ecore_con_client_del.
* @li ECORE_CON_EVENT_CLIENT_DATA: Whenever a server object receives
* data, then an event of this type is emitted. The data will contain
* the size and contents of the message sent by the client. It should be noted that
* data within this object is transient, so it must be duplicated in order to be
* retained. This event will continue to occur until the client has stopped sending its
* message, so a good option for storing this data is an Eina_Strbuf. Once the message has
* been received in full, the client object must be freed with ecore_con_client_free.
*
* Client side events:
* @li ECORE_CON_EVENT_SERVER_ADD: Whenever a server object is created
* with @ref ecore_con_server_connect, an event of this type is emitted,
* allowing for data to be serialized and sent to the server using
* @ref ecore_con_server_send. At this point, the http handshake has
* occurred.
* @li ECORE_CON_EVENT_SERVER_DEL: Whenever a server object is destroyed,
* usually by the server connection being refused or dropped, an event of this
* type is emitted. The contents of the data with this event are variable,
* but if the server object in the data is non-null, it must be freed
* with @ref ecore_con_server_del.
* @li ECORE_CON_EVENT_SERVER_DATA: Whenever client object receives
* data from the server, an event of this type is emitted. The data will contain both
* the size and contents of the message sent by the server. It should be noted that
* data within this object is transient, so it must be duplicated in order to be
* retained. This event will continue to occur until the server has stopped sending its
* message, so a good option for storing this data is an Eina_Strbuf. Once the message has
* been received in full, the server object must be freed with ecore_con_server_free.
*
*/
/**
* @defgroup Ecore_Con_Buffer Ecore Connection Buffering
* @ingroup Ecore_Con_Group
*
* As Ecore_Con works on an event driven design, as data arrives, events will
* be produced containing the data that arrived. It is up to the user of
* Ecore_Con to either parse as they go, append to a file to later parse the
* whole file in one go, or append to memory to parse or handle later.
*
* To help with this Eina has some handy API's. The Eina_Binbuf and
* Eina_Strbuf APIs, abstract dynamic buffer management and make it trivial
* to handle buffers at runtime, without having to manage them. Eina_Binbuf
* makes it possible to create, expand, reset and slice a blob of memory -
* all via API. No system calls, no pointer manipulations and no size
* calculation.
*
* Additional functions include adding content at specified byte positions in
* the buffer, escaping the inputs, find and replace strings. This provides
* extreme flexibility to play around, with a dynamic blob of memory.
*
* It is good to free it (using eina_binbuf_free()) after using it.
*
* Eina_Binbuf compliments Ecore_Con use cases, where dynamic sizes of data
* arrive from the network (think http download in chunks). Using
* Eina_Binbuf provides enough flexibility to handle data as it arrives and
* to defer its processing until desired, without having to think about
* where to store the temporary data and how to manage its size.
*
* An example of how to use these with Ecore_Con follows.
*
* @code
* #include <Eina.h>
* #include <Ecore.h>
* #include <Ecore_Con.h>
*
* static Eina_Bool
* data_callback(void *data, int type, void *event)
* {
* Ecore_Con_Event_Url_Data *url_data = event;
* if ( url_data->size > 0)
* {
* // append data as it arrives - don't worry where or how it gets stored.
* // Also don't worry about size, expanding, reallocing etc.
* // just keep appending - size is automatically handled.
*
* eina_binbuf_append_length(data, url_data->data, url_data->size);
*
* fprintf(stderr, "Appended %d \n", url_data->size);
* }
* return EINA_TRUE;
* }
*
*
*
* static Eina_Bool
* completion_callback(void *data, int type, void *event)
* {
* Ecore_Con_Event_Url_Complete *url_complete = event;
* printf("download completed with status code: %d\n", url_complete->status);
*
* // get the data back from Eina_Binbuf
* char *ptr = eina_binbuf_string_get(data);
* size_t size = eina_binbuf_length_get(data);
*
* // process data as required (write to file)
* fprintf(stderr, "Size of data = %d bytes\n", size);
* int fd = open("./elm.png", O_CREAT);
* write(fd, ptr, size);
* close(fd);
*
* // free it when done.
* eina_binbuf_free(data);
*
* ecore_main_loop_quit();
*
* return EINA_TRUE;
* }
*
*
* int
* main(int argc, char **argv)
* {
*
* const char *url = "http://www.enlightenment.org/p/index/d/logo.png";
*
* ecore_init();
* ecore_con_init();
* ecore_con_url_init();
*
*
* // This is single additional line to manage dynamic network data.
* Eina_Binbuf *data = eina_binbuf_new();
* Ecore_Con_Url *url_con = ecore_con_url_new(url);
*
* ecore_event_handler_add(ECORE_CON_EVENT_URL_COMPLETE,
* completion_callback,
* data);
* ecore_event_handler_add(ECORE_CON_EVENT_URL_DATA,
* data_callback,
* data);
* ecore_con_url_get(url_con);
*
* ecore_main_loop_begin();
* return 0;
* }
* @endcode
*/
#ifdef __cplusplus
extern "C" {
#endif
#define ECORE_CON_USE_SSL ECORE_CON_USE_SSL2
#define ECORE_CON_REMOTE_SYSTEM ECORE_CON_REMOTE_TCP
/** Types for an ecore_con client/server object. A correct way to set this
* type is with an ECORE_CON_$TYPE, optionally OR'ed with an ECORE_CON_$USE if
* encryption is desired, and LOAD_CERT if the previously loaded certificate
* should be used.
*
* @ingroup Ecore_Con
*/
typedef enum
{
ECORE_CON_LOCAL_USER = 0, /** Socket in "~/.ecore" */
ECORE_CON_LOCAL_SYSTEM = 1, /** Socket in /tmp */
ECORE_CON_LOCAL_ABSTRACT = 2, /** Abstract socket */
ECORE_CON_REMOTE_TCP = 3, /** Remote server using TCP */
ECORE_CON_REMOTE_MCAST = 4, /** Remote multicast UDP server (ecore_con_server_add() only) */
ECORE_CON_REMOTE_UDP = 5, /** Remote server using UDP */
ECORE_CON_REMOTE_BROADCAST = 6, /** Remote broadcast using UDP (ecore_con_server_connect() only) */
ECORE_CON_REMOTE_NODELAY = 7, /** Remote TCP connection sending packets
* immediately */
ECORE_CON_REMOTE_CORK = 8, /** Remote TCP connection sending data in large chunks
* Note: Only available on Linux
*
* @since 1.2 */
ECORE_CON_USE_SSL2 = 16 /* 1 << 4 */, /** Use SSL2: UNSUPPORTED. */
ECORE_CON_USE_SSL3 = 32 /* 1 << 5 */, /** Use SSL3: UNSUPPORTED. */
ECORE_CON_USE_TLS = 64 /* 1 << 6 */, /** Use TLS */
ECORE_CON_USE_MIXED = 96 /* Ecore.Con.Type.use_tls | Ecore.Con.Type.use_ssl3 */, /** Use both TLS and SSL3 */
ECORE_CON_LOAD_CERT = 128 /* 1 << 7 */, /** Attempt to use the loaded
* certificate */
ECORE_CON_NO_PROXY = 256 /* 1 << 8 */, /** Disable all types of proxy on the
* server Note: Only functional for
* clients
*
* @since 1.2 */
ECORE_CON_SOCKET_ACTIVATE = 512 /* 1 << 9 */
} Ecore_Con_Type;
/**
* @typedef Ecore_Con_Socks
* An object representing a SOCKS proxy
* @ingroup Ecore_Con_Socks_Group
* @since 1.2
*/
typedef struct Ecore_Con_Socks Ecore_Con_Socks;
/**
* @defgroup Ecore_Con_Lib_Group Ecore Connection Library Functions
* @ingroup Ecore_Con_Group
*
* Utility functions that set up and shut down the Ecore Connection
* library.
*
* There's also ecore_con_lookup() that can be used to make simple asynchronous
* DNS lookups.
*
* A simple example of how to use these functions:
* @li @ref ecore_con_lookup_example_c
*
* @{
*/
/**
* @typedef Ecore_Con_Dns_Cb
* A callback type for use with @ref ecore_con_lookup.
*/
typedef void (*Ecore_Con_Dns_Cb)(const char *canonname,
const char *ip,
struct sockaddr *addr,
int addrlen,
void *data);
/** @} */
/**
* @struct _Ecore_Con_Server
* Used to provide legacy ABI/ABI compatibility with non-Eo applications.
* @ingroup Ecore_Con_Server_Group
*/
struct _Ecore_Con_Server;
/**
* @typedef Ecore_Con_Server
* Used to provide legacy API/ABI compatibility with non-Eo applications.
* @ingroup Ecore_Con_Server_Group
*/
typedef struct _Ecore_Con_Server Ecore_Con_Server;
/**
* @struct _Ecore_Con_Client
* Used to provide legacy ABI/ABI compatibility with non-Eo applications.
* @ingroup Ecore_Con_Client_Group
*/
struct _Ecore_Con_Client;
/**
* @typedef Ecore_Con_Client
* Used to provide legacy API/ABI compatibility with non-Eo applications.
* @ingroup Ecore_Con_Client_Group
*/
typedef struct _Ecore_Con_Client Ecore_Con_Client;
/**
* @struct _Ecore_Con_Url
* Used to provide legacy ABI/ABI compatibility with non-Eo applications.
* @ingroup Ecore_Con_Url_Group
*/
struct _Ecore_Con_Url;
/**
* @typedef Ecore_Con_Url
* Used to provide legacy API/ABI compatibility with non-Eo applications.
* @ingroup Ecore_Con_Url_Group
*/
typedef struct _Ecore_Con_Url Ecore_Con_Url;
/**
* @addtogroup Ecore_Con_Events_Group
* @{
*/
/**
* @typedef Ecore_Con_Event_Client_Add
* Used as the @p data param for the corresponding event.
*/
typedef struct _Ecore_Con_Event_Client_Add Ecore_Con_Event_Client_Add;
/**
* @typedef Ecore_Con_Event_Client_Upgrade
* Used as the @p data param for the corresponding event.
* @since 1.1
*/
typedef struct _Ecore_Con_Event_Client_Upgrade Ecore_Con_Event_Client_Upgrade;
/**
* @typedef Ecore_Con_Event_Client_Del
* Used as the @p data param for the corresponding event.
*/
typedef struct _Ecore_Con_Event_Client_Del Ecore_Con_Event_Client_Del;
/**
* @typedef Ecore_Con_Event_Client_Error
* Used as the @p data param for the corresponding event.
* @since 1.1
*/
typedef struct _Ecore_Con_Event_Client_Error Ecore_Con_Event_Client_Error;
/**
* @typedef Ecore_Con_Event_Server_Add
* Used as the @p data param for the corresponding event.
*/
typedef struct _Ecore_Con_Event_Server_Add Ecore_Con_Event_Server_Add;
/**
* @typedef Ecore_Con_Event_Server_Upgrade
* Used as the @p data param for the corresponding event.
* @since 1.1
*/
typedef struct _Ecore_Con_Event_Server_Upgrade Ecore_Con_Event_Server_Upgrade;
/**
* @typedef Ecore_Con_Event_Server_Del
* Used as the @p data param for the corresponding event.
*/
typedef struct _Ecore_Con_Event_Server_Del Ecore_Con_Event_Server_Del;
/**
* @typedef Ecore_Con_Event_Server_Error
* Used as the @p data param for the corresponding event.
* @since 1.1
*/
typedef struct _Ecore_Con_Event_Server_Error Ecore_Con_Event_Server_Error;
/**
* @typedef Ecore_Con_Event_Client_Data
* Used as the @p data param for the corresponding event.
*/
typedef struct _Ecore_Con_Event_Client_Data Ecore_Con_Event_Client_Data;
/**
* @typedef Ecore_Con_Event_Server_Data
* Used as the @p data param for the corresponding event.
*/
typedef struct _Ecore_Con_Event_Server_Data Ecore_Con_Event_Server_Data;
/**
* @typedef Ecore_Con_Event_Client_Write
* Used as the @p data param for the corresponding event.
* @since 1.1
*/
typedef struct _Ecore_Con_Event_Client_Write Ecore_Con_Event_Client_Write;
/**
* @typedef Ecore_Con_Event_Server_Write
* Used as the @p data param for the corresponding event.
* @since 1.1
*/
typedef struct _Ecore_Con_Event_Server_Write Ecore_Con_Event_Server_Write;
/**
* @typedef Ecore_Con_Event_Proxy_Bind
* Used as the @p data param for the corresponding event.
* @since 1.2
*/
typedef struct _Ecore_Con_Event_Proxy_Bind Ecore_Con_Event_Proxy_Bind;
/**
* @typedef Ecore_Con_Event_Url_Data
* Used as the @p data param for the corresponding event.
* @ingroup Ecore_Con_Url_Group
*/
typedef struct _Ecore_Con_Event_Url_Data Ecore_Con_Event_Url_Data;
/**
* @typedef Ecore_Con_Event_Url_Complete
* Used as the @p data param for the corresponding event.
* @ingroup Ecore_Con_Url_Group
*/
typedef struct _Ecore_Con_Event_Url_Complete Ecore_Con_Event_Url_Complete;
/**
* @typedef Ecore_Con_Event_Url_Progress
* Used as the @p data param for the corresponding event.
* @ingroup Ecore_Con_Url_Group
*/
typedef struct _Ecore_Con_Event_Url_Progress Ecore_Con_Event_Url_Progress;
/**
* @struct _Ecore_Con_Event_Client_Add
* Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_ADD event.
*/
struct _Ecore_Con_Event_Client_Add
{
Ecore_Con_Client *client; /**< the client that connected */
};
/**
* @struct _Ecore_Con_Event_Client_Upgrade
* Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_UPGRADE event.
* @since 1.1
*/
struct _Ecore_Con_Event_Client_Upgrade
{
Ecore_Con_Client *client; /**< the client that completed handshake */
};
/**
* @struct _Ecore_Con_Event_Client_Del
* Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_DEL event.
*/
struct _Ecore_Con_Event_Client_Del
{
Ecore_Con_Client *client; /**< the client that was lost */
};
/**
* @struct _Ecore_Con_Event_Client_Error
* Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_ERROR event.
*/
struct _Ecore_Con_Event_Client_Error
{
Ecore_Con_Client *client; /**< the client for which an error occurred */
char *error; /**< the error string describing what happened */
};
/**
* @struct _Ecore_Con_Event_Server_Add
* Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_ADD event.
*/
struct _Ecore_Con_Event_Server_Add
{
Ecore_Con_Server *server; /**< the server that was connected to */
};
/**
* @struct _Ecore_Con_Event_Server_Upgrade
* Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_UPGRADE event.
* @since 1.1
*/
struct _Ecore_Con_Event_Server_Upgrade
{
Ecore_Con_Server *server; /**< the server that was connected to */
};
/**
* @struct _Ecore_Con_Event_Server_Del
* Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_DEL event.
*/
struct _Ecore_Con_Event_Server_Del
{
Ecore_Con_Server *server; /**< the client that was lost */
};
/**
* @struct _Ecore_Con_Event_Server_Error
* Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_ERROR event.
*/
struct _Ecore_Con_Event_Server_Error
{
Ecore_Con_Server *server; /**< the server for which an error occurred */
char *error; /**< the error string describing what happened */
};
/**
* @struct _Ecore_Con_Event_Client_Data
* Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_DATA event.
*/
struct _Ecore_Con_Event_Client_Data
{
Ecore_Con_Client *client; /**< the client that connected */
void *data; /**< the data that the client sent */
int size; /**< the length of the data sent */
};
/**
* @struct _Ecore_Con_Event_Server_Data
* Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_DATA event
*/
struct _Ecore_Con_Event_Server_Data
{
Ecore_Con_Server *server; /**< the server that was connected to */
void *data; /**< the data that the server sent */
int size; /**< the length of the data sent */
};
/**
* @struct _Ecore_Con_Event_Client_Write
* Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_WRITE event.
*/
struct _Ecore_Con_Event_Client_Write
{
Ecore_Con_Client *client; /**< the client that connected */
int size; /**< the length of the data sent */
};
/**
* @struct _Ecore_Con_Event_Server_Write
* Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_WRITE event
*/
struct _Ecore_Con_Event_Server_Write
{
Ecore_Con_Server *server; /**< the server that was connected to */
int size; /**< the length of the data sent */
};
/**
* @struct _Ecore_Con_Event_Proxy_Bind
* Used as the @p data param for the @ref ECORE_CON_EVENT_PROXY_BIND event.
* @ingroup Ecore_Con_Socks_Group
* @since 1.2
*/
struct _Ecore_Con_Event_Proxy_Bind
{
Ecore_Con_Server *server; /**< the server object connected to the proxy */
const char *ip; /**< the proxy-bound ip address */
int port; /**< the proxy-bound port */
};
/**
* @struct _Ecore_Con_Event_Url_Data
* Used as the @p data param for the @ref ECORE_CON_EVENT_URL_DATA event.
* @ingroup Ecore_Con_Url_Group
*/
struct _Ecore_Con_Event_Url_Data
{
Ecore_Con_Url *url_con; /**< a pointer to the connection object */
int size; /**< the size of the current received data (in bytes) */
unsigned char data[1]; /**< the data received on this event */
};
/**
* @struct _Ecore_Con_Event_Url_Complete
* Used as the @p data param for the @ref ECORE_CON_EVENT_URL_COMPLETE event.
* @ingroup Ecore_Con_Url_Group
*/
struct _Ecore_Con_Event_Url_Complete
{
Ecore_Con_Url *url_con; /**< a pointer to the connection object */
int status; /**< HTTP status code of the operation (200, 404, 401, etc.) */
};
/**
* @struct _Ecore_Con_Event_Url_Progress
* Used as the @p data param for the @ref ECORE_CON_EVENT_URL_PROGRESS event.
* @ingroup Ecore_Con_Url_Group
*/
struct _Ecore_Con_Event_Url_Progress
{
Ecore_Con_Url *url_con; /**< a pointer to the connection object */
struct
{
double total; /**< total size of the downloading data (in bytes) */
double now; /**< current size of the downloading data (in bytes) */
} down; /**< download info */
struct
{
double total; /**< total size of the uploading data (in bytes) */
double now; /**< current size of the uploading data (in bytes) */
} up; /**< upload info */
};
/** A client has connected to the server. */
EAPI extern int ECORE_CON_EVENT_CLIENT_ADD;
/** A client has disconnected from the server. */
EAPI extern int ECORE_CON_EVENT_CLIENT_DEL;
/** A client experienced an error.
* @since 1.1
*/
EAPI extern int ECORE_CON_EVENT_CLIENT_ERROR;
/** A client connection has been upgraded to SSL.
* @since 1.1
*/
EAPI extern int ECORE_CON_EVENT_CLIENT_UPGRADE;
/** A server was created. */
EAPI extern int ECORE_CON_EVENT_SERVER_ADD;
/** A server connection was lost. */
EAPI extern int ECORE_CON_EVENT_SERVER_DEL;
/** A server experienced an error.
* @since 1.1
*/
EAPI extern int ECORE_CON_EVENT_SERVER_ERROR;
/** A server connection has been upgraded to SSL.
* @since 1.1
*/
EAPI extern int ECORE_CON_EVENT_SERVER_UPGRADE;
/** A server connection has sent data to its client.
* @since 1.1
*/
EAPI extern int ECORE_CON_EVENT_CLIENT_WRITE;
/** A server connection object has sent data.
* @since 1.1
*/
EAPI extern int ECORE_CON_EVENT_SERVER_WRITE;
/** A client connected to the server has sent data. */
EAPI extern int ECORE_CON_EVENT_CLIENT_DATA;
/** A server connection object has data.*/
EAPI extern int ECORE_CON_EVENT_SERVER_DATA;
/** A server connection has successfully negotiated an ip:port binding.
* @since 1.2
*/
EAPI extern int ECORE_CON_EVENT_PROXY_BIND;
/** A URL object has data. */
EAPI extern int ECORE_CON_EVENT_URL_DATA;
/** A URL object has completed its transfer to and from the server and can be reused. */
EAPI extern int ECORE_CON_EVENT_URL_COMPLETE;
/** A URL object has made progress in its transfer. */
EAPI extern int ECORE_CON_EVENT_URL_PROGRESS;
/**
* @}
*/
/**
* @addtogroup Ecore_Con_Lib_Group
* @ingroup Ecore_Con_Group
*
* @{
*/
/**
* @brief Initializes the Ecore_Con library.
* @return Number of times the library has been initialised without being
* shut down.
*
* @note This function already calls ecore_init() internally, so you don't need
* to call it explicitly.
*/
EAPI int ecore_con_init(void);
/**
* @brief Shuts down the Ecore_Con library.
* @return Number of times the library has been initialised without being
* shut down.
* @note This function already calls ecore_shutdown() internally, so you don't
* need to call it explicitly unless you called ecore_init() explicitly too.
*/
EAPI int ecore_con_shutdown(void);
/**
* @brief Do an asynchronous DNS lookup.
*
* This function performs a DNS lookup on the hostname specified by name, then
* calls done_cb with the result and the data given as parameter. The result
* will be given to the done_cb as follows: