urls.md 1.69 KB
Newer Older
Ticki's avatar
Ticki committed
1
2
3
URLs
====

Elijah Caine's avatar
Elijah Caine committed
4
The URL _itself_ is a relatively uninteresting (yet very important) notion for the design of Redox. The interesting part is what it represents.
Ticki's avatar
Ticki committed
5
6
7
8

The URL
-------

adrian5's avatar
adrian5 committed
9
In short, a URL is an identifier of a resource. It contains two parts:
Ticki's avatar
Ticki committed
10

Elijah Caine's avatar
Elijah Caine committed
11
1. The scheme part. This represents the "receiver", i.e. what scheme will handle the (F)OPEN call. This can be any arbitrary UTF-8 string, and will often simply be the name of your protocol.
Ticki's avatar
Ticki committed
12

Elijah Caine's avatar
Elijah Caine committed
13
2. The reference part. This represents the "payload" of the URL, namely what the URL refers to. Consider `file`, as an example. A URL starting with `file:` simply has a reference which is a path to a file. The reference can be any arbitrary byte string. The parsing, interpretation, and storage of the reference is left to the scheme. For this reason, it is not required to be a tree-like structure.
Ticki's avatar
Ticki committed
14
15
16
17
18
19
20

So, the string representation of an URL looks like:

```
[scheme]:[reference]
```

Elijah Caine's avatar
Elijah Caine committed
21
22
23
24
25
26
For example:

```
file:/path/to/myfile
```

Ticki's avatar
Ticki committed
27
28
Note that `//` is not required, for convenience.

29
30
Opening a URL
-------------
Ticki's avatar
Ticki committed
31

Elijah Caine's avatar
Elijah Caine committed
32
URLs can be opened, yielding _schemes_, which can be opened to resources, which can be read, written and (for some resources) seeked (there are more operations which are described later on).
Ticki's avatar
Ticki committed
33

34
For compatibility reasons, we use a file API similar to the Rust standard library's for opening URLs:
Ticki's avatar
Ticki committed
35

36
```rust
Ticki's avatar
Ticki committed
37
38
39
40
41
42
43
44
45
46
47
48
49
use std::fs::OpenOptions;
use std::io::prelude::*;


fn main() {
    // Let's read from a TCP stream
    let tcp = OpenOptions::new()
                .read(true) // readable
                .write(true) // writable
                .open("tcp:0.0.0.0");
}
```

Ticki's avatar
Ticki committed
50
> TODO: Maybe do something with the tcp stream. Ping-pong?
Ticki's avatar
Ticki committed
51

Ticki's avatar
Ticki committed
52
> TODO: The terminology may be somewhat confusing for the reader.