## InfChatSession InfChatSession — Simple standalone chat |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

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

                        InfChatSession;
    struct              InfChatSessionClass;
    enum                InfChatSessionError;
    InfChatSession *    inf_chat_session_new                (InfCommunicationManager *manager,
                                                             guint backlog_size,
                                                             InfSessionStatus status,
                                                             InfCommunicationGroup *sync_group,
                                                             InfXmlConnection *sync_connection);
    gboolean            inf_chat_session_set_log_file       (InfChatSession *session,
                                                             const gchar *log_file,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----InfSession
             +----InfChatSession

## Implemented Interfaces

InfChatSession implements InfCommunicationObject.

## Properties

      "log-file"                 gchar*                : Read / Write

## Signals

      "receive-message"                                : Run Last
      "send-message"                                   : Run Last

## Description

InfChatSession represents a chat session. Normally, there is one chat session per server, and it can be enabled via `infd_directory_enable_chat()`. Clients can subscribe to the chat session via `infc_browser_subscribe_chat()`.

## Details

### InfChatSession

    typedef struct _InfChatSession InfChatSession;

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

### struct InfChatSessionClass

    struct InfChatSessionClass {
      void (*receive_message)(InfChatSession* session,
                              const InfChatBufferMessage* message);
      void (*send_message)(InfChatSession* session,
                           const InfChatBufferMessage* message);
    };

This structure contains default signal handlers for InfChatSession.

`receive_message` () | Default signal handler for the "receive-message" signal.
`send_message` () | Default signal handler for the "send-message" signal.

### enum InfChatSessionError

    typedef enum {
      INF_CHAT_SESSION_ERROR_TYPE_INVALID,
      INF_CHAT_SESSION_ERROR_NO_SUCH_USER,

      INF_CHAT_SESSION_ERROR_FAILED
    } InfChatSessionError;

Errors that can occur with a chat session, especially in the process_xml_sync and process_xml_run vfunc implementations.

`INF_CHAT_SESSION_ERROR_TYPE_INVALID` | An invalid message type was sent.
`INF_CHAT_SESSION_ERROR_NO_SUCH_USER` | A message referred to a nonexisting user.
`INF_CHAT_SESSION_ERROR_FAILED` | Generic error code when no further reason of failure is known.

### inf_chat_session_new ()

    InfChatSession *    inf_chat_session_new                (InfCommunicationManager *manager,
                                                             guint backlog_size,
                                                             InfSessionStatus status,
                                                             InfCommunicationGroup *sync_group,
                                                             InfXmlConnection *sync_connection);

Creates a new InfChatSession with no initial messages. The communication manager is used to send and receive requests from subscription and synchronization.

`backlog_size` specifies how much messages to save before dropping old messages. This also limits how many old messages are transferred when synchronizing the session.

If `status` is `INF_SESSION_PRESYNC` or `INF_SESSION_SYNCHRONIZING`, then the session will initially be synchronized, meaning an initial backlog is retrieved from `sync_connection` (which must not be `NULL` in this case). If you are subscribed to the session, set the subscription group via `inf_session_set_subscription_group()`.

`manager` : | A InfCommunicationManager.
`backlog_size` : | The number of messages to store.
`status` : | Initial status of the session. If this is `INF_SESSION_SYNCHRONIZING` or `INF_SESSION_PRESYNC`, then `sync_group` and `sync_connection` need to be set.
`sync_group` : | A group in which the session is synchronized. Ignored if `status` is `INF_SESSION_RUNNING`.
`sync_connection` : | A connection to synchronize the session from. Ignored if `status` is `INF_SESSION_RUNNING`.
Returns : | A new InfChatSession.

### inf_chat_session_set_log_file ()

    gboolean            inf_chat_session_set_log_file       (InfChatSession *session,
                                                             const gchar *log_file,
                                                             GError **error);

Sets a file onto which all received messages are appended. The file is created if it does not exist. If a previous log file was set, then it is closed before opening the new file.

Backlog messages received upon synchronization are not logged.

`session` : | A InfChatSession.
`log_file` : | A filename to store all received messages into.
`error` : | Location to store error information, if any.
Returns : | `TRUE` if the log file could be opened, `FALSE` otherwise (in which case `error` is set).

## Property Details

### The `"log-file"` property

      "log-file"                 gchar*                : Read / Write

The file into which to store all received messages.

Default value: NULL

## Signal Details

### The `"receive-message"` signal

    void                user_function                      (InfChatSession       *session,
                                                            InfChatBufferMessage *message,
                                                            gpointer              user_data)      : Run Last

This signal is emitted whenever a message has been received. If the session is in `INF_SESSION_SYNCHRONIZING` state the received message was a backlog message.

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

### The `"send-message"` signal

    void                user_function                      (InfChatSession       *session,
                                                            InfChatBufferMessage *message,
                                                            gpointer              user_data)      : Run Last

This signal is emitted whenever a message is sent. Messages can be sent by calling `inf_chat_buffer_add_message()` or `inf_chat_buffer_add_emote_message()` on the session's InfChatBuffer. Messages of type `INF_CHAT_BUFFER_MESSAGE_USERJOIN` or `INF_CHAT_BUFFER_MESSAGE_USERPART` can not be sent explicitely, so this signal will never be emitted for such messages.

`session` : | The InfChatSession that is sending a message.
`message` : | The InfChatBufferMessage that is sent.
`user_data` : | user data set when the signal handler was connected.