![]() | ![]() | ![]() | 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;void (*LmResultFunction) (LmConnection *connection,gboolean success,gpointer user_data);void (*LmDisconnectFunction) (LmConnection *connection, LmDisconnectReason reason,gpointer user_data); LmConnection* lm_connection_new (constgchar *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, constgchar *username, constgchar *password, constgchar *resource, LmResultFunction function,gpointer user_data,GDestroyNotify notify,GError **error);gboolean lm_connection_authenticate_and_block (LmConnection *connection, constgchar *username, constgchar *password, constgchar *resource,GError **error);gboolean lm_connection_is_open (LmConnection *connection);gboolean lm_connection_is_authenticated (LmConnection *connection); constgchar * lm_connection_get_server (LmConnection *connection);void lm_connection_set_server (LmConnection *connection, constgchar *server);guint lm_connection_get_port (LmConnection *connection);void lm_connection_set_port (LmConnection *connection,guint port);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, constgchar *str,GError **error); LmConnection* lm_connection_ref (LmConnection *connection);void lm_connection_unref (LmConnection *connection);
#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 |
LM_HANDLER_PRIORITY_NORMAL | Called before handlers with priority |
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. |
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 (constgchar *server);
Creates a new closed connection. To open the connection call
lm_connection_open(). server can be
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 : | |
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 : | |
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 |
gboolean lm_connection_authenticate (LmConnection *connection, constgchar *username, constgchar *password, constgchar *resource, LmResultFunction function,gpointer user_data,GDestroyNotify notify,GError **error);
Tries to authenticate a user against the server. The
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 : | |
gboolean lm_connection_authenticate_and_block (LmConnection *connection, constgchar *username, constgchar *password, constgchar *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 : | |
gboolean lm_connection_is_open (LmConnection *connection);
Check if the connection is currently open.
connection : | LmConnection to check if it is open. |
Returns : | |
gboolean lm_connection_is_authenticated (LmConnection *connection);
Check if connection is authenticated.
connection : | LmConnection to check if it is authenticated |
Returns : | |
constgchar * 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, constgchar *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 |
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 |
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 : | |
error : | location to store error, or NULL |
Returns : | Returns |
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
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 |
gboolean lm_connection_send_raw (LmConnection *connection, constgchar *str,GError **error);
Asynchronous call to send a raw string. Useful for debugging and testing.
connection : | Connection used to send |
str : | The string to send, the entire string will be sent. |
error : | Set if error was detected during sending. |
Returns : | Returns |
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 >> |