URI form extension

Ideas for ADC may be presented here for others to review and point out flaws or further improve the idea.
Forum rules
If you have an account on the wiki, remember to update the ADC Proposals page for new ideas.

http://dcbase.org/wiki/ADC_Proposals_list
Locked
Pretorian
Site Admin
Posts: 214
Joined: 21 Jul 2009, 10:21

URI form extension

Post by Pretorian » 10 Aug 2009, 22:35

The following is a suggestion for extending the current URI form to be more complex and handle more use cases. There is a suggestion to use static URLs to simplify "common tasks". However, the following will NOT outline anything such.

The URI form allowed for hub addresses is "adc://server:port/", with the potential ADCS variant using adcs instead of adc. However, while this may be sufficient for most uses, there are a few potential other uses;
  • Ability to add user to queue.
    Ability to add file (with appropriate hash) to download queue.
    Ability to reference the sending address (similar to advertisement click references).
    Ability to set per-hub settings.
    Ability to send messages (MSG or any other) as default entry message. (Basic request to perform some action - possibly registration; see below).
    Ability to integrate hub with other systems, allowing users to have only one login data for e.g. hub, forum, wiki etc.
As described above, there are a few use cases. This extension may NOT cover them all; use other extensions for that or extend this extension.

This extension will NOT add an additonal URI but extend the present one(s). If a client does not understand part of the URI, it shall attempt to reduce the URI to a form it can understand, where the last deductable form is as described in BASE. There is no case-sensitivity unless otherwise noted. There are three main concepts in the extension URI; ACTION, QUERY (consisting of parameter and value) and ADDITONAL. All escape sequences shall use ADC BASE with additional exceptions; "?", "=", "#" and ";", as they are part of the URI. QUERY and ADDITIONAL need not be present.

Full URI example:
adc://server:port/action[?parameter=value[#additional]][;action?parameter=value#additional]
or
adc://example.com:80/usermessage?name=john#Hi\sJohn!

ACTION
The ACTION shall be used as the main command or action to be taken. An action can be combined with other actions by adding a semi-colon and starting a new sequence after the old action, where there is no final level.

Actions:
  • file - Specifying that the action will have to do with files.
    filesearch - Search for a file.
    filequeue - Add file to the client's download queue.
    user - Specifying that the action will have to do with (other) users.
    userqueue - Add user's file list to queue.
    usermessage - Send user a private message.
    hubinfo - Specifying that the action will be information that the hub may be interested in (or otherwise hub related info).
    userinfo - Specifying that the action will be information that the client will send about itself (or otherwise client [re-]configuration).
QUERY
The QUERY shall be used as the parameter driven part of the URI. A QUERY is in the form of parameter=value. QUERYs shall NOT be combined. A QUERY parameter depend on the context it is given in; that means a parameter named "name" does not mean that same in a filesearch action as it does in a usermessage action.

QUERY parameters and potential values:
  • name
    • File path.
      File name.
      Nick-name.
    hash
    • Type of hash algorithm (TTH, SHA1 etc). The same as in BASE GET command etc.]
    type
    • Type of file;
      audio
      video
      document
      executable
      compressed
      picture
      directory
    cid
    • CID of user.
    referrer
    • Referring URL. Note that if the referring URL comes from a secure environment, this should not be present when sending to the hub.
    data
    • Arbitrary data.
    request
    • Request to perform below action;
      register - A request to register the user in the hub.
      unregister - A request to unregister the user in the hub.
      addtofavorite - A request to add the hub as favorite.


ADDITIONAL
The ADDITIONAL shall be used if the QUERY parameter and value pair is not explicit enough to specify an action the client or hub shall take. ADDITIONAL can therefore be seen as an extension on the QUERY parameter and value pair but must not be used interchangeably without explicit note that it is valid. ADDITIONAL shall be treated as a data stream that shall be interpreted depending on context. Therefore, it is not possible to list all potential ADDITIONAL values, but rather suggestions are given below.

ADDITIONAL potential values:
  • Message data ("name=john#Hi\sJohn!")
    Hash data ("hash=TTH#AAAAAA...")

Pietry
Senior Member
Posts: 328
Joined: 04 Dec 2007, 07:25
Location: Bucharest
Contact:

Re: URI form extension

Post by Pietry » 11 Aug 2009, 07:32

Interesting extension but I don't see much functionality for it , at least now. Perhaps in the future when clients will implement it, we will see some real usage. I think I saw some other request for URIs parameters on some hub or forum but I'm not sure, perhaps the ones in question can add their ideas to this thread.
Just someone

Locked