1 /** 2 * @file conversation.h Conversation API 3 * @ingroup core 4 * @see @ref conversation-signals 5 */ 6 7 /* purple 8 * 9 * Purple is the legal property of its developers, whose names are too numerous 10 * to list here. Please refer to the COPYRIGHT file distributed with this 11 * source distribution. 12 * 13 * This program is free software; you can redistribute it and/or modify 14 * it under the terms of the GNU General Public License as published by 15 * the Free Software Foundation; either version 2 of the License, or 16 * (at your option) any later version. 17 * 18 * This program is distributed in the hope that it will be useful, 19 * but WITHOUT ANY WARRANTY; without even the implied warranty of 20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 21 * GNU General Public License for more details. 22 * 23 * You should have received a copy of the GNU General Public License 24 * along with this program; if not, write to the Free Software 25 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA 26 */ 27 #ifndef _PURPLE_CONVERSATION_H_ 28 #define _PURPLE_CONVERSATION_H_ 29 30 /**************************************************************************/ 31 /** Data Structures */ 32 /**************************************************************************/ 33 34 35 /** @copydoc _PurpleConversationUiOps */ 36 typedef struct _PurpleConversationUiOps PurpleConversationUiOps; 37 /** @copydoc _PurpleConversation */ 38 typedef struct _PurpleConversation PurpleConversation; 39 /** @copydoc _PurpleConvIm */ 40 typedef struct _PurpleConvIm PurpleConvIm; 41 /** @copydoc _PurpleConvChat */ 42 typedef struct _PurpleConvChat PurpleConvChat; 43 /** @copydoc _PurpleConvChatBuddy */ 44 typedef struct _PurpleConvChatBuddy PurpleConvChatBuddy; 45 /** @copydoc _PurpleConvMessage */ 46 typedef struct _PurpleConvMessage PurpleConvMessage; 47 48 /** 49 * A type of conversation. 50 */ 51 typedef enum 52 { 53 PURPLE_CONV_TYPE_UNKNOWN = 0, /**< Unknown conversation type. */ 54 PURPLE_CONV_TYPE_IM, /**< Instant Message. */ 55 PURPLE_CONV_TYPE_CHAT, /**< Chat room. */ 56 PURPLE_CONV_TYPE_MISC, /**< A misc. conversation. */ 57 PURPLE_CONV_TYPE_ANY /**< Any type of conversation. */ 58 59 } PurpleConversationType; 60 61 /** 62 * Conversation update type. 63 */ 64 typedef enum 65 { 66 PURPLE_CONV_UPDATE_ADD = 0, /**< The buddy associated with the conversation 67 was added. */ 68 PURPLE_CONV_UPDATE_REMOVE, /**< The buddy associated with the conversation 69 was removed. */ 70 PURPLE_CONV_UPDATE_ACCOUNT, /**< The purple_account was changed. */ 71 PURPLE_CONV_UPDATE_TYPING, /**< The typing state was updated. */ 72 PURPLE_CONV_UPDATE_UNSEEN, /**< The unseen state was updated. */ 73 PURPLE_CONV_UPDATE_LOGGING, /**< Logging for this conversation was 74 enabled or disabled. */ 75 PURPLE_CONV_UPDATE_TOPIC, /**< The topic for a chat was updated. */ 76 /* 77 * XXX These need to go when we implement a more generic core/UI event 78 * system. 79 */ 80 PURPLE_CONV_ACCOUNT_ONLINE, /**< One of the user's accounts went online. */ 81 PURPLE_CONV_ACCOUNT_OFFLINE, /**< One of the user's accounts went offline. */ 82 PURPLE_CONV_UPDATE_AWAY, /**< The other user went away. */ 83 PURPLE_CONV_UPDATE_ICON, /**< The other user's buddy icon changed. */ 84 PURPLE_CONV_UPDATE_TITLE, 85 PURPLE_CONV_UPDATE_CHATLEFT, 86 87 PURPLE_CONV_UPDATE_FEATURES /**< The features for a chat have changed */ 88 89 } PurpleConvUpdateType; 90 91 /** 92 * The typing state of a user. 93 */ 94 typedef enum 95 { 96 PURPLE_NOT_TYPING = 0, /**< Not typing. */ 97 PURPLE_TYPING, /**< Currently typing. */ 98 PURPLE_TYPED /**< Stopped typing momentarily. */ 99 100 } PurpleTypingState; 101 102 /** 103 * Flags applicable to a message. Most will have send, recv or system. 104 */ 105 typedef enum 106 { 107 PURPLE_MESSAGE_SEND = 0x0001, /**< Outgoing message. */ 108 PURPLE_MESSAGE_RECV = 0x0002, /**< Incoming message. */ 109 PURPLE_MESSAGE_SYSTEM = 0x0004, /**< System message. */ 110 PURPLE_MESSAGE_AUTO_RESP = 0x0008, /**< Auto response. */ 111 PURPLE_MESSAGE_ACTIVE_ONLY = 0x0010, /**< Hint to the UI that this 112 message should not be 113 shown in conversations 114 which are only open for 115 internal UI purposes 116 (e.g. for contact-aware 117 conversations). */ 118 PURPLE_MESSAGE_NICK = 0x0020, /**< Contains your nick. */ 119 PURPLE_MESSAGE_NO_LOG = 0x0040, /**< Do not log. */ 120 PURPLE_MESSAGE_WHISPER = 0x0080, /**< Whispered message. */ 121 PURPLE_MESSAGE_ERROR = 0x0200, /**< Error message. */ 122 PURPLE_MESSAGE_DELAYED = 0x0400, /**< Delayed message. */ 123 PURPLE_MESSAGE_RAW = 0x0800, /**< "Raw" message - don't 124 apply formatting */ 125 PURPLE_MESSAGE_IMAGES = 0x1000, /**< Message contains images */ 126 PURPLE_MESSAGE_NOTIFY = 0x2000, /**< Message is a notification */ 127 PURPLE_MESSAGE_NO_LINKIFY = 0x4000, /**< Message should not be auto- 128 linkified @since 2.1.0 */ 129 PURPLE_MESSAGE_INVISIBLE = 0x8000, /**< Message should not be displayed */ 130 PURPLE_MESSAGE_REMOTE_SEND = 0x10000 /**< Message sent from another location, 131 not an echo of a local one 132 @since 2.12.0 */ 133 } PurpleMessageFlags; 134 135 /** 136 * Flags applicable to users in Chats. 137 */ 138 typedef enum 139 { 140 PURPLE_CBFLAGS_NONE = 0x0000, /**< No flags */ 141 PURPLE_CBFLAGS_VOICE = 0x0001, /**< Voiced user or "Participant" */ 142 PURPLE_CBFLAGS_HALFOP = 0x0002, /**< Half-op */ 143 PURPLE_CBFLAGS_OP = 0x0004, /**< Channel Op or Moderator */ 144 PURPLE_CBFLAGS_FOUNDER = 0x0008, /**< Channel Founder */ 145 PURPLE_CBFLAGS_TYPING = 0x0010, /**< Currently typing */ 146 PURPLE_CBFLAGS_AWAY = 0x0020 /**< Currently away. @since 2.8.0 */ 147 148 } PurpleConvChatBuddyFlags; 149 150 #include "account.h" 151 #include "buddyicon.h" 152 #include "log.h" 153 #include "server.h" 154 155 /** 156 * Conversation operations and events. 157 * 158 * Any UI representing a conversation must assign a filled-out 159 * PurpleConversationUiOps structure to the PurpleConversation. 160 */ 161 struct _PurpleConversationUiOps 162 { 163 /** Called when @a conv is created (but before the @ref 164 * conversation-created signal is emitted). 165 */ 166 void (*create_conversation)(PurpleConversation *conv); 167 168 /** Called just before @a conv is freed. */ 169 void (*destroy_conversation)(PurpleConversation *conv); 170 /** Write a message to a chat. If this field is @c NULL, libpurple will 171 * fall back to using #write_conv. 172 * @see purple_conv_chat_write() 173 */ 174 void (*write_chat)(PurpleConversation *conv, const char *who, 175 const char *message, PurpleMessageFlags flags, 176 time_t mtime); 177 /** Write a message to an IM conversation. If this field is @c NULL, 178 * libpurple will fall back to using #write_conv. 179 * @see purple_conv_im_write() 180 */ 181 void (*write_im)(PurpleConversation *conv, const char *who, 182 const char *message, PurpleMessageFlags flags, 183 time_t mtime); 184 /** Write a message to a conversation. This is used rather than the 185 * chat- or im-specific ops for errors, system messages (such as "x is 186 * now know as y"), and as the fallback if #write_im and #write_chat 187 * are not implemented. It should be implemented, or the UI will miss 188 * conversation error messages and your users will hate you. 189 * 190 * @see purple_conversation_write() 191 */ 192 void (*write_conv)(PurpleConversation *conv, 193 const char *name, 194 const char *alias, 195 const char *message, 196 PurpleMessageFlags flags, 197 time_t mtime); 198 199 /** Add @a cbuddies to a chat. 200 * @param cbuddies A @c GList of #PurpleConvChatBuddy structs. 201 * @param new_arrivals Whether join notices should be shown. 202 * (Join notices are actually written to the 203 * conversation by #purple_conv_chat_add_users().) 204 */ 205 void (*chat_add_users)(PurpleConversation *conv, 206 GList *cbuddies, 207 gboolean new_arrivals); 208 /** Rename the user in this chat named @a old_name to @a new_name. (The 209 * rename message is written to the conversation by libpurple.) 210 * @param new_alias @a new_name's new alias, if they have one. 211 * @see purple_conv_chat_add_users() 212 */ 213 void (*chat_rename_user)(PurpleConversation *conv, const char *old_name, 214 const char *new_name, const char *new_alias); 215 /** Remove @a users from a chat. 216 * @param users A @c GList of <tt>const char *</tt>s. 217 * @see purple_conv_chat_rename_user() 218 */ 219 void (*chat_remove_users)(PurpleConversation *conv, GList *users); 220 /** Called when a user's flags are changed. 221 * @see purple_conv_chat_user_set_flags() 222 */ 223 void (*chat_update_user)(PurpleConversation *conv, const char *user); 224 225 /** Present this conversation to the user; for example, by displaying 226 * the IM dialog. 227 */ 228 void (*present)(PurpleConversation *conv); 229 230 /** If this UI has a concept of focus (as in a windowing system) and 231 * this conversation has the focus, return @c TRUE; otherwise, return 232 * @c FALSE. 233 */ 234 gboolean (*has_focus)(PurpleConversation *conv); 235 236 /* Custom Smileys */ 237 gboolean (*custom_smiley_add)(PurpleConversation *conv, const char *smile, gboolean remote); 238 void (*custom_smiley_write)(PurpleConversation *conv, const char *smile, 239 const guchar *data, gsize size); 240 void (*custom_smiley_close)(PurpleConversation *conv, const char *smile); 241 242 /** Prompt the user for confirmation to send @a message. This function 243 * should arrange for the message to be sent if the user accepts. If 244 * this field is @c NULL, libpurple will fall back to using 245 * #purple_request_action(). 246 */ 247 void (*send_confirm)(PurpleConversation *conv, const char *message); 248 249 void (*_purple_reserved1)(void); 250 void (*_purple_reserved2)(void); 251 void (*_purple_reserved3)(void); 252 void (*_purple_reserved4)(void); 253 }; 254 255 /** 256 * Data specific to Instant Messages. 257 */ 258 struct _PurpleConvIm 259 { 260 PurpleConversation *conv; /**< The parent conversation. */ 261 262 PurpleTypingState typing_state; /**< The current typing state. */ 263 guint typing_timeout; /**< The typing timer handle. */ 264 time_t type_again; /**< The type again time. */ 265 guint send_typed_timeout; /**< The type again timer handle. */ 266 267 PurpleBuddyIcon *icon; /**< The buddy icon. */ 268 }; 269 270 /** 271 * Data specific to Chats. 272 */ 273 struct _PurpleConvChat 274 { 275 PurpleConversation *conv; /**< The parent conversation. */ 276 277 GList *in_room; /**< The users in the room. 278 * @deprecated Will be removed in 3.0.0 279 */ 280 GList *ignored; /**< Ignored users. */ 281 char *who; /**< The person who set the topic. */ 282 char *topic; /**< The topic. */ 283 int id; /**< The chat ID. */ 284 char *nick; /**< Your nick in this chat. */ 285 286 gboolean left; /**< We left the chat and kept the window open */ 287 GHashTable *users; /**< Hash table of the users in the room. 288 * @since 2.9.0 289 */ 290 }; 291 292 /** 293 * Data for "Chat Buddies" 294 */ 295 struct _PurpleConvChatBuddy 296 { 297 char *name; /**< The chat participant's name in the chat. */ 298 char *alias; /**< The chat participant's alias, if known; 299 * @a NULL otherwise. 300 */ 301 char *alias_key; /**< A string by which this buddy will be sorted, 302 * or @c NULL if the buddy should be sorted by 303 * its @c name. (This is currently always @c 304 * NULL.) 305 */ 306 gboolean buddy; /**< @a TRUE if this chat participant is on the 307 * buddy list; @a FALSE otherwise. 308 */ 309 PurpleConvChatBuddyFlags flags; /**< A bitwise OR of flags for this participant, 310 * such as whether they are a channel operator. 311 */ 312 GHashTable *attributes; /**< A hash table of attributes about the user, such as 313 * real name, user@host, etc. 314 */ 315 gpointer ui_data; /** < The UI can put whatever it wants here. */ 316 }; 317 318 /** 319 * Description of a conversation message 320 * 321 * @since 2.2.0 322 */ 323 struct _PurpleConvMessage 324 { 325 char *who; 326 char *what; 327 PurpleMessageFlags flags; 328 time_t when; 329 PurpleConversation *conv; /**< @since 2.3.0 */ 330 char *alias; /**< @since 2.3.0 */ 331 }; 332 333 /** 334 * A core representation of a conversation between two or more people. 335 * 336 * The conversation can be an IM or a chat. 337 */ 338 struct _PurpleConversation 339 { 340 PurpleConversationType type; /**< The type of conversation. */ 341 342 PurpleAccount *account; /**< The user using this conversation. */ 343 344 345 char *name; /**< The name of the conversation. */ 346 char *title; /**< The window title. */ 347 348 gboolean logging; /**< The status of logging. */ 349 350 GList *logs; /**< This conversation's logs */ 351 352 union 353 { 354 PurpleConvIm *im; /**< IM-specific data. */ 355 PurpleConvChat *chat; /**< Chat-specific data. */ 356 void *misc; /**< Misc. data. */ 357 358 } u; 359 360 PurpleConversationUiOps *ui_ops; /**< UI-specific operations. */ 361 void *ui_data; /**< UI-specific data. */ 362 363 GHashTable *data; /**< Plugin-specific data. */ 364 365 PurpleConnectionFlags features; /**< The supported features */ 366 GList *message_history; /**< Message history, as a GList of PurpleConvMessage's */ 367 }; 368 369 #ifdef __cplusplus 370 extern "C" { 371 #endif 372 373 /**************************************************************************/ 374 /** @name Conversation API */ 375 /**************************************************************************/ 376 /*@{*/ 377 378 /** 379 * Creates a new conversation of the specified type. 380 * 381 * @param type The type of conversation. 382 * @param account The account opening the conversation window on the purple 383 * user's end. 384 * @param name The name of the conversation. For PURPLE_CONV_TYPE_IM, 385 * this is the name of the buddy. 386 * 387 * @return The new conversation. 388 */ 389 PurpleConversation *purple_conversation_new(PurpleConversationType type, 390 PurpleAccount *account, 391 const char *name); 392 393 /** 394 * Destroys the specified conversation and removes it from the parent 395 * window. 396 * 397 * If this conversation is the only one contained in the parent window, 398 * that window is also destroyed. 399 * 400 * @param conv The conversation to destroy. 401 */ 402 void purple_conversation_destroy(PurpleConversation *conv); 403 404 405 /** 406 * Present a conversation to the user. This allows core code to initiate a 407 * conversation by displaying the IM dialog. 408 * @param conv The conversation to present 409 */ 410 void purple_conversation_present(PurpleConversation *conv); 411 412 413 /** 414 * Returns the specified conversation's type. 415 * 416 * @param conv The conversation. 417 * 418 * @return The conversation's type. 419 */ 420 PurpleConversationType purple_conversation_get_type(const PurpleConversation *conv); 421 422 /** 423 * Sets the specified conversation's UI operations structure. 424 * 425 * @param conv The conversation. 426 * @param ops The UI conversation operations structure. 427 */ 428 void purple_conversation_set_ui_ops(PurpleConversation *conv, 429 PurpleConversationUiOps *ops); 430 431 /** 432 * Sets the default conversation UI operations structure. 433 * 434 * @param ops The UI conversation operations structure. 435 */ 436 void purple_conversations_set_ui_ops(PurpleConversationUiOps *ops); 437 438 /** 439 * Returns the specified conversation's UI operations structure. 440 * 441 * @param conv The conversation. 442 * 443 * @return The operations structure. 444 */ 445 PurpleConversationUiOps *purple_conversation_get_ui_ops( 446 const PurpleConversation *conv); 447 448 /** 449 * Sets the specified conversation's purple_account. 450 * 451 * This purple_account represents the user using purple, not the person the user 452 * is having a conversation/chat/flame with. 453 * 454 * @param conv The conversation. 455 * @param account The purple_account. 456 */ 457 void purple_conversation_set_account(PurpleConversation *conv, 458 PurpleAccount *account); 459 460 /** 461 * Returns the specified conversation's purple_account. 462 * 463 * This purple_account represents the user using purple, not the person the user 464 * is having a conversation/chat/flame with. 465 * 466 * @param conv The conversation. 467 * 468 * @return The conversation's purple_account. 469 */ 470 PurpleAccount *purple_conversation_get_account(const PurpleConversation *conv); 471 472 /** 473 * Returns the specified conversation's purple_connection. 474 * 475 * This is the same as purple_conversation_get_user(conv)->gc. 476 * 477 * @param conv The conversation. 478 * 479 * @return The conversation's purple_connection. 480 */ 481 PurpleConnection *purple_conversation_get_gc(const PurpleConversation *conv); 482 483 /** 484 * Sets the specified conversation's title. 485 * 486 * @param conv The conversation. 487 * @param title The title. 488 */ 489 void purple_conversation_set_title(PurpleConversation *conv, const char *title); 490 491 /** 492 * Returns the specified conversation's title. 493 * 494 * @param conv The conversation. 495 * 496 * @return The title. 497 */ 498 const char *purple_conversation_get_title(const PurpleConversation *conv); 499 500 /** 501 * Automatically sets the specified conversation's title. 502 * 503 * This function takes OPT_IM_ALIAS_TAB into account, as well as the 504 * user's alias. 505 * 506 * @param conv The conversation. 507 */ 508 void purple_conversation_autoset_title(PurpleConversation *conv); 509 510 /** 511 * Sets the specified conversation's name. 512 * 513 * @param conv The conversation. 514 * @param name The conversation's name. 515 */ 516 void purple_conversation_set_name(PurpleConversation *conv, const char *name); 517 518 /** 519 * Returns the specified conversation's name. 520 * 521 * @param conv The conversation. 522 * 523 * @return The conversation's name. If the conversation is an IM with a PurpleBuddy, 524 * then it's the name of the PurpleBuddy. 525 */ 526 const char *purple_conversation_get_name(const PurpleConversation *conv); 527 528 /** 529 * Get an attribute of a chat buddy 530 * 531 * @param cb The chat buddy. 532 * @param key The key of the attribute. 533 * 534 * @return The value of the attribute key. 535 */ 536 const char *purple_conv_chat_cb_get_attribute(PurpleConvChatBuddy *cb, const char *key); 537 538 /** 539 * Get the keys of all atributes of a chat buddy 540 * 541 * @param cb The chat buddy. 542 * 543 * @return A list of the attributes of a chat buddy. 544 */ 545 GList *purple_conv_chat_cb_get_attribute_keys(PurpleConvChatBuddy *cb); 546 547 /** 548 * Set an attribute of a chat buddy 549 * 550 * @param chat The chat. 551 * @param cb The chat buddy. 552 * @param key The key of the attribute. 553 * @param value The value of the attribute. 554 */ 555 void purple_conv_chat_cb_set_attribute(PurpleConvChat *chat, PurpleConvChatBuddy *cb, const char *key, const char *value); 556 557 /** 558 * Set attributes of a chat buddy 559 * 560 * @param chat The chat. 561 * @param cb The chat buddy. 562 * @param keys A GList of the keys. 563 * @param values A GList of the values. 564 */ 565 void 566 purple_conv_chat_cb_set_attributes(PurpleConvChat *chat, PurpleConvChatBuddy *cb, GList *keys, GList *values); 567 568 /** 569 * Enables or disables logging for this conversation. 570 * 571 * @param conv The conversation. 572 * @param log @c TRUE if logging should be enabled, or @c FALSE otherwise. 573 */ 574 void purple_conversation_set_logging(PurpleConversation *conv, gboolean log); 575 576 /** 577 * Returns whether or not logging is enabled for this conversation. 578 * 579 * @param conv The conversation. 580 * 581 * @return @c TRUE if logging is enabled, or @c FALSE otherwise. 582 */ 583 gboolean purple_conversation_is_logging(const PurpleConversation *conv); 584 585 /** 586 * Closes any open logs for this conversation. 587 * 588 * Note that new logs will be opened as necessary (e.g. upon receipt of a 589 * message, if the conversation has logging enabled. To disable logging for 590 * the remainder of the conversation, use purple_conversation_set_logging(). 591 * 592 * @param conv The conversation. 593 */ 594 void purple_conversation_close_logs(PurpleConversation *conv); 595 596 /** 597 * Returns the specified conversation's IM-specific data. 598 * 599 * If the conversation type is not PURPLE_CONV_TYPE_IM, this will return @c NULL. 600 * 601 * @param conv The conversation. 602 * 603 * @return The IM-specific data. 604 */ 605 PurpleConvIm *purple_conversation_get_im_data(const PurpleConversation *conv); 606 607 #define PURPLE_CONV_IM(c) (purple_conversation_get_im_data(c)) 608 609 /** 610 * Returns the specified conversation's chat-specific data. 611 * 612 * If the conversation type is not PURPLE_CONV_TYPE_CHAT, this will return @c NULL. 613 * 614 * @param conv The conversation. 615 * 616 * @return The chat-specific data. 617 */ 618 PurpleConvChat *purple_conversation_get_chat_data(const PurpleConversation *conv); 619 620 #define PURPLE_CONV_CHAT(c) (purple_conversation_get_chat_data(c)) 621 622 /** 623 * Sets extra data for a conversation. 624 * 625 * @param conv The conversation. 626 * @param key The unique key. 627 * @param data The data to assign. 628 */ 629 void purple_conversation_set_data(PurpleConversation *conv, const char *key, 630 gpointer data); 631 632 /** 633 * Returns extra data in a conversation. 634 * 635 * @param conv The conversation. 636 * @param key The unqiue key. 637 * 638 * @return The data associated with the key. 639 */ 640 gpointer purple_conversation_get_data(PurpleConversation *conv, const char *key); 641 642 /** 643 * Returns a list of all conversations. 644 * 645 * This list includes both IMs and chats. 646 * 647 * @constreturn A GList of all conversations. 648 */ 649 GList *purple_get_conversations(void); 650 651 /** 652 * Returns a list of all IMs. 653 * 654 * @constreturn A GList of all IMs. 655 */ 656 GList *purple_get_ims(void); 657 658 /** 659 * Returns a list of all chats. 660 * 661 * @constreturn A GList of all chats. 662 */ 663 GList *purple_get_chats(void); 664 665 /** 666 * Finds a conversation with the specified type, name, and Purple account. 667 * 668 * @param type The type of the conversation. 669 * @param name The name of the conversation. 670 * @param account The purple_account associated with the conversation. 671 * 672 * @return The conversation if found, or @c NULL otherwise. 673 */ 674 PurpleConversation *purple_find_conversation_with_account( 675 PurpleConversationType type, const char *name, 676 const PurpleAccount *account); 677 678 /** 679 * Writes to a conversation window. 680 * 681 * This function should not be used to write IM or chat messages. Use 682 * purple_conv_im_write() and purple_conv_chat_write() instead. Those functions will 683 * most likely call this anyway, but they may do their own formatting, 684 * sound playback, etc. 685 * 686 * This can be used to write generic messages, such as "so and so closed 687 * the conversation window." 688 * 689 * @param conv The conversation. 690 * @param who The user who sent the message. 691 * @param message The message. 692 * @param flags The message flags. 693 * @param mtime The time the message was sent. 694 * 695 * @see purple_conv_im_write() 696 * @see purple_conv_chat_write() 697 */ 698 void purple_conversation_write(PurpleConversation *conv, const char *who, 699 const char *message, PurpleMessageFlags flags, 700 time_t mtime); 701 702 /** 703 Set the features as supported for the given conversation. 704 @param conv The conversation 705 @param features Bitset defining supported features 706 */ 707 void purple_conversation_set_features(PurpleConversation *conv, 708 PurpleConnectionFlags features); 709 710 711 /** 712 Get the features supported by the given conversation. 713 @param conv The conversation 714 */ 715 PurpleConnectionFlags purple_conversation_get_features(PurpleConversation *conv); 716 717 /** 718 * Determines if a conversation has focus 719 * 720 * @param conv The conversation. 721 * 722 * @return @c TRUE if the conversation has focus, @c FALSE if 723 * it does not or the UI does not have a concept of conversation focus 724 */ 725 gboolean purple_conversation_has_focus(PurpleConversation *conv); 726 727 /** 728 * Updates the visual status and UI of a conversation. 729 * 730 * @param conv The conversation. 731 * @param type The update type. 732 */ 733 void purple_conversation_update(PurpleConversation *conv, PurpleConvUpdateType type); 734 735 /** 736 * Calls a function on each conversation. 737 * 738 * @param func The function. 739 */ 740 void purple_conversation_foreach(void (*func)(PurpleConversation *conv)); 741 742 /** 743 * Retrieve the message history of a conversation. 744 * 745 * @param conv The conversation 746 * 747 * @return A GList of PurpleConvMessage's. The must not modify the list or the data within. 748 * The list contains the newest message at the beginning, and the oldest message at 749 * the end. 750 * 751 * @since 2.2.0 752 */ 753 GList *purple_conversation_get_message_history(PurpleConversation *conv); 754 755 /** 756 * Clear the message history of a conversation. 757 * 758 * @param conv The conversation 759 * 760 * @since 2.2.0 761 */ 762 void purple_conversation_clear_message_history(PurpleConversation *conv); 763 764 /** 765 * Get the sender from a PurpleConvMessage 766 * 767 * @param msg A PurpleConvMessage 768 * 769 * @return The name of the sender of the message 770 * 771 * @since 2.2.0 772 */ 773 const char *purple_conversation_message_get_sender(PurpleConvMessage *msg); 774 775 /** 776 * Get the message from a PurpleConvMessage 777 * 778 * @param msg A PurpleConvMessage 779 * 780 * @return The name of the sender of the message 781 * 782 * @since 2.2.0 783 */ 784 const char *purple_conversation_message_get_message(PurpleConvMessage *msg); 785 786 /** 787 * Get the message-flags of a PurpleConvMessage 788 * 789 * @param msg A PurpleConvMessage 790 * 791 * @return The message flags 792 * 793 * @since 2.2.0 794 */ 795 PurpleMessageFlags purple_conversation_message_get_flags(PurpleConvMessage *msg); 796 797 /** 798 * Get the timestamp of a PurpleConvMessage 799 * 800 * @param msg A PurpleConvMessage 801 * 802 * @return The timestamp of the message 803 * 804 * @since 2.2.0 805 */ 806 time_t purple_conversation_message_get_timestamp(PurpleConvMessage *msg); 807 808 /*@}*/ 809 810 811 /**************************************************************************/ 812 /** @name IM Conversation API */ 813 /**************************************************************************/ 814 /*@{*/ 815 816 /** 817 * Gets an IM's parent conversation. 818 * 819 * @param im The IM. 820 * 821 * @return The parent conversation. 822 */ 823 PurpleConversation *purple_conv_im_get_conversation(const PurpleConvIm *im); 824 825 /** 826 * Sets the IM's buddy icon. 827 * 828 * This should only be called from within Purple. You probably want to 829 * call purple_buddy_icon_set_data(). 830 * 831 * @param im The IM. 832 * @param icon The buddy icon. 833 * 834 * @see purple_buddy_icon_set_data() 835 */ 836 void purple_conv_im_set_icon(PurpleConvIm *im, PurpleBuddyIcon *icon); 837 838 /** 839 * Returns the IM's buddy icon. 840 * 841 * @param im The IM. 842 * 843 * @return The buddy icon. 844 */ 845 PurpleBuddyIcon *purple_conv_im_get_icon(const PurpleConvIm *im); 846 847 /** 848 * Sets the IM's typing state. 849 * 850 * @param im The IM. 851 * @param state The typing state. 852 */ 853 void purple_conv_im_set_typing_state(PurpleConvIm *im, PurpleTypingState state); 854 855 /** 856 * Returns the IM's typing state. 857 * 858 * @param im The IM. 859 * 860 * @return The IM's typing state. 861 */ 862 PurpleTypingState purple_conv_im_get_typing_state(const PurpleConvIm *im); 863 864 /** 865 * Starts the IM's typing timeout. 866 * 867 * @param im The IM. 868 * @param timeout The timeout. 869 */ 870 void purple_conv_im_start_typing_timeout(PurpleConvIm *im, int timeout); 871 872 /** 873 * Stops the IM's typing timeout. 874 * 875 * @param im The IM. 876 */ 877 void purple_conv_im_stop_typing_timeout(PurpleConvIm *im); 878 879 /** 880 * Returns the IM's typing timeout. 881 * 882 * @param im The IM. 883 * 884 * @return The timeout. 885 */ 886 guint purple_conv_im_get_typing_timeout(const PurpleConvIm *im); 887 888 /** 889 * Sets the quiet-time when no PURPLE_TYPING messages will be sent. 890 * Few protocols need this. If the user is still typing after this 891 * quiet-period, then another PURPLE_TYPING message will be sent. 892 * 893 * @param im The IM. 894 * @param val The number of seconds to wait before allowing another 895 * PURPLE_TYPING message to be sent to the user. Or 0 to 896 * not send another PURPLE_TYPING message. 897 */ 898 void purple_conv_im_set_type_again(PurpleConvIm *im, unsigned int val); 899 900 /** 901 * Returns the time after which another PURPLE_TYPING message should be sent. 902 * 903 * @param im The IM. 904 * 905 * @return The time in seconds since the epoch. Or 0 if no additional 906 * PURPLE_TYPING message should be sent. 907 */ 908 time_t purple_conv_im_get_type_again(const PurpleConvIm *im); 909 910 /** 911 * Starts the IM's type again timeout. 912 * 913 * @param im The IM. 914 */ 915 void purple_conv_im_start_send_typed_timeout(PurpleConvIm *im); 916 917 /** 918 * Stops the IM's type again timeout. 919 * 920 * @param im The IM. 921 */ 922 void purple_conv_im_stop_send_typed_timeout(PurpleConvIm *im); 923 924 /** 925 * Returns the IM's type again timeout interval. 926 * 927 * @param im The IM. 928 * 929 * @return The type again timeout interval. 930 */ 931 guint purple_conv_im_get_send_typed_timeout(const PurpleConvIm *im); 932 933 /** 934 * Updates the visual typing notification for an IM conversation. 935 * 936 * @param im The IM. 937 */ 938 void purple_conv_im_update_typing(PurpleConvIm *im); 939 940 /** 941 * Writes to an IM. 942 * 943 * @param im The IM. 944 * @param who The user who sent the message. 945 * @param message The message to write. 946 * @param flags The message flags. 947 * @param mtime The time the message was sent. 948 */ 949 void purple_conv_im_write(PurpleConvIm *im, const char *who, 950 const char *message, PurpleMessageFlags flags, 951 time_t mtime); 952 953 /** 954 * Presents an IM-error to the user 955 * 956 * This is a helper function to find a conversation, write an error to it, and 957 * raise the window. If a conversation with this user doesn't already exist, 958 * the function will return FALSE and the calling function can attempt to present 959 * the error another way (purple_notify_error, most likely) 960 * 961 * @param who The user this error is about 962 * @param account The account this error is on 963 * @param what The error 964 * @return TRUE if the error was presented, else FALSE 965 */ 966 gboolean purple_conv_present_error(const char *who, PurpleAccount *account, const char *what); 967 968 /** 969 * Sends a message to this IM conversation. 970 * 971 * @param im The IM. 972 * @param message The message to send. 973 */ 974 void purple_conv_im_send(PurpleConvIm *im, const char *message); 975 976 /** 977 * Sends a message to a conversation after confirming with 978 * the user. 979 * 980 * This function is intended for use in cases where the user 981 * hasn't explicitly and knowingly caused a message to be sent. 982 * The confirmation ensures that the user isn't sending a 983 * message by mistake. 984 * 985 * @param conv The conversation. 986 * @param message The message to send. 987 */ 988 void purple_conv_send_confirm(PurpleConversation *conv, const char *message); 989 990 /** 991 * Sends a message to this IM conversation with specified flags. 992 * 993 * @param im The IM. 994 * @param message The message to send. 995 * @param flags The PurpleMessageFlags flags to use in addition to PURPLE_MESSAGE_SEND. 996 */ 997 void purple_conv_im_send_with_flags(PurpleConvIm *im, const char *message, PurpleMessageFlags flags); 998 999 /** 1000 * Adds a smiley to the conversation's smiley tree. If this returns 1001 * @c TRUE you should call purple_conv_custom_smiley_write() one or more 1002 * times, and then purple_conv_custom_smiley_close(). If this returns 1003 * @c FALSE, either the conv or smile were invalid, or the icon was 1004 * found in the cache. In either case, calling write or close would 1005 * be an error. 1006 * 1007 * @param conv The conversation to associate the smiley with. 1008 * @param smile The text associated with the smiley 1009 * @param cksum_type The type of checksum. 1010 * @param chksum The checksum, as a NUL terminated base64 string. 1011 * @param remote @c TRUE if the custom smiley is set by the remote user (buddy). 1012 * @return @c TRUE if an icon is expected, else FALSE. Note that 1013 * it is an error to never call purple_conv_custom_smiley_close if 1014 * this function returns @c TRUE, but an error to call it if 1015 * @c FALSE is returned. 1016 */ 1017 1018 gboolean purple_conv_custom_smiley_add(PurpleConversation *conv, const char *smile, 1019 const char *cksum_type, const char *chksum, 1020 gboolean remote); 1021 1022 1023 /** 1024 * Updates the image associated with the current smiley. 1025 * 1026 * @param conv The conversation associated with the smiley. 1027 * @param smile The text associated with the smiley. 1028 * @param data The actual image data. 1029 * @param size The length of the data. 1030 */ 1031 1032 void purple_conv_custom_smiley_write(PurpleConversation *conv, 1033 const char *smile, 1034 const guchar *data, 1035 gsize size); 1036 1037 /** 1038 * Close the custom smiley, all data has been written with 1039 * purple_conv_custom_smiley_write, and it is no longer valid 1040 * to call that function on that smiley. 1041 * 1042 * @param conv The purple conversation associated with the smiley. 1043 * @param smile The text associated with the smiley 1044 */ 1045 1046 void purple_conv_custom_smiley_close(PurpleConversation *conv, const char *smile); 1047 1048 /*@}*/ 1049 1050 1051 /**************************************************************************/ 1052 /** @name Chat Conversation API */ 1053 /**************************************************************************/ 1054 /*@{*/ 1055 1056 /** 1057 * Gets a chat's parent conversation. 1058 * 1059 * @param chat The chat. 1060 * 1061 * @return The parent conversation. 1062 */ 1063 PurpleConversation *purple_conv_chat_get_conversation(const PurpleConvChat *chat); 1064 1065 /** 1066 * Sets the list of users in the chat room. 1067 * 1068 * @note Calling this function will not update the display of the users. 1069 * Please use purple_conv_chat_add_user(), purple_conv_chat_add_users(), 1070 * purple_conv_chat_remove_user(), and purple_conv_chat_remove_users() instead. 1071 * 1072 * @param chat The chat. 1073 * @param users The list of users. 1074 * 1075 * @return The list passed. 1076 * 1077 * @deprecated This function will be removed in 3.0.0. You shouldn't be using it anyway. 1078 */ 1079 GList *purple_conv_chat_set_users(PurpleConvChat *chat, GList *users); 1080 1081 /** 1082 * Returns a list of users in the chat room. The members of the list 1083 * are PurpleConvChatBuddy objects. 1084 * 1085 * @param chat The chat. 1086 * 1087 * @constreturn The list of users. 1088 */ 1089 GList *purple_conv_chat_get_users(const PurpleConvChat *chat); 1090 1091 /** 1092 * Ignores a user in a chat room. 1093 * 1094 * @param chat The chat. 1095 * @param name The name of the user. 1096 */ 1097 void purple_conv_chat_ignore(PurpleConvChat *chat, const char *name); 1098 1099 /** 1100 * Unignores a user in a chat room. 1101 * 1102 * @param chat The chat. 1103 * @param name The name of the user. 1104 */ 1105 void purple_conv_chat_unignore(PurpleConvChat *chat, const char *name); 1106 1107 /** 1108 * Sets the list of ignored users in the chat room. 1109 * 1110 * @param chat The chat. 1111 * @param ignored The list of ignored users. 1112 * 1113 * @return The list passed. 1114 */ 1115 GList *purple_conv_chat_set_ignored(PurpleConvChat *chat, GList *ignored); 1116 1117 /** 1118 * Returns the list of ignored users in the chat room. 1119 * 1120 * @param chat The chat. 1121 * 1122 * @constreturn The list of ignored users. 1123 */ 1124 GList *purple_conv_chat_get_ignored(const PurpleConvChat *chat); 1125 1126 /** 1127 * Returns the actual name of the specified ignored user, if it exists in 1128 * the ignore list. 1129 * 1130 * If the user found contains a prefix, such as '+' or '\@', this is also 1131 * returned. The username passed to the function does not have to have this 1132 * formatting. 1133 * 1134 * @param chat The chat. 1135 * @param user The user to check in the ignore list. 1136 * 1137 * @return The ignored user if found, complete with prefixes, or @c NULL 1138 * if not found. 1139 */ 1140 const char *purple_conv_chat_get_ignored_user(const PurpleConvChat *chat, 1141 const char *user); 1142 1143 /** 1144 * Returns @c TRUE if the specified user is ignored. 1145 * 1146 * @param chat The chat. 1147 * @param user The user. 1148 * 1149 * @return @c TRUE if the user is in the ignore list; @c FALSE otherwise. 1150 */ 1151 gboolean purple_conv_chat_is_user_ignored(const PurpleConvChat *chat, 1152 const char *user); 1153 1154 /** 1155 * Sets the chat room's topic. 1156 * 1157 * @param chat The chat. 1158 * @param who The user that set the topic. 1159 * @param topic The topic. 1160 */ 1161 void purple_conv_chat_set_topic(PurpleConvChat *chat, const char *who, 1162 const char *topic); 1163 1164 /** 1165 * Returns the chat room's topic. 1166 * 1167 * @param chat The chat. 1168 * 1169 * @return The chat's topic. 1170 */ 1171 const char *purple_conv_chat_get_topic(const PurpleConvChat *chat); 1172 1173 /** 1174 * Sets the chat room's ID. 1175 * 1176 * @param chat The chat. 1177 * @param id The ID. 1178 */ 1179 void purple_conv_chat_set_id(PurpleConvChat *chat, int id); 1180 1181 /** 1182 * Returns the chat room's ID. 1183 * 1184 * @param chat The chat. 1185 * 1186 * @return The ID. 1187 */ 1188 int purple_conv_chat_get_id(const PurpleConvChat *chat); 1189 1190 /** 1191 * Writes to a chat. 1192 * 1193 * @param chat The chat. 1194 * @param who The user who sent the message. 1195 * @param message The message to write. 1196 * @param flags The flags. 1197 * @param mtime The time the message was sent. 1198 */ 1199 void purple_conv_chat_write(PurpleConvChat *chat, const char *who, 1200 const char *message, PurpleMessageFlags flags, 1201 time_t mtime); 1202 1203 /** 1204 * Sends a message to this chat conversation. 1205 * 1206 * @param chat The chat. 1207 * @param message The message to send. 1208 */ 1209 void purple_conv_chat_send(PurpleConvChat *chat, const char *message); 1210 1211 /** 1212 * Sends a message to this chat conversation with specified flags. 1213 * 1214 * @param chat The chat. 1215 * @param message The message to send. 1216 * @param flags The PurpleMessageFlags flags to use. 1217 */ 1218 void purple_conv_chat_send_with_flags(PurpleConvChat *chat, const char *message, PurpleMessageFlags flags); 1219 1220 /** 1221 * Adds a user to a chat. 1222 * 1223 * @param chat The chat. 1224 * @param user The user to add. 1225 * @param extra_msg An extra message to display with the join message. 1226 * @param flags The users flags 1227 * @param new_arrival Decides whether or not to show a join notice. 1228 */ 1229 void purple_conv_chat_add_user(PurpleConvChat *chat, const char *user, 1230 const char *extra_msg, PurpleConvChatBuddyFlags flags, 1231 gboolean new_arrival); 1232 1233 /** 1234 * Adds a list of users to a chat. 1235 * 1236 * The data is copied from @a users, @a extra_msgs, and @a flags, so it is up to 1237 * the caller to free this list after calling this function. 1238 * 1239 * @param chat The chat. 1240 * @param users The list of users to add. 1241 * @param extra_msgs An extra message to display with the join message for each 1242 * user. This list may be shorter than @a users, in which 1243 * case, the users after the end of extra_msgs will not have 1244 * an extra message. By extension, this means that extra_msgs 1245 * can simply be @c NULL and none of the users will have an 1246 * extra message. 1247 * @param flags The list of flags for each user. 1248 * @param new_arrivals Decides whether or not to show join notices. 1249 */ 1250 void purple_conv_chat_add_users(PurpleConvChat *chat, GList *users, GList *extra_msgs, 1251 GList *flags, gboolean new_arrivals); 1252 1253 /** 1254 * Renames a user in a chat. 1255 * 1256 * @param chat The chat. 1257 * @param old_user The old username. 1258 * @param new_user The new username. 1259 */ 1260 void purple_conv_chat_rename_user(PurpleConvChat *chat, const char *old_user, 1261 const char *new_user); 1262 1263 /** 1264 * Removes a user from a chat, optionally with a reason. 1265 * 1266 * It is up to the developer to free this list after calling this function. 1267 * 1268 * @param chat The chat. 1269 * @param user The user that is being removed. 1270 * @param reason The optional reason given for the removal. Can be @c NULL. 1271 */ 1272 void purple_conv_chat_remove_user(PurpleConvChat *chat, const char *user, 1273 const char *reason); 1274 1275 /** 1276 * Removes a list of users from a chat, optionally with a single reason. 1277 * 1278 * @param chat The chat. 1279 * @param users The users that are being removed. 1280 * @param reason The optional reason given for the removal. Can be @c NULL. 1281 */ 1282 void purple_conv_chat_remove_users(PurpleConvChat *chat, GList *users, 1283 const char *reason); 1284 1285 /** 1286 * Finds a user in a chat 1287 * 1288 * @param chat The chat. 1289 * @param user The user to look for. 1290 * 1291 * @return TRUE if the user is in the chat, FALSE if not 1292 */ 1293 gboolean purple_conv_chat_find_user(PurpleConvChat *chat, const char *user); 1294 1295 /** 1296 * Set a users flags in a chat 1297 * 1298 * @param chat The chat. 1299 * @param user The user to update. 1300 * @param flags The new flags. 1301 */ 1302 void purple_conv_chat_user_set_flags(PurpleConvChat *chat, const char *user, 1303 PurpleConvChatBuddyFlags flags); 1304 1305 /** 1306 * Get the flags for a user in a chat 1307 * 1308 * @param chat The chat. 1309 * @param user The user to find the flags for 1310 * 1311 * @return The flags for the user 1312 */ 1313 PurpleConvChatBuddyFlags purple_conv_chat_user_get_flags(PurpleConvChat *chat, 1314 const char *user); 1315 1316 /** 1317 * Clears all users from a chat. 1318 * 1319 * @param chat The chat. 1320 */ 1321 void purple_conv_chat_clear_users(PurpleConvChat *chat); 1322 1323 /** 1324 * Sets your nickname (used for hilighting) for a chat. 1325 * 1326 * @param chat The chat. 1327 * @param nick The nick. 1328 */ 1329 void purple_conv_chat_set_nick(PurpleConvChat *chat, const char *nick); 1330 1331 /** 1332 * Gets your nickname (used for hilighting) for a chat. 1333 * 1334 * @param chat The chat. 1335 * @return The nick. 1336 */ 1337 const char *purple_conv_chat_get_nick(PurpleConvChat *chat); 1338 1339 /** 1340 * Finds a chat with the specified chat ID. 1341 * 1342 * @param gc The purple_connection. 1343 * @param id The chat ID. 1344 * 1345 * @return The chat conversation. 1346 */ 1347 PurpleConversation *purple_find_chat(const PurpleConnection *gc, int id); 1348 1349 /** 1350 * Lets the core know we left a chat, without destroying it. 1351 * Called from serv_got_chat_left(). 1352 * 1353 * @param chat The chat. 1354 */ 1355 void purple_conv_chat_left(PurpleConvChat *chat); 1356 1357 /** 1358 * Invite a user to a chat. 1359 * The user will be prompted to enter the user's name or a message if one is 1360 * not given. 1361 * 1362 * @param chat The chat. 1363 * @param user The user to invite to the chat. 1364 * @param message The message to send with the invitation. 1365 * @param confirm Prompt before sending the invitation. The user is always 1366 * prompted if either \a user or \a message is @c NULL. 1367 * 1368 * @since 2.6.0 1369 */ 1370 void purple_conv_chat_invite_user(PurpleConvChat *chat, const char *user, 1371 const char *message, gboolean confirm); 1372 1373 /** 1374 * Returns true if we're no longer in this chat, 1375 * and just left the window open. 1376 * 1377 * @param chat The chat. 1378 * 1379 * @return @c TRUE if we left the chat already, @c FALSE if 1380 * we're still there. 1381 */ 1382 gboolean purple_conv_chat_has_left(PurpleConvChat *chat); 1383 1384 /** 1385 * Creates a new chat buddy 1386 * 1387 * @param name The name. 1388 * @param alias The alias. 1389 * @param flags The flags. 1390 * 1391 * @return The new chat buddy 1392 */ 1393 PurpleConvChatBuddy *purple_conv_chat_cb_new(const char *name, const char *alias, 1394 PurpleConvChatBuddyFlags flags); 1395 1396 /** 1397 * Find a chat buddy in a chat 1398 * 1399 * @param chat The chat. 1400 * @param name The name of the chat buddy to find. 1401 */ 1402 PurpleConvChatBuddy *purple_conv_chat_cb_find(PurpleConvChat *chat, const char *name); 1403 1404 /** 1405 * Get the name of a chat buddy 1406 * 1407 * @param cb The chat buddy. 1408 * 1409 * @return The name of the chat buddy. 1410 */ 1411 const char *purple_conv_chat_cb_get_name(PurpleConvChatBuddy *cb); 1412 1413 /** 1414 * Destroys a chat buddy 1415 * 1416 * @param cb The chat buddy to destroy 1417 */ 1418 void purple_conv_chat_cb_destroy(PurpleConvChatBuddy *cb); 1419 1420 /** 1421 * Retrieves the extended menu items for the conversation. 1422 * 1423 * @param conv The conversation. 1424 * 1425 * @return A list of PurpleMenuAction items, harvested by the 1426 * chat-extended-menu signal. The list and the menuaction 1427 * items should be freed by the caller. 1428 * 1429 * @since 2.1.0 1430 */ 1431 GList * purple_conversation_get_extended_menu(PurpleConversation *conv); 1432 1433 /** 1434 * Perform a command in a conversation. Similar to @see purple_cmd_do_command 1435 * 1436 * @param conv The conversation. 1437 * @param cmdline The entire command including the arguments. 1438 * @param markup @c NULL, or the formatted command line. 1439 * @param error If the command failed errormsg is filled in with the appropriate error 1440 * message, if not @c NULL. It must be freed by the caller with g_free(). 1441 * 1442 * @return @c TRUE if the command was executed successfully, @c FALSE otherwise. 1443 * 1444 * @since 2.1.0 1445 */ 1446 gboolean purple_conversation_do_command(PurpleConversation *conv, const gchar *cmdline, const gchar *markup, gchar **error); 1447 1448 /*@}*/ 1449 1450 /**************************************************************************/ 1451 /** @name Conversations Subsystem */ 1452 /**************************************************************************/ 1453 /*@{*/ 1454 1455 /** 1456 * Returns the conversation subsystem handle. 1457 * 1458 * @return The conversation subsystem handle. 1459 */ 1460 void *purple_conversations_get_handle(void); 1461 1462 /** 1463 * Initializes the conversation subsystem. 1464 */ 1465 void purple_conversations_init(void); 1466 1467 /** 1468 * Uninitializes the conversation subsystem. 1469 */ 1470 void purple_conversations_uninit(void); 1471 1472 /*@}*/ 1473 1474 #ifdef __cplusplus 1475 } 1476 #endif 1477 1478 #endif /* _PURPLE_CONVERSATION_H_ */ 1479