path: root/src/lac.h

/* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- */

/*  Lac - Library for asynchronous communication
 *  Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007
 *        Søren Sandmann (sandmann@daimi.au.dk)
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Library General Public
 *  License as published by the Free Software Foundation; either
 *  version 2 of the License, or (at your option) any later version.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Library General Public License for more details.
 *
 *  You should have received a copy of the GNU Library General Public
 *  License along with this library; if not, write to the 
 *  Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 *  Boston, MA  02111-1307, USA.
 */

#ifndef LAC_H
#define LAC_H

#include <glib.h>
#include <sys/types.h>

G_BEGIN_DECLS

/*
 * Addresses 
 */
#define LAC_DNS_ERROR lac_dns_error_quark ()

GQuark lac_dns_error_quark (void);

typedef enum
{
    LAC_DNS_ERROR_NO_SUCH_NAME,
    LAC_DNS_ERROR_NO_DATA,
    LAC_DNS_ERROR_CNAME_CYCLE,
    LAC_DNS_ERROR_TIMEOUT,
    LAC_DNS_ERROR_SERVER_FAILED,
    LAC_DNS_ERROR_NO_SERVERS_CONFIGURED,
    LAC_DNS_ERROR_MALFORMED_NAME,
    
    LAC_DNS_ERROR_FAILED
} LacDnsError;

typedef struct LacAddress    LacAddress;

typedef void (* LacAddressFunc)	  (const LacAddress *address,
				   gpointer	   data,
                                   const GError     *err);
typedef void (* LacAddressesFunc) (const GPtrArray *addresses,
                                   gpointer         data,
                                   const GError    *err);
typedef void (* LacNameFunc)      (const gchar     *name,
                                   gpointer         data,
                                   const GError    *err);

LacAddress *lac_address_new_from_a_b_c_d          (gchar              a,
                                                   gchar              b,
                                                   gchar              c,
                                                   gchar              d);
LacAddress *lac_address_new_from_string           (const gchar       *str);

void        lac_address_new_lookup_from_name      (const gchar       *name,
                                                   LacAddressFunc     f,
                                                   gpointer           data);
void        lac_address_new_lookup_all_from_name  (const gchar       *name,
                                                   LacAddressesFunc   f,
                                                   gpointer           data);
LacAddress *lac_address_new_from_name_wait        (const gchar       *name,
                                                   GError           **err);
void        lac_address_new_lookup_from_localhost (LacAddressFunc     f,
                                                   gpointer           data);
LacAddress *lac_address_new_from_localhost_wait   (GError           **err);
void        lac_address_lookup_name               (const LacAddress  *addr,
                                                   LacNameFunc        f,
                                                   gpointer           data);
gchar *     lac_address_lookup_name_wait          (const LacAddress  *addr,
                                                   GError           **err);
gchar *     lac_address_to_string                 (const LacAddress  *addr);
guint       lac_address_hash                      (gconstpointer      addr);
gint        lac_address_compare                   (gconstpointer      addr1,
                                                   gconstpointer      addr2);
gboolean    lac_address_equal                     (gconstpointer      addr1,
                                                   gconstpointer      addr2);
LacAddress *lac_address_copy                      (const LacAddress  *addr);
void        lac_address_free                      (LacAddress        *addr);
#ifdef LAC_IPV6_UNSAFE
void        lac_address_get_a_b_c_d               (const LacAddress  *addr,
                                                   gint              *a,
                                                   gint              *b,
                                                   gint              *c,
                                                   gint              *d);
#endif

/*
 * Primitives
 */

#define LAC_SOCKET_ERROR lac_socket_error_quark ()

typedef enum
{
    LAC_SOCKET_ERROR_IN_PROGRESS,
    LAC_SOCKET_ERROR_CONNECTION_REFUSED,
    LAC_SOCKET_ERROR_NET_UNREACHABLE,
    LAC_SOCKET_ERROR_TIMEOUT,
    LAC_SOCKET_ERROR_CONNECTION_RESET,
    
    LAC_SOCKET_ERROR_NO_RESOURCES,
    LAC_SOCKET_ERROR_AGAIN,            /* also known as WOULDBLOCK */
    
    LAC_SOCKET_ERROR_FAILED
} LacError;

GQuark     lac_socket_error_quark      (void);

/* General primitives */
typedef enum {
    LAC_SHUTDOWN_READ	 = 0,
    LAC_SHUTDOWN_WRITE	 = 1,
    LAC_SHUTDOWN_NEITHER = 2
} LacShutdownMethod;

void     lac_sigpipe_ignore  (void);
void     lac_sigpipe_default (void);
gboolean lac_close           (gint                fd,
                              GError            **err);
gboolean lac_shutdown        (gint                fd,
                              LacShutdownMethod   how,
                              GError            **err);
gboolean lac_set_blocking    (gint                fd,
                              gboolean            blocking,
                              GError            **err);
gboolean lac_listen          (gint                fd,
                              guint               backlog,
                              GError            **err);
gint     lac_send            (gint                fd,
                              const gchar        *msg,
                              guint               len,
                              GError            **err);
gint     lac_recv            (gint                fd,
                              gchar              *buf,
                              guint               len,
                              GError            **err);
gint     lac_sendto          (gint                fd,
                              gchar              *buf,
                              guint               len,
                              const LacAddress   *address,
                              gint                port,
                              GError            **err);
gint     lac_recvfrom        (gint                fd,
                              gchar              *buf,
                              guint               len,
                              LacAddress        **address,
                              gint               *port,
                              GError            **err);
gint     lac_socket_tcp      (GError            **err);
gint     lac_socket_udp      (GError            **err);
gboolean lac_set_nagle       (gint                fd,
                              gboolean            use_nagle,
                              GError            **err);
gboolean lac_bind            (gint                fd,
                              const LacAddress   *address,
                              gint                port,
                              GError            **err);
gint     lac_accept          (gint                fd,
                              LacAddress        **addr,
                              gint               *port,
                              GError            **err);
gboolean lac_connect         (gint                fd,
                              const LacAddress   *address,
                              gint                port,
                              GError            **err);
gboolean lac_getpeername     (gint                fd,
                              LacAddress        **addr,
                              gint               *port,
                              GError            **err);
gchar *  lac_gethostname     (void);

/* LacByteQueue */
typedef struct LacByteQueue LacByteQueue;

LacByteQueue *lac_byte_queue_new           (void);
gchar        *lac_byte_queue_free          (LacByteQueue *queue,
                                            gboolean      free_data);
gsize	      lac_byte_queue_get_length    (LacByteQueue *queue);
gboolean      lac_byte_queue_is_empty      (LacByteQueue *queue);
const gchar  *lac_byte_queue_peek          (LacByteQueue *queue,
                                            gsize        *n_bytes);
gchar        *lac_byte_queue_steal         (LacByteQueue *queue,
                                            gsize        *n_bytes);
gchar        *lac_byte_queue_alloc_tail    (LacByteQueue *queue,
                                            gsize	  size);
void	      lac_byte_queue_append        (LacByteQueue *queue,
                                            const gchar  *bytes,
                                            gsize         n_bytes);
void          lac_byte_queue_append_printf (LacByteQueue *queue,
                                            const gchar  *fmt,
                                            ...);
void	      lac_byte_queue_transfer_data (LacByteQueue *dest,
                                            LacByteQueue *src);
void          lac_byte_queue_delete_head   (LacByteQueue *queue,
                                            gsize         size);
void          lac_byte_queue_delete_tail   (LacByteQueue *queue,
                                            gsize	   size);


/* TLS */
typedef struct LacTLS LacTLS;

typedef int (* LacTLSSendFunc) (LacTLS *tls,
                                const guint8 *data,
                                gsize len,
                                GError **err);
typedef int (* LacTLSRecvFunc) (LacTLS *tls,
                                guint8 *data,
                                gsize   buf_size,
                                GError **err);
LacTLS   *lac_tls_new         (int      fd);
LacTLS   *lac_tls_new2        (LacTLSSendFunc   send_func,
                               LacTLSRecvFunc   recv_func,
                               gpointer         data);
gpointer  lac_tls_get_data    (LacTLS *tls);
gboolean  lac_tls_handshake   (LacTLS  *tls,
                               GError **err);
gint	  lac_tls_recv        (LacTLS  *tls,
                               gchar   *buf,
                               guint    len,
                               GError **err);
gint	  lac_tls_send        (LacTLS  *tls,
                               gchar   *buf,
                               guint    len,
                               GError **err);
gboolean  lac_tls_needs_write (LacTLS  *tls);
void	  lac_tls_free        (LacTLS  *tls);


/*
 * Watching file descriptors
 */
typedef void (* LacWatchCallback) (gpointer data);

void     lac_fd_add_watch             (gint             fd,
                                       gpointer         data);
void     lac_fd_set_read_callback     (gint             fd,
                                       LacWatchCallback read_cb);
void     lac_fd_set_write_callback    (gint             fd,
                                       LacWatchCallback write_cb);
void     lac_fd_set_hangup_callback   (gint             fd,
                                       LacWatchCallback hangup_cb);
void     lac_fd_set_error_callback    (gint             fd,
                                       LacWatchCallback error_cb);
void     lac_fd_set_priority_callback (gint             fd,
                                       LacWatchCallback priority_cb);
void     lac_fd_remove_watch          (gint             fd);
gboolean lac_fd_is_watched            (gint             fd);

/*
 * Connection
 */
typedef struct _LacConnection        LacConnection;
typedef union  _LacConnectionEvent   LacConnectionEvent;

typedef enum {
    LAC_CONNECTION_EVENT_CONNECT,  /* connect successful	*/
    LAC_CONNECTION_EVENT_READ,	   /* data to read		*/
    LAC_CONNECTION_EVENT_CLOSE,    /* Connection closed         */
    LAC_CONNECTION_EVENT_ERROR,    /* error                     */
} LacConnectionEventType;

typedef struct {
    LacConnectionEventType type;
} LacConnectionConnectEvent;

typedef struct {
    LacConnectionEventType type;
    gpointer _lac_reserved0;
    gpointer _lac_reserved1;
    LacByteQueue *byte_queue;
    const gchar *data;
    guint len;
} LacConnectionReadEvent;

typedef struct {
    LacConnectionEventType      type;
    gboolean                    remote_closed; /* true: remote closed.
                                                  false: local closed */
} LacConnectionCloseEvent;

typedef struct {
    LacConnectionEventType  type;
    const GError *err;
} LacConnectionErrorEvent;

union _LacConnectionEvent {
    LacConnectionEventType    type;
    LacConnectionConnectEvent connect;
    LacConnectionReadEvent    read;
    LacConnectionCloseEvent   close;
    LacConnectionErrorEvent   error;
};

typedef void (* LacConnectionFunc)  (LacConnection            *connection,
				     const LacConnectionEvent *event);

LacConnection *            lac_connection_new            (const LacAddress  *address,
                                                          gint               port,
                                                          LacConnectionFunc  callback,
                                                          gpointer           data);
gpointer                   lac_connection_get_data       (LacConnection     *connection);
void                       lac_connection_write          (LacConnection     *connection,
                                                          const gchar       *data,
                                                          guint              len);
void                       lac_connection_write_cstr     (LacConnection     *connection,
                                                          const gchar       *data);
void                       lac_connection_shutdown_write (LacConnection     *connection);
LacConnection *            lac_connection_ref            (LacConnection     *connection);
void                       lac_connection_unref          (LacConnection     *connection);
G_CONST_RETURN LacAddress *lac_connection_get_address    (LacConnection     *connection);
gint                       lac_connection_get_port       (LacConnection     *connection);
void                       lac_connection_close          (LacConnection     *connection);
gboolean                   lac_connection_is_connected   (LacConnection     *connection);
void                       lac_connection_flush          (LacConnection     *connection);


/*
 * LacTlsConnection
 */
typedef struct _LacTlsConnection        LacTlsConnection;

typedef void (* LacTlsConnectionFunc)  (LacTlsConnection            *connection,
                                        const LacConnectionEvent *event);

LacTlsConnection *            lac_tls_connection_new            (const LacAddress  *address,
                                                          gint               port,
                                                          LacTlsConnectionFunc  callback,
                                                          gpointer           data);
gpointer                   lac_tls_connection_get_data       (LacTlsConnection     *connection);
void                       lac_tls_connection_write          (LacTlsConnection     *connection,
                                                          const gchar *data,
                                                          guint              len);
void                       lac_tls_connection_write_cstr     (LacTlsConnection     *connection,
                                                          const gchar       *data);
void                       lac_tls_connection_shutdown_write (LacTlsConnection     *connection);
LacTlsConnection *            lac_tls_connection_ref            (LacTlsConnection     *connection);
void                       lac_tls_connection_unref          (LacTlsConnection     *connection);
G_CONST_RETURN LacAddress *lac_tls_connection_get_address    (LacTlsConnection     *connection);
gint                       lac_tls_connection_get_port       (LacTlsConnection     *connection);
void                       lac_tls_connection_close          (LacTlsConnection     *connection);
gboolean                   lac_tls_connection_is_connected   (LacTlsConnection     *connection);
void                       lac_tls_connection_flush          (LacTlsConnection     *connection);

/*
 * LacGenConnection
 */
typedef struct _LacGenConnection LacGenConnection;

typedef void (* LacGenConnectionFunc)  (LacGenConnection            *connection,
                                        const LacConnectionEvent *event);

LacGenConnection *            lac_gen_connection_new_tcp            (const LacAddress  *address,
                                                          gint               port,
                                                          LacGenConnectionFunc  callback,
                                                          gpointer           data);
LacGenConnection *            lac_gen_connection_new_tls (const LacAddress *address,
                                                          gint port,
                                                          LacGenConnectionFunc callback,
                                                          gpointer data);
gpointer                   lac_gen_connection_get_data       (LacGenConnection     *connection);
void                       lac_gen_connection_write          (LacGenConnection     *connection,
                                                          const gchar       *data,
                                                          guint              len);
void                       lac_gen_connection_write_cstr     (LacGenConnection     *connection,
                                                          const gchar       *data);
void                       lac_gen_connection_shutdown_write (LacGenConnection     *connection);
LacGenConnection *            lac_gen_connection_ref            (LacGenConnection     *connection);
void                       lac_gen_connection_unref          (LacGenConnection     *connection);
G_CONST_RETURN LacAddress *lac_gen_connection_get_address    (LacGenConnection     *connection);
gint                       lac_gen_connection_get_port       (LacGenConnection     *connection);
void                       lac_gen_connection_close          (LacGenConnection     *connection);
gboolean                   lac_gen_connection_is_connected   (LacGenConnection     *connection);
void                       lac_gen_connection_flush          (LacGenConnection     *connection);


/*
 * URI
 */
typedef enum {
    LAC_SCHEME_UNKNOWN,  
    LAC_SCHEME_HTTP,
    LAC_SCHEME_FTP,
} LacScheme;

typedef enum {
    LAC_FTP_TYPE_A, 
    LAC_FTP_TYPE_I, 
    LAC_FTP_TYPE_D,
    LAC_FTP_TYPE_NONE,
} LacFtpType;

typedef struct _LacUri LacUri;
struct _LacUri {
    /* all fields are *read-only* */
    LacScheme scheme;
    union {
	struct {
	    gchar *scheme;
	    gchar *authority;
	    gchar *path;
	    gchar *query;
	} unknown;
	struct {
	    gchar *host;
	    guint port;
	    gchar *path;
	    gchar *query;
	} http;
	struct {
	    gchar *host;
	    gchar *username;
	    gchar *password;
	    guint port;
	    gchar *path;
	    LacFtpType type;
	} ftp;
    } u;
    gchar *fragment;
    
    guint checksum;     /* used internally */
};

LacUri * lac_uri_new_from_string (const LacUri *base,
                                  const gchar  *str);
LacUri * lac_uri_copy            (const LacUri *uri);
gchar  * lac_uri_string          (const LacUri *uri);
void     lac_uri_free            (LacUri       *uri);
gboolean lac_uri_equal           (const LacUri *uri1,
                                  const LacUri *uri2);

/*
 * HTTP
 */

GQuark lac_http_error_quark (void);

#define LAC_HTTP_ERROR lac_http_error_quark()

typedef enum {
    LAC_HTTP_ERROR_MALFORMED_RESPONSE,  /* server sent an unparsable message */
    LAC_HTTP_ERROR_PREMATURE_CLOSE,     /* server closed connection before
                                         * sending a complete response
                                         */
    LAC_HTTP_ERROR_PIPELINE_TIMEOUT     /* Some servers have a bug that make them stall
                                         * in the middle of a pipelined response. 
                                         */
} LacHttpError;

typedef struct _LacHttpRequest          LacHttpRequest;
typedef union  _LacHttpEvent            LacHttpEvent;

typedef void (* LacHttpFunc) (LacHttpRequest *request,
                              const LacHttpEvent *event);
LacHttpRequest *lac_http_request_new_get     (const LacUri   *uri,
                                              LacHttpFunc     func,
                                              gpointer        data);
LacHttpRequest *lac_http_request_new_head    (const LacUri   *uri,
                                              LacHttpFunc     func,
                                              gpointer        data);
LacHttpRequest *lac_http_request_new_post    (const LacUri   *uri,
                                              LacHttpFunc     func,
                                              gpointer        data);
LacHttpRequest *lac_http_request_new_put     (const LacUri   *uri,
                                              LacHttpFunc     func,
                                              gpointer        data);
LacHttpRequest *lac_http_request_new_delete  (const LacUri   *uri,
                                              LacHttpFunc     func,
                                              gpointer        data);
void            lac_http_request_add_content (LacHttpRequest *request,
                                              const gchar    *content,
                                              gsize           length);
void            lac_http_request_add_header  (LacHttpRequest *request,
                                              const gchar    *header,
                                              const gchar    *value);
gpointer        lac_http_request_get_data    (LacHttpRequest *request);
void            lac_http_request_dispatch    (LacHttpRequest *request);
void            lac_http_request_cancel      (LacHttpRequest *request);
LacHttpRequest *lac_http_request_ref         (LacHttpRequest *request);
void            lac_http_request_unref       (LacHttpRequest *request);

typedef enum {
    LAC_HTTP_EVENT_HOST_FOUND,          /* dns lookup done                   */
    LAC_HTTP_EVENT_CONNECTING,          /* waiting for connect()             */
    LAC_HTTP_EVENT_SENT,                /* request was sent (not pipelined)  */
    LAC_HTTP_EVENT_STATUS_LINE,         /* received status line              */
    LAC_HTTP_EVENT_NO_STATUS_LINE,      /* received HTTP/0.9 response        */
    LAC_HTTP_EVENT_HEADER,              /* received header                   */
    LAC_HTTP_EVENT_BEGIN_CONTENT,       /* contents starts now               */
    LAC_HTTP_EVENT_CONTENT,             /* a chunk of content                */
    LAC_HTTP_EVENT_END_CONTENT,         /* end of response                   */
    LAC_HTTP_EVENT_NO_CONTENT,          /* response does not contain a body  */
    LAC_HTTP_EVENT_ERROR                /* error                             */
} LacHttpEventType;

typedef struct {
    LacHttpEventType    type;
    const char *        hostname;
    const LacAddress *  address;
} LacHttpHostFoundEvent;

typedef struct {
    LacHttpEventType    type;
    gint                status_code;
    gint                major;          /* major version number */
    gint                minor;          /* minor version number */
    const gchar *       reason_phrase;
} LacHttpStatusLineEvent;

typedef struct {
    LacHttpEventType    type;
} LacHttpNoStatusLineEvent;

typedef struct {
    LacHttpEventType    type;
    const gchar *       header;
    const gchar *       value;
} LacHttpHeaderEvent;

typedef struct {
    LacHttpEventType    type;
    gint                length;         /* total length of content in bytes,
                                         * -1 if unknown
                                         */
} LacHttpBeginContentEvent;

typedef struct {
    LacHttpEventType    type;
    const guint8 *      data;
    gsize               length;
} LacHttpContentEvent;

typedef struct {
    LacHttpEventType    type;
    gint                total;
} LacHttpEndContentEvent;

typedef struct {
    LacHttpEventType    type;
    const GError *      err;
} LacHttpErrorEvent;

union _LacHttpEvent {
    LacHttpEventType            type;
    LacHttpHostFoundEvent       host_found;
    LacHttpStatusLineEvent      status_line;
    LacHttpNoStatusLineEvent    no_status_line;
    LacHttpHeaderEvent          header;
    LacHttpBeginContentEvent    begin_content;
    LacHttpContentEvent         content;
    LacHttpEndContentEvent      end_content;
    LacHttpErrorEvent           error;
};

/* make LAC write lots of spam to stdout */
void     lac_set_verbose (gboolean verbose);

#define lac_debug_checkpoint() lac_debug_out ("reached%s", "")

G_END_DECLS

#endif