Rebase

index.bs

@@ -61,6 +61,8 @@ urlPrefix: https://w3c.github.io/remote-playback/#dfn-; type: dfn; spec: REMOTE-
     text: remote playback source
 urlPrefix: https://www.w3.org/TR/html51/single-page.html; type: dfn; spec: HTML51
     text: media element
+url: https://tools.ietf.org/html/rfc6763#section-7; type: dfn; spec: RFC6763; text: service name
+url: https://tools.ietf.org/html/rfc6763#section-4.1.1; type: dfn; spec: RFC6763; text: instance name
 </pre>
 
 <h2 class='no-num no-toc no-ref' id='status'>Status of this document</h2>
@@ -150,7 +152,7 @@ Presentation API Requirements {#requirements-presentation-api}
     by IP multicast.
 
 2.  A controlling user agent must be able to obtain the IPv4 or IPv6 address of
-    the display, a friendly name for the display, and an IP port number for
+    the display, a display name for the display, and an IP port number for
     establishing a network transport to the display.
 
 3.  A controlling user agent must be able to determine if the receiver is
@@ -280,25 +282,43 @@ Non-Functional Requirements {#requirements-non-functional}
 Discovery with mDNS {#discovery}
 ===============================
 
-Agents may discover one another using [[RFC6763|DNS-SD]] over [[RFC6762|mDNS]].
-To do so, agents must use the service name "_openscreen._udp.local".
+Agents must discover one another using [[RFC6763|DNS-SD]] over [[RFC6762|mDNS]].
+To do so, agents must use the [=Service Name=] `_openscreen._udp.local`.
 
 Issue(107): Define suspend and resume behavior for discovery protocol.
 
-Advertising Agents must use an instance name that is a prefix of the agent's
-display name. If the instance name is not the complete display name (if it has
-been truncated), it must be terminated by a null character.  It is prefix so
-that the name displayed to the user pre-verification can be verified later.  It
-is terminated by a null character in the case of truncation so that the
-listening agent knows it has been truncated.  This complexity is necessary to
-all for display names that exceed the size allowed in an instance name and for
-such (possibly  truncated) display names to be visible to the user sooner
-(before a QUIC connection is made).  Listening agents must treat instance names
-as unverified and must verify that the instance name is a prefix of the verified
-display name before showing the user a verified display name.
-
-Agents should use the complete display name to the user rather than a
-truncated display name.
+An <dfn noexport>advertising agent</dfn> is one that responds to mDNS queries
+for `_openscreen._udp.local`.  Such an agent should have a <dfn noexport>display
+name</dfn> (a non-empty string) that is a human readable description of the
+presentation display, e.g. "Living Room TV."
+
+A <dfn noexport>listening agent</dfn> is one that sends mDNS queries for
+`_openscreen._udp.local`.  Listening agents may have a display name.
+
+Advertising agents must use a DNS-SD [=Instance Name=] that is a prefix of the
+agent's display name.  If the Instance Name is not the complete display name, it
+must be terminated by a null (`\000`) character, so that a listening agent knows
+it has been truncated.
+
+Agents must treat Instance Names as unverified information, and should check
+that the Instance Name is a prefix of the display name received through the
+`agent-info` message after a successful QUIC connection.  Once an agent has done
+this check, it can show the name as a <dfn noexport>verified display name</dfn>.
+
+Agents should show only complete display names to the user, instead of truncated
+display names from DNS-SD.  A truncated display name should be verified as above
+before being shown in full as a [=verified display name=].
+
+<div class="note">
+This means there are three categories of display names that agents should be
+capable of handling:
+<ol>
+  <li>Truncated and unverified DNS-SD Instance Names, which should not be shown to the user.</li>
+  <li>Complete but unverified DNS-SD Instance Names, which can be shown as
+     unverified prior to [[#authentication]].</li>
+  <li>Verified display names.</li>
+</ol>
+</div>
 
 Advertising agents must include DNS TXT records with the following
 keys and values:
@@ -550,11 +570,8 @@ When either agent has received both auth-spake2-message and
 auth-spake2-confirmation messages, the agent validates the confirmation message
 and sends the auth-status authenticated message.
 
-Control Protocols {#control-protocols}
-============================
-
 Presentation Protocol {#presentation-protocol}
----------------------------------------------
+=====================
 
 This section defines the use of the Open Screen Protocol for starting,
 terminating, and controlling presentations as defined by
@@ -685,9 +702,9 @@ message contains the following values:
 : reason
 :: The reason the presentation was terminated.
 
-To accept incoming connections requests from controller, a receiver
-must receive and process the presentation-connection-open-request
-message which contains the following values:
+To accept incoming connection requests from controller, a receiver must receive
+and process the presentation-connection-open-request message which contains the
+following values:
 
 : presentation-id
 :: The ID of the presentation to connect to.
@@ -709,39 +726,29 @@ following values:
     the message receiver chooses the connection-id, it may keep the ID unique
     across connections, thus making message demuxing/routing easier).
 
-
-A controller may terminate a connection without terminating the presentation by
-sending a presentation-connection-close-request message with the following
-values:
+A controller may close a connection without terminating the presentation by
+sending a `presentation-connection-close-event` message to the receiver with the
+following values:
 
 : connection-id
-:: The ID of the connection to close.
-
-Issue(124): Is a Presentation close/terminate from a controller a request/response or event?
+:: The ID of the connection that was closed.
 
-The receiver should, upon receipt of a presentation-connection-close-request,
-send back a presentation-connection-close-response message with the following
-values:
-
-: result
-:: If the close succeed or failed, and if it failed why it failed.
-
-Issue(138): Remove presentation-connection-close-response message.
+: reason
+:: Set to `close-method-called` or `connection-object-discarded`.
 
-The receiver may also close a connection without a request from the controller
-to do so and without terminating a presentation.  If it does so, it should send
-a presentation-connection-close-event to the controller with the following
-values:
+The receiver may also close a connection without terminating a presentation.  If
+it does so, it should send a `presentation-connection-close-event` message to the
+controller with the following values:
 
 : connection-id
-:: The ID of the connection that was closed
+:: The ID of the connection that was closed.
 
 : reason
-:: The reason the connection was closed
+:: Set to `close-method-called` or `connection-object-discarded`.
 
-: error-message
-:: A debug message suitable for a log or perhaps presented to
-    the user with more explanation as to why it was closed.
+Note: When an agent closes a presentation connection, it is always successful,
+so request and response messages are not needed.  A request to terminate a
+presentation may succeed or fail, so a response message is required.
 
 
 Presentation API {#presentation-api}
@@ -781,6 +788,12 @@ messageOrData for the presentation message data.  Note that the messageType is
 embedded in the encoded CBOR type and does not need an additional value in the
 message.
 
+When [[PRESENTATION-API#closing-a-presentationconnection|section 6.5.5]] says
+"Start to signal to the destination browsing context the intention to close the
+corresponding PresentationConnection", the [=user agent=] may send a
+`presentation-connection-close-event` message to the user agent with the
+destination browsing context.
+
 When
 [[PRESENTATION-API#terminating-a-presentation-in-a-controlling-browsing-context|section
 6.5.6]] says "Send a termination request for the presentation to its receiving
@@ -801,7 +814,7 @@ user agent=], must send a presentation-connection-open-response message.
 
 
 Remote Playback Protocol {#remote-playback-protocol}
-----------------------------------------------------
+========================
 
 This section defines the use of the Open Screen Protocol for starting, terminating,
 and controlling remote playback of media as defined by the
@@ -1704,7 +1717,7 @@ and/or high value data:
 Presentation IDs are considered high value data because they can be used in
 conjunction with a Presentation URL to connect to a running presentation.
 
-Presentation display friendly names, model names, and capabilities, while not
+Presentation display names, model names, and capabilities, while not
 considered personally identifiable, are important to protect to prevent an
 attacker from changing them or substituting other values during the discovery
 and authentication process.
@@ -1841,10 +1854,10 @@ should be flagged include:
 
 * Untrusted agents whose public key fingerprint collides with that from an
     already-trusted agent that is concurrently being advertised.
-* Untrusted agents whose friendly name differs from the one previously
+* Untrusted agents whose display name differs from the one previously
     advertised under a given public key fingerprint.
 * Untrusted agents that fail the authentication challenge a certain number of times.
-* Untrusted agents that advertise a friendly name that is similar to that from an
+* Untrusted agents that advertise a display name that is similar to that from an
     already-trusted agent.
 * Already-trusted agents whose metadata provided through the `agent-info`
     message has changed.