gaim/gaim
Clone
Summary
Browse
Changes
Graph
dave142 in patch #1193896 noticed that the SetDllDirectory magic probably never worked... This fixes it.
oldstatus
2005-05-03, Daniel Atallah
8e9c0e0ae15c
dave142 in patch #1193896 noticed that the SetDllDirectory magic probably never worked... This fixes it.
/**
* @file conversation.h Conversation API
* @ingroup core
*
* gaim
*
* Gaim is the legal property of its developers, whose names are too numerous
* to list here. Please refer to the COPYRIGHT file distributed with this
* source distribution.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
* @see @ref conversation-signals
*/
#ifndef _GAIM_CONVERSATION_H_
#define _GAIM_CONVERSATION_H_
/**************************************************************************/
/** Data Structures */
/**************************************************************************/
typedef
struct
_GaimConvWindowUiOps
GaimConvWindowUiOps
;
typedef
struct
_GaimConvWindow
GaimConvWindow
;
typedef
struct
_GaimConversationUiOps
GaimConversationUiOps
;
typedef
struct
_GaimConversation
GaimConversation
;
typedef
struct
_GaimConvIm
GaimConvIm
;
typedef
struct
_GaimConvChat
GaimConvChat
;
typedef
struct
_GaimConvChatBuddy
GaimConvChatBuddy
;
/**
* A type of conversation.
*/
typedef
enum
{
GAIM_CONV_UNKNOWN
=
0
,
/**< Unknown conversation type. */
GAIM_CONV_IM
,
/**< Instant Message. */
GAIM_CONV_CHAT
,
/**< Chat room. */
GAIM_CONV_MISC
/**< A misc. conversation. */
}
GaimConversationType
;
/**
* Unseen text states.
*/
typedef
enum
{
GAIM_UNSEEN_NONE
=
0
,
/**< No unseen text in the conversation. */
GAIM_UNSEEN_TEXT
,
/**< Unseen text in the conversation. */
GAIM_UNSEEN_NICK
,
/**< Unseen text and the nick was said. */
GAIM_UNSEEN_EVENT
/**< Unseen events in the conversation. */
}
GaimUnseenState
;
/**
* Conversation update type.
*/
typedef
enum
{
GAIM_CONV_UPDATE_ADD
=
0
,
/**< The buddy associated with the conversation
was added. */
GAIM_CONV_UPDATE_REMOVE
,
/**< The buddy associated with the conversation
was removed. */
GAIM_CONV_UPDATE_ACCOUNT
,
/**< The gaim_account was changed. */
GAIM_CONV_UPDATE_TYPING
,
/**< The typing state was updated. */
GAIM_CONV_UPDATE_UNSEEN
,
/**< The unseen state was updated. */
GAIM_CONV_UPDATE_LOGGING
,
/**< Logging for this conversation was
enabled or disabled. */
GAIM_CONV_UPDATE_TOPIC
,
/**< The topic for a chat was updated. */
/*
* XXX These need to go when we implement a more generic core/UI event
* system.
*/
GAIM_CONV_ACCOUNT_ONLINE
,
/**< One of the user's accounts went online. */
GAIM_CONV_ACCOUNT_OFFLINE
,
/**< One of the user's accounts went offline. */
GAIM_CONV_UPDATE_AWAY
,
/**< The other user went away. */
GAIM_CONV_UPDATE_ICON
,
/**< The other user's buddy icon changed. */
GAIM_CONV_UPDATE_TITLE
,
GAIM_CONV_UPDATE_CHATLEFT
,
GAIM_CONV_UPDATE_FEATURES
,
/**< The features for a chat have changed */
}
GaimConvUpdateType
;
/**
* The typing state of a user.
*/
typedef
enum
{
GAIM_NOT_TYPING
=
0
,
/**< Not typing. */
GAIM_TYPING
,
/**< Currently typing. */
GAIM_TYPED
/**< Stopped typing momentarily. */
}
GaimTypingState
;
/**
* Flags applicable to a message. Most will have send, recv or system.
*/
typedef
enum
{
GAIM_MESSAGE_SEND
=
0x0001
,
/**< Outgoing message. */
GAIM_MESSAGE_RECV
=
0x0002
,
/**< Incoming message. */
GAIM_MESSAGE_SYSTEM
=
0x0004
,
/**< System message. */
GAIM_MESSAGE_AUTO_RESP
=
0x0008
,
/**< Auto response. */
GAIM_MESSAGE_COLORIZE
=
0x0010
,
/**< Colorize nicks. */
GAIM_MESSAGE_NICK
=
0x0020
,
/**< Contains your nick. */
GAIM_MESSAGE_NO_LOG
=
0x0040
,
/**< Do not log. */
GAIM_MESSAGE_WHISPER
=
0x0080
,
/**< Whispered message. */
GAIM_MESSAGE_ERROR
=
0x0200
,
/**< Error message. */
GAIM_MESSAGE_DELAYED
=
0x0400
/**< Delayed message. */
}
GaimMessageFlags
;
/**
* Flags applicable to users in Chats.
*/
typedef
enum
{
GAIM_CBFLAGS_NONE
=
0x0000
,
/**< No flags */
GAIM_CBFLAGS_VOICE
=
0x0001
,
/**< Voiced user or "Participant" */
GAIM_CBFLAGS_HALFOP
=
0x0002
,
/**< Half-op */
GAIM_CBFLAGS_OP
=
0x0004
,
/**< Channel Op or Moderator */
GAIM_CBFLAGS_FOUNDER
=
0x0008
/**< Channel Founder */
}
GaimConvChatBuddyFlags
;
#include
"account.h"
#include
"buddyicon.h"
#include
"log.h"
#include
"server.h"
/**
* Conversation window operations.
*
* Any UI representing a window must assign a filled-out gaim_conv_window_ops
* structure to the GaimConvWindow.
*/
struct
_GaimConvWindowUiOps
{
GaimConversationUiOps
*
(
*
get_conversation_ui_ops
)(
void
);
void
(
*
new_window
)(
GaimConvWindow
*
win
);
void
(
*
destroy_window
)(
GaimConvWindow
*
win
);
void
(
*
show
)(
GaimConvWindow
*
win
);
void
(
*
hide
)(
GaimConvWindow
*
win
);
void
(
*
raise
)(
GaimConvWindow
*
win
);
void
(
*
flash
)(
GaimConvWindow
*
win
);
void
(
*
switch_conversation
)(
GaimConvWindow
*
win
,
unsigned
int
index
);
void
(
*
add_conversation
)(
GaimConvWindow
*
win
,
GaimConversation
*
conv
);
void
(
*
remove_conversation
)(
GaimConvWindow
*
win
,
GaimConversation
*
conv
);
void
(
*
move_conversation
)(
GaimConvWindow
*
win
,
GaimConversation
*
conv
,
unsigned
int
newIndex
);
int
(
*
get_active_index
)(
const
GaimConvWindow
*
win
);
gboolean
(
*
has_focus
)(
GaimConvWindow
*
win
);
};
/**
* Conversation operations and events.
*
* Any UI representing a conversation must assign a filled-out
* GaimConversationUiOps structure to the GaimConversation.
*/
struct
_GaimConversationUiOps
{
void
(
*
destroy_conversation
)(
GaimConversation
*
conv
);
void
(
*
write_chat
)(
GaimConversation
*
conv
,
const
char
*
who
,
const
char
*
message
,
GaimMessageFlags
flags
,
time_t
mtime
);
void
(
*
write_im
)(
GaimConversation
*
conv
,
const
char
*
who
,
const
char
*
message
,
GaimMessageFlags
flags
,
time_t
mtime
);
void
(
*
write_conv
)(
GaimConversation
*
conv
,
const
char
*
who
,
const
char
*
message
,
GaimMessageFlags
flags
,
time_t
mtime
);
void
(
*
chat_add_user
)(
GaimConversation
*
conv
,
const
char
*
user
,
gboolean
new_arrival
);
void
(
*
chat_add_users
)(
GaimConversation
*
conv
,
GList
*
users
);
void
(
*
chat_rename_user
)(
GaimConversation
*
conv
,
const
char
*
old_name
,
const
char
*
new_name
);
void
(
*
chat_remove_user
)(
GaimConversation
*
conv
,
const
char
*
user
);
void
(
*
chat_remove_users
)(
GaimConversation
*
conv
,
GList
*
users
);
void
(
*
chat_update_user
)(
GaimConversation
*
conv
,
const
char
*
user
);
void
(
*
update_progress
)(
GaimConversation
*
conv
,
float
percent
);
gboolean
(
*
has_focus
)(
GaimConversation
*
conv
);
/* Events */
void
(
*
updated
)(
GaimConversation
*
conv
,
GaimConvUpdateType
type
);
};
/**
* A core representation of a graphical window containing one or more
* conversations.
*/
struct
_GaimConvWindow
{
GList
*
conversations
;
/**< The conversations in the window. */
size_t
conversation_count
;
/**< The number of conversations. */
GaimConvWindowUiOps
*
ui_ops
;
/**< UI-specific window operations. */
void
*
ui_data
;
/**< UI-specific data. */
};
/**
* Data specific to Instant Messages.
*/
struct
_GaimConvIm
{
GaimConversation
*
conv
;
/**< The parent conversation. */
GaimTypingState
typing_state
;
/**< The current typing state. */
guint
typing_timeout
;
/**< The typing timer handle. */
time_t
type_again
;
/**< The type again time. */
guint
type_again_timeout
;
/**< The type again timer handle. */
GaimBuddyIcon
*
icon
;
/**< The buddy icon. */
};
/**
* Data specific to Chats.
*/
struct
_GaimConvChat
{
GaimConversation
*
conv
;
/**< The parent conversation. */
GList
*
in_room
;
/**< The users in the room. */
GList
*
ignored
;
/**< Ignored users. */
char
*
who
;
/**< The person who set the topic. */
char
*
topic
;
/**< The topic. */
int
id
;
/**< The chat ID. */
char
*
nick
;
/**< Your nick in this chat. */
gboolean
left
;
/**< We left the chat and kept the window open */
};
/**
* Data for "Chat Buddies"
*/
struct
_GaimConvChatBuddy
{
char
*
name
;
/**< The name */
GaimConvChatBuddyFlags
flags
;
/**< Flags (ops, voice etc.) */
};
/**
* A core representation of a conversation between two or more people.
*
* The conversation can be an IM or a chat. Each conversation is kept
* in a GaimConvWindow and has a UI representation.
*/
struct
_GaimConversation
{
GaimConversationType
type
;
/**< The type of conversation. */
GaimAccount
*
account
;
/**< The user using this conversation. */
GaimConvWindow
*
window
;
/**< The parent window. */
int
conversation_pos
;
/**< The position in the window's list. */
char
*
name
;
/**< The name of the conversation. */
char
*
title
;
/**< The window title. */
gboolean
logging
;
/**< The status of logging. */
GaimLog
*
log
;
/**< This conversation's log */
GList
*
send_history
;
/**< The send history. */
GString
*
history
;
/**< The conversation history. */
GaimUnseenState
unseen
;
/**< The unseen tab state. */
union
{
GaimConvIm
*
im
;
/**< IM-specific data. */
GaimConvChat
*
chat
;
/**< Chat-specific data. */
void
*
misc
;
/**< Misc. data. */
}
u
;
GaimConversationUiOps
*
ui_ops
;
/**< UI-specific operations. */
void
*
ui_data
;
/**< UI-specific data. */
GHashTable
*
data
;
/**< Plugin-specific data. */
GaimConnectionFlags
features
;
/**< The supported features */
};
typedef
void
(
*
GaimConvPlacementFunc
)(
GaimConversation
*
);
#ifdef __cplusplus
extern
"C"
{
#endif
/**************************************************************************/
/** @name Conversation Window API */
/**************************************************************************/
/*@{*/
/**
* Creates a new conversation window.
*
* This window is added to the list of windows, but is not shown until
* gaim_conv_window_show() is called.
*
* @return The new conversation window.
*/
GaimConvWindow
*
gaim_conv_window_new
(
void
);
/**
* Destroys the specified conversation window and all conversations in it.
*
* @param win The window to destroy.
*/
void
gaim_conv_window_destroy
(
GaimConvWindow
*
win
);
/**
* Shows the specified conversation window.
*
* @param win The window.
*/
void
gaim_conv_window_show
(
GaimConvWindow
*
win
);
/**
* Hides the specified conversation window.
*
* @param win The window.
*/
void
gaim_conv_window_hide
(
GaimConvWindow
*
win
);
/**
* Raises the specified conversation window.
*
* @param win The window.
*/
void
gaim_conv_window_raise
(
GaimConvWindow
*
win
);
/**
* Causes the window to flash for IM notification, if the UI supports this.
*
* @param win The window.
*/
void
gaim_conv_window_flash
(
GaimConvWindow
*
win
);
/**
* Sets the specified window's UI window operations structure.
*
* @param win The window.
* @param ops The UI window operations structure.
*/
void
gaim_conv_window_set_ui_ops
(
GaimConvWindow
*
win
,
GaimConvWindowUiOps
*
ops
);
/**
* Returns the specified window's UI window operations structure.
*
* @param win The window.
*
* @return The UI window operations structure.
*/
GaimConvWindowUiOps
*
gaim_conv_window_get_ui_ops
(
const
GaimConvWindow
*
win
);
/**
* Adds a conversation to this window.
*
* If the conversation already has a parent window, this will do nothing.
*
* @param win The window.
* @param conv The conversation.
*
* @return The new index of the conversation in the window.
*/
int
gaim_conv_window_add_conversation
(
GaimConvWindow
*
win
,
GaimConversation
*
conv
);
/**
* Removes the conversation at the specified index from the window.
*
* If there is no conversation at this index, this will do nothing.
*
* @param win The window.
* @param index The index of the conversation.
*
* @return The conversation removed.
*/
GaimConversation
*
gaim_conv_window_remove_conversation
(
GaimConvWindow
*
win
,
unsigned
int
index
);
/**
* Moves the conversation at the specified index in a window to a new index.
*
* @param win The window.
* @param index The index of the conversation to move.
* @param new_index The new index.
*/
void
gaim_conv_window_move_conversation
(
GaimConvWindow
*
win
,
unsigned
int
index
,
unsigned
int
new_index
);
/**
* Returns the conversation in the window at the specified index.
*
* If the index is out of range, this returns @c NULL.
*
* @param win The window.
* @param index The index containing a conversation.
*
* @return The conversation at the specified index.
*/
GaimConversation
*
gaim_conv_window_get_conversation_at
(
const
GaimConvWindow
*
win
,
unsigned
int
index
);
/**
* Returns the number of conversations in the window.
*
* @param win The window.
*
* @return The number of conversations.
*/
size_t
gaim_conv_window_get_conversation_count
(
const
GaimConvWindow
*
win
);
/**
* Switches the active conversation to the one at the specified index.
*
* If @a index is out of range, this does nothing.
*
* @param win The window.
* @param index The new index.
*/
void
gaim_conv_window_switch_conversation
(
GaimConvWindow
*
win
,
unsigned
int
index
);
/**
* Returns the active conversation in the window.
*
* @param win The window.
*
* @return The active conversation.
*/
GaimConversation
*
gaim_conv_window_get_active_conversation
(
const
GaimConvWindow
*
win
);
/**
* Determines if a conversation window has focus
*
* @param win The window.
*
* @return @c TRUE if the conversation window has focus, @c FALSE if
* it does not or the UI does not have a concept of window focus
*/
gboolean
gaim_conv_window_has_focus
(
GaimConvWindow
*
win
);
/**
* Returns the list of conversations in the specified window.
*
* @param win The window.
*
* @return The list of conversations.
*/
GList
*
gaim_conv_window_get_conversations
(
const
GaimConvWindow
*
win
);
/**
* Returns a list of all windows.
*
* @return A list of windows.
*/
GList
*
gaim_get_windows
(
void
);
/**
* Returns the first window containing a conversation of the specified type.
*
* @param type The conversation type.
*
* @return The window if found, or @c NULL if not found.
*/
GaimConvWindow
*
gaim_get_first_window_with_type
(
GaimConversationType
type
);
/**
* Returns the last window containing a conversation of the specified type.
*
* @param type The conversation type.
*
* @return The window if found, or @c NULL if not found.
*/
GaimConvWindow
*
gaim_get_last_window_with_type
(
GaimConversationType
type
);
/*@}*/
/**************************************************************************/
/** @name Conversation API */
/**************************************************************************/
/*@{*/
/**
* Creates a new conversation of the specified type.
*
* @param type The type of conversation.
* @param account The account opening the conversation window on the gaim
* user's end.
* @param name The name of the conversation.
*
* @return The new conversation.
*/
GaimConversation
*
gaim_conversation_new
(
GaimConversationType
type
,
GaimAccount
*
account
,
const
char
*
name
);
/**
* Destroys the specified conversation and removes it from the parent
* window.
*
* If this conversation is the only one contained in the parent window,
* that window is also destroyed.
*
* @param conv The conversation to destroy.
*/
void
gaim_conversation_destroy
(
GaimConversation
*
conv
);
/**
* Returns the specified conversation's type.
*
* @param conv The conversation.
*
* @return The conversation's type.
*/
GaimConversationType
gaim_conversation_get_type
(
const
GaimConversation
*
conv
);
/**
* Sets the specified conversation's UI operations structure.
*
* @param conv The conversation.
* @param ops The UI conversation operations structure.
*/
void
gaim_conversation_set_ui_ops
(
GaimConversation
*
conv
,
GaimConversationUiOps
*
ops
);
/**
* Returns the specified conversation's UI operations structure.
*
* @param conv The conversation.
*
* @return The operations structure.
*/
GaimConversationUiOps
*
gaim_conversation_get_ui_ops
(
const
GaimConversation
*
conv
);
/**
* Sets the specified conversation's gaim_account.
*
* This gaim_account represents the user using gaim, not the person the user
* is having a conversation/chat/flame with.
*
* @param conv The conversation.
* @param account The gaim_account.
*/
void
gaim_conversation_set_account
(
GaimConversation
*
conv
,
GaimAccount
*
account
);
/**
* Returns the specified conversation's gaim_account.
*
* This gaim_account represents the user using gaim, not the person the user
* is having a conversation/chat/flame with.
*
* @param conv The conversation.
*
* @return The conversation's gaim_account.
*/
GaimAccount
*
gaim_conversation_get_account
(
const
GaimConversation
*
conv
);
/**
* Returns the specified conversation's gaim_connection.
*
* This is the same as gaim_conversation_get_user(conv)->gc.
*
* @param conv The conversation.
*
* @return The conversation's gaim_connection.
*/
GaimConnection
*
gaim_conversation_get_gc
(
const
GaimConversation
*
conv
);
/**
* Sets the specified conversation's title.
*
* @param conv The conversation.
* @param title The title.
*/
void
gaim_conversation_set_title
(
GaimConversation
*
conv
,
const
char
*
title
);
/**
* Returns the specified conversation's title.
*
* @param conv The conversation.
*
* @return The title.
*/
const
char
*
gaim_conversation_get_title
(
const
GaimConversation
*
conv
);
/**
* Automatically sets the specified conversation's title.
*
* This function takes OPT_IM_ALIAS_TAB into account, as well as the
* user's alias.
*
* @param conv The conversation.
*/
void
gaim_conversation_autoset_title
(
GaimConversation
*
conv
);
/**
* Returns the specified conversation's index in the parent window.
*
* @param conv The conversation.
*
* @return The current index in the parent window.
*/
int
gaim_conversation_get_index
(
const
GaimConversation
*
conv
);
/**
* Sets the conversation's unseen state.
*
* @param conv The conversation.
* @param state The new unseen state.
*/
void
gaim_conversation_set_unseen
(
GaimConversation
*
conv
,
GaimUnseenState
state
);
/**
* Returns the conversation's unseen state.
*
* @param conv The conversation.
*
* @return The conversation's unseen state.
*/
GaimUnseenState
gaim_conversation_get_unseen
(
const
GaimConversation
*
conv
);
/**
* Sets the specified conversation's name.
*
* @param conv The conversation.
* @param name The conversation's name.
*/
void
gaim_conversation_set_name
(
GaimConversation
*
conv
,
const
char
*
name
);
/**
* Returns the specified conversation's name.
*
* @param conv The conversation.
*
* @return The conversation's name.
*/
const
char
*
gaim_conversation_get_name
(
const
GaimConversation
*
conv
);
/**
* Enables or disables logging for this conversation.
*
* @param conv The conversation.
* @param log @c TRUE if logging should be enabled, or @c FALSE otherwise.
*/
void
gaim_conversation_set_logging
(
GaimConversation
*
conv
,
gboolean
log
);
/**
* Returns whether or not logging is enabled for this conversation.
*
* @param conv The conversation.
*
* @return @c TRUE if logging is enabled, or @c FALSE otherwise.
*/
gboolean
gaim_conversation_is_logging
(
const
GaimConversation
*
conv
);
/**
* Returns the specified conversation's send history.
*
* @param conv The conversation.
*
* @return The conversation's send history.
*/
GList
*
gaim_conversation_get_send_history
(
const
GaimConversation
*
conv
);
/**
* Sets the specified conversation's history.
*
* @param conv The conversation.
* @param history The history.
*/
void
gaim_conversation_set_history
(
GaimConversation
*
conv
,
GString
*
history
);
/**
* Returns the specified conversation's history.
*
* @param conv The conversation.
*
* @return The conversation's history.
*/
GString
*
gaim_conversation_get_history
(
const
GaimConversation
*
conv
);
/**
* Returns the specified conversation's parent window.
*
* @param conv The conversation.
*
* @return The conversation's parent window.
*/
GaimConvWindow
*
gaim_conversation_get_window
(
const
GaimConversation
*
conv
);
/**
* Returns the specified conversation's IM-specific data.
*
* If the conversation type is not GAIM_CONV_IM, this will return @c NULL.
*
* @param conv The conversation.
*
* @return The IM-specific data.
*/
GaimConvIm
*
gaim_conversation_get_im_data
(
const
GaimConversation
*
conv
);
#define GAIM_CONV_IM(c) (gaim_conversation_get_im_data(c))
/**
* Returns the specified conversation's chat-specific data.
*
* If the conversation type is not GAIM_CONV_CHAT, this will return @c NULL.
*
* @param conv The conversation.
*
* @return The chat-specific data.
*/
GaimConvChat
*
gaim_conversation_get_chat_data
(
const
GaimConversation
*
conv
);
#define GAIM_CONV_CHAT(c) (gaim_conversation_get_chat_data(c))
/**
* Sets extra data for a conversation.
*
* @param conv The conversation.
* @param key The unique key.
* @param data The data to assign.
*/
void
gaim_conversation_set_data
(
GaimConversation
*
conv
,
const
char
*
key
,
gpointer
data
);
/**
* Returns extra data in a conversation.
*
* @param conv The conversation.
* @param key The unqiue key.
*
* @return The data associated with the key.
*/
gpointer
gaim_conversation_get_data
(
GaimConversation
*
conv
,
const
char
*
key
);
/**
* Returns a list of all conversations.
*
* This list includes both IMs and chats.
*
* @return A GList of all conversations.
*/
GList
*
gaim_get_conversations
(
void
);
/**
* Returns a list of all IMs.
*
* @return A GList of all IMs.
*/
GList
*
gaim_get_ims
(
void
);
/**
* Returns a list of all chats.
*
* @return A GList of all chats.
*/
GList
*
gaim_get_chats
(
void
);
/**
* Finds the conversation with the specified name.
*
* @param name The name of the conversation.
*
* @return The conversation if found, or @c NULL otherwise.
*/
GaimConversation
*
gaim_find_conversation
(
const
char
*
name
);
/**
* Finds a conversation with the specified name and user.
*
* @param name The name of the conversation.
* @param account The gaim_account associated with the conversation.
*
* @return The conversation if found, or @c NULL otherwise.
*/
GaimConversation
*
gaim_find_conversation_with_account
(
const
char
*
name
,
const
GaimAccount
*
account
);
/**
* Writes to a conversation window.
*
* This function should not be used to write IM or chat messages. Use
* gaim_conv_im_write() and gaim_conv_chat_write() instead. Those functions will
* most likely call this anyway, but they may do their own formatting,
* sound playback, etc.
*
* This can be used to write generic messages, such as "so and so closed
* the conversation window."
*
* @param conv The conversation.
* @param who The user who sent the message.
* @param message The message.
* @param flags The message flags.
* @param mtime The time the message was sent.
*
* @see gaim_conv_im_write()
* @see gaim_conv_chat_write()
*/
void
gaim_conversation_write
(
GaimConversation
*
conv
,
const
char
*
who
,
const
char
*
message
,
GaimMessageFlags
flags
,
time_t
mtime
);
/**
Set the features as supported for the given conversation.
@param conv The conversation
@param features Bitset defining supported features
*/
void
gaim_conversation_set_features
(
GaimConversation
*
conv
,
GaimConnectionFlags
features
);
/**
Get the features supported by the given conversation.
@param conv The conversation
*/
GaimConnectionFlags
gaim_conversation_get_features
(
GaimConversation
*
conv
);
/**
* Updates the progress bar on a conversation window
* (if one exists in the UI).
*
* This is used for loading images typically.
*
* @param conv The conversation.
* @param percent The percentage.
*/
void
gaim_conversation_update_progress
(
GaimConversation
*
conv
,
float
percent
);
/**
* Determines if a conversation has focus
*
* @param conv The conversation.
*
* @return @c TRUE if the conversation has focus, @c FALSE if
* it does not or the UI does not have a concept of conversation focus
*/
gboolean
gaim_conversation_has_focus
(
GaimConversation
*
conv
);
/**
* Updates the visual status and UI of a conversation.
*
* @param conv The conversation.
* @param type The update type.
*/
void
gaim_conversation_update
(
GaimConversation
*
conv
,
GaimConvUpdateType
type
);
/**
* Calls a function on each conversation.
*
* @param func The function.
*/
void
gaim_conversation_foreach
(
void
(
*
func
)(
GaimConversation
*
conv
));
/*@}*/
/**************************************************************************/
/** @name IM Conversation API */
/**************************************************************************/
/*@{*/
/**
* Gets an IM's parent conversation.
*
* @param im The IM.
*
* @return The parent conversation.
*/
GaimConversation
*
gaim_conv_im_get_conversation
(
const
GaimConvIm
*
im
);
/**
* Sets the IM's buddy icon.
*
* This should only be called from within Gaim. You probably want to
* call gaim_buddy_icon_set_data().
*
* @param im The IM.
* @param icon The buddy icon.
*
* @see gaim_buddy_icon_set_data()
*/
void
gaim_conv_im_set_icon
(
GaimConvIm
*
im
,
GaimBuddyIcon
*
icon
);
/**
* Returns the IM's buddy icon.
*
* @param im The IM.
*
* @return The buddy icon.
*/
GaimBuddyIcon
*
gaim_conv_im_get_icon
(
const
GaimConvIm
*
im
);
/**
* Sets the IM's typing state.
*
* @param im The IM.
* @param state The typing state.
*/
void
gaim_conv_im_set_typing_state
(
GaimConvIm
*
im
,
GaimTypingState
state
);
/**
* Returns the IM's typing state.
*
* @param im The IM.
*
* @return The IM's typing state.
*/
GaimTypingState
gaim_conv_im_get_typing_state
(
const
GaimConvIm
*
im
);
/**
* Starts the IM's typing timeout.
*
* @param im The IM.
* @param timeout The timeout.
*/
void
gaim_conv_im_start_typing_timeout
(
GaimConvIm
*
im
,
int
timeout
);
/**
* Stops the IM's typing timeout.
*
* @param im The IM.
*/
void
gaim_conv_im_stop_typing_timeout
(
GaimConvIm
*
im
);
/**
* Returns the IM's typing timeout.
*
* @param im The IM.
*
* @return The timeout.
*/
guint
gaim_conv_im_get_typing_timeout
(
const
GaimConvIm
*
im
);
/**
* Sets the IM's time until it should send another typing notification.
*
* @param im The IM.
* @param val The time.
*/
void
gaim_conv_im_set_type_again
(
GaimConvIm
*
im
,
time_t
val
);
/**
* Returns the IM's time until it should send another typing notification.
*
* @param im The IM.
*
* @return The time.
*/
time_t
gaim_conv_im_get_type_again
(
const
GaimConvIm
*
im
);
/**
* Starts the IM's type again timeout.
*
* @param im The IM.
*/
void
gaim_conv_im_start_type_again_timeout
(
GaimConvIm
*
im
);
/**
* Stops the IM's type again timeout.
*
* @param im The IM.
*/
void
gaim_conv_im_stop_type_again_timeout
(
GaimConvIm
*
im
);
/**
* Returns the IM's type again timeout interval.
*
* @param im The IM.
*
* @return The type again timeout interval.
*/
guint
gaim_conv_im_get_type_again_timeout
(
const
GaimConvIm
*
im
);
/**
* Updates the visual typing notification for an IM conversation.
*
* @param im The IM.
*/
void
gaim_conv_im_update_typing
(
GaimConvIm
*
im
);
/**
* Writes to an IM.
*
* @param im The IM.
* @param who The user who sent the message.
* @param message The message to write.
* @param flags The message flags.
* @param mtime The time the message was sent.
*/
void
gaim_conv_im_write
(
GaimConvIm
*
im
,
const
char
*
who
,
const
char
*
message
,
GaimMessageFlags
flags
,
time_t
mtime
);
/**
* Presents an IM-error to the user
*
* This is a helper function to find a conversation, write an error to it, and
* raise the window. If a conversation with this user doesn't already exist,
* the function will return FALSE and the calling function can attempt to present
* the error another way (gaim_notify_error, most likely)
*
* @param who The user this error is about
* @param account The account this error is on
* @param what The error
* @return TRUE if the error was presented, else FALSE
*/
gboolean
gaim_conv_present_error
(
const
char
*
who
,
GaimAccount
*
account
,
const
char
*
what
);
/**
* Sends a message to this IM conversation.
*
* @param im The IM.
* @param message The message to send.
*/
void
gaim_conv_im_send
(
GaimConvIm
*
im
,
const
char
*
message
);
/*@}*/
/**************************************************************************/
/** @name Chat Conversation API */
/**************************************************************************/
/*@{*/
/**
* Gets a chat's parent conversation.
*
* @param chat The chat.
*
* @return The parent conversation.
*/
GaimConversation
*
gaim_conv_chat_get_conversation
(
const
GaimConvChat
*
chat
);
/**
* Sets the list of users in the chat room.
*
* @note Calling this function will not update the display of the users.
* Please use gaim_conv_chat_add_user(), gaim_conv_chat_add_users(),
* gaim_conv_chat_remove_user(), and gaim_conv_chat_remove_users() instead.
*
* @param chat The chat.
* @param users The list of users.
*
* @return The list passed.
*/
GList
*
gaim_conv_chat_set_users
(
GaimConvChat
*
chat
,
GList
*
users
);
/**
* Returns a list of users in the chat room.
*
* @param chat The chat.
*
* @return The list of users.
*/
GList
*
gaim_conv_chat_get_users
(
const
GaimConvChat
*
chat
);
/**
* Ignores a user in a chat room.
*
* @param chat The chat.
* @param name The name of the user.
*/
void
gaim_conv_chat_ignore
(
GaimConvChat
*
chat
,
const
char
*
name
);
/**
* Unignores a user in a chat room.
*
* @param chat The chat.
* @param name The name of the user.
*/
void
gaim_conv_chat_unignore
(
GaimConvChat
*
chat
,
const
char
*
name
);
/**
* Sets the list of ignored users in the chat room.
*
* @param chat The chat.
* @param ignored The list of ignored users.
*
* @return The list passed.
*/
GList
*
gaim_conv_chat_set_ignored
(
GaimConvChat
*
chat
,
GList
*
ignored
);
/**
* Returns the list of ignored users in the chat room.
*
* @param chat The chat.
*
* @return The list of ignored users.
*/
GList
*
gaim_conv_chat_get_ignored
(
const
GaimConvChat
*
chat
);
/**
* Returns the actual name of the specified ignored user, if it exists in
* the ignore list.
*
* If the user found contains a prefix, such as '+' or '\@', this is also
* returned. The username passed to the function does not have to have this
* formatting.
*
* @param chat The chat.
* @param user The user to check in the ignore list.
*
* @return The ignored user if found, complete with prefixes, or @c NULL
* if not found.
*/
const
char
*
gaim_conv_chat_get_ignored_user
(
const
GaimConvChat
*
chat
,
const
char
*
user
);
/**
* Returns @c TRUE if the specified user is ignored.
*
* @param chat The chat.
* @param user The user.
*
* @return @c TRUE if the user is in the ignore list; @c FALSE otherwise.
*/
gboolean
gaim_conv_chat_is_user_ignored
(
const
GaimConvChat
*
chat
,
const
char
*
user
);
/**
* Sets the chat room's topic.
*
* @param chat The chat.
* @param who The user that set the topic.
* @param topic The topic.
*/
void
gaim_conv_chat_set_topic
(
GaimConvChat
*
chat
,
const
char
*
who
,
const
char
*
topic
);
/**
* Returns the chat room's topic.
*
* @param chat The chat.
*
* @return The chat's topic.
*/
const
char
*
gaim_conv_chat_get_topic
(
const
GaimConvChat
*
chat
);
/**
* Sets the chat room's ID.
*
* @param chat The chat.
* @param id The ID.
*/
void
gaim_conv_chat_set_id
(
GaimConvChat
*
chat
,
int
id
);
/**
* Returns the chat room's ID.
*
* @param chat The chat.
*
* @return The ID.
*/
int
gaim_conv_chat_get_id
(
const
GaimConvChat
*
chat
);
/**
* Writes to a chat.
*
* @param chat The chat.
* @param who The user who sent the message.
* @param message The message to write.
* @param flags The flags.
* @param mtime The time the message was sent.
*/
void
gaim_conv_chat_write
(
GaimConvChat
*
chat
,
const
char
*
who
,
const
char
*
message
,
GaimMessageFlags
flags
,
time_t
mtime
);
/**
* Sends a message to this chat conversation.
*
* @param chat The chat.
* @param message The message to send.
*/
void
gaim_conv_chat_send
(
GaimConvChat
*
chat
,
const
char
*
message
);
/**
* Adds a user to a chat.
*
* @param chat The chat.
* @param user The user to add.
* @param extra_msg An extra message to display with the join message.
* @param flags The users flags
* @param new_arrival Decides whether or not to show a join notice.
*/
void
gaim_conv_chat_add_user
(
GaimConvChat
*
chat
,
const
char
*
user
,
const
char
*
extra_msg
,
GaimConvChatBuddyFlags
flags
,
gboolean
new_arrival
);
/**
* Adds a list of users to a chat.
*
* The data is copied from @a users, so it is up to the developer to
* free this list after calling this function.
*
* @param chat The chat.
* @param users The list of users to add.
* @param flags The list of flags for each user.
*/
void
gaim_conv_chat_add_users
(
GaimConvChat
*
chat
,
GList
*
users
,
GList
*
flags
);
/**
* Renames a user in a chat.
*
* @param chat The chat.
* @param old_user The old username.
* @param new_user The new username.
*/
void
gaim_conv_chat_rename_user
(
GaimConvChat
*
chat
,
const
char
*
old_user
,
const
char
*
new_user
);
/**
* Removes a user from a chat, optionally with a reason.
*
* It is up to the developer to free this list after calling this function.
*
* @param chat The chat.
* @param user The user that is being removed.
* @param reason The optional reason given for the removal. Can be @c NULL.
*/
void
gaim_conv_chat_remove_user
(
GaimConvChat
*
chat
,
const
char
*
user
,
const
char
*
reason
);
/**
* Removes a list of users from a chat, optionally with a single reason.
*
* @param chat The chat.
* @param users The users that are being removed.
* @param reason The optional reason given for the removal. Can be @c NULL.
*/
void
gaim_conv_chat_remove_users
(
GaimConvChat
*
chat
,
GList
*
users
,
const
char
*
reason
);
/**
* Finds a user in a chat
*
* @param chat The chat.
* @param user The user to look for.
*
* @return TRUE if the user is in the chat, FALSE if not
*/
gboolean
gaim_conv_chat_find_user
(
GaimConvChat
*
chat
,
const
char
*
user
);
/**
* Set a users flags in a chat
*
* @param chat The chat.
* @param user The user to update.
* @param flags The new flags.
*/
void
gaim_conv_chat_user_set_flags
(
GaimConvChat
*
chat
,
const
char
*
user
,
GaimConvChatBuddyFlags
flags
);
/**
* Get the flags for a user in a chat
*
* @param chat The chat.
* @param user The user to find the flags for
*
* @return The flags for the user
*/
GaimConvChatBuddyFlags
gaim_conv_chat_user_get_flags
(
GaimConvChat
*
chat
,
const
char
*
user
);
/**
* Clears all users from a chat.
*
* @param chat The chat.
*/
void
gaim_conv_chat_clear_users
(
GaimConvChat
*
chat
);
/**
* Sets your nickname (used for hilighting) for a chat.
*
* @param chat The chat.
* @param nick The nick.
*/
void
gaim_conv_chat_set_nick
(
GaimConvChat
*
chat
,
const
char
*
nick
);
/**
* Gets your nickname (used for hilighting) for a chat.
*
* @param chat The chat.
* @return The nick.
*/
const
char
*
gaim_conv_chat_get_nick
(
GaimConvChat
*
chat
);
/**
* Finds a chat with the specified chat ID.
*
* @param gc The gaim_connection.
* @param id The chat ID.
*
* @return The chat conversation.
*/
GaimConversation
*
gaim_find_chat
(
const
GaimConnection
*
gc
,
int
id
);
/**
* Lets the core know we left a chat, without destroying it.
* Called from serv_got_chat_left().
*
* @param chat The chat.
*/
void
gaim_conv_chat_left
(
GaimConvChat
*
chat
);
/**
* Returns true if we're no longer in this chat,
* and just left the window open.
*
* @param chat The chat.
*
* @return @c TRUE if we left the chat already, @c FALSE if
* we're still there.
*/
gboolean
gaim_conv_chat_has_left
(
GaimConvChat
*
chat
);
/**
* Creates a new chat buddy
*
* @param name The name.
* @param flags The flags.
*
* @return The new chat buddy
*/
GaimConvChatBuddy
*
gaim_conv_chat_cb_new
(
const
char
*
name
,
GaimConvChatBuddyFlags
flags
);
/**
* Find a chat buddy in a chat
*
* @param chat The chat.
* @param name The name of the chat buddy to find.
*/
GaimConvChatBuddy
*
gaim_conv_chat_cb_find
(
GaimConvChat
*
chat
,
const
char
*
name
);
/**
* Get the name of a chat buddy
*
* @param cb The chat buddy.
*
* @return The name of the chat buddy.
*/
const
char
*
gaim_conv_chat_cb_get_name
(
GaimConvChatBuddy
*
cb
);
/**
* Destroys a chat buddy
*
* @param cb The chat buddy to destroy
*/
void
gaim_conv_chat_cb_destroy
(
GaimConvChatBuddy
*
cb
);
/*@}*/
/**************************************************************************/
/** @name Conversation Placement API */
/**************************************************************************/
/*@{*/
/**
* Returns a GList containing the IDs and Names of the registered placement
* functions.
*
* @return The list of IDs and names.
*/
GList
*
gaim_conv_placement_get_options
(
void
);
/**
* Adds a conversation placement function to the list of possible functions.
*
* @param id The unique ID of the placement function.
* @param name The name of the function.
* @param fnc A pointer to the function.
*/
void
gaim_conv_placement_add_fnc
(
const
char
*
id
,
const
char
*
name
,
GaimConvPlacementFunc
fnc
);
/**
* Removes a conversation placement function from the list of possible
* functions.
*
* @param id The id of the function.
*/
void
gaim_conv_placement_remove_fnc
(
const
char
*
id
);
/**
* Returns the name of the conversation placement function at the
* specified id.
*
* @param id The id.
*
* @return The name of the function, or @c NULL if this id is invalid.
*/
const
char
*
gaim_conv_placement_get_name
(
const
char
*
id
);
/**
* Returns a pointer to the conversation placement function at the
* specified id.
*
* @param id The id.
*
* @return A pointer to the function.
*/
GaimConvPlacementFunc
gaim_conv_placement_get_fnc
(
const
char
*
id
);
/**
* Sets the current conversation placement function.
*
* @param func The new conversation placement function.
*/
void
gaim_conv_placement_set_current_func
(
GaimConvPlacementFunc
func
);
/**
* Returns the current conversation placement function.
*
* @return The current conversation placement function.
*/
GaimConvPlacementFunc
gaim_conv_placement_get_current_func
(
void
);
/**
* Returns the id of the specified conversation placement function.
*
* @param fnc A pointer to the registered function.
*
* @return The id of the conversation, or NULL if the function is not
* registered.
*/
const
char
*
gaim_conv_placement_get_fnc_id
(
GaimConvPlacementFunc
fnc
);
/*@}*/
/**************************************************************************/
/** @name UI Registration Functions */
/**************************************************************************/
/*@{*/
/**
* Sets the UI operations structure to be used in all gaim conversation
* windows.
*
* @param ops The UI operations structure.
*/
void
gaim_conversations_set_win_ui_ops
(
GaimConvWindowUiOps
*
ops
);
/**
* Returns the gaim window UI operations structure to be used in
* new windows.
*
* @return A filled-out GaimConvWindowUiOps structure.
*/
GaimConvWindowUiOps
*
gaim_conversations_get_win_ui_ops
(
void
);
/*@}*/
/**************************************************************************/
/** @name Conversations Subsystem */
/**************************************************************************/
/*@{*/
/**
* Returns the conversation subsystem handle.
*
* @return The conversation subsystem handle.
*/
void
*
gaim_conversations_get_handle
(
void
);
/**
* Initializes the conversation subsystem.
*/
void
gaim_conversations_init
(
void
);
/**
* Uninitializes the conversation subsystem.
*/
void
gaim_conversations_uninit
(
void
);
/*@}*/
#ifdef __cplusplus
}
#endif
#endif
/* _GAIM_CONVERSATION_H_ */