LmConnection

## LmConnection LmConnection — A client connection to the server |

## Synopsis

    #define             LM_CONNECTION                       (o)
    #define             LM_CONNECTION_DEFAULT_PORT
    #define             LM_CONNECTION_DEFAULT_PORT_SSL
                        LmConnection;
    enum                LmHandlerResult;
    enum                LmHandlerPriority;
    enum                LmDisconnectReason;
    enum                LmConnectionState;
    void                (*LmResultFunction)                 (LmConnection *connection,
                                                             gboolean success,
                                                             gpointer user_data);
    void                (*LmDisconnectFunction)             (LmConnection *connection,
                                                             LmDisconnectReason reason,
                                                             gpointer user_data);
    LmConnection *      lm_connection_new                   (const gchar *server);
    LmConnection *      lm_connection_new_with_context      (const gchar *server,
                                                             GMainContext *context);
    gboolean            lm_connection_open                  (LmConnection *connection,
                                                             LmResultFunction function,
                                                             gpointer user_data,
                                                             GDestroyNotify notify,
                                                             GError **error);
    gboolean            lm_connection_open_and_block        (LmConnection *connection,
                                                             GError **error);
    gboolean            lm_connection_close                 (LmConnection *connection,
                                                             GError **error);
    gboolean            lm_connection_authenticate          (LmConnection *connection,
                                                             const gchar *username,
                                                             const gchar *password,
                                                             const gchar *resource,
                                                             LmResultFunction function,
                                                             gpointer user_data,
                                                             GDestroyNotify notify,
                                                             GError **error);
    gboolean            lm_connection_authenticate_and_block
                                                            (LmConnection *connection,
                                                             const gchar *username,
                                                             const gchar *password,
                                                             const gchar *resource,
                                                             GError **error);
    guint               lm_connection_get_keep_alive_rate   (LmConnection *connection);
    void                lm_connection_set_keep_alive_rate   (LmConnection *connection,
                                                             guint rate);
    gboolean            lm_connection_is_open               (LmConnection *connection);
    gboolean            lm_connection_is_authenticated      (LmConnection *connection);
    const gchar *       lm_connection_get_server            (LmConnection *connection);
    void                lm_connection_set_server            (LmConnection *connection,
                                                             const gchar *server);
    const gchar *       lm_connection_get_jid               (LmConnection *connection);
    void                lm_connection_set_jid               (LmConnection *connection,
                                                             const gchar *jid);
    guint               lm_connection_get_port              (LmConnection *connection);
    void                lm_connection_set_port              (LmConnection *connection,
                                                             guint port);
    LmSSL *             lm_connection_get_ssl               (LmConnection *connection);
    void                lm_connection_set_ssl               (LmConnection *connection,
                                                             LmSSL *ssl);
    LmProxy *           lm_connection_get_proxy             (LmConnection *connection);
    void                lm_connection_set_proxy             (LmConnection *connection,
                                                             LmProxy *proxy);
    gboolean            lm_connection_send                  (LmConnection *connection,
                                                             LmMessage *message,
                                                             GError **error);
    gboolean            lm_connection_send_with_reply       (LmConnection *connection,
                                                             LmMessage *message,
                                                             LmMessageHandler *handler,
                                                             GError **error);
    LmMessage *         lm_connection_send_with_reply_and_block
                                                            (LmConnection *connection,
                                                             LmMessage *message,
                                                             GError **error);
    void                lm_connection_register_message_handler
                                                            (LmConnection *connection,
                                                             LmMessageHandler *handler,
                                                             LmMessageType type,
                                                             LmHandlerPriority priority);
    void                lm_connection_unregister_message_handler
                                                            (LmConnection *connection,
                                                             LmMessageHandler *handler,
                                                             LmMessageType type);
    void                lm_connection_set_disconnect_function
                                                            (LmConnection *connection,
                                                             LmDisconnectFunction function,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);
    gboolean            lm_connection_send_raw              (LmConnection *connection,
                                                             const gchar *str,
                                                             GError **error);
    LmConnectionState   lm_connection_get_state             (LmConnection *connection);
    LmConnection*       lm_connection_ref                   (LmConnection *connection);
    void                lm_connection_unref                 (LmConnection *connection);

## Description

An example of how to use Loudmouth with the synchronous API.

    int
    main (int argc, char **argv)
    {
            LmConnection *connection;
            GError       *error = NULL;
            gint          i;
    	LmMessage    *m;
            connection = lm_connection_new ("myserver");
            if (!lm_connection_open_and_block (connection, &error)) {
                    g_error ("Failed to open: %s\n", error->message);
            }
    	if (!lm_connection_authenticate_and_block (connection,
    						   "username", "password",
    						   "resource",
    						   &error)) {
    		g_error ("Failed to authenticate: %s\n", error->message);
    	}
    	m = lm_message_new ("recipient", LM_MESSAGE_TYPE_MESSAGE);
    	lm_message_node_add_child (m->node, "body", "message");
    	if (!lm_connection_send (connection, m, &error)) {
    		g_error ("Send failed: %s\n", error->message);
    	}
    	lm_message_unref (m);
    	lm_connection_close (connection, NULL);
    	lm_connection_unref (connection);
            return 0;
    }

## Details

### LM_CONNECTION()

    #define LM_CONNECTION(o) (LmConnection *) o;

Convenience macro used to cast a pointer to a LmConnection.

`o` : | pointer to cast

### LM_CONNECTION_DEFAULT_PORT

    #define LM_CONNECTION_DEFAULT_PORT     5222

Default jabber client port.

### LM_CONNECTION_DEFAULT_PORT_SSL

    #define LM_CONNECTION_DEFAULT_PORT_SSL 5223

Default jabber client port when using SSL encryption.

### LmConnection

    typedef struct _LmConnection LmConnection;

This should not be accessed directly. Use the accessor functions as described below.

### enum LmHandlerResult

    typedef enum {
    	LM_HANDLER_RESULT_REMOVE_MESSAGE,
    	LM_HANDLER_RESULT_ALLOW_MORE_HANDLERS
    } LmHandlerResult;

The return type of an LmMessageHandler. This determines whether more message handlers should be called.

`LM_HANDLER_RESULT_REMOVE_MESSAGE` | Stop calling message handlers. The message handler returning this declares the message has been handled and should be removed.
`LM_HANDLER_RESULT_ALLOW_MORE_HANDLERS` | Return to continue the calling handlers from the handler list. This declares that another handlers should handle the message.

### enum LmHandlerPriority

    typedef enum {
    	LM_HANDLER_PRIORITY_LAST   = 1,
    	LM_HANDLER_PRIORITY_NORMAL = 2,
    	LM_HANDLER_PRIORITY_FIRST  = 3
    } LmHandlerPriority;

Since the handlers decide whether to stop the calling chain with there return values it's sometimes decirable to be able to set priority. For example a handler that only logs all incoming messages and then pass the message on to another handler wants to have priority `LM_HANDLER_PRIORITY_FIRST`. An handler that should take all messages that wasn't handled by anything else would want to have priority `LM_HANDLER_PRIORITY_LAST`. If several handlers have the same priority nothing can be said about the order the handlers will be called in.

`LM_HANDLER_PRIORITY_LAST` | Call the handler after all handlers with NORMAL and FIRST priority.
`LM_HANDLER_PRIORITY_NORMAL` | Called before handlers with priority LAST and after those with FIRST.
`LM_HANDLER_PRIORITY_FIRST` | These are called before all other handlers.

### enum LmDisconnectReason

    typedef enum {
    	LM_DISCONNECT_REASON_OK,
    	LM_DISCONNECT_REASON_PING_TIME_OUT,
    	LM_DISCONNECT_REASON_HUP,
    	LM_DISCONNECT_REASON_ERROR,
    	LM_DISCONNECT_REASON_RESOURCE_CONFLICT,
    	LM_DISCONNECT_REASON_INVALID_XML,
    	LM_DISCONNECT_REASON_UNKNOWN
    } LmDisconnectReason;

Sent with LmDisconnectFunction to describe why a connection was closed.

`LM_DISCONNECT_REASON_OK` | User requested disconnect.
`LM_DISCONNECT_REASON_PING_TIME_OUT` | Connection to the server timed out.
`LM_DISCONNECT_REASON_HUP` | The socket emitted that the connection was hung up.
`LM_DISCONNECT_REASON_ERROR` | A generic error somewhere in the transport layer.
`LM_DISCONNECT_REASON_RESOURCE_CONFLICT` | Another connection was made to the server with the same resource.
`LM_DISCONNECT_REASON_INVALID_XML` | Invalid XML was sent from the client.
`LM_DISCONNECT_REASON_UNKNOWN` | An unknown error.

### enum LmConnectionState

    typedef enum {
    	LM_CONNECTION_STATE_CLOSED,
    	LM_CONNECTION_STATE_OPENING,
    	LM_CONNECTION_STATE_OPEN,
    	LM_CONNECTION_STATE_AUTHENTICATING,
    	LM_CONNECTION_STATE_AUTHENTICATED
    } LmConnectionState;

Describes the current state of an LmConnection.

`LM_CONNECTION_STATE_CLOSED` | The connection is closed.
`LM_CONNECTION_STATE_OPENING` | The connection is in the process of opening.
`LM_CONNECTION_STATE_OPEN` | The connection is open.
`LM_CONNECTION_STATE_AUTHENTICATING` | The connection is in the process of authenticating.
`LM_CONNECTION_STATE_AUTHENTICATED` | The connection is authenticated and is ready to start sending/receiving messages.

### LmResultFunction ()

    void                (*LmResultFunction)                 (LmConnection *connection,
                                                             gboolean success,
                                                             gpointer user_data);

Callback for informing if an asynchronous operation was successful.

`connection` : | an LmConnection
`success` : | the result, `TRUE` if operation succeeded, otherwise `FALSE`
`user_data` : | User data passed when function being called.

### LmDisconnectFunction ()

    void                (*LmDisconnectFunction)             (LmConnection *connection,
                                                             LmDisconnectReason reason,
                                                             gpointer user_data);

Callback called when a connection is closed.

`connection` : | an LmConnection
`reason` : | the reason the connection was closed.
`user_data` : | User data passed when function being called.

### lm_connection_new ()

    LmConnection *      lm_connection_new                   (const gchar *server);

Creates a new closed connection. To open the connection call `lm_connection_open()`. `server` can be NULL but must be set before calling `lm_connection_open()`.

`server` : | The hostname to the server for the connection.
Returns : | A newly created LmConnection, should be unreffed with `lm_connection_unref()`.

### lm_connection_new_with_context ()

    LmConnection *      lm_connection_new_with_context      (const gchar *server,
                                                             GMainContext *context);

Creates a new closed connection running in a certain context. To open the connection call lm_connection_open. `server` can be NULL but must be set before calling lm_connection_open.

`server` : | The hostname to the server for the connection.
`context` : | The context this connection should be running in.
Returns : | A newly created LmConnection, should be unreffed with `lm_connection_unref()`.

### lm_connection_open ()

    gboolean            lm_connection_open                  (LmConnection *connection,
                                                             LmResultFunction function,
                                                             gpointer user_data,
                                                             GDestroyNotify notify,
                                                             GError **error);

An async call to open `connection`. When the connection is open `function` will be called.

`connection` : | LmConnection to open
`function` : | Callback function that will be called when the connection is open.
`user_data` : | User data that will be passed to `function`.
`notify` : | Function for freeing that user_data, can be NULL.
`error` : | location to store error, or `NULL`
Returns : | TRUE if everything went fine, otherwise FALSE.

### lm_connection_open_and_block ()

    gboolean            lm_connection_open_and_block        (LmConnection *connection,
                                                             GError **error);

Opens `connection` and waits until the stream is setup.

`connection` : | an LmConnection to open
`error` : | location to store error, or `NULL`
Returns : | TRUE if no errors where encountered during opening and stream setup successfully, FALSE otherwise.

### lm_connection_close ()

    gboolean            lm_connection_close                 (LmConnection *connection,
                                                             GError **error);

A synchronous call to close the connection. When returning the connection is considered to be closed and can be opened again with `lm_connection_open()`.

`connection` : | LmConnection to close
`error` : | location to store error, or `NULL`
Returns : | Returns TRUE if no errors where detected, otherwise FALSE.

### lm_connection_authenticate ()

    gboolean            lm_connection_authenticate          (LmConnection *connection,
                                                             const gchar *username,
                                                             const gchar *password,
                                                             const gchar *resource,
                                                             LmResultFunction function,
                                                             gpointer user_data,
                                                             GDestroyNotify notify,
                                                             GError **error);

Tries to authenticate a user against the server. The LmResult in the result callback `function` will say whether it succeeded or not.

`connection` : | LmConnection to authenticate.
`username` : | Username used to authenticate.
`password` : | Password corresponding to `username`.
`resource` : | Resource used for this connection.
`function` : | Callback called when authentication is finished.
`user_data` : | Userdata passed to `function` when called.
`notify` : | Destroy function to free the memory used by `user_data`, can be NULL.
`error` : | location to store error, or `NULL`
Returns : | TRUE if no errors where detected while sending the authentication message, FALSE otherwise.

### lm_connection_authenticate_and_block ()

    gboolean            lm_connection_authenticate_and_block
                                                            (LmConnection *connection,
                                                             const gchar *username,
                                                             const gchar *password,
                                                             const gchar *resource,
                                                             GError **error);

Tries to authenticate a user against the server. This function blocks until a reply to the authentication attempt is returned and returns whether it was successful or not.

`connection` : | an LmConnection
`username` : | Username used to authenticate.
`password` : | Password corresponding to `username`.
`resource` : | Resource used for this connection.
`error` : | location to store error, or `NULL`
Returns : | TRUE if no errors where detected and authentication was successful. FALSE otherwise.

### lm_connection_get_keep_alive_rate ()

    guint               lm_connection_get_keep_alive_rate   (LmConnection *connection);

Get the keep alive rate, in seconds. Zero is returned if no keep alive rate has been set.

Since 1.4.0

`connection` : | an LmConnection
Returns : | The keep alive rate in seconds.

### lm_connection_set_keep_alive_rate ()

    void                lm_connection_set_keep_alive_rate   (LmConnection *connection,
                                                             guint rate);

Set the keep alive rate, in seconds. Set to 0 to prevent keep alive messages to be sent. A keep alive message is a single space character.

`connection` : | an LmConnection
`rate` : | Number of seconds between keep alive packages are sent.

### lm_connection_is_open ()

    gboolean            lm_connection_is_open               (LmConnection *connection);

Check if the `connection` is currently open.

`connection` : | LmConnection to check if it is open.
Returns : | TRUE if connection is open and FALSE if it is closed.

### lm_connection_is_authenticated ()

    gboolean            lm_connection_is_authenticated      (LmConnection *connection);

Check if `connection` is authenticated.

`connection` : | LmConnection to check if it is authenticated
Returns : | TRUE if connection is authenticated, FALSE otherwise.

### lm_connection_get_server ()

    const gchar *       lm_connection_get_server            (LmConnection *connection);

Fetches the server address that `connection` is using.

`connection` : | an LmConnection
Returns : | the server address

### lm_connection_set_server ()

    void                lm_connection_set_server            (LmConnection *connection,
                                                             const gchar *server);

Sets the server address for `connection` to `server`. Notice that `connection` can't be open while doing this.

`connection` : | an LmConnection
`server` : | Address of the server

### lm_connection_get_jid ()

    const gchar *       lm_connection_get_jid               (LmConnection *connection);

Fetches the jid set for `connection` is using.

`connection` : | an LmConnection
Returns : | the jid

### lm_connection_set_jid ()

    void                lm_connection_set_jid               (LmConnection *connection,
                                                             const gchar *jid);

Sets the JID to be used for `connection`.

`connection` : | an LmConnection
`jid` : | JID to be used for `connection`

### lm_connection_get_port ()

    guint               lm_connection_get_port              (LmConnection *connection);

Fetches the port that `connection` is using.

`connection` : | an LmConnection
Returns : | The port used.

### lm_connection_set_port ()

    void                lm_connection_set_port              (LmConnection *connection,
                                                             guint port);

Sets the server port that `connection` will be using.

`connection` : | an LmConnection
`port` : | server port

### lm_connection_get_ssl ()

    LmSSL *             lm_connection_get_ssl               (LmConnection *connection);

Returns the SSL struct if the connection is using one.

`connection` : | an LmConnection
Returns : | The ssl struct or `NULL` if no proxy is used.

### lm_connection_set_ssl ()

    void                lm_connection_set_ssl               (LmConnection *connection,
                                                             LmSSL *ssl);

Sets SSL struct or unset if `ssl` is `NULL`. If set `connection` will use SSL to for the connection.

`connection` : | An LmConnection
`ssl` : | An LmSSL

### lm_connection_get_proxy ()

    LmProxy *           lm_connection_get_proxy             (LmConnection *connection);

Returns the proxy if the connection is using one.

`connection` : | an LmConnection
Returns : | The proxy or `NULL` if no proxy is used.

### lm_connection_set_proxy ()

    void                lm_connection_set_proxy             (LmConnection *connection,
                                                             LmProxy *proxy);

Sets the proxy to use for this connection. To unset pass NULL.

`connection` : | an LmConnection
`proxy` : | an LmProxy

### lm_connection_send ()

    gboolean            lm_connection_send                  (LmConnection *connection,
                                                             LmMessage *message,
                                                             GError **error);

Asynchronous call to send a message.

`connection` : | LmConnection to send message over.
`message` : | LmMessage to send.
`error` : | location to store error, or `NULL`
Returns : | Returns TRUE if no errors where detected while sending, FALSE otherwise.

### lm_connection_send_with_reply ()

    gboolean            lm_connection_send_with_reply       (LmConnection *connection,
                                                             LmMessage *message,
                                                             LmMessageHandler *handler,
                                                             GError **error);

Send a LmMessage which will result in a reply.

`connection` : | LmConnection used to send message.
`message` : | LmMessage to send.
`handler` : | LmMessageHandler that will be used when a reply to `message` arrives
`error` : | location to store error, or `NULL`
Returns : | Returns TRUE if no errors where detected while sending, FALSE otherwise.

### lm_connection_send_with_reply_and_block ()

    LmMessage *         lm_connection_send_with_reply_and_block
                                                            (LmConnection *connection,
                                                             LmMessage *message,
                                                             GError **error);

Send `message` and wait for return.

`connection` : | an LmConnection
`message` : | an LmMessage
`error` : | Set if error was detected during sending.
Returns : | The reply

### lm_connection_register_message_handler ()

    void                lm_connection_register_message_handler
                                                            (LmConnection *connection,
                                                             LmMessageHandler *handler,
                                                             LmMessageType type,
                                                             LmHandlerPriority priority);

Registers a LmMessageHandler to handle incoming messages of a certain type. To unregister the handler call `lm_connection_unregister_message_handler()`.

`connection` : | Connection to register a handler for.
`handler` : | Message handler to register.
`type` : | Message type that `handler` will handle.
`priority` : | The priority in which to call `handler`.

### lm_connection_unregister_message_handler ()

    void                lm_connection_unregister_message_handler
                                                            (LmConnection *connection,
                                                             LmMessageHandler *handler,
                                                             LmMessageType type);

Unregisters a handler for `connection`. `handler` will no longer be called when incoming messages of `type` arrive.

`connection` : | Connection to unregister a handler for.
`handler` : | The handler to unregister.
`type` : | What type of messages to unregister this handler for.

### lm_connection_set_disconnect_function ()

    void                lm_connection_set_disconnect_function
                                                            (LmConnection *connection,
                                                             LmDisconnectFunction function,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);

Set the callback that will be called when a connection is closed.

`connection` : | Connection to register disconnect callback for.
`function` : | Function to be called when `connection` is closed.
`user_data` : | User data passed to `function`.
`notify` : | Function that will be called with `user_data` when `user_data` needs to be freed. Pass NULL if it shouldn't be freed.

### lm_connection_send_raw ()

    gboolean            lm_connection_send_raw              (LmConnection *connection,
                                                             const gchar *str,
                                                             GError **error);

Asynchronous call to send a raw string. Useful for debugging and testing.

`connection` : | Connection used to send
`str` : | The string to send, the entire string will be sent.
`error` : | Set if error was detected during sending.
Returns : | Returns TRUE if no errors was detected during sending, FALSE otherwise.

### lm_connection_get_state ()

    LmConnectionState   lm_connection_get_state             (LmConnection *connection);

Returns the state of the connection.

`connection` : | Connection to get state on
Returns : | The state of the connection.

### lm_connection_ref ()

    LmConnection*       lm_connection_ref                   (LmConnection *connection);

Add a reference on `connection`. To remove a reference call `lm_connection_unref()`.

`connection` : | Connection to add a reference to.
Returns : | Returns the same connection.

### lm_connection_unref ()

    void                lm_connection_unref                 (LmConnection *connection);

Removes a reference on `connection`. If there are no references to `connection` it will be freed and shouldn't be used again.

`connection` : | Connection to remove reference from.