Page 1 of 1

URI form extension

Posted: 10 Aug 2009, 22:35
by Pretorian
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...")

Re: URI form extension

Posted: 11 Aug 2009, 07:32
by Pietry
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.