![]() |
![]() |
![]() |
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.
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.
|
Connection used to send |
|
The string to send, the entire string will be sent. |
|
Set if error was detected during sending. |
Returns : |
Returns TRUE if no errors was detected during sending, FALSE otherwise. |
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. |