[Spice-commits] docs/Makefile.am docs/meson.build docs/spice_uri_scheme.txt

[GitLab Mirror]

 docs/Makefile.am          |    1 
 docs/meson.build          |    2 
 docs/spice_uri_scheme.txt |  131 ++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 133 insertions(+), 1 deletion(-)

New commits:
commit c5e7d92dc60685dd07f68cf7627ca27bbce79f12
Author: Marc-André Lureau <marcandre.lureau at redhat.com>
Date:   Fri Jan 11 23:07:14 2019 +0400

    docs: add spice URI scheme
    
    Signed-off-by: Marc-André Lureau <marcandre.lureau at redhat.com>
    Acked-by: Christophe Fergeau <cfergeau at redhat.com>

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 at .html',
diff --git a/docs/spice_uri_scheme.txt b/docs/spice_uri_scheme.txt
new file mode 100644
index 0000000..350a062
--- /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&param2=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 UTF8-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.