| Loudmouth Reference Manual | ||||
|---|---|---|---|---|
| Top | Description | ||||
#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); guint lm_connection_get_keep_alive_rate (LmConnection *connection); 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);
An example of how to use Loudmouth with the synchronous API.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
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; } |
#define LM_CONNECTION(o) (LmConnection *) o;
Convenience macro used to cast a pointer to a LmConnection.
|
pointer to cast |
#define LM_CONNECTION_DEFAULT_PORT_SSL 5223
Default jabber client port when using SSL encryption.
typedef struct _LmConnection 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.
| Stop calling message handlers. The message handler returning this declares the message has been handled and should be removed. | |
| 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.
typedef enum {
LM_DISCONNECT_REASON_OK,
LM_DISCONNECT_REASON_PING_TIME_OUT,
LM_DISCONNECT_REASON_HUP,
LM_DISCONNECT_REASON_ERROR,
LM_DISCONNECT_REASON_RESOURCE_CONFLICT,
LM_DISCONNECT_REASON_INVALID_XML,
LM_DISCONNECT_REASON_UNKNOWN
} LmDisconnectReason;
Sent with LmDisconnectFunction to describe why a connection was closed.
| User requested disconnect. | |
| Connection to the server timed out. | |
| The socket emitted that the connection was hung up. | |
| A generic error somewhere in the transport layer. | |
| Another connection was made to the server with the same resource. | |
| Invalid XML was sent from the client. | |
| 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.
| The connection is closed. | |
| The connection is in the process of opening. | |
| The connection is open. | |
| The connection is in the process of authenticating. | |
| 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.
|
an LmConnection |
|
the result, TRUE if operation succeeded, otherwise FALSE
|
|
User data passed when function being called. |
void (*LmDisconnectFunction) (LmConnection *connection,LmDisconnectReason reason,gpointer user_data);
Callback called when a connection is closed.
|
an LmConnection |
|
the reason the connection was closed. |
|
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().
|
The hostname to the server for the connection. |
Returns : |
A newly created LmConnection, should be unreffed with lm_connection_unref(). |
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.
|
The hostname to the server for the connection. |
|
The context this connection should be running in. |
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.
|
LmConnection to open |
|
Callback function that will be called when the connection is open. |
|
User data that will be passed to function. |
|
Function for freeing that user_data, can be NULL. |
|
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.
|
an LmConnection to open |
|
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().
|
LmConnection to close |
|
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.
|
LmConnection to authenticate. |
|
Username used to authenticate. |
|
Password corresponding to username. |
|
Resource used for this connection. |
|
Callback called when authentication is finished. |
|
Userdata passed to function when called. |
|
Destroy function to free the memory used by user_data, can be NULL. |
|
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.
|
an LmConnection |
|
Username used to authenticate. |
|
Password corresponding to username. |
|
Resource used for this connection. |
|
location to store error, or NULL
|
Returns : |
TRUE if no errors where detected and authentication was successful. FALSE otherwise. |
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.4.0
|
an LmConnection |
Returns : |
The keep alive rate in seconds. |
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.
|
an LmConnection |
|
Number of seconds between keep alive packages are sent. |
gboolean lm_connection_is_open (LmConnection *connection);
Check if the connection is currently open.
|
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.
|
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.
|
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.
|
an LmConnection |
|
Address of the server |
const gchar * lm_connection_get_jid (LmConnection *connection);
Fetches the jid set for connection is using.
|
an LmConnection |
Returns : |
the jid |
void lm_connection_set_jid (LmConnection *connection,const gchar *jid);
Sets the JID to be used for connection.
|
an LmConnection |
|
JID to be used for connection
|
guint lm_connection_get_port (LmConnection *connection);
Fetches the port that connection is using.
|
an LmConnection |
Returns : |
The port used. |
void lm_connection_set_port (LmConnection *connection,guint port);
Sets the server port that connection will be using.
|
an LmConnection |
|
server port |
LmSSL * lm_connection_get_ssl (LmConnection *connection);
Returns the SSL struct if the connection is using one.
|
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.
|
An LmConnection |
|
An LmSSL |
LmProxy * lm_connection_get_proxy (LmConnection *connection);
Returns the proxy if the connection is using one.
|
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 NULL.
|
an LmConnection |
|
an LmProxy |
gboolean lm_connection_send (LmConnection *connection,LmMessage *message,GError **error);
Asynchronous call to send a message.
|
LmConnection to send message over. |
|
LmMessage to send. |
|
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.
|
LmConnection used to send message. |
|
LmMessage to send. |
|
LmMessageHandler that will be used when a reply to message arrives |
|
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.
|
an LmConnection |
|
an LmMessage |
|
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 to register a handler for. |
|
Message handler to register. |
|
Message type that handler will handle. |
|
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 to unregister a handler for. |
|
The handler to unregister. |
|
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 to register disconnect callback for. |
|
Function to be called when connection is closed. |
|
User data passed to function. |
|
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 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 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 to remove reference from. |