thunderbird-dev 1:52.8.0-1~deb8u1 / usr / share / idl / thunderbird / prplIConversation.idl

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */


#include "nsISupports.idl"
#include "nsISimpleEnumerator.idl"
#include "nsIObserver.idl"

interface prplIAccountBuddy;
interface imIAccount;
interface imIOutgoingMessage;
interface imIMessage;
interface nsIURI;
interface nsIDOMDocument;
interface prplIChatRoomFieldValues;

/*
 * This is the XPCOM purple conversation component, a proxy for PurpleConversation.
 */

[scriptable, uuid(f71c58d6-2c47-4468-934b-b1c61462c01a)]
interface prplIConversation: nsISupports {

  /* Indicate if this conversation implements prplIConvIM or prplIConvChat */
  readonly attribute boolean isChat;

  /* The account used for this conversation */
  readonly attribute imIAccount account;

  /* The name of the conversation, typically in English */
  readonly attribute AUTF8String name;

  /* A name that can be used to check for duplicates and is the basis
     for the directory name for log storage. */
  readonly attribute AUTF8String normalizedName;

  /* The title of the conversation, typically localized */
  readonly attribute AUTF8String title;

  /* The time and date of the conversation's creation, in microseconds */
  readonly attribute PRTime startDate;
  /* Unique identifier of the conversation */
  /* Setable only once by purpleCoreService while calling addConversation. */
           attribute unsigned long id;

  /* Send a message in the conversation */
  void sendMsg(in AUTF8String aMsg);

  /* Preprocess messages before they are sent (eg. split long messages).
     Can return null if no changes are to be made. */
  void prepareForSending(in imIOutgoingMessage aMsg,
                         [optional] out unsigned long aMsgCount,
                         [retval, array, size_is(aMsgCount)] out wstring aMsgs);

  /* Postprocess messages before they are displayed (eg. escaping). The
     implementation can set aMsg.displayMessage, otherwise the originalMessage
     is used. */
  void prepareForDisplaying(in imIMessage aMsg);

  /* Send information about the current typing state to the server.
     aString should contain the content currently in the text field. The
     protocol should return the number of characters that can still be typed. */
  long sendTyping(in AUTF8String aString);
  const long NO_TYPING_LIMIT = 2147483647; // max int = 2 ^ 31 - 1

  /* Un-initialize the conversation. Will be called by
     purpleCoreService::RemoveConversation when the conversation is
     closed or by purpleCoreService::Quit while exiting. */
  void unInit();

  /* When the conversation is closed from the UI. */
  void close();

  /* Method to add or remove an observer */
  void addObserver(in nsIObserver aObserver);
  void removeObserver(in nsIObserver aObserver);

  /* Observers will be all receive new-text notifications.
     aSubject will contain the message (prplIMessage) */
};

[scriptable, uuid(c0b5b647-b0ec-4dc6-9e53-31a762a30a6e)]
interface prplIConvIM: prplIConversation {

  /* The buddy at the remote end of the conversation */
  readonly attribute prplIAccountBuddy buddy;

  /* The remote buddy is not currently typing */
  const short NOT_TYPING = 0;

  /* The remote buddy is currently typing */
  const short TYPING = 1;

  /* The remote buddy started typing, but has stopped typing */
  const short TYPED = 2;

  /* The typing state of the remote buddy.
     The value is NOT_TYPING, TYPING or TYPED. */
  readonly attribute short typingState;
};

/* This represents a participant in a chat room */
[scriptable, uuid(b0e9177b-40f6-420b-9918-04bbbb9ce44f)]
interface prplIConvChatBuddy: nsISupports {

  /* The name of the buddy */
  readonly attribute AUTF8String name;

  /* The alias (FIXME: can this be non-null if buddy is null?) */
  readonly attribute AUTF8String alias;

  /* Indicates if this chat buddy corresponds to a buddy in our buddy list */
  readonly attribute boolean buddy;

  /* URI of the user icon for the buddy */
  readonly attribute AUTF8String buddyIconFilename;

  /* PurpleConvChatBuddyFlags flags; (ops, voice etc.) */
  readonly attribute boolean noFlags;
  readonly attribute boolean voiced;
  readonly attribute boolean halfOp;
  readonly attribute boolean op;
  readonly attribute boolean founder;
  readonly attribute boolean typing;
};

[scriptable, uuid(72c17398-639f-4141-a19c-78cbdeb39fba)]
interface prplIConvChat: prplIConversation {

  /* Get the prplIConvChatBuddy if a participant with name aName (the
     participant's nick in the conversation) exists, otherwise return null */
  prplIConvChatBuddy getParticipant(in AUTF8String aName);

  /* Get an nsISimpleEnumerator of prplIConvChatBuddy objects:
     The list of people participating in this chat */
  nsISimpleEnumerator getParticipants();

  /* The normalized chat buddy name will be suitable for calling
     createConversation to start a private conversation or calling
     requestBuddyInfo. */
  AUTF8String getNormalizedChatBuddyName(in AUTF8String aChatBuddyName);

  /* The topic of this chat room */
           attribute AUTF8String topic;

  /* The name/nick of the person who set the topic */
  readonly attribute AUTF8String topicSetter;

  /* Whether the protocol plugin can set a topic. Doesn't check that
     the user has the necessary rights in the current conversation. */
  readonly attribute boolean topicSettable;

  /* The nick seen by other people in the room */
  readonly attribute AUTF8String nick;

  /* This is true when we left the chat but kept the conversation open */
  readonly attribute boolean left;

  /* This is true if we are in the process of joining the channel */
  readonly attribute boolean joining;

  /* This stores the data required to join the chat with joinChat().
     If null, the chat will not be rejoined automatically when the
     account reconnects after a disconnect.
     Should be set to null by the prpl if the user parts the chat. */
  readonly attribute prplIChatRoomFieldValues chatRoomFields;

  /* Observers will receive chat-buddy-add, chat-buddy-update,
     chat-buddy-remove and chat-update-topic notifications.

     aSubject will be of type:
       nsISimpleEnumerator of prplIConvChatBuddy for chat-buddy-add,
       nsISimpleEnumerator of nsISupportsString for chat-buddy-remove,
       prplIConvChatBuddy for chat-buddy-update,
       null for chat-update-topic.

     aData will contain the old nick for chat-buddy-update if the name
     has changed.
   */
};