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.

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

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.