Loudmouth Reference Manual: LmConnection

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

## Functions

#define | LM_CONNECTION()
void | (*LmResultFunction) ()
void | (*LmDisconnectFunction) ()
LmConnection * | lm_connection_new ()
LmConnection * | lm_connection_new_with_context ()
gboolean | lm_connection_open ()
gboolean | lm_connection_open_and_block ()
gboolean | lm_connection_close ()
gboolean | lm_connection_authenticate ()
gboolean | lm_connection_authenticate_and_block ()
guint | lm_connection_get_keep_alive_rate ()
void | lm_connection_set_keep_alive_rate ()
gboolean | lm_connection_is_open ()
gboolean | lm_connection_is_authenticated ()
const gchar * | lm_connection_get_server ()
void | lm_connection_set_server ()
const gchar * | lm_connection_get_jid ()
void | lm_connection_set_jid ()
guint | lm_connection_get_port ()
void | lm_connection_set_port ()
LmSSL * | lm_connection_get_ssl ()
void | lm_connection_set_ssl ()
LmProxy * | lm_connection_get_proxy ()
void | lm_connection_set_proxy ()
gboolean | lm_connection_send ()
gboolean | lm_connection_send_with_reply ()
LmMessage * | lm_connection_send_with_reply_and_block ()
void | lm_connection_unregister_reply_handler ()
void | lm_connection_register_message_handler ()
void | lm_connection_unregister_message_handler ()
void | lm_connection_set_disconnect_function ()
gboolean | lm_connection_send_raw ()
LmConnectionState | lm_connection_get_state ()
LmConnection * | lm_connection_ref ()
void | lm_connection_unref ()

## Types and Values

#define | LM_CONNECTION_DEFAULT_PORT
#define | LM_CONNECTION_DEFAULT_PORT_SSL
| LmConnection
enum | LmHandlerResult
enum | LmHandlerPriority
enum | LmDisconnectReason
enum | LmConnectionState

## Description

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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    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;
    }

## Functions

### LM_CONNECTION()

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

Convenience macro used to cast a pointer to a LmConnection.

#### Parameters

o | pointer to cast |

### LmResultFunction ()

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

Callback for informing if an asynchronous operation was successful.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.3.5

#### Parameters

connection | an LmConnection |

### 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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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.

#### Parameters

connection | an LmConnection |

#### Returns

### lm_connection_set_port ()

    void
    lm_connection_set_port (LmConnection *connection,
                            guint port);

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

connection | an LmConnection |
message | an LmMessage |
error | Set if error was detected during sending. |

#### Returns

The reply

### lm_connection_unregister_reply_handler ()

    void
    lm_connection_unregister_reply_handler
                                   (LmConnection *connection,
                                    LmMessageHandler *handler);

Unregisters the reply handler for `connection` . `handler` will no longer be called if an incoming message has the id for which it was registered.

#### Parameters

connection | Connection to unregister a handler for. |
handler | The handler to unregister. |

### 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()`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

connection | Connection to remove reference from. |

## Types and Values

### 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;

### enum LmHandlerResult

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

#### Members

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

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.

#### Members

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

Sent with LmDisconnectFunction to describe why a connection was closed.

#### Members

LM_DISCONNECT_REASON_OK |  |
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 |  |
LM_DISCONNECT_REASON_INVALID_XML |  |
LM_DISCONNECT_REASON_UNKNOWN | An unknown error. |

### enum LmConnectionState

Describes the current state of an LmConnection.

#### Members

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. |