# `./fio-stl/002 url.h`

7 public symbols.

### Macros

#### `FIO_URL_QUERY_EACH`

```c
#define FIO_URL_QUERY_EACH(query_buf, i)   \
  for (fio_url_query_each_s i = fio_url_query_each_next(   \
           (fio_url_query_each_s){.private___ = (query_buf)});   \
       i.name.buf;   \
       i = fio_url_query_each_next(i))
```

Iterates through each of the query elements.

_Symbol type:_ `macro`

### Types

#### `fio_url_s`

```c
typedef struct {
fio_buf_info_s scheme;
fio_buf_info_s user;
fio_buf_info_s password;
fio_buf_info_s host;
fio_buf_info_s port;
fio_buf_info_s path;
fio_buf_info_s query;
fio_buf_info_s target;
} fio_url_s
```

the result returned by `fio_url_parse`

_Symbol type:_ `type`

#### `fio_url_query_each_s`

```c
typedef struct {
fio_buf_info_s name;
fio_buf_info_s value;
fio_buf_info_s private___;
} fio_url_query_each_s
```

The type used by the `FIO_URL_QUERY_EACH` iterator macro.

_Symbol type:_ `type`

#### `fio_url_tls_info_s`

```c
typedef struct {
fio_buf_info_s key;
fio_buf_info_s cert;
fio_buf_info_s trust;
fio_buf_info_s pass;
bool tls;
} fio_url_tls_info_s
```



_Symbol type:_ `type`

### Functions

#### `fio_url_parse`

```c
fio_url_s fio_url_parse(const char *url, size_t len)
```

Parses the URI returning it's components and their lengths (no decoding
performed, doesn't accept decoded URIs).

The returned string are NOT NUL terminated, they are merely locations within
the original string.

This function attempts to accept many different formats, including any of the
following:

* `/complete_path?query#target`

  i.e.: /index.html?page=1#list

* `host:port/complete_path?query#target`

  i.e.:
     example.com
     example.com:8080
     example.com/index.html
     example.com:8080/index.html
     example.com:8080/index.html?key=val#target

* `user:password@host:port/path?query#target`

  i.e.: user:1234@example.com:8080/index.html

* `username[:password]@host[:port][...]`

  i.e.: john:1234@example.com

* `schema://user:password@host:port/path?query#target`

  i.e.: http://example.com/index.html?page=1#list

For performance reasons, no format validation is performed. Function assumes
that the `url` string is `len` long and contains a valid URL. Invalid formats
might produce unexpected results.

NOTE: the `unix`, `file` and `priv` schemas are reserved for file paths.

_Symbol type:_ `function`

#### `fio_url_query_each_next`

```c
FIO_SFUNC fio_url_query_each_s fio_url_query_each_next(fio_url_query_each_s)
```

A helper function for the `FIO_URL_QUERY_EACH` macro implementation.

_Symbol type:_ `function`

#### `fio_url_is_tls`

```c
fio_url_tls_info_s fio_url_is_tls(fio_url_s u)
```

Returns TLS data associated with the URL.

This function supports implicit TLS by scheme data for the following possible
values:

- `wss`   - Secure WebSockets.
- `sses`  - Secure SSE (Server Sent Events).
- `https` - Secure HTTP.
- `tcps`  - Secure TCP/IP.
- `tls`   - Secure TCP/IP.
- `udps`  - Secure UDP.

i.e.:
    tls://example.com/
    tcps://example.com/
    udps://example.com/

    wss://example.com/
    https://example.com/
    sses://example.com/

This function also supports explicit TLS by query data for the following
possible key-pair values:

- `tls`                   - self-signed TLS (unless key / cert are provided).
- `tls=true`              - self-signed TLS (unless key / cert are provided).
- `tls=<file>`            - key and certificate files (same path, different
                            file extensions).
- `key=<file/env_data>`   - path or env variable name for the private key.
- `cert=<file/env_data>`  - path or env variable name for the public
                            certificate.

- `pass`                  - password for decrypting key / cert data.

i.e.:

    tcp://example.com/?tls          (anonymous TLS)
    udp://example.com/?tls=true

    https://example.com/?tls=key_cert_folder_or_prefix&pass=key_password

    https://example.com/?key=key_file_or_env_var&cert=cert_file_or_env_var&pass=key_password
    wss://example.com/?key=key_file_or_env_var&cert=cert_file_or_env_var&pass=key_password
    tcp://example.com/?key=key_file_or_env_var&cert=cert_file_or_env_var&pass=key_password

_Symbol type:_ `function`

-----------------------------------------------------