From: Marc-André Lureau <marcandre.lureau@xxxxxxxxxx>
Signed-off-by: Marc-André Lureau <marcandre.lureau@xxxxxxxxxx>
---
docs/Makefile.am | 1 +
docs/meson.build | 2 +-
docs/spice_uri_scheme.txt | 131 ++++++++++++++++++++++++++++++++++++++
3 files changed, 133 insertions(+), 1 deletion(-)
create mode 100644 docs/spice_uri_scheme.txt
diff --git a/docs/Makefile.am b/docs/Makefile.am
index e7e126b..6f7a0ac 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -3,6 +3,7 @@ CLEANFILES =
ASCIIDOC_FILES = \
spice_protocol.txt \
+ spice_uri_scheme.txt \
$(NULL)
ASCIIDOC_FLAGS = -n -a icons -a toc
diff --git a/docs/meson.build b/docs/meson.build
index 8901762..51a10c3 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -1,7 +1,7 @@
if get_option('manual')
asciidoc = find_program('asciidoc', required : false)
if asciidoc.found()
- foreach f: ['spice_protocol.txt']
+ foreach f: ['spice_protocol.txt', 'spice_uri_scheme.txt']
custom_target('HTML for @0@'.format(f),
input : f,
output : '@BASENAME@.html',
diff --git a/docs/spice_uri_scheme.txt b/docs/spice_uri_scheme.txt
new file mode 100644
index 0000000..0e4bcf9
--- /dev/null
+++ b/docs/spice_uri_scheme.txt
@@ -0,0 +1,131 @@
+The "spice" URI scheme
+======================
+
+This document is inspired by 'The "vnc" URI Scheme' (rfc7869) and
+attempts to document a standard Spice URI scheme.
+
+The normative syntax of the Spice URI is defined in the <spice-uri>
+rule in the following syntax specification. This specification
+uses the Augmented Backus-Naur Form (ABNF) as described in
+[RFC5234]. The Spice URI conforms to the generic URI syntax
+specified in [RFC3986]. The <userinfo>, <host>, <port>,
+<unreserved>, and <pct-encoded> rules are defined in [RFC3986].
+
+ spice-uri = spice-scheme "://" [ userinfo "@" ] [ host [ ":" port ] ]
+ [ "?" [ spice-params ] ]
+
+ spice-scheme = "spice" / "spice+unix" / "spice+tls"
+
+ spice-params = param "=" value *("&" param "=" value) ["&"]
+
+ param = 1*( param-char )
+
+ value = *( param-char )
+
+ param-char = unreserved / pct-encoded / unreserved-symbols
+
+ unreserved-symbols = ":" / "/" / "@" / "!" / "$" / "'"
+ / "(" / ")" / "*" / "," / ";"
+
+The "?", "=", and "&" characters are used to delimit Spice parameters
+and must be percent-encoded when representing a data octet as
+specified in [RFC3986]. Within the <spice-params> portion of a Spice
+URI, the <unreserved-symbols> do not have special meaning and need not
+be percent-encoded when representing a data octet.
+
+A Spice URI has the general form:
+
+ spice-scheme://host:port?param1=value1¶m2=value2...
+
+The host information and each parameter value specify information
+used in establishing or operating the remote desktop session as
+specified in Section "URI Parameters".
+
+URI Parameters
+--------------
+
+A description of host information and URI parameters is provided in
+this section. Information on the constraints of various data types is
+provided in Section "Data Types". All parameters are considered optional;
+however, a client will not be able to connect without sufficient
+information.
+
+A parameter without a specified default value indicates that no
+default value is implied by this URI scheme; however, Spice clients
+can apply implementation-dependent default behaviors otherwise
+consistent with this document.
+
+The <host> and <port> values in the "spice://" and "spice+tls://" URIs
+specify the address of the Spice server on the remote host:
+
+[options="header"]
+|=======================================================================
+| Name | Type | Description | Default
+| host | string | Spice server hostname or IP | none
+| port | ushort | Spice server port | none
+|=======================================================================
+
+The <host> value in the "spice+unix://" URI specify the UNIX domain
+socket path of the Spice server on the local host:
+
+[options="header"]
+|=======================================================================
+| Name | Type | Description | Default
+| host | string | UNIX domain socket path | none
+|=======================================================================
+
+The Spice URI parameter values specify remote desktop connection or
+session properties, including aspects of client operation, usability,
+and security as specified in the table below:
+
+[options="header"]
+|=======================================================================
+| Name | Type | Description | Default
+| port | ushort | Spice server port (legacy) | none
+| tls-port | ushort | Spice server TLS port (legacy) | none
+| password | string | Spice server password (legacy) | none
+| ... | | |
+|=======================================================================
+
+Parameter names SHOULD be provided in the case specified in this
+document; however, for compatibility, clients SHOULD accept
+parameters in a case-insensitive manner. Values SHALL be interpreted
+in a case-sensitive manner, unless otherwise noted.
+
+Additional parameters likely to be useful with multiple Spice clients
+can be added to the "URI Parameters" registry (at the moment,
+discussed and approved on the Spice mailing list). Individual clients
+MAY support parameters specific to that client. Spice clients
+supporting application-specific parameters SHOULD include a
+distinguishing prefix within the parameter name, such as the name of
+the application package specified in source code except when precluded
+by compatibility constraints. For example:
+
+ spice://?com.redhat.spiceclient.MonitorMapping=2&
+
+It can also be expected that clients will maintain backward
+compatibility with legacy URI formats and parameters.
+
+Legacy software applications respond to "spice" URIs in different ways
+and may fail to behave as expected. It is advisable to test "spice"
+URIs with specific applications or consult application-specific
+documentation.
+
+Data Types
+----------
+
+Spice URIs can be percent-encoded as specified in [RFC3986] and MUST
+be decoded. After decoding, the following type constraints and
+semantics apply:
+
+string
+~~~~~~
+
+Values of "string" type are UTF-encoded strings as specified in
+[RFC3629].
+
+ushort
+~~~~~~
+
+The "ushort" values represent unsigned 16-bit integers expressed
+in decimal digits with value between 0-65535 inclusive.
--
2.20.1.98.gecbdaf0899
_______________________________________________
Spice-devel mailing list
Spice-devel@xxxxxxxxxxxxxxxxxxxxx
https://lists.freedesktop.org/mailman/listinfo/spice-devel