|  |  |  | Loudmouth Reference Manual |  | 
|---|
LmConnection — A client connection to the server
#define LM_CONNECTION (o) #define LM_CONNECTION_DEFAULT_PORT #define LM_CONNECTION_DEFAULT_PORT_SSL struct 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); 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); 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);
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: <literal>s</literal>\n", error->message);
        }
	if (!lm_connection_authenticate_and_block (connection,
						   "username", "password", 
						   "resource",
						   &error)) {
		g_error ("Failed to authenticate: <literal>s</literal>\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: <literal>s</literal>\n", error->message);
	}
	lm_message_unref (m);
	lm_connection_close (connection, NULL);
	lm_connection_unref (connection);
	
        return 0;
}
#define LM_CONNECTION(o) (LmConnection *) o;
Convenience macro used to cast a pointer to a LmConnection.
| o : | pointer to cast | 
#define LM_CONNECTION_DEFAULT_PORT_SSL 5223
Default jabber client port when using SSL encryption.
struct LmConnection;
This should not be accessed directly. Use the accessor functions as described below.
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. | 
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. | 
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. | 
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. | 
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. | 
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. | 
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(). | 
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. | 
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. | 
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. | 
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. | 
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. | 
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. | 
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. | 
const gchar* lm_connection_get_server (LmConnection *connection);
Fetches the server address that connection is using.
| connection : | an LmConnection | 
| Returns : | the server address | 
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 | 
guint lm_connection_get_port (LmConnection *connection);
Fetches the port that connection is using.
| connection : | an LmConnection | 
| Returns : | 
void lm_connection_set_port (LmConnection *connection, guint port);
Sets the server port that connection will be using.
| connection : | an LmConnection | 
| port : | server port | 
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. | 
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 | 
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. | 
void lm_connection_set_proxy (LmConnection *connection, LmProxy *proxy);
Sets the proxy to use for this connection. To unset pass a proxy of type LM_PROXY_TYPE_NONE to this function.
| connection : | an LmConnection | 
| proxy : | an LmProxy | 
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. | 
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. | 
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 | 
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. | 
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. | 
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. | 
gboolean lm_connection_send_raw (LmConnection *connection, const gchar *str, GError **error);
Asynchronous call to send a raw string. Useful for debugging and testing.
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. | 
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. | 
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. | 
| << Loudmouth | LmError >> |