LmConnection

LmConnection — A client connection to the server

Functions

Types and Values

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.