Loudmouth Reference Manual: LmMessageHandler

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

## Functions

LmHandlerResult | (*LmHandleMessageFunction) ()
LmMessageHandler * | lm_message_handler_new ()
void | lm_message_handler_invalidate ()
gboolean | lm_message_handler_is_valid ()
LmMessageHandler * | lm_message_handler_ref ()
void | lm_message_handler_unref ()

## Types and Values

typedef | LmMessageHandler

## 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.

## Functions

### 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.

#### Parameters

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.

#### Parameters

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

#### Parameters

handler | an LmMessageHandler |

### lm_message_handler_is_valid ()

    gboolean
    lm_message_handler_is_valid (LmMessageHandler *handler);

Fetches whether the handler is valid or not.

#### Parameters

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` .

#### Parameters

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.

#### Parameters

handler | an LmMessageHandler |

## Types and Values

### LmMessageHandler

    typedef struct LmMessageHandler LmMessageHandler;