$UserCommand

From DCppWiki

Jump to: navigation, search

The $UserCommand command is used by hubs to put commands into the users context menu.

Contents

Syntax

$UserCommand <type> <context> <details>|
  • <type> is a positive integer describing the kind of command, where:
    • 0 = separator
    • 1 = raw
    • 2 = raw-nick-limited (same as raw with the exception that it should only be used once per %[nick])
    • 255 = erase all sent commands
  • <context> is sent as an integer, but is derived by logical or'ing the following values together. This number controls which contexts the menus will be shown in:
    • 0x01 = Hub context (available in DC++ when clicking on the hub's tab)
      • Example: view hub rules, change password
      • This command should contain no 'somenick' arguments (i.e. not %[nick] but it may contain %[mynick] or %[line:blah]).
    • 0x02 = User context (generally available in DC++ when clicking on a user's nick)
      • Example: show users's statistics, ban user
      • This command may take nick-specific arguments.
    • 0x04 = Search context
      • Example: report "bad" file in search results
      • This command may take nick and file-specific arguments.
    • 0x08 = Filelist command
      • Example: report a bad file found then browsing a user's list
      • This command may take nick and file-specific arguments.
      • Note: this context is new in DC++ 0.669
  • <details> differs per <type>
    • type 0 (separator) and 255 (erase) leave this field empty
    • type 1 (raw) uses <title>$<command> for the command title and the command itself
      • Furthermore, clients MAY support sub-menus using the backslash ('\') in <title>, like: <menuname>\<title>. This scheme could also be used to create sub-sub-sub-menus.

Higher numbers are reserved for future use.

Escaping

Escaping of dollar and pipe is necessary for the <command> in 'raw' mode. The DC++ escape sequence will be used. i.e. &#124; for pipe, &#36; for dollar and &amp; for the ampersand.

Escaping is used for all fields before they are sent to the hub / shown to the user.

As with all NMDC commands, they must be terminated by the pipe character.

Contexts

The context number is a binary flag that can be combined with other numbers, i.e. a user command shown in chat and search has number (2 | 4 = 6).

Details

Separator

$UserCommand 0 <context> |

Will add a menu separator (vertical bar) to the specified contexts (<context>). It is legal to add text (after the space) before the pipe, but it won't be used (yet).

Raw

$UserCommand 1 <context> <title>$<raw>|

Will add a raw menu item with title <title> with command <raw>. This command must end with a |, if not it should be discarded. The raw command may be used to specify multiple commands to be sent to the hub.

Raw-Nick-Limited

$UserCommand 2 <context> <title>$<raw>|

Is exactly the same as Raw, except that the command should only be run once per %[nick]. This is to prevent the client from sending out more than one message that disconnects someone. Generally, this is only useful in the User-File context (e.g. viewing Search Results) where it is possible to select one user multiple times.

Erase

$UserCommand 255 <context> |

Will erase all commands that the hub has sent previously. This is for hubs/scripts that allow for updates while running. The erase all is intentional, keeping it simple. Note that contexts must still be used, and that erasing will remove all commands that match any of those ORed contexts (i.e. 7 will remove commands previously sent with any context of 1 through 7) but only from that context

Examples

$UserCommand 2 6 Kick$&#36;To: %[nick] From: %[mynick] &#36;<%[mynick]> You are being kicked====&#124;&#36;Kick %[nick]&#124;|

This sends a PM with "You are being kicked====" to nick, and sends the $Kick command, shows up in search and chat, uses Raw-Nick-Limited to prevent multiple (redundant) kicks of one user

$UserCommand 255 1 |

This removes all commands in the hub context, also removing those that were sent with any mask which included the hub context, from the hub context commands. i.e., if you had some-command with context 7, you now have some-command with context 6