# LINCConnection

## Name

LINCConnection -- the basic connection object

## Synopsis

    enum        LINCConnectionStatus;
    gboolean    linc_connection_from_fd         (LINCConnection *cnx,
                                                 int fd,
                                                 const LINCProtocolInfo *proto,
                                                 gchar *remote_host_info,
                                                 gchar *remote_serv_info,
                                                 gboolean was_initiated,
                                                 LINCConnectionStatus status,
                                                 LINCConnectionOptions options);
    gboolean    linc_connection_initiate        (LINCConnection *cnx,
                                                 const char *proto_name,
                                                 const char *remote_host_info,
                                                 const char *remote_serv_info,
                                                 LINCConnectionOptions options);
    glong       linc_connection_read            (LINCConnection *cnx,
                                                 guchar *buf,
                                                 int len,
                                                 gboolean block_for_full_read);
    LINCIOStatus linc_connection_write          (LINCConnection *cnx,
                                                 const guchar *buf,
                                                 gulong len,
                                                 const LINCWriteOpts *opt_write_opts);
    LINCIOStatus linc_connection_writev         (LINCConnection *cnx,
                                                 struct iovec *vecs,
                                                 int nvecs,
                                                 const LINCWriteOpts *opt_write_opts);
    void        linc_connection_state_changed   (LINCConnection *cnx,
                                                 LINCConnectionStatus status);

## Description

## Details

### enum LINCConnectionStatus

    typedef enum { LINC_CONNECTING, LINC_CONNECTED, LINC_DISCONNECTED } LINCConnectionStatus;

### linc_connection_from_fd ()

    gboolean    linc_connection_from_fd         (LINCConnection *cnx,
                                                 int fd,
                                                 const LINCProtocolInfo *proto,
                                                 gchar *remote_host_info,
                                                 gchar *remote_serv_info,
                                                 gboolean was_initiated,
                                                 LINCConnectionStatus status,
                                                 LINCConnectionOptions options);

`cnx` : |
`fd` : |
`proto` : |
`remote_host_info` : |
`remote_serv_info` : |
`was_initiated` : |
`status` : |
`options` : |
Returns : |

### linc_connection_initiate ()

    gboolean    linc_connection_initiate        (LINCConnection *cnx,
                                                 const char *proto_name,
                                                 const char *remote_host_info,
                                                 const char *remote_serv_info,
                                                 LINCConnectionOptions options);

`cnx` : |
`proto_name` : |
`remote_host_info` : |
`remote_serv_info` : |
`options` : |
Returns : |

### linc_connection_read ()

    glong       linc_connection_read            (LINCConnection *cnx,
                                                 guchar *buf,
                                                 int len,
                                                 gboolean block_for_full_read);

Warning, block_for_full_read is of limited usefullness.

`cnx` : | the connection to write to
`buf` : | a pointer to the start of an array of bytes to read data into
`len` : | the length of the array in bytes to read ingo
`block_for_full_read` : | whether to block for a full read
Returns : | number of bytes written on success; negative on error.

### linc_connection_write ()

    LINCIOStatus linc_connection_write          (LINCConnection *cnx,
                                                 const guchar *buf,
                                                 gulong len,
                                                 const LINCWriteOpts *opt_write_opts);

Writes a contiguous block of data to the abstract connection.

FIXME: it allows re-enterancy via linc_connection_iterate in certain cases. FIXME: on this basis, the connection can die underneath our feet eg. between the main_iteration and the g_return_if_fail.

`cnx` : | the connection to write to
`buf` : | a pointer to the start of an array of bytes
`len` : | the length of the array in bytes
`opt_write_opts` : | optional write options, or NULL
Returns : | 0 on success, non 0 on error.

### linc_connection_writev ()

    LINCIOStatus linc_connection_writev         (LINCConnection *cnx,
                                                 struct iovec *vecs,
                                                 int nvecs,
                                                 const LINCWriteOpts *opt_write_opts);

This routine writes data to the abstract connection. FIXME: it allows re-enterancy via linc_connection_iterate in certain cases. FIXME: on this basis, the connection can die underneath our feet.

`cnx` : | the connection to write to
`vecs` : | a structure of iovecs to write - this is altered.
`nvecs` : | the number of populated iovecs
`opt_write_opts` : | optional write options, or NULL
Returns : | 0 on success, non 0 on error.

### linc_connection_state_changed ()

    void        linc_connection_state_changed   (LINCConnection *cnx,
                                                 LINCConnectionStatus status);

`cnx` : |
`status` : |