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);
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_UNKNOWN,
	LM_DISCONNECT_REASON_RESOURCE_CONFLICT,
	LM_DISCONNECT_REASON_INVALID_XML
} LmDisconnectReason;

Sent with LmDisconnectFunction to describe why a connection was closed.

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_UNKNOWN An unknown error.
LM_DISCONNECT_REASON_RESOURCE_CONFLICT
LM_DISCONNECT_REASON_INVALID_XML

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_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 : LmConnection to check if it is open.
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 :

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.