libinfinity-0.6 Reference Manual: InfChatBuffer

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

## Stability Level

Unstable, unless otherwise indicated

## Functions

InfChatBufferMessage * | inf_chat_buffer_message_copy ()
void | inf_chat_buffer_message_free ()
InfChatBuffer * | inf_chat_buffer_new ()
void | inf_chat_buffer_add_message ()
void | inf_chat_buffer_add_emote_message ()
void | inf_chat_buffer_add_userjoin_message ()
void | inf_chat_buffer_add_userpart_message ()
const InfChatBufferMessage * | inf_chat_buffer_get_message ()
guint | inf_chat_buffer_get_n_messages ()
guint | inf_chat_buffer_get_size ()

## Properties

guint | size | Read / Write / Construct Only

## Signals

void | add-message | Run Last

## Types and Values

enum | InfChatBufferMessageType
enum | InfChatBufferMessageFlags
struct | InfChatBufferMessage
struct | InfChatBuffer
struct | InfChatBufferClass

## Object Hierarchy

        GBoxed
        ╰── InfChatBufferMessage
        GEnum
        ╰── InfChatBufferMessageType
        GFlags
        ╰── InfChatBufferMessageFlags
        GObject
        ╰── InfChatBuffer

## Implemented Interfaces

InfChatBuffer implements InfBuffer.

## Includes

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

## Description

InfChatBuffer contains the chat messages for a InfChatSession.

## Functions

### inf_chat_buffer_message_copy ()

    InfChatBufferMessage *
    inf_chat_buffer_message_copy (const InfChatBufferMessage *message);

Creates a copy of the given message.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

buffer | A InfChatBuffer. |

#### Returns

The number of messages in the chat buffer.

## Types and Values

### enum InfChatBufferMessageType

Possible chat message types.

#### Members

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

Possible chat message flags.

#### Members

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.

#### Members

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

### struct InfChatBuffer

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

#### Members

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

## Property Details

### The `“size”` property

      “size”                     guint

The maxmimum number of messages saved.

Flags: Read / Write / Construct Only

Default value: 256

## Signal Details

### The `“add-message”` signal

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

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

#### Parameters

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

Flags: Run Last