UCMD - User Commands

From ADCPortal Wiki

General

User commands are used to send hub-specific commands to the client which provide useful shortcuts for the user. These commands contain strings which must be sent back to the hub and keyword substitutions in the strings. Each user command has a display name, a string to be sent to the hub, and one or more categories where it may appear. The strings passed to the hub must first be passed through a dictionary replacement that replaces all keywords in the string and then through the equivalent of the C standard function "strftime", with the current time.

Changes to the protocol

CMD

   CMD name

Context: F

Name uniquely (per hub) identifies a particular user command. The name may contain "/" to indicate a logical structure on the viewing client, where each "/" introduces a new submenu level. Other than name, the command also has a number of flags that further detail what to do with it.

RM | 1 = Remove command 

CT | Message category, 
 1 = Hub command, client parameters only, 
 2 = User list command, client and user parameters, 
 4 = Search result command, client, user and file parameters, 
 8 = File list command, client, user and file parameters. 
Multiple categories are specified by adding the numbers together. 

TT | The full text to be sent to hub, including FOURCC, parameters and keywords.

CO | 1 = Constrained, when sending this command on multiple users (for example in search results), constrain it to once per CID only 

SP | 1 = Insert separator instead of command name (name must still be present to uniquely identify the command).

Keywords are specified using "%[keyword]". Unknown keywords must be replaced by the empty string. Additionally, all %-substitutions of the C function "strftime" must be supported.

The following tables specify the keywords that must be supported.

Client parameters

myCID | Client CID 
mySID | Client SID 
myXX | One for each flag on that particular hub; for example, myI4 and myNI

User parameters

userCID | User CID
userSID | SID of the user 
userXX | One for each flag the user sent; for example, userI4 and userNI

File parameters

fileXX | One for each flag contained within a search result or file list entry (see RES)
fileMN | Specify magnet link. Magnet links are used to reference files across networks and applications. 
         Clients may ignore parameters it does not understand, but are free to pass on the parameters to other programs.

Hub parameters

hubXX | One for each flag of the hub; for example, hubNI and hubVE

The following tables specify the keywords that are optional.

User parameters

line:info | Prompts the user for input where info is the displayed text description for the user input. info can be used for 
            multiple values (combobox etc), and should be structured as "general info/default selection/value0/value1/…/valueN". 
            The general info can be viewed as the caption of the user input dialog. Default selection is an integer k which signifies 
            the default value to be used. Note that N >= k >= 0 and N >= 1. Note that values are 0-index based. Values are separated 
            with a forward slash (/). If a forward slash is part of a value, it should be escaped by using an additional forward slash (//).

Example

Here are some examples of UCMD commands sent by the hub to the client:

 ICMD ADCH++/Hub\smanagement/Register\snick TTHMSG\s+regnick\\s%[userNI]\\s%[line:Password\\s(leave\\sempty\\sto\\sun-reg)]\\s%[line:Level\\s(facultative;\\sdefaults\\sto\\syour\\sown\\slevel\\sminus\\sone)]\n CT2
 ICMD ADCH++/Hub\smanagement/Reload\sbans TTHMSG\s+loadbans\n CT3
 ICMD ADCH++/Hub\smanagement/Reload\sscripts TTHMSG\s+reload\n CT3
 ICMD ADCH++/Info TTHMSG\s+info\\s%[userNI]\n CT2
 ICMD ADCH++/Info TTHMSG\s+info\n CT1

See Also