## InfChatBuffer InfChatBuffer — A ring buffer for chat messages |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <libinfinity/common/inf-chat-buffer.h>

    enum                InfChatBufferMessageType;
    enum                InfChatBufferMessageFlags;
    struct              InfChatBufferMessage;
                        InfChatBuffer;
    struct              InfChatBufferClass;
    InfChatBufferMessage * inf_chat_buffer_message_copy     (const InfChatBufferMessage *message);
    void                inf_chat_buffer_message_free        (InfChatBufferMessage *message);
    InfChatBuffer *     inf_chat_buffer_new                 (guint size);
    void                inf_chat_buffer_add_message         (InfChatBuffer *buffer,
                                                             InfUser *by,
                                                             const gchar *message,
                                                             gsize length,
                                                             time_t time,
                                                             InfChatBufferMessageFlags flags);
    void                inf_chat_buffer_add_emote_message   (InfChatBuffer *buffer,
                                                             InfUser *by,
                                                             const gchar *message,
                                                             gsize length,
                                                             time_t time,
                                                             InfChatBufferMessageFlags flags);
    void                inf_chat_buffer_add_userjoin_message
                                                            (InfChatBuffer *buffer,
                                                             InfUser *user,
                                                             time_t time,
                                                             InfChatBufferMessageFlags flags);
    void                inf_chat_buffer_add_userpart_message
                                                            (InfChatBuffer *buffer,
                                                             InfUser *user,
                                                             time_t time,
                                                             InfChatBufferMessageFlags flags);
    const InfChatBufferMessage * inf_chat_buffer_get_message
                                                            (InfChatBuffer *buffer,
                                                             guint n);
    guint               inf_chat_buffer_get_n_messages      (InfChatBuffer *buffer);
    guint               inf_chat_buffer_get_size            (InfChatBuffer *buffer);

## Object Hierarchy

      GEnum
       +----InfChatBufferMessageType

      GFlags
       +----InfChatBufferMessageFlags

      GBoxed
       +----InfChatBufferMessage

      GObject
       +----InfChatBuffer

## Implemented Interfaces

InfChatBuffer implements InfBuffer.

## Properties

      "size"                     guint                 : Read / Write / Construct Only

## Signals

      "add-message"                                    : Run Last

## Description

InfChatBuffer contains the chat messages for a InfChatSession.

## Details

### enum InfChatBufferMessageType

    typedef enum {
      INF_CHAT_BUFFER_MESSAGE_NORMAL,
      INF_CHAT_BUFFER_MESSAGE_EMOTE,
      INF_CHAT_BUFFER_MESSAGE_USERJOIN,
      INF_CHAT_BUFFER_MESSAGE_USERPART
    } InfChatBufferMessageType;

Possible chat message types.

`INF_CHAT_BUFFER_MESSAGE_NORMAL` | A normal chat message.
`INF_CHAT_BUFFER_MESSAGE_EMOTE` | An emote chat message (/me is doing something).
`INF_CHAT_BUFFER_MESSAGE_USERJOIN` | A user join notification.
`INF_CHAT_BUFFER_MESSAGE_USERPART` | A user part notification.

### enum InfChatBufferMessageFlags

    typedef enum {
      INF_CHAT_BUFFER_MESSAGE_BACKLOG = 1 << 0
    } InfChatBufferMessageFlags;

Possible chat message flags.

`INF_CHAT_BUFFER_MESSAGE_BACKLOG` | The message is a backlog message, i.e. it originated in a previous session.

### struct InfChatBufferMessage

    struct InfChatBufferMessage {
      InfChatBufferMessageType type;
      InfUser* user;
      gchar* text;
      gsize length;
      time_t time;
      InfChatBufferMessageFlags flags;
    };

Represents a chat message.

InfChatBufferMessageType `type`; | The InfChatBufferMessageType of the message.
InfUser *`user`; | The InfUser that issued the message.
gchar *`text`; | The UTF-8 encoded text of the message.
gsize `length`; | The length of the message, in bytes.
time_t `time`; | The time at which the message was received.
InfChatBufferMessageFlags `flags`; | Additional flags for the message, see InfChatBufferMessageFlags.

### InfChatBuffer

    typedef struct _InfChatBuffer InfChatBuffer;

InfChatBuffer is an opaque data type. You should only access it via the public API functions.

### struct InfChatBufferClass

    struct InfChatBufferClass {
      void (*add_message)(InfChatBuffer* buffer,
                          const InfChatBufferMessage* message);
    };

This structure contains default signal handlers for InfChatBuffer.

`add_message` () | Default signal handler for the "add-message" signal.

### inf_chat_buffer_message_copy ()

    InfChatBufferMessage * inf_chat_buffer_message_copy     (const InfChatBufferMessage *message);

Creates a copy of the given message.

`message` : | The InfChatBufferMessage to copy.
Returns : | A new InfChatBufferMessage. Free with `inf_chat_buffer_message_free()` when no longer needed.

### inf_chat_buffer_message_free ()

    void                inf_chat_buffer_message_free        (InfChatBufferMessage *message);

Frees the given InfChatBufferMessage which must have been created with `inf_chat_buffer_message_copy()`.

`message` : | A InfChatBufferMessage.

### inf_chat_buffer_new ()

    InfChatBuffer *     inf_chat_buffer_new                 (guint size);

Creates a new InfChatBuffer which contains no initial messages. `size` specifies how many messages to store before dropping old messages.

`size` : | The number of messages to store.
Returns : | A new InfChatBuffer.

### inf_chat_buffer_add_message ()

    void                inf_chat_buffer_add_message         (InfChatBuffer *buffer,
                                                             InfUser *by,
                                                             const gchar *message,
                                                             gsize length,
                                                             time_t time,
                                                             InfChatBufferMessageFlags flags);

Adds a new message to the chat buffer. If the buffer is full (meaning the number of messages in the buffer equals its size), then an old message will get discarded. If the message to be added is older than all other messages in the buffer, then it will not be added at all.

`buffer` : | A InfChatBuffer.
`by` : | A InfUser who wrote the message.
`message` : | The message text.
`length` : | The length of `message`, in bytes.
`time` : | The time at which the user has written the message.
`flags` : | Flags to set for the message to add.

### inf_chat_buffer_add_emote_message ()

    void                inf_chat_buffer_add_emote_message   (InfChatBuffer *buffer,
                                                             InfUser *by,
                                                             const gchar *message,
                                                             gsize length,
                                                             time_t time,
                                                             InfChatBufferMessageFlags flags);

Adds a new emote message to the chat buffer. If the buffer is full (meaning the number of messages in the buffer equals its size), then an old message will get discarded. If the message to be added is older than all other messages in the buffer, then it will not be added at all.

`buffer` : | A InfChatBuffer.
`by` : | A InfUser who wrote the message.
`message` : | The message text.
`length` : | The length of `message`, in bytes.
`time` : | The time at which the user has written the message.
`flags` : | Flags to set for the message to add.

### inf_chat_buffer_add_userjoin_message ()

    void                inf_chat_buffer_add_userjoin_message
                                                            (InfChatBuffer *buffer,
                                                             InfUser *user,
                                                             time_t time,
                                                             InfChatBufferMessageFlags flags);

Adds a new userjoin message to the chat buffer. If the buffer is full (meaning the number of messages in the buffer equals its size), then an old message will get discarded. If the message to be added is older than all other messages in the buffer, then it will not be added at all.

`buffer` : | A InfChatBuffer.
`user` : | A InfUser who wrote the message.
`time` : | The time at which the user has written the message.
`flags` : | Flags to set for the message to add.

### inf_chat_buffer_add_userpart_message ()

    void                inf_chat_buffer_add_userpart_message
                                                            (InfChatBuffer *buffer,
                                                             InfUser *user,
                                                             time_t time,
                                                             InfChatBufferMessageFlags flags);

Adds a new userpart message to the chat buffer. If the buffer is full (meaning the number of messages in the buffer equals its size), then an old message will get discarded. If the message to be added is older than all other messages in the buffer, then it will not be added at all.

`buffer` : | A InfChatBuffer.
`user` : | A InfUser who wrote the message.
`time` : | The time at which the user has written the message.
`flags` : | Flags to set for the message to add.

### inf_chat_buffer_get_message ()

    const InfChatBufferMessage * inf_chat_buffer_get_message
                                                            (InfChatBuffer *buffer,
                                                             guint n);

Returns the message with the given index from the buffer. The oldest message in the buffer has index 0, and the most recent one has index `inf_chat_buffer_get_n_messages()` - 1.

`buffer` : | A InfChatBuffer.
`n` : | The index of the message to obtain.
Returns : | The InfChatBufferMessage with the given index.

### inf_chat_buffer_get_n_messages ()

    guint               inf_chat_buffer_get_n_messages      (InfChatBuffer *buffer);

Returns the number of messages in the buffer.

`buffer` : | A InfChatBuffer.
Returns : | The number of messages in the buffer.

### inf_chat_buffer_get_size ()

    guint               inf_chat_buffer_get_size            (InfChatBuffer *buffer);

Returns the size of the chat buffer, which is the maximum number of messages that can be stored in the buffer.

`buffer` : | A InfChatBuffer.
Returns : | The number of messages in the chat buffer.

## Property Details

### The `"size"` property

      "size"                     guint                 : Read / Write / Construct Only

The maxmimum number of messages saved.

Default value: 256

## Signal Details

### The `"add-message"` signal

    void                user_function                      (InfChatBuffer        *buffer,
                                                            InfChatBufferMessage *message,
                                                            gpointer              user_data)      : Run Last

This signal is emitted whenever a message has been added to `buffer`.

`buffer` : | The InfChatBuffer that is receiving a message.
`message` : | The InfChatBufferMessage that was received.
`user_data` : | user data set when the signal handler was connected.