## Conn

Conn — TCP connection object

## Synopsis

    #include <gnet.h>

                        GConn;
                        GConnEvent;
    enum                GConnEventType;
    void                (*GConnFunc)                        (GConn *conn,
                                                             GConnEvent *event,
                                                             gpointer user_data);
    GConn*              gnet_conn_new                       (const gchar *hostname,
                                                             gint port,
                                                             GConnFunc func,
                                                             gpointer user_data);
    GConn*              gnet_conn_new_inetaddr              (const GInetAddr *inetaddr,
                                                             GConnFunc func,
                                                             gpointer user_data);
    GConn*              gnet_conn_new_socket                (GTcpSocket *socket,
                                                             GConnFunc func,
                                                             gpointer user_data);
    void                gnet_conn_delete                    (GConn *conn);
    void                gnet_conn_ref                       (GConn *conn);
    void                gnet_conn_unref                     (GConn *conn);
    void                gnet_conn_set_callback              (GConn *conn,
                                                             GConnFunc func,
                                                             gpointer user_data);
    gboolean            gnet_conn_set_main_context          (GConn *conn,
                                                             GMainContext *context);
    void                gnet_conn_connect                   (GConn *conn);
    void                gnet_conn_disconnect                (GConn *conn);
    gboolean            gnet_conn_is_connected              (const GConn *conn);
    void                gnet_conn_read                      (GConn *conn);
    void                gnet_conn_readn                     (GConn *conn,
                                                             gint length);
    void                gnet_conn_readline                  (GConn *conn);
    void                gnet_conn_write                     (GConn *conn,
                                                             gchar *buffer,
                                                             gint length);
    void                gnet_conn_write_direct              (GConn *conn,
                                                             gchar *buffer,
                                                             gint length,
                                                             GDestroyNotify buffer_destroy_cb);
    void                gnet_conn_set_watch_error           (GConn *conn,
                                                             gboolean enable);
    void                gnet_conn_set_watch_readable        (GConn *conn,
                                                             gboolean enable);
    void                gnet_conn_set_watch_writable        (GConn *conn,
                                                             gboolean enable);
    void                gnet_conn_timeout                   (GConn *conn,
                                                             guint timeout);

## Description

A GConn represents a TCP connection. A GConn is usually created directly by the user by calling `gnet_conn_new()` or `gnet_conn_new_inetaddr()`. To connect to the remote host, call `gnet_conn_connect()` and to disconnect call `gnet_conn_disconnect()`. You may use the same GConn to connect again to the host after you disconnected. Free the GConn with `gnet_conn_unref()` or `gnet_conn_delete()` when no longer needed.

GConns are also created by a GServer when a client connects. You will need to call `gnet_conn_set_callback()` to set the GConn callback after it is created by the GServer. A GConn that has been created by a GServer is already connect, you don't have to call `gnet_conn_connect()` in this case. Call `gnet_conn_unref()` or `gnet_conn_delete()` to disconnect the remote client and free the GConn.

The iochannel field and GIOChannel functions can be used to read from or write to the socket. GIOChannel functions block. To make an asynchronous read call `gnet_conn_read()` and to make an asynchronous write call `gnet_conn_write()`. The callback is called whenever a read or write completes.

Special use cases (you usually do not need this): use `gnet_conn_set_watch_error()` to get an event if an error occurs. Use `gnet_conn_set_watch_readable()` and `gnet_conn_set_watch_writable()` to get events when the connection is readable or writable. These can be used to implement custom I/O handling for cases where `gnet_conn_read()`, `gnet_conn_write()` and `gnet_conn_write_direct()` are not suitable. For example, consider writing from a `mmap()`'ed file. `gnet_conn_write()` will allocate memory for a buffer and copy part of the file into the buffer. To avoid the copy, use `gnet_conn_set_watch_writable()` to catch the writable event and then write directly from memory to the socket (note: this is obsolete, you can now use `gnet_conn_write_direct()` for this).

`gnet_conn_timeout()` sets a timeout on the GConn. The `GNET_CONN_TIMEOUT` event occurs when the timer expires. For example, the timer may be set before connecting to the host. If the connection is made, the `GNET_CONN_CONNECT` event occurs. The timer can then be reset by setting the timeout to 0. Otherwise, the `GNET_CONN_TIMEOUT` event will eventually occur.

## Details

### GConn

    typedef struct {
      /* Public */
      gchar*			hostname;
      gint				port;

      GIOChannel* 			iochannel;
      GTcpSocket* 			socket;
      GInetAddr*			inetaddr;

      /* Private */
      guint				ref_count;
      guint				ref_count_internal;

      /* Connect */
      GTcpSocketConnectAsyncID 	connect_id;
      GTcpSocketNewAsyncID 		new_id;

      /* Write */
      GList*			write_queue;
      guint				bytes_written;

      /* Read */
      gchar* 			buffer;
      guint 			length;
      guint 			bytes_read;
      gboolean			read_eof;
      GList*			read_queue;
      guint				process_buffer_timeout;

      /* Readable/writable */
      gboolean			watch_readable;
      gboolean			watch_writable;

      /* IO watch */
      guint				watch_flags;
      guint				watch;

      /* Timer */
      guint				timer;

      /* User data */
      GConnFunc			func;
      gpointer			user_data;

      GMainContext                * context;
      gint                          priority;
    } GConn;

TCP Connection. Some of the fields are public, but do not set these fields.

gchar *`hostname`; | host name
gint `port`; | port
GIOChannel *`iochannel`; | IO channel
GTcpSocket *`socket`; | socket
GInetAddr *`inetaddr`; | address
guint `ref_count`; | [private]
guint `ref_count_internal`; | [private]
GTcpSocketConnectAsyncID `connect_id`; | [private]
GTcpSocketNewAsyncID `new_id`; | [private]
GList *`write_queue`; | [private]
guint `bytes_written`; | [private]
gchar *`buffer`; | [private]
guint `length`; | [private]
guint `bytes_read`; | [private]
gboolean `read_eof`; | [private]
GList *`read_queue`; | [private]
guint `process_buffer_timeout`; | [private]
gboolean `watch_readable`; | [private]
gboolean `watch_writable`; | [private]
guint `watch_flags`; | [private]
guint `watch`; | [private]
guint `timer`; | [private]
GConnFunc `func`; | [private]
gpointer `user_data`; | [private]
GMainContext *`context`; |
gint `priority`; |

### GConnEvent

    typedef struct {
      GConnEventType type;
      gchar*	 buffer;
      gint		 length;
    } GConnEvent;

GConn Event. `buffer` and `length` are set only on GNET_CONN_READ events. The buffer is caller-owned.

GConnEventType `type`; | event type
gchar *`buffer`; | buffer
gint `length`; | buffer length

### enum GConnEventType

    typedef enum {
      GNET_CONN_ERROR,
      GNET_CONN_CONNECT,
      GNET_CONN_CLOSE,
      GNET_CONN_TIMEOUT,
      GNET_CONN_READ,
      GNET_CONN_WRITE,
      GNET_CONN_READABLE,
      GNET_CONN_WRITABLE
    } GConnEventType;

Event type. Used by GConnEvent.

`GNET_CONN_ERROR` | Connection error
`GNET_CONN_CONNECT` | Connection complete
`GNET_CONN_CLOSE` | Connection closed
`GNET_CONN_TIMEOUT` | Timeout
`GNET_CONN_READ` | Read complete
`GNET_CONN_WRITE` | Write complete
`GNET_CONN_READABLE` | Connection is readable
`GNET_CONN_WRITABLE` | Connection is writable

### GConnFunc ()

    void                (*GConnFunc)                        (GConn *conn,
                                                             GConnEvent *event,
                                                             gpointer user_data);

Callback for GConn.

Possible events:

`GNET_CONN_ERROR`: GConn error. The event occurs if the connection fails somehow. The connection is closed before this event occurs.

`GNET_CONN_CONNECT`: Completion of `gnet_conn_connect()`.

`GNET_CONN_CLOSE`: Connection has been closed. The event does not occur as a result of calling `gnet_conn_disconnect()`, `gnet_conn_unref()`, or `gnet_conn_delete()`.

`GNET_CONN_TIMEOUT`: Timer set by `gnet_conn_timeout()` expires.

`GNET_CONN_READ`: Data has been read. This event occurs as a result of calling `gnet_conn_read()`, `gnet_conn_readn()`, or `gnet_conn_readline()`. buffer and length are set in the event object. The buffer is caller owned.

`GNET_CONN_WRITE`: Data has been written. This event occurs as a result of calling `gnet_conn_write()` or `gnet_conn_write_direct()`.

`GNET_CONN_READABLE`: The connection is readable.

`GNET_CONN_WRITABLE`: The connection is writable.

`conn` : | GConn
`event` : | event (caller owned)
`user_data` : | user data specified in `gnet_conn_new()`

### gnet_conn_new ()

    GConn*              gnet_conn_new                       (const gchar *hostname,
                                                             gint port,
                                                             GConnFunc func,
                                                             gpointer user_data);

Creates a GConn. A connection is not made until `gnet_conn_connect()` is called. The callback `func` is called when events occur.

`hostname` : | name of host to connect to
`port` : | port to connect to
`func` : | function to call on GConn events
`user_data` : | data to pass to `func` on callbacks
Returns : | a GConn.

### gnet_conn_new_inetaddr ()

    GConn*              gnet_conn_new_inetaddr              (const GInetAddr *inetaddr,
                                                             GConnFunc func,
                                                             gpointer user_data);

Creates a GConn. A connection is not made until `gnet_conn_connect()` is called. The callback `func` is called when events occur.

`inetaddr` : | address of host to connect to
`func` : | function to call on GConn events
`user_data` : | data to pass to `func` on callbacks
Returns : | a GConn.

### gnet_conn_new_socket ()

    GConn*              gnet_conn_new_socket                (GTcpSocket *socket,
                                                             GConnFunc func,
                                                             gpointer user_data);

Creates a GConn. The GConn is created from the `socket`. The socket is callee owned - do not delete it (meaning: GConn will take ownership of the socket). The callback is called when events occur.

`socket` : | TCP Socket (callee owned)
`func` : | function to call on GConn events
`user_data` : | data to pass to `func` on callbacks
Returns : | a GConn.

### gnet_conn_delete ()

    void                gnet_conn_delete                    (GConn *conn);

### Warning

`gnet_conn_delete` is deprecated and should not be used in newly-written code. Use `g_conn_unref()`, which does the same.

Deletes a GConn.

`conn` : | a GConn

### gnet_conn_ref ()

    void                gnet_conn_ref                       (GConn *conn);

Adds a reference to a GConn.

`conn` : | a GConn

### gnet_conn_unref ()

    void                gnet_conn_unref                     (GConn *conn);

Removes a reference from a GConn. A GConn is deleted when the reference count reaches 0.

`conn` : | a GConn

### gnet_conn_set_callback ()

    void                gnet_conn_set_callback              (GConn *conn,
                                                             GConnFunc func,
                                                             gpointer user_data);

Sets the GConnEvent callback for a GConn. The callback `func` is called when events occur.

`conn` : | a GConn
`func` : | function to call on GConn events
`user_data` : | data to pass to `func` on callbacks

### gnet_conn_set_main_context ()

    gboolean            gnet_conn_set_main_context          (GConn *conn,
                                                             GMainContext *context);

Sets the GLib GMainContext to use for asynchronous operations. You should call this function right after you create `conn`. You must not call this function after the actual connection process has started or watches have been set up (e.g. for reading, writing or errors).

You are very unlikely to ever need this function.

`conn` : | a GConn
`context` : | a GMainContext, or NULL to use the default GLib main context
Returns : | TRUE on success, FALSE on failure.

Since 2.0.8

### gnet_conn_connect ()

    void                gnet_conn_connect                   (GConn *conn);

Establishes a connection. If the connection is pending or already established, this function does nothing. The callback is called when the connection is established or an error occurs.

`conn` : | a GConn

### gnet_conn_disconnect ()

    void                gnet_conn_disconnect                (GConn *conn);

Closes the connection. The connection can later be reestablished by calling `gnet_conn_connect()` again. If the connection was not established, this function does nothing.

`conn` : | a GConn

### gnet_conn_is_connected ()

    gboolean            gnet_conn_is_connected              (const GConn *conn);

Checks if the connection is established.

`conn` : | a GConn
Returns : | TRUE if the connection is established, FALSE otherwise.

### gnet_conn_read ()

    void                gnet_conn_read                      (GConn *conn);

Begins an asynchronous read. The connection callback is called when any data has been read. This function may be called again before the asynchronous read completes.

`conn` : | a GConn

### gnet_conn_readn ()

    void                gnet_conn_readn                     (GConn *conn,
                                                             gint length);

Begins an asynchronous read of exactly `length` bytes. The connection callback is called when the data has been read. This function may be called again before the asynchronous read completes.

`conn` : | a GConn
`length` : | Number of bytes to read

### gnet_conn_readline ()

    void                gnet_conn_readline                  (GConn *conn);

Begins an asynchronous line read. The connection callback is called when a line has been read. Lines are terminated with \n, \r, \r\n, or \0. The terminator is \0'ed out in the buffer. The terminating \0 is accounted for in the buffer length. This function may be called again before the asynchronous read completes.

`conn` : | a GConn

### gnet_conn_write ()

    void                gnet_conn_write                     (GConn *conn,
                                                             gchar *buffer,
                                                             gint length);

Sets up an asynchronous write to `conn` from `buffer`. The buffer is copied, so it may be deleted by the caller. This function can be called again before the asynchronous write completes.

`conn` : | a GConn
`buffer` : | buffer to write from
`length` : | length of `buffer`

### gnet_conn_write_direct ()

    void                gnet_conn_write_direct              (GConn *conn,
                                                             gchar *buffer,
                                                             gint length,
                                                             GDestroyNotify buffer_destroy_cb);

Sets up an asynchronous write to `conn` from `buffer`. The buffer is created by the caller and will not be copied. The caller needs to make sure the buffer stays valid until `buffer_destroy_cb` is called. This function can be called again before the asynchronous write completes. `buffer_destroy_cb` may be `NULL`.

`conn` : | a GConn
`buffer` : | buffer to write from
`length` : | length of `buffer`
`buffer_destroy_cb` : | function to call when buffer is no longer needed

### gnet_conn_set_watch_error ()

    void                gnet_conn_set_watch_error           (GConn *conn,
                                                             gboolean enable);

Enables (or disables) the `GNET_CONN_ERROR` event for a GConn. If enabled, the `GNET_CONN_ERROR` event occurs when an error occurs. The `conn` is disconnected before the callback is made.

`conn` : | a GConn
`enable` : | enable the `GNET_CONN_READABLE` event?

### gnet_conn_set_watch_readable ()

    void                gnet_conn_set_watch_readable        (GConn *conn,
                                                             gboolean enable);

Enables (or disables) the `GNET_CONN_READABLE` event for a GConn. If enabled, the `GNET_CONN_READABLE` event occurs when data can be read from the socket. Read from the iochannel member of the `conn`. Do not enable this while using `gnet_conn_read()`, `gnet_conn_readn()`, or `gnet_conn_readline()`.

`conn` : | a GConn
`enable` : | enable the `GNET_CONN_READABLE` event?

### gnet_conn_set_watch_writable ()

    void                gnet_conn_set_watch_writable        (GConn *conn,
                                                             gboolean enable);

Enables (or disables) the `GNET_CONN_WRITABLE` event for a GConn. If enabled, the GNET_CONN_WRITABLE event occurs when data can be written to the socket. Write to the iochannel member of the `conn`. Do not enable this while using `gnet_conn_write()`.

`conn` : | a GConn
`enable` : | enable the GNET_CONN_WRITABLE event?

### gnet_conn_timeout ()

    void                gnet_conn_timeout                   (GConn *conn,
                                                             guint timeout);

Sets a timeout on a GConn. When the timer expires, the `GNET_CONN_STATUS_TIMEOUT` event occurs. If there already is a timeout set on `conn`, the old timeout is canceled. Set `timeout` to 0 to cancel the current timeout.

`conn` : | a GConn
`timeout` : | Timeout (in milliseconds)

## See Also

See also GServer and the echoclient-gconn example.