LmConnection

LmConnection — A client connection to the server

Synopsis




#define     LM_CONNECTION                   (o)
#define     LM_CONNECTION_DEFAULT_PORT
#define     LM_CONNECTION_DEFAULT_PORT_SSL
struct      LmConnection;
enum        LmHandlerResult;
enum        LmHandlerPriority;
enum        LmDisconnectReason;
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);
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);
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);
guint       lm_connection_get_port          (LmConnection *connection);
void        lm_connection_set_port          (LmConnection *connection,
                                             guint port);
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);
LmConnection* lm_connection_ref             (LmConnection *connection);
void        lm_connection_unref             (LmConnection *connection);

Description

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.

struct LmConnection

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

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