src/lib/ecore_con/Ecore_Con.h

   1 #ifndef _ECORE_CON_H
   2 #define _ECORE_CON_H
   3
   4 #include <time.h>
   5 #include <libgen.h>
   6 #ifdef _WIN32
   7 # include <ws2tcpip.h>
   8 #else
   9 # include <netdb.h>
  10 #endif
  11 #include <Eina.h>
  12
  13 #ifdef EAPI
  14 # undef EAPI
  15 #endif
  16
  17 #ifdef _MSC_VER
  18 # ifdef BUILDING_DLL
  19 #  define EAPI __declspec(dllexport)
  20 # else
  21 #  define EAPI __declspec(dllimport)
  22 # endif
  23 #else
  24 # ifdef __GNUC__
  25 #  if __GNUC__ >= 4
  26 #   define EAPI __attribute__ ((visibility("default")))
  27 #  else
  28 #   define EAPI
  29 #  endif
  30 # else
  31 #  define EAPI
  32 # endif
  33 #endif
  34
  35 /**
  36  * @file Ecore_Con.h
  37  * @brief Sockets functions.
  38  *
  39  * The Ecore Connection Library ( @c Ecore_Con ) provides simple mechanisms
  40  * for communications between programs using reliable sockets.  It saves
  41  * the programmer from having to worry about file descripters and waiting
  42  * for incoming connections.
  43  *
  44  * There are two main objects in the @c Ecore_Con library: the @c
  45  * Ecore_Con_Server and the @c Ecore_Con_Client.
  46  *
  47  * The @c Ecore_Con_Server represents a server that can be connected to.
  48  * It is used regardless of whether the program is acting as a server or
  49  * client itself.
  50  *
  51  * To create a listening server call @c ecore_con_server_add(), optionally using
  52  * an ECORE_CON_USE_* encryption type OR'ed with the type for encryption.
  53  *
  54  * To connect to a server, call @c ecore_con_server_connect().  Data can
  55  * then be sent to the server using the @c ecore_con_server_send().
  56  *
  57  * Functions are described in the following groupings:
  58  * @li @ref Ecore_Con_Lib_Group
  59  * @li @ref Ecore_Con_Server_Group
  60  * @li @ref Ecore_Con_Client_Group
  61  * @li @ref Ecore_Con_Url_Group
  62  *
  63  * Events are described in @ref Ecore_Con_Events_Group.
  64  */
  65
  66
  67 /**
  68  * @addtogroup Ecore_Con_Events_Group Events
  69  *
  70  * @li @ref ECORE_CON_CLIENT_ADD: Whenever a client connection is made to an
  71  * @c Ecore_Con_Server, an event of this type is emitted, allowing the
  72  * retrieval of the client's ip with @ref ecore_con_client_ip_get and
  73  * associating data with the client using ecore_con_client_data_set.
  74  * @li @ref ECORE_CON_EVENT_CLIENT_DEL: Whenever a client connection to an
  75  * @c Ecore_Con_Server, an event of this type is emitted.  The contents of
  76  * the data with this event are variable, but if the client object in the data
  77  * is non-null, it must be freed with @ref ecore_con_client_del.
  78  * @li @ref ECORE_CON_EVENT_SERVER_ADD: Whenever a server object is created
  79  * with @ref ecore_con_server_connect, an event of this type is emitted,
  80  * allowing for data to be serialized and sent to the server using
  81  * @ref ecore_con_server_send. At this point, the http handshake has
  82  * occurred.
  83  * @li @ref ECORE_CON_EVENT_SERVER_DEL: Whenever a server object is destroyed,
  84  * usually by the server connection being refused or dropped, an event of this
  85  * type is emitted.  The contents of the data with this event are variable,
  86  * but if the server object in the data is non-null, it must be freed
  87  * with @ref ecore_con_server_del.
  88  * @li @ref ECORE_CON_EVENT_CLIENT_DATA: Whenever a client connects to your server
  89  * object and sends data, an event of this type is emitted.  The data will contain both
  90  * the size and contents of the message sent by the client.  It should be noted that
  91  * data within this object is transient, so it must be duplicated in order to be
  92  * retained.  This event will continue to occur until the client has stopped sending its
  93  * message, so a good option for storing this data is an Eina_Strbuf.  Once the message has
  94  * been recieved in full, the client object must be freed with @ref ecore_con_client_free.
  95  * @li @ref ECORE_CON_EVENT_SERVER_DATA: Whenever your server object connects to its destination
  96  * and receives data, an event of this type is emitted.  The data will contain both
  97  * the size and contents of the message sent by the server.  It should be noted that
  98  * data within this object is transient, so it must be duplicated in order to be
  99  * retained.  This event will continue to occur until the server has stopped sending its
 100  * message, so a good option for storing this data is an Eina_Strbuf.  Once the message has
 101  * been recieved in full, the server object must be freed with @ref ecore_con_server_free.
 102  *
 103  */
 104
 105 #ifdef __cplusplus
 106 extern "C" {
 107 #endif
 108
 109 /** @typedef Ecore_Con_Server
 110  * A connection handle to a server
 111  */
 112 typedef struct _Ecore_Con_Server Ecore_Con_Server;
 113 /** @typedef Ecore_Con_Client
 114  * A connection handle to a client
 115  */
 116 typedef struct _Ecore_Con_Client Ecore_Con_Client;
 117 /** @typedef Ecore_Con_Url
 118  * A handle to an http upload/download object
 119  */
 120 typedef struct _Ecore_Con_Url Ecore_Con_Url;
 121
 122 /**
 123  * @typedef Ecore_Con_Dns_Cb
 124  * A callback type for use with @ref ecore_con_lookup.
 125  */
 126 typedef void (*Ecore_Con_Dns_Cb)(const char *canonname,
 127                                  const char *ip,
 128                                  struct sockaddr *addr,
 129                                  int addrlen,
 130                                  void *data);
 131
 132 /**
 133  * @typedef Ecore_Con_Type
 134  * @enum _Ecore_Con_Type
 135  * Types for an ecore_con client/server object.  A correct way to set this type is
 136  * with an ECORE_CON_$TYPE, optionally OR'ed with an ECORE_CON_$USE if encryption is desired,
 137  * and LOAD_CERT if the previously loaded certificate should be used.
 138  * @example ECORE_CON_REMOTE_TCP | ECORE_CON_USE_TLS | ECORE_CON_LOAD_CERT
 139  */
 140 typedef enum _Ecore_Con_Type
 141 {
 142    /** Socket in ~/.ecore */
 143    ECORE_CON_LOCAL_USER = 0,
 144    /** Socket in /tmp */
 145    ECORE_CON_LOCAL_SYSTEM = 1,
 146    /** Abstract socket */
 147    ECORE_CON_LOCAL_ABSTRACT = 2,
 148    /** Remote server using TCP */
 149    ECORE_CON_REMOTE_TCP = 3,
 150    /** Remote multicast server */
 151    ECORE_CON_REMOTE_MCAST = 4,
 152    /** Remote server using UDP */
 153    ECORE_CON_REMOTE_UDP = 5,
 154    /** Remote broadcast using UDP */
 155    ECORE_CON_REMOTE_BROADCAST = 6,
 156    ECORE_CON_REMOTE_NODELAY = 7,
 157    /** Use SSL2: UNSUPPORTED. **/
 158    ECORE_CON_USE_SSL2 = (1 << 4),
 159    /** Use SSL3 */
 160    ECORE_CON_USE_SSL3 = (1 << 5),
 161    /** Use TLS */
 162    ECORE_CON_USE_TLS = (1 << 6),
 163    /** Attempt to use the previously loaded certificate */
 164    ECORE_CON_LOAD_CERT = (1 << 7)
 165 } Ecore_Con_Type;
 166 #define ECORE_CON_USE_SSL ECORE_CON_USE_SSL2
 167 #define ECORE_CON_REMOTE_SYSTEM ECORE_CON_REMOTE_TCP
 168
 169 /**
 170  * @typedef Ecore_Con_Url_Time
 171  * @enum _Ecore_Con_Url_Time
 172  * The type of time in the object
 173  */
 174 typedef enum _Ecore_Con_Url_Time
 175 {
 176    ECORE_CON_URL_TIME_NONE = 0,
 177    ECORE_CON_URL_TIME_IFMODSINCE,
 178    ECORE_CON_URL_TIME_IFUNMODSINCE,
 179    ECORE_CON_URL_TIME_LASTMOD
 180 } Ecore_Con_Url_Time;
 181
 182 /**
 183  * @addtogroup Ecore_Con_Events_Group Events
 184  * @{
 185  */
 186
 187 /** @typedef Ecore_Con_Event_Client_Add
 188  * Used as the @p data param for the corresponding event
 189  */
 190 typedef struct _Ecore_Con_Event_Client_Add Ecore_Con_Event_Client_Add;
 191 /** @typedef Ecore_Con_Event_Client_Del
 192  * Used as the @p data param for the corresponding event
 193  */
 194 typedef struct _Ecore_Con_Event_Client_Del Ecore_Con_Event_Client_Del;
 195 /** @typedef Ecore_Con_Event_Server_Add
 196  * Used as the @p data param for the corresponding event
 197  */
 198 typedef struct _Ecore_Con_Event_Server_Add Ecore_Con_Event_Server_Add;
 199 /** @typedef Ecore_Con_Event_Server_Del
 200  * Used as the @p data param for the corresponding event
 201  */
 202 typedef struct _Ecore_Con_Event_Server_Del Ecore_Con_Event_Server_Del;
 203 /** @typedef Ecore_Con_Event_Client_Data
 204  * Used as the @p data param for the corresponding event
 205  */
 206 typedef struct _Ecore_Con_Event_Client_Data Ecore_Con_Event_Client_Data;
 207 /** @typedef Ecore_Con_Event_Server_Data
 208  * Used as the @p data param for the corresponding event
 209  */
 210 typedef struct _Ecore_Con_Event_Server_Data Ecore_Con_Event_Server_Data;
 211 /** @typedef Ecore_Con_Event_Url_Data
 212  * Used as the @p data param for the corresponding event
 213  */
 214 typedef struct _Ecore_Con_Event_Url_Data Ecore_Con_Event_Url_Data;
 215 /** @typedef Ecore_Con_Event_Url_Complete
 216  * Used as the @p data param for the corresponding event
 217  */
 218 typedef struct _Ecore_Con_Event_Url_Complete Ecore_Con_Event_Url_Complete;
 219 /** @typedef Ecore_Con_Event_Url_Progress
 220  * Used as the @p data param for the corresponding event
 221  */
 222 typedef struct _Ecore_Con_Event_Url_Progress Ecore_Con_Event_Url_Progress;
 223
 224 /**
 225  * @struct _Ecore_Con_Event_Client_Add
 226  * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_ADD event
 227  */
 228 struct _Ecore_Con_Event_Client_Add
 229 {
 230    Ecore_Con_Client *client; /** the client that connected */
 231 };
 232
 233 /**
 234  * @struct _Ecore_Con_Event_Client_Del
 235  * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_DEL event
 236  */
 237 struct _Ecore_Con_Event_Client_Del
 238 {
 239    Ecore_Con_Client *client; /** the client that was lost */
 240 };
 241
 242 /**
 243  * @struct _Ecore_Con_Event_Server_Add
 244  * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_ADD event
 245  */
 246 struct _Ecore_Con_Event_Server_Add
 247 {
 248    Ecore_Con_Server *server; /** the server that was connected to */
 249 };
 250
 251 /**
 252  * @struct _Ecore_Con_Event_Server_Del
 253  * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_DEL event
 254  */
 255 struct _Ecore_Con_Event_Server_Del
 256 {
 257    Ecore_Con_Server *server; /** the client that was lost */
 258 };
 259
 260 /**
 261  * @struct _Ecore_Con_Event_Client_Data
 262  * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_DATA event
 263  */
 264 struct _Ecore_Con_Event_Client_Data
 265 {
 266  /** the client that connected */
 267    Ecore_Con_Client *client;
 268    /** the data that the client sent */
 269    void *data;
 270    /** the length of the data sent */
 271    int size;
 272 };
 273
 274 /**
 275  * @struct _Ecore_Con_Event_Server_Data
 276  * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_DATA event
 277  */
 278 struct _Ecore_Con_Event_Server_Data
 279 {
 280  /** the server that was connected to */
 281    Ecore_Con_Server *server;
 282    /** the data that the server sent */
 283    void *data;
 284    /** the length of the data sent */
 285    int size;
 286 };
 287
 288 /**
 289  * @struct _Ecore_Con_Event_Url_Data
 290  * Used as the @p data param for the @ref ECORE_CON_EVENT_URL_DATA event
 291  */
 292 struct _Ecore_Con_Event_Url_Data
 293 {
 294    Ecore_Con_Url *url_con;
 295    int size;
 296    unsigned char data[1];
 297 };
 298
 299 /**
 300  * @struct _Ecore_Con_Event_Url_Complete
 301  * Used as the @p data param for the @ref ECORE_CON_EVENT_URL_COMPLETE event
 302  */
 303 struct _Ecore_Con_Event_Url_Complete
 304 {
 305    Ecore_Con_Url *url_con;
 306    int status;
 307 };
 308
 309 /**
 310  * @struct _Ecore_Con_Event_Url_Progress
 311  * Used as the @p data param for the @ref ECORE_CON_EVENT_URL_PROGRESS event
 312  */
 313 struct _Ecore_Con_Event_Url_Progress
 314 {
 315    Ecore_Con_Url *url_con;
 316    struct
 317    {
 318       double total;
 319       double now;
 320    } down;
 321    struct
 322    {
 323       double total;
 324       double now;
 325    } up;
 326 };
 327
 328 /** A client has connected to the server */
 329 EAPI extern int ECORE_CON_EVENT_CLIENT_ADD;
 330 /** A client has disconnected from the server */
 331 EAPI extern int ECORE_CON_EVENT_CLIENT_DEL;
 332 /** A server was created */
 333 EAPI extern int ECORE_CON_EVENT_SERVER_ADD;
 334 /** A server connection was lost */
 335 EAPI extern int ECORE_CON_EVENT_SERVER_DEL;
 336 /** A client connected to the server has sent data */
 337 EAPI extern int ECORE_CON_EVENT_CLIENT_DATA;
 338 /** A server connection object has data */
 339 EAPI extern int ECORE_CON_EVENT_SERVER_DATA;
 340 /** A URL object has data */
 341 EAPI extern int ECORE_CON_EVENT_URL_DATA;
 342 /** A URL object has completed its transfer to and from the server and can be reused */
 343 EAPI extern int ECORE_CON_EVENT_URL_COMPLETE;
 344 /** A URL object has made progress in its transfer */
 345 EAPI extern int ECORE_CON_EVENT_URL_PROGRESS;
 346 /**
 347  * @}
 348  */
 349 EAPI int               ecore_con_init(void);
 350 EAPI int               ecore_con_shutdown(void);
 351 EAPI Eina_Bool         ecore_con_server_ssl_cert_add(const char *cert);
 352 EAPI Eina_Bool         ecore_con_client_ssl_cert_add(const char *cert_file,
 353                                                      const char *crl_file,
 354                                                      const char *key_file);
 355
 356 EAPI Ecore_Con_Server *ecore_con_server_add(Ecore_Con_Type type,
 357                                             const char *name, int port,
 358                                             const void *data);
 359
 360 EAPI Ecore_Con_Server *ecore_con_server_connect(Ecore_Con_Type type,
 361                                                 const char *name, int port,
 362                                                 const void *data);
 363 EAPI void *            ecore_con_server_del(Ecore_Con_Server *svr);
 364 EAPI void *            ecore_con_server_data_get(Ecore_Con_Server *svr);
 365 EAPI void *            ecore_con_server_data_set(Ecore_Con_Server *svr,
 366                                                  void *data);
 367 EAPI int               ecore_con_server_connected_get(Ecore_Con_Server *svr);
 368 EAPI Eina_List *       ecore_con_server_clients_get(Ecore_Con_Server *svr);
 369 EAPI int               ecore_con_server_send(Ecore_Con_Server *svr,
 370                                              const void *data,
 371                                              int size);
 372 EAPI void              ecore_con_server_client_limit_set(
 373    Ecore_Con_Server *svr,
 374    int client_limit,
 375    char
 376    reject_excess_clients);
 377 EAPI const char *      ecore_con_server_ip_get(Ecore_Con_Server *svr);
 378 EAPI void              ecore_con_server_flush(Ecore_Con_Server *svr);
 379
 380 EAPI int               ecore_con_client_send(Ecore_Con_Client *cl,
 381                                              const void *data,
 382                                              int size);
 383 EAPI Ecore_Con_Server *ecore_con_client_server_get(Ecore_Con_Client *cl);
 384 EAPI void *            ecore_con_client_del(Ecore_Con_Client *cl);
 385 EAPI void              ecore_con_client_data_set(Ecore_Con_Client *cl,
 386                                                  const void *data);
 387 EAPI void *            ecore_con_client_data_get(Ecore_Con_Client *cl);
 388 EAPI const char *      ecore_con_client_ip_get(Ecore_Con_Client *cl);
 389 EAPI void              ecore_con_client_flush(Ecore_Con_Client *cl);
 390
 391 EAPI int               ecore_con_ssl_available_get(void);
 392
 393 EAPI int               ecore_con_url_init(void);
 394 EAPI int               ecore_con_url_shutdown(void);
 395 EAPI Ecore_Con_Url *   ecore_con_url_new(const char *url);
 396 EAPI Ecore_Con_Url *   ecore_con_url_custom_new(const char *url,
 397                                                 const char *custom_request);
 398 EAPI void              ecore_con_url_destroy(Ecore_Con_Url *url_con);
 399 EAPI void              ecore_con_url_data_set(Ecore_Con_Url *url_con,
 400                                               void *data);
 401 EAPI void *            ecore_con_url_data_get(Ecore_Con_Url *url_con);
 402 EAPI void              ecore_con_url_additional_header_add(
 403    Ecore_Con_Url *url_con,
 404    const char *key,
 405    const char *value);
 406 EAPI void              ecore_con_url_additional_headers_clear(
 407    Ecore_Con_Url *url_con);
 408 EAPI const Eina_List * ecore_con_url_response_headers_get(
 409    Ecore_Con_Url *url_con);
 410 EAPI int               ecore_con_url_url_set(Ecore_Con_Url *url_con,
 411                                              const char *url);
 412 EAPI void              ecore_con_url_fd_set(Ecore_Con_Url *url_con, int fd);
 413 EAPI int               ecore_con_url_received_bytes_get(Ecore_Con_Url *url_con);
 414 EAPI int               ecore_con_url_httpauth_set(Ecore_Con_Url *url_con,
 415                                                   const char *username,
 416                                                   const char *password,
 417                                                   Eina_Bool safe);
 418 EAPI int               ecore_con_url_send(Ecore_Con_Url *url_con,
 419                                           const void *data, size_t length,
 420                                           const char *content_type);
 421 EAPI void              ecore_con_url_time(Ecore_Con_Url *url_con,
 422                                           Ecore_Con_Url_Time condition,
 423                                           time_t tm);
 424
 425 EAPI Eina_Bool         ecore_con_lookup(const char *name,
 426                                         Ecore_Con_Dns_Cb done_cb,
 427                                         const void *data);
 428
 429 EAPI int               ecore_con_url_ftp_upload(Ecore_Con_Url *url_con,
 430                                                 const char *filename,
 431                                                 const char *user,
 432                                                 const char *pass,
 433                                                 const char *upload_dir);
 434 EAPI void              ecore_con_url_verbose_set(Ecore_Con_Url *url_con,
 435                                                  int verbose);
 436 EAPI void              ecore_con_url_ftp_use_epsv_set(Ecore_Con_Url *url_con,
 437                                                       int use_epsv);
 438 EAPI int               ecore_con_url_http_post_send(Ecore_Con_Url *url_con,
 439                                                     void *curl_httppost);
 440
 441 #ifdef __cplusplus
 442 }
 443 #endif
 444
 445 #endif