libinfinity-0.6 Reference Manual: InfChatSession

## InfChatSession InfChatSession — Simple standalone chat |

## Stability Level

Unstable, unless otherwise indicated

## Functions

InfChatSession * | inf_chat_session_new ()
gboolean | inf_chat_session_set_log_file ()

## Properties

gchar * | log-file | Read / Write

## Signals

void | receive-message | Run Last
void | send-message | Run Last

## Types and Values

struct | InfChatSession
struct | InfChatSessionClass
enum | InfChatSessionError

## Object Hierarchy

        GObject
        ╰── InfSession
            ╰── InfChatSession

## Implemented Interfaces

InfChatSession implements InfCommunicationObject.

## Includes

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

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

## Functions

### inf_chat_session_new ()

    InfChatSession *
    inf_chat_session_new (InfCommunicationManager *manager,
                          InfChatBuffer *buffer,
                          InfSessionStatus status,
                          InfCommunicationGroup *sync_group,
                          InfXmlConnection *sync_connection);

Creates a new InfChatSession with the messages contained in `buffer` as initial messages. The communication manager is used to send and receive requests from subscription and synchronization.

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

#### Parameters

manager | A InfCommunicationManager. |
buffer | The InfChatBuffer to use for the session. |
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.

#### Parameters

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

## Types and Values

### struct InfChatSession

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

#### Members

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

### enum InfChatSessionError

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

#### Members

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

## Property Details

### The `“log-file”` property

      “log-file”                 gchar *

The file into which to store all received messages.

Flags: Read / Write

Default value: NULL

## Signal Details

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

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

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.

#### Parameters

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

Flags: Run Last

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

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

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.

#### Parameters

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

Flags: Run Last