![]() |
![]() |
![]() |
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
);
typedef enum { LM_HANDLER_RESULT_REMOVE_MESSAGE, LM_HANDLER_RESULT_ALLOW_MORE_HANDLERS } LmHandlerResult;
typedef enum { LM_HANDLER_PRIORITY_LAST = 1, LM_HANDLER_PRIORITY_NORMAL = 2, LM_HANDLER_PRIORITY_FIRST = 3 } LmHandlerPriority;
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;
typedef enum { LM_CONNECTION_STATE_CLOSED, LM_CONNECTION_STATE_OPENING, LM_CONNECTION_STATE_OPEN, LM_CONNECTION_STATE_AUTHENTICATING, LM_CONNECTION_STATE_AUTHENTICATED } 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
);
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. |