/* 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 "imIAccount.idl"

interface prplIPref;
interface prplIUsernameSplit;

/**
 * This must be implemented for every protocol.
 *
 * See jsProtoHelper.jsm for a base class.
 */
[scriptable, uuid(7d302db0-3813-4c51-8372-c7eb5fc9f3d3)]
interface prplIProtocol: nsISupports {
  /**
   * This method is used so that classes implementing several protocol
   * plugins can know which protocol is desired for this instance.
   *
   * @param aId The prpl id.
   */
  void init(in AUTF8String aId);

  /**
   * A human readable (potentially localized) name for the protocol.
   */
  readonly attribute AUTF8String name;
  /**
   * A unique ID for the protocol, should start with the prefix 'prpl-'.
   */
  readonly attribute AUTF8String id;
  /**
   * A unique name for this protocol, it must consist of only lowercase letters
   * & numbers.
   *
   * It can be used to check for duplicates and is the basis for the directory
   * name for log storage.
   */
  readonly attribute AUTF8String normalizedName;

  /**
   * A chrome URI pointing to a folder that contains the icon files:
   * icon.png icon32.png and icon48.png
   */
  readonly attribute AUTF8String iconBaseURI;

  /**
   * @returns an array of prplIPref
   */
  Array<prplIPref> getOptions();

  /**
   * String to put in front of the full account username identifier. Usually
   * an empty string.
   */
  readonly attribute AUTF8String usernamePrefix;

  /**
   * @returns an array of prplIUsernameSplit
   */
  Array<prplIUsernameSplit> getUsernameSplit();

  /**
   * Split a username into its parts without separators (or prefix).
   * Returns an empty array if the username can not be split.
   */
  Array<AUTF8String> splitUsername(in AUTF8String aName);

  /**
   * Descriptive text used in the account wizard to describe the username.
   */
  readonly attribute AUTF8String usernameEmptyText;

  /**
   * Use this function to avoid attempting to create duplicate accounts.
   */
  boolean accountExists(in AUTF8String aName);

  // The following should all be flags that describe whether a protocol has a
  // particular feature.

  /**
   * Whether chat rooms have topics.
   */
  readonly attribute boolean chatHasTopic;

  /**
   * True if passwords are unused for this protocol.
   *
   * Passwords are unused for some protocols, e.g. Bonjour.
   */
  readonly attribute boolean noPassword;

  /**
   * True if a password is not required for sign-in.
   *
   * Passwords in IRC are optional, and are needed for certain functionality.
   */
  readonly attribute boolean passwordOptional;

  /**
   * Indicates that slash commands are native to this protocol.
   * Used as a hint that unknown commands should not be sent as messages.
   */
  readonly attribute boolean slashCommandsNative;

  /**
   * True if the protocol can provide end-to-end message encryption in
   * conversations.
   */
  readonly attribute boolean canEncrypt;

  /**
   * Get the protocol specific part of an already initialized
   * imIAccount instance.
   */
  prplIAccount getAccount(in imIAccount aImAccount);
};

/**
 * The chat account wizards requests the sign-in information as a series of
 * fields generated by a list of prplIUsernameSplit.
 *
 * The result of these is composed into a string and stored as the account name.
 * It is the responsibity of the prplIAccount to re-parse this back to usable
 * connection data.
 *
 * TODO Replace this with storing account data as separate fields.
 */
[scriptable, uuid(20c4971a-f7c2-4781-8e85-69fee7b83a3d)]
interface prplIUsernameSplit: nsISupports {
  /**
   * The field name presented in the account wizard, e.g. server.
   */
  readonly attribute AUTF8String label;
  /**
   * The default value that is presented in the account wizard.
   */
  readonly attribute AUTF8String defaultValue;
  /**
   * The string used to compose the account name.
   *
   * E.g. an "@" would cause "@" to be appended before this field.
   */
  readonly attribute char separator;
};