## LmMessageHandler LmMessageHandler — A handler for incoming messages. |

## Synopsis

    LmHandlerResult     (*LmHandleMessageFunction)          (LmMessageHandler *handler,
                                                             LmConnection *connection,
                                                             LmMessage *message,
                                                             gpointer user_data);
    LmMessageHandler *  lm_message_handler_new              (LmHandleMessageFunction function,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);
    void                lm_message_handler_invalidate       (LmMessageHandler *handler);
    gboolean            lm_message_handler_is_valid         (LmMessageHandler *handler);
    LmMessageHandler *  lm_message_handler_ref              (LmMessageHandler *handler);
    void                lm_message_handler_unref            (LmMessageHandler *handler);

## Description

A handler can be registered to listen to incoming messages with `lm_connection_register_message_handler()`. When a message is recieved the handlers of the correct type will be called.

## Details

### LmHandleMessageFunction ()

    LmHandlerResult     (*LmHandleMessageFunction)          (LmMessageHandler *handler,
                                                             LmConnection *connection,
                                                             LmMessage *message,
                                                             gpointer user_data);

The actual callback function in an LmMessageHandler. This function is called when an incoming message arrives that haven't been handled by an handler with higher priority.

`handler` : | an LmMessageHandler
`connection` : | an LmConnection
`message` : | an LmMessage
`user_data` : | user data set when creating the handler
Returns : | #LM_HANDLER_RESULT_REMOVE_MESSAGE to indicate that message has been handled, otherwise LM_HANDLER_RESULT_ALLOW_MORE_HANDLERS.

### lm_message_handler_new ()

    LmMessageHandler *  lm_message_handler_new              (LmHandleMessageFunction function,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);

Creates a new message handler. This can be set to handle incoming messages and when a message of the type the handler is registered to handle is received `function` will be called and `user_data` will be passed to it. `notify` is called when the message handler is freed, that way any memory allocated by `user_data` can be freed.

`function` : | a callback
`user_data` : | user data passed to function
`notify` : | function called when the message handler is freed
Returns : | a newly created message handler

### lm_message_handler_invalidate ()

    void                lm_message_handler_invalidate       (LmMessageHandler *handler);

Invalidates the handler. Useful if you need to cancel a reply

`handler` : | an LmMessageHandler

### lm_message_handler_is_valid ()

    gboolean            lm_message_handler_is_valid         (LmMessageHandler *handler);

Fetches whether the handler is valid or not.

`handler` : | an LmMessageHandler
Returns : | TRUE if `handler` is valid, otherwise FALSE

### lm_message_handler_ref ()

    LmMessageHandler *  lm_message_handler_ref              (LmMessageHandler *handler);

Adds a reference to `handler`.

`handler` : | an LmMessageHandler
Returns : | the message handler

### lm_message_handler_unref ()

    void                lm_message_handler_unref            (LmMessageHandler *handler);

Removes a reference from `handler`. When no more references are present the handler is freed.

`handler` : | an LmMessagHandler