GNet Network Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# Connection

## Name

Connection -- TCP Connection

## Synopsis

    struct      GConn;
    enum        GConnStatus;
    gboolean    (*GConnFunc)                    (GConn *conn,
                                                 GConnStatus status,
                                                 gchar *buffer,
                                                 gint length,
                                                 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);
    void        gnet_conn_delete                (GConn *conn,
                                                 gboolean delete_buffers);
    void        gnet_conn_ref                   (GConn *conn);
    void        gnet_conn_unref                 (GConn *conn,
                                                 gboolean delete_buffers);
    void        gnet_conn_connect               (GConn *conn,
                                                 guint timeout);
    void        gnet_conn_disconnect            (GConn *conn,
                                                 gboolean delete_buffers);
    gboolean    gnet_conn_is_connected          (const GConn *conn);
    void        gnet_conn_read                  (GConn *conn,
                                                 gchar *buffer,
                                                 guint length,
                                                 guint timeout,
                                                 gboolean read_one_byte_at_a_time,
                                                 GNetIOChannelReadAsyncCheckFunc check_func,
                                                 gpointer check_user_data);
    void        gnet_conn_readany               (GConn *conn,
                                                 gchar *buffer,
                                                 guint length,
                                                 guint timeout);
    void        gnet_conn_readline              (GConn *conn,
                                                 gchar *buffer,
                                                 guint length,
                                                 guint timeout);
    void        gnet_conn_write                 (GConn *conn,
                                                 gchar *buffer,
                                                 gint length,
                                                 guint timeout);
    void        gnet_conn_timeout               (GConn *conn,
                                                 guint timeout);

## Description

Conn represents a TCP connection. New connections can be created and connected to. New connections can also by created by a Server.

## Details

### struct GConn

    struct GConn
    {
      gchar*			hostname;
      gint				port;

      guint				ref_count;

      GTcpSocketConnectAsyncID 	connect_id;
      GTcpSocketNewAsyncID 		new_id;

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

      guint				read_watch;	/* DEPRICATED */
      guint				write_watch;	/* DEPRICATED */
      guint				err_watch;	/* DEPRICATED */

      GNetIOChannelWriteAsyncID 	write_id;
      GList*			queued_writes;

      GNetIOChannelReadAsyncID  	read_id;

      guint				timer;

      GConnFunc			func;
      gpointer			user_data;

    };

### enum GConnStatus

    typedef enum {
      GNET_CONN_STATUS_CONNECT,
      GNET_CONN_STATUS_CLOSE,
      GNET_CONN_STATUS_READ,
      GNET_CONN_STATUS_WRITE,
      GNET_CONN_STATUS_TIMEOUT,
      GNET_CONN_STATUS_ERROR
    } GConnStatus;

Status of GConn, passed by GConnFunc.

### GConnFunc ()

    gboolean    (*GConnFunc)                    (GConn *conn,
                                                 GConnStatus status,
                                                 gchar *buffer,
                                                 gint length,
                                                 gpointer user_data);

Callback for gnet_conn_new(). When g_conn_connect() completes, the callback is called with status CONNECT. If the connection closes during a read, the callback is called with status CLOSE (and a NULL buffer). If gnet_conn_read() or another read function has data available, the callback is called with status READ and the buffer is set. If gnet_conn_read() was called with a NULL buffer, that buffer was allocated by GNet but is callee owned. If gnet_conn_read() was called with a non-NULL buffer, the buffer was allocated by the gnet_conn_read() caller (so is GConnFunc callee owned). The callee should return TRUE if they want to continue reading data. If gnet_conn_write() completes, the callback is called with status WRITE and the buffer is set the the buffer passed to gnet_conn_write(). If the gnet_conn_timeout() timer expires, the callback is called with status TIMEOUT. If an error ever occurs, the callback is called with status ERROR.

`conn` : |
`status` : |
`buffer` : |
`length` : |
`user_data` : |
Returns : |

### gnet_conn_new ()

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

Create a connection object representing a connection to a host. The actual connection is not made until gnet_conn_connect() is called. The callback is called when events occur. The events are connect, read, write, error, and timeout. These only occur if the appropriate function is called first. For example, use gnet_conn_read() to have the callback called when data is read.

`hostname` : |
`port` : |
`func` : |
`user_data` : |
Returns : |

### gnet_conn_new_inetaddr ()

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

Create a connection object representing a connection to a host. This function is similar to gnet_conn_new() but has different arguments.

`inetaddr` : |
`func` : |
`user_data` : |
Returns : |

### gnet_conn_delete ()

    void        gnet_conn_delete                (GConn *conn,
                                                 gboolean delete_buffers);

Delete the connection. If delete_buffers is set, any write buffers are deleted.

`conn` : |
`delete_buffers` : |

### gnet_conn_ref ()

    void        gnet_conn_ref                   (GConn *conn);

Increment the reference counter of the GConn.

`conn` : |

### gnet_conn_unref ()

    void        gnet_conn_unref                 (GConn *conn,
                                                 gboolean delete_buffers);

Remove a reference from the GConn. When reference count reaches 0, the connection is deleted.

`conn` : |
`delete_buffers` : |

### gnet_conn_connect ()

    void        gnet_conn_connect               (GConn *conn,
                                                 guint timeout);

Establish the 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. THE TIMEOUT IS NOT CURRENTLY USED (FIX).

`conn` : |
`timeout` : |

### gnet_conn_disconnect ()

    void        gnet_conn_disconnect            (GConn *conn,
                                                 gboolean delete_buffers);

End the connection. The connection can later be reestablished by calling gnet_conn_connect() again. If there the connection was not establish, this function does nothing. If delete_buffers is set, any write buffers are deleted.

`conn` : |
`delete_buffers` : |

### gnet_conn_is_connected ()

    gboolean    gnet_conn_is_connected          (const GConn *conn);

Check if the connection is established.

`conn` : |
Returns : |

### gnet_conn_read ()

    void        gnet_conn_read                  (GConn *conn,
                                                 gchar *buffer,
                                                 guint length,
                                                 guint timeout,
                                                 gboolean read_one_byte_at_a_time,
                                                 GNetIOChannelReadAsyncCheckFunc check_func,
                                                 gpointer check_user_data);

Set up an asynchronous read from the connection to the buffer. This is a wrapper around gnet_io_channel_read_async(), which reads data until the check function stops it. The callback for this GConn is called when the read is complete or there is an error.

`conn` : |
`buffer` : |
`length` : |
`timeout` : |
`read_one_byte_at_a_time` : |
`check_func` : |
`check_user_data` : |

### gnet_conn_readany ()

    void        gnet_conn_readany               (GConn *conn,
                                                 gchar *buffer,
                                                 guint length,
                                                 guint timeout);

Set up an asynchronous read from the connection to the buffer. This is a wrapper around gnet_io_channel_readany(), which will read any amount of data.

`conn` : |
`buffer` : |
`length` : |
`timeout` : |

### gnet_conn_readline ()

    void        gnet_conn_readline              (GConn *conn,
                                                 gchar *buffer,
                                                 guint length,
                                                 guint timeout);

Set up an asynchronous read from the connection to the buffer. This is a wrapper around gnet_io_channel_readline(), which will read data until a newline.

`conn` : |
`buffer` : |
`length` : |
`timeout` : |

### gnet_conn_write ()

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

Set up an asynchronous write to the connection from the buffer. This is a wrapper around gnet_io_channel_write_async(). This function may be called again before another asynchronous write completes.

`conn` : |
`buffer` : |
`length` : |
`timeout` : |

### gnet_conn_timeout ()

    void        gnet_conn_timeout               (GConn *conn,
                                                 guint timeout);

Set a timeout on the connection. When the time expires, the GConn's callback is called. If there already is a timeout, the old timeout is canceled.

`conn` : |
`timeout` : |

<<< Previous Page | Home | Up | Next Page >>>
URL | Server