/* 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"
interface prplIConversation;

[scriptable, uuid(b12b0d89-0e5b-499c-9567-37f2deacc182)]
interface imICommand: nsISupports {
  readonly attribute AUTF8String name;

  // Help message displayed when the user types /help <name>.
  // Format: <command name> <parameters>: <help message>
  // Example: "help &lt;name&gt;: show the help message for the &lt;name&gt;
  //           command, or the list of possible commands when used without
  //           parameter."
  readonly attribute AUTF8String helpString;

  const short CMD_CONTEXT_IM   = 1;
  const short CMD_CONTEXT_CHAT = 2;
  const short CMD_CONTEXT_ALL  = CMD_CONTEXT_IM | CMD_CONTEXT_CHAT;
  readonly attribute long usageContext;

  const short CMD_PRIORITY_LOW     = -1000;
  const short CMD_PRIORITY_DEFAULT = 0;
  const short CMD_PRIORITY_PRPL    = 1000;
  const short CMD_PRIORITY_HIGH    = 4000;
  // Any integer value is usable as a priority.
  //    0 is the default priority.
  //  < 0 is lower priority.
  //  > 0 is higher priority.
  // Commands registered by protocol plugins will usually use PRIORITY_PRPL.
  readonly attribute long priority;

  // Will return true if the command handled the message (it should not be sent).
  // The leading slash, the command name and the following space are not included
  // in the aMessage parameter.
  // If a conversation is returned as a result of executing the command,
  // the caller should consider focusing it.
  boolean run(in AUTF8String aMessage,
              [optional] in prplIConversation aConversation,
              [optional] out prplIConversation aReturnedConv);
};

[scriptable, uuid(9a1accfd-9bd8-4548-aef7-e8107fc7839f)]
interface imICommandsService: nsISupports {
  void initCommands();
  void unInitCommands();

  // Commands registered without a protocol id will work for all protocols.
  // Registering several commands of the same name with the same
  // protocol id or no protocol id will replace the former command
  // with the latter.
  void registerCommand(in imICommand aCommand,
                       [optional] in AUTF8String aPrplId);

  // aPrplId should be the same as what was used for the command registration.
  void unregisterCommand(in AUTF8String aCommandName,
                         [optional] in AUTF8String aPrplId);

  Array<imICommand> listCommandsForConversation(
    [optional] in prplIConversation aConversation);

  Array<imICommand> listCommandsForProtocol(in AUTF8String aPrplId);

  // Will return true if a command handled the message (it should not be sent).
  // The aConversation parameters is required to execute protocol specific
  // commands. Application global commands will work without it.
  // If a conversation is returned as a result of executing the command,
  // the caller should consider focusing it.
  boolean executeCommand(in AUTF8String aMessage,
                         [optional] in prplIConversation aConversation,
                         [optional] out prplIConversation aReturnedConv);
};

%{ C++
#define IM_COMMANDS_SERVICE_CONTRACTID \
  "@mozilla.org/chat/commands-service;1"
%}