ejabberd commands

By defining command using api available through ejabberd_commands module, it's possible to add operations that would be available to users through ejabberdctl command, XML-RPC socket or JSON based REST service.

Each command needs to provide information about required arguments and produced result by filling #ejabberd_commands record and registering it in dispatcher by calling ejabberd_commands:register_commands([ListOfEjabberdCommandsRecords]).

Structure of #ejabberd_commands record

Writing ejabberd commands supporting OAuth

If you have existing commands that you want to make OAuth compliant, you can make them OAuth compliant very easily.

An ejabberd command is defined by an #ejabberd_commands Erlang record. The record requires a few fields:

• name: This is an atom defining the name of the command.

• tags: This is a list of atoms used to group the command into consistent group of commands. This is mostly used to group commands in ejabberdctl command-line tool. Existing categories are:

  • session: For commands related to user XMPP sessions.
  • roster: Commands related to contact list management.

• desc: Description of the command for online help.

• module and function: Module and function to call to execute the command logic.

• args: Argument of the command. An argument is defined by a tuple of atoms of the form {argument_name, data_type}. data_type can be one of:

  • binary

• result: defines what the command will return.

• policy: Is an optional field, containing an atom that define restriction policy of the command. It can be on of: open, admin, user, restricted. Default is restricted, meaning the command can be used from ejabberdctl command-line tool.
• version: API version number where this command is available (see API versioning documentation for details).

To define a command that can be used by server user over ReST or XML-RPC API, you just have to define it with policy user. Then, you have to make sure that the function will take a user binary and a host binary as first parameter of the function. They do not have to be put in the args list in #ejabberd_commands record as the `user policy implicitly expect them.

That's all you need to have commands that can be used in a variety of ways.

Here is a example way to register commands when

start(_Host, _Opts) ->
    ejabberd_commands:register_commands(commands()).

stop(_Host) ->
    ejabberd_commands:unregister_commands(commands()).

%%%
%%% Register commands
%%%

commands() ->
    [#ejabberd_commands{name = user_get_roster,
                        tags = [roster],
                        desc = "Retrieve the roster",
                        longdesc =
                            "Returns a list of the contacts in a "
                            "user roster.\n\nAlso returns the state "
                            "of the contact subscription. Subscription "
                            "can be either  \"none\", \"from\", \"to\", "
                            "\"both\". Pending can be \"in\", \"out\" "
                            "or \"none\".",
                        module = ?MODULE, function = get_roster,
                        args = [],
                        policy = user,
                        result =
                            {contacts,
                             {list,
                              {contact,
                               {tuple,
                                [{jid, string},
                                 {groups, {list, {group, string}}},
                                 {nick, string}, {subscription, string},
                                 {pending, string}]}}}}}
        ].