<!-- ##### SECTION Title ##### -->
LmConnection
<!-- ##### SECTION Short_Description ##### -->
A client connection to the server
<!-- ##### SECTION Long_Description ##### -->
<para>
An example of how to use Loudmouth with the synchronous API.
<informalexample><programlisting>
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;
}
</programlisting></informalexample>
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### MACRO LM_CONNECTION ##### -->
<para>
Convenience macro used to cast a pointer to a #LmConnection.
</para>
@o: pointer to cast
<!-- ##### MACRO LM_CONNECTION_DEFAULT_PORT ##### -->
<para>
Default jabber client port.
</para>
<!-- ##### MACRO LM_CONNECTION_DEFAULT_PORT_SSL ##### -->
<para>
Default jabber client port when using SSL encryption.
</para>
<!-- ##### STRUCT LmConnection ##### -->
<para>
This should not be accessed directly. Use the accessor functions as described below.
</para>
<!-- ##### ENUM LmHandlerResult ##### -->
<para>
The return type of an LmMessageHandler. This determines whether more message handlers should be called.
</para>
@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 ##### -->
<para>
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.
</para>
@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 ##### -->
<para>
Sent with #LmDisconnectFunction to describe why a connection was closed.
</para>
@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 ##### -->
<para>
Describes the current state of an #LmConnection.
</para>
@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.
<!-- ##### USER_FUNCTION LmResultFunction ##### -->
<para>
Callback for informing if an asynchronous operation was successful.
</para>
@connection: an #LmConnection
@success: the result, %TRUE if operation succeeded, otherwise %FALSE
@user_data: User data passed when function being called.
<!-- ##### USER_FUNCTION LmDisconnectFunction ##### -->
<para>
Callback called when a connection is closed.
</para>
@connection: an #LmConnection
@reason: the reason the connection was closed.
@user_data: User data passed when function being called.
<!-- ##### FUNCTION lm_connection_new ##### -->
<para>
</para>
@server:
@Returns:
<!-- ##### FUNCTION lm_connection_new_with_context ##### -->
<para>
</para>
@server:
@context:
@Returns:
<!-- ##### FUNCTION lm_connection_open ##### -->
<para>
</para>
@connection:
@function:
@user_data:
@notify:
@error:
@Returns:
<!-- ##### FUNCTION lm_connection_open_and_block ##### -->
<para>
</para>
@connection:
@error:
@Returns:
<!-- ##### FUNCTION lm_connection_close ##### -->
<para>
</para>
@connection:
@error:
@Returns:
<!-- ##### FUNCTION lm_connection_authenticate ##### -->
<para>
</para>
@connection:
@username:
@password:
@resource:
@function:
@user_data:
@notify:
@error:
@Returns:
<!-- ##### FUNCTION lm_connection_authenticate_and_block ##### -->
<para>
</para>
@connection:
@username:
@password:
@resource:
@error:
@Returns:
<!-- ##### FUNCTION lm_connection_set_keep_alive_rate ##### -->
<para>
</para>
@connection:
@rate:
<!-- ##### FUNCTION lm_connection_is_open ##### -->
<para>
</para>
@connection:
@Returns:
<!-- ##### FUNCTION lm_connection_is_authenticated ##### -->
<para>
</para>
@connection:
@Returns:
<!-- ##### FUNCTION lm_connection_get_server ##### -->
<para>
</para>
@connection:
@Returns:
<!-- ##### FUNCTION lm_connection_set_server ##### -->
<para>
</para>
@connection:
@server:
<!-- ##### FUNCTION lm_connection_get_jid ##### -->
<para>
</para>
@connection:
@Returns:
<!-- ##### FUNCTION lm_connection_set_jid ##### -->
<para>
</para>
@connection:
@jid:
<!-- ##### FUNCTION lm_connection_get_port ##### -->
<para>
</para>
@connection:
@Returns:
<!-- ##### FUNCTION lm_connection_set_port ##### -->
<para>
</para>
@connection:
@port:
<!-- ##### FUNCTION lm_connection_get_ssl ##### -->
<para>
</para>
@connection:
@Returns:
<!-- ##### FUNCTION lm_connection_set_ssl ##### -->
<para>
</para>
@connection:
@ssl:
<!-- ##### FUNCTION lm_connection_get_proxy ##### -->
<para>
</para>
@connection:
@Returns:
<!-- ##### FUNCTION lm_connection_set_proxy ##### -->
<para>
</para>
@connection:
@proxy:
<!-- ##### FUNCTION lm_connection_send ##### -->
<para>
</para>
@connection:
@message:
@error:
@Returns:
<!-- ##### FUNCTION lm_connection_send_with_reply ##### -->
<para>
</para>
@connection:
@message:
@handler:
@error:
@Returns:
<!-- ##### FUNCTION lm_connection_send_with_reply_and_block ##### -->
<para>
</para>
@connection:
@message:
@error:
@Returns:
<!-- ##### FUNCTION lm_connection_register_message_handler ##### -->
<para>
</para>
@connection:
@handler:
@type:
@priority:
<!-- ##### FUNCTION lm_connection_unregister_message_handler ##### -->
<para>
</para>
@connection:
@handler:
@type:
<!-- ##### FUNCTION lm_connection_set_disconnect_function ##### -->
<para>
</para>
@connection:
@function:
@user_data:
@notify:
<!-- ##### FUNCTION lm_connection_send_raw ##### -->
<para>
</para>
@connection:
@str:
@error:
@Returns:
<!-- ##### FUNCTION lm_connection_get_state ##### -->
<para>
</para>
@connection:
@Returns:
<!-- ##### FUNCTION lm_connection_ref ##### -->
<para>
</para>
@connection:
@Returns:
<!-- ##### FUNCTION lm_connection_unref ##### -->
<para>
</para>
@connection:
y<