docs/dc3.txt

   1
   2
   3
   4
   5
   6
   7
   8   This document explains how to write an interface for DCPlus 3.0. DCPlus version
   9    3 has a seperate communications interface for server to client and client to
  10    client communications and should act as a object oriented environment.
  11   Objects are represented by a single character representing the object class and
  12    the object identifier. If the hub supports DCPlus 3.0, it represents itself
  13    as M:local or M:me. For backward compatibility purposes, it is recommended
  14    that most clients use M:me.
  15   Hubs with DCPlus 3.0 support MUST send this command when a user connects or
  16
  17    sends $GetNickList:
  18     $Hello $DCPlus|
  19   If a hub previously did NOT have DCPlus support and wishes to enable it, the
  20    hub should send all clients the above command also.
  21   If a hub previously had DCPlus 3.0 support and wishes to disable it, it must
  22    send to all clients:
  23     $Quit $DCPlus|
  24   A hub may choose to disable DCPlus support for users who are not using DCPlus
  25    3.0 compatible clients. In no case should a hub initialize a conversation with
  26    a client which does not support DCPlus 3.0.
  27
  28
  29   Clients which support DCPlus 3.0 are represented by U: plus the username that
  30    the client is logged onto the current hub as. To enable DCPlus 3.0, a client
  31    must set Bit 4 (1-based) in the connection flag byte. This can easilly be
  32    accomplished by applying an OR 0x10 operation to the normal connection flag
  33    byte. For informational purposes, the connection flag byte referred to here is
  34    located at the * in the following command:
  35     $MyINFO $ALL bakanick nothin$ $Magic Wire*$$0$|
  36
  37   For a hub to send a command to a client, it should format it as seen below:
  38     $To: ClientsUsername From: $DCPlus $<$DCPlus> Command-And-Parameters|
  39   For a client to send a command to the hub, it should format it as seen below:
  40
  41     $To: $DCPlus From: ClientsUsername $<ClientsUsername> Command-And-Parameters|
  42   For a client to send a command to another client, it should send to the hub:
  43     $To: OtherClientUsername From: ClientsUsername $<ClientsUsername> *Cmd&Params|
  44   In the above line, the client MUST replace * with ASCII character code number 4.
  45    If a user on the client wishes to PM a message starting with a real character
  46    number 4 in a message, the client should escape it with a \ (only if dest
  47    user is DCPlus 3). Therefore when a message starting with \* (*=asc chr 4) is
  48    received from a DCPlus 3 client, it should remove the \ from the start of the
  49    message.
  50
  51   For a DCPlus supporting client to send a command to ALL DCPlus users, they
  52
  53    should use the following command:
  54     $Search 0:0 F*?F*?0*?9*?DCPlus/Command-And-Parameters|
  55
  56   For certain commands which can be sent via "SR UDP", they must be sent in the
  57    following command:
  58     $DCPlus Command-And-Parameters|
  59
  60   Parameters are a single word long. To include spaces in a parameter, the entire
  61    parameter must be enclosed in double quotes ("). Double quote and backslash
  62    characters within an enclosed parameter must be escaped by a backslash. For
  63    example: \" or \\
  64
  65   Below, <A> to <Z> are required arguments, [A] to [Z] are optional arguments,
  66    and [@] refers to whatever extra data is there.
  67   *in the case of a $Search usage, the $Search command may specific values for
  68    'maxsize', 'minsize', and 'filetype'.
  69
  70   Hub to Client commands are:
  71     SetOption ReserveSlots <A> [B]
  72       <A> is the number of slots to reserve for users on this hub. Reply via
  73        OptionSet required. [B] is response code.
  74     SetOption DisCloseDownload <A> [B]
  75       If <A> is non-zero then the client should close all downloads from users
  76
  77        in the current hub when the user leaves that hub. For example, if UserA
  78        downloads from UserB in HubB and then leaves HubB, UserA's download is
  79        cut. If <A> is a non-negative number, the client may wait <A> minutes
  80        before cutting the downloads. Reply via OptionSet required. [B] is
  81        response code.
  82     Error <A> [@]
  83       <A> is the command that caused the error. If present, [@] has more
  84        details.
  85     UserIP <A> <B> [C]
  86       Informs the client that <B> is the IP of <A>. [C] is a flag set by the
  87        request command.
  88
  89     Success <A> [@]
  90       <A> is the command that succeeded and [@] might have more details.
  91     GotProp <A> <B> <C>
  92       Optional backward compatibility for DCPlus 2.0. See 2.0 docs for details.
  93     CmdOk [@] [@] [...]
  94       Arguments are a list of supported (or unsupported) commands. Supported
  95        commands should be prefixed with a + and unsupported by a -.
  96     PageCount <A>
  97       <A> is the number of pages waiting for the client's username
  98     PageMsg <A> <@>
  99       <A> is the user who the page is from and <@> is the page message.
 100
 101     HelpStart <A> <B>
 102       <A> is the page id code and <B> is the response code.
 103     HelpData <A> <B>
 104       <A> is the response code and <B> is the line of data.
 105     HelpEnd <A>
 106       <A> is the response code.
 107     Ping [A]
 108       [A] is the response code. A reply should be sent back via Pong ASAP.
 109     Pong [A]
 110       [A] is the response code. This should be sent when a Ping is received.
 111     Cmd [@] [@] [...]
 112
 113       Arguments are specific commands to check for. If none are present, a full
 114        list of supported commands is returned. Reply is via CmdOk reply.
 115     RegisterOk <A>
 116       <A> is the response code. This is a reply to RegisterNick.
 117     RegisterDenied <A>
 118       <A> is the response code. This is similar to a permission denied for
 119        RegisterNick.
 120     OptionSet <A> [B] <C>
 121       <A> is the option that was set. [B] is the new value. <C> is replycode
 122     ListOptions [A] [@] [@] [...]
 123       [A] is a reply code. The arguments are what commands to look for. If no
 124
 125        arguments (besides [A]), all commands will be returned.
 126     OptionList [A] [@] [@] [...]
 127       [A] is a reply code. The arguments are the options supported. If an
 128        option is listed but not supported, it should appear in brackets ('[]')
 129   Client to Hub Commands are:
 130     GetIP [@] [@] [...]
 131       Arguments are the usernames to get the IPs of. Result is sent back via
 132        UserIP responses.
 133     GetIP+ [A] [@] [@] [...]
 134       Arguments are the usernames to get the IPs of. Result is sent back via
 135        UserIP responses. [A] is the response code.
 136
 137     Boot [@] [@] [...]
 138       Arguments are the usernames to boot. There is no reply.
 139     BanMAC <A>
 140       <A> is the MAC address to ban. There is no reply.
 141     UnBanMAC [A] [@] [@] [...]
 142       [A] is the response code. The arguments after it are MACs to unban. There
 143        should be a 'Success/Error UnBanMAC [A]' reply.
 144     BanIP <A>
 145       <A> is the IP address to ban. There is no reply.
 146     UnBanIP [A] [@] [@] [...]
 147       [A] is the response code. The arguments after it are IPs to unban. There
 148
 149        should be a 'Success/Error UnBanIP [A]' reply.
 150     Kick <A>
 151       <A> is the user to kick. There is no reply.
 152     TempBanIP <A>
 153       <A> is the IP address to temp ban. There is no reply.
 154     UnTempBanIP [A] [@] [@] [...]
 155       [A] is the response code. The arguments after it are IPs to un temp ban.
 156        There should be a 'Success/Error UnTempBanIP [A]' reply.
 157     BanName [@] [@] [...]
 158       Arguments are usernames to ban usage of. There is no reply.
 159     UnBanName [A] [@] [@] [...]
 160
 161       [A] is the response code. The arguments after it are names to unban. There
 162        should be a 'Success/Error UnBanName [A]' reply.
 163     Ban <A>
 164       <A> is the username of the user to ban (in any method). There is no reply
 165     GetProp <A> <B>
 166       Optional backward compatibility for DCPlus 2.0. See 2.0 docs for details.
 167     PutProp <A> <B> <C>
 168       Optional backward compatibility for DCPlus 2.0. See 2.0 docs for details.
 169     AppProp <A> <B> <C>
 170       Optional backward compatibility for DCPlus 2.0. See 2.0 docs for details.
 171     RitProp <A> <B> <C>
 172
 173       Optional backward compatibility for DCPlus 2.0. See 2.0 docs for details.
 174     Cmd [@] [@] [...]
 175       Arguments are specific commands to check for. If none are present, a full
 176        list of supported commands is returned. Reply is via CmdOk reply.
 177     MassMsg [@]
 178       [@] is the message to mass-announce. No reply.
 179     SendPage <A> [@]
 180       <A> is the user to send a page to. [@] is the message.
 181     GetPage [A]
 182       [A] is the message number to retrieve. If present, message is sent to
 183        client via PageMsg reply and the message is deleted from the hub. If
 184
 185        not, number of messages is sent to client via PageCount reply.
 186     PeekPage <A>
 187       <A> is the message number to retrieve. Message should be sent via PageMsg
 188        reply and the message SHOULD NOT BE DELETED FROM HUB.
 189     HelpOn <A> [B]
 190       <A> is the help id code. If present, [B] is the response code.
 191     Ping [A]
 192       [A] is the response code. A reply should be sent back via Pong ASAP.
 193     Pong [A]
 194       [A] is the response code. This should be sent when a Ping is received.
 195     OptionSet <A> [B] <C>
 196
 197       <A> is the option which was set correctly. <B> is the new value. This is
 198        a reply to the SetOption command.
 199     CmdOk [@] [@] [...]
 200       Arguments are a list of supported (or unsupported) commands. Supported
 201        commands should be prefixed with a + and unsupported by a -.
 202     RegisterNick <A> <B>
 203       <A> is the password to register the nickname with. <B> is a response code
 204     SetOption Topic <A> [B]
 205       <A> is the new hub topic/name. [B] is response code.
 206     SetOption Chat.<A> <B> [C]
 207       <A> is the username of the client to affect. If <B> is zero, chat
 208
 209        messages should no longer be sent to the client. [C] is the response
 210        code. 'SetOption Chat <B> [C]' affects the client sending the command
 211     SetOption Userlist.<A> <B> [C]
 212       <A> is the username of the client to affect. If <B> is zero, userlist
 213        updates should no longer be sent to the client. [C] is the response
 214        code. 'SetOption Userlist <B> [C]' affects the client sending command
 215     SetOption Search.<A> <B> [C]
 216       <A> is the username of the client to affect. If <B> is zero, searches
 217        should no longer be sent to the client. [C] is the response code.
 218        'SetOption Search <B> [C]' affects the client sending the command
 219       Note: It is recommended that hubs put bot restrictions on this.
 220
 221     SetOption Visible.<A> <B> [C]
 222       <A> is the username of the client to affect. If <B> is non-zero, then
 223        user should be kept off the userlist. [C] is the response code.
 224        'SetOption Visible <B> [C]' affects the client sending the command
 225       Note: It is recommended that hubs put bot restrictions on this.
 226     SetOption BlockConnects.<A> <B> [C]
 227       <A> is the username of the client to affect. If <B> is non-zero, then
 228        hub should prevent [Rev]ConnectToMe commands from reaching the client.
 229        [C] is the response code. 'SetOption BlockConnects <B> [C]' affects
 230        the client sending the command
 231       Note: It is recommended that hubs put bot restrictions on this.
 232
 233     ListOptions [A] [@] [@] [...]
 234       [A] is a reply code. The arguments are what commands to look for. If no
 235        arguments (besides [A]), all commands will be returned.
 236     OptionList [A] [@] [@] [...]
 237       [A] is a reply code. The arguments are the options supported. If an
 238        option is listed but not supported, it should appear in braces ('{}')
 239   Client to Client commands are:
 240     Ping [A]
 241       [A] is the response code. A reply should be sent back via Pong ASAP.
 242     Pong [A]
 243       [A] is the response code. This should be sent when a Ping is received.
 244
 245     IsPassive [A]
 246       [A] is the response code. The client should reply with MyModeIs.
 247     MyModeIs <A> [B]
 248       If <A> is non-zero, the user is passive. [B] is the response code.
 249     SendFile <A> [B]
 250       <A> is the URI of where the file can be received. [B] = replycode
 251        Example: DC1C://bakausername:apassword@my.hostname.com/folder/file.exe
 252     RefuseURI [B]
 253       [B] is the reply code.
 254     ProtocolOk <A> [B]
 255       <A> is the protocol. [B] is the reply code. Reply via ICProtocol cmd.
 256
 257     ICProtocol <A> <B> [C]
 258       <A> is the protocol. <B> is non-zero if it is supported. [C] is replycode
 259     ProtocolsAre [A]
 260       [A] is the reply code. Response is via ICProtocol command.
 261     ExternChat <A> [B]
 262       <A> is the URI to chat with. [B] is the response code.
 263        Example of <A>: telnet://my.hostname.net:2222
 264     NetGame <A> [B]
 265       <A> is the URI of where to meet for a game. [B] is the response code.
 266        Example of <A>: armagetron://games.secret.com.au/
 267            snes9x://my.hostname.org:1998/
 268
 269     NetApp <A> [B]
 270       <A> is the URI. [B] is the response code.
 271     FindFile <A> <B> [@]/[@]/[...]
 272       <A> is either host:port or "Hub:"+username. <B> is the response code.
 273        [1] is the minimum file size. [2] is the file type (see DC1 protocol
 274        specs for more info). [3] is the maximum file size. The [@] arguments
 275        are sets of option=value. If a client does not recognize an option it
 276        should ignore the FindFile command and NOT continue. If the unrecognized
 277        option is enclosed in braces then the client should ignore the option
 278        and do a Find without it. For example:
 279        'FindFile Hub:baka 0 md5=9291047/{id3v2_title}=sing$filename' would
 280
 281        cause a client to search for a file with 'filename' in the actual
 282        filename and MD5 of '9291047'. If the client understands the
 283        id3v2_title option, it will only return results that match it. If not,
 284        it returns results regardless of the id3v2_title option. If the client
 285        doesn't understand the md5 option it will not search at all and will not
 286        return any search results. See post-command info for standard options.
 287        Note: option and value pairings can be o=v o>v o<v o>=v o<=v or o!=v
 288        Note: option and value names with non-alphanumeric characters must be
 289              escaped with % followed by 2 hex characters.
 290        Note: This command may be sent via SR UDP.
 291     FileFound <A> [B] [@]
 292
 293       <A> is the response code. [B] is detailed information about the file in
 294        option=value format with / as a delimiter. [@] is the data for the SR
 295        standard command. See DC1 protocol specs for more info.
 296        Note: option and value pairings can be o=v o>v o<v o>=v o<=v or o!=v
 297        Note: option and value names with non-alphanumeric characters must be
 298              escaped with % followed by 2 hex characters.
 299        Note: This command may be sent via SR UDP.
 300     PrivMsg [A] <B> [@]
 301       [A] is the host:port of a common hub. This field may be skipped. <B> is
 302        the username who the PrivMsg is sent by. [@] is the actual message.
 303        Note: This command may be sent via SR UDP
 304
 305     ConnectToMe <A> [B] [C]
 306       <A> is host:port of the user. If [B] is present and non-zero, the
 307        sender is the one who will upload. Otherwise, the sender downloads.
 308        If present, [C] is the protocol identifier to use. If not present, the
 309        DC1C protocol will be used. Note: this command may be sent via SR UDP
 310     RevConnectToMe <A> [B]
 311       <A> is the username. Send a ConnectToMe back with a non-zero 2nd argument
 312        If present, [B] is the protocol to use for the connection.
 313     Cmd [@] [@] [...]
 314       Arguments are specific commands to check for. If none are present, a full
 315        list of supported commands is returned. Reply is via CmdOk reply.
 316
 317        Note: this command may be sent via SR UDP
 318     CmdOk [@] [@] [...]
 319       Arguments are a list of supported (or unsupported) commands. Supported
 320        commands should be prefixed with a + and unsupported by a -.
 321        Note: this command may be sent via SR UDP
 322     OptionSet <A> [B] <C>
 323       <A> is the option that was set. [B] is the new value. <C> is replycode
 324     ListOptions [A] [@] [@] [...]
 325       [A] is a reply code. The arguments are what commands to look for. If no
 326        arguments (besides [A]), all commands will be returned.
 327     OptionList [A] [@] [@] [...]
 328
 329       [A] is a reply code. The arguments are the options supported. If an
 330        option is listed but not supported, it should appear in brackets ('[]')
 331     Finger <A> [B] [C]
 332       <A> is a reply code. If present, [B] is the return path for the response.
 333        If present, [C] is a specific FingerInfo name to get: No other fields
 334        should be returned.
 335        Note: this command may be sent via SR UDP
 336     FingerInfo <A> [@]
 337       <A> is a reply code. [@] is the finger data in the format of:
 338        name=value/name=value/n=v/etc (similar to FindFile options)
 339        See below for common FingerInfo names. Note: this command may be sent
 340
 341        via SR UDP
 342
 343   Standard FindFile options:
 344     md5
 345       A MD5 hash of the file.
 346     exactname
 347       Specifies that the filename specified is exact (not within)
 348     id3v2_title
 349       The title of the ID3v2 file
 350     id3v2_copyright
 351       Non-Zero if the ID3v2 file is copyrighted
 352
 353     media_length
 354       Length of WAV/MP3/Video
 355     avi_fourcc
 356       FOURCC code of the AVI video
 357     video_width
 358       Width of the video in pixels
 359     video_height
 360       Height of the video in pixels
 361     video_pixels
 362       Width*Height of the video in pixels
 363     audio_bitrate
 364
 365       Bitrate of audio (kbit/s)
 366     video_bitrate
 367       Bitrate of video (kbit/s)
 368     audio_channels
 369       Number of audio channels (1=Mono; 2=Stereo)
 370     audio_hz
 371       Hz of audio
 372     minsize
 373       Minimum filesize (overrides everything else)
 374     maxsize
 375       Maximum filesize (overrides everything else)
 376
 377     filetype
 378       'audio', 'video', etc (overrides all else)
 379
 380   Standard FingerInfo options:
 381     EMail
 382     IM-Jabber
 383     IM-AIM
 384     IM-ICQ
 385     IM-.NET
 386       Formerly known as MSN
 387     IM-Yahoo
 388
 389       (USA)
 390     IM-YahooJP
 391       (Japan)
 392     URI-Homepage
 393     URI-Link
 394     Birthdate
 395     Comment
 396       (usually the DC 'Content Info' field)
 397     Code-Geek
 398       GeekCode
 399     Code-Moonie
 400
 401       MoonieCode