Adds Presentation Receiver status.

control_protocol.md

@@ -231,6 +231,9 @@ Value | Flavor
 `MESSAGE_TYPE_ID` is used to group related messages together, and
 `MESSAGE_SUBTYPE_ID` can distinguish individual message types within that group.
 
+**TODO**: Define an extensions format to allow additional data to be bundled
+with a defined message type.
+
 ## Presentation API Control Protocol
 
 To outline the control protocol, we describe the messages used to implement each
@@ -667,42 +670,162 @@ Subtype: 0x0001
 Byte Offset
   32           +-----------------------+
                +  PRESENTATION_ID      +
-  40           +-----------------------+
+  160          +-----------------------+
                +  CONNECTION_ID        +
-  44           +-----------------------+
+  164          +-----------------------+
                +  MESSAGE_TYPE         +
-  45           +-----------------------+
+  165          +-----------------------+
                +  MESSAGE_LENGTH       +
-  49           +-----------------------+
+  197          +-----------------------+
                +  MESSAGE_CONTENT      +
                +-----------------------+
 ```
 
 - `PRESENTATION_ID` is a null (zero-byte) terminated ASCII string of 128 bytes
   that communicates the ID for the presentation.  Values shorter than 128 bytes
   should be zero-byte padded.
-- `MESSAGE_LENGTH` is an unsigned 32-bit integer with the length, in bytes,
-  of the message content.
-- `MESSAGE_CONTENT` is the content of the message.  It must be exactly
-  `MESSAGE_LENGTH` bytes in length.
-- `MESSAGE_TYPE` is a one-byte code describing the message type:
+- `CONNECTION_ID` is a 32-bit positive integer that corresponds to the ID of the
+  receiver `PresentationConnection` that is conveying the message.
+- `MESSAGE_TYPE` is a one-byte code describing the message type as follows:
 
 Message Type | Meaning
 -------------|--------
 1            | Text message
 2            | Binary message
+3            | Empty text message
+
+- `MESSAGE_LENGTH` is an unsigned 32-bit integer with the length, in bytes,
+  of the message content.
+- `MESSAGE_CONTENT` is the content of the message.  It must be exactly
+  `MESSAGE_LENGTH` bytes in length. For text messages, the `MESSAGE_CONTENT`
+  must correspond to a valid and non-empty UTF-8 string.  For binary messages,
+  the content is arbitrary binary data.
 
-**TODO**: Define text encoding
-**TODO**: Include locale slot?
+A `MESSAGE_TYPE` of 3 corresponds to an empty string, i.e. `send('')`.
+If the `MESSAGE_TYPE` is 3, the `MESSAGE_LENGTH` must be zero.
+
+**TODO:** Do we need special handling of empty binary messages, i.e. `new
+ArrayBuffer(0)`
 
 ### Presentation Receiver Status Event
 
-**TODO:** Finish
+This message allows the receiver to broadcast status information to all
+connected controlling user agents.  It may be sent at any time, but should be
+sent when the content of a Display Info or Presentation Info has changed since
+the last broadcast.  The receiver may be configured to broadcast a subset of the
+information in this message or none at all depending on the policies and privacy
+preferences of the user.
+
+This Receiver Status event is a composition of sub-messages.  See below for the
+breakout of the sub-message formats.
+
+```
+Flavor:  Event
+Type:    0x0005
+Subtype: 0x0001
+
+Byte Offset
+  32           +-----------------------+
+               + DISPLAY_INFO          +
+  K            +-----------------------+
+               + NUM_PRESENTATION_INFO +
+  K+4          +-----------------------+
+               + PRESENTATION_INFO_1   +
+               +-----------------------+
+               + ...                   +
+               +-----------------------+
+               + PRESENTATION_INFO_N   +
+               +-----------------------+
+```
+
+### Display Info
+
+The Display Info struct conveys information about the presentation display
+device itself.  Currently this includes information about the friendly name
+which may be too long to fit in a discovery protocol message.
+
+```
+Byte Offset
+  0            +-----------------------+
+               + FRIENDLY_NAME_LOCALE  +
+  64           +-----------------------+
+               + FRIENDLY_NAME_LENGTH  +
+  66           +-----------------------+
+               + FRIENDLY_NAME_CONTENT +
+               +-----------------------+
+```
+
+- `FRIENDLY_NAME_LOCALE` is a 64-byte, zero terminated ASCII value with the
+  BCP-47 language code of the friendly name.  If it is shorter than 64 bytes, it
+  should be right-padded by zeroes.
+- `FRIENDLY_NAME_LENGTH` is a 2-byte positive unsigned integer with the length
+  of `FRIENDLY_NAME_CONTENT`.
+- `FRIENDLY_NAME_CONTENT` is a valid UTF-8 encoded string with the friendly name
+  of the presentation display.  It is exactly `FRIENDLY_NAME_LENGTH` bytes in
+  length.
+
+**TODO:** [Representation of BCP-47 language tags](issues/47)
+
+### Presentation Info
+
+The Presentation Info struct conveys information about a running presentation.
+All fields are optional.  By advertising a presentation's URL and ID, the
+receiver will allow any connected controlling user agent to connect to that
+presentation.
+
+```
+Byte Offset
+  0            +-----------------------+
+               +  PRESENTATION_ID      +
+  128          +-----------------------+
+               +  URL_LENGTH           +
+  132          +-----------------------+
+               +  URL_CONTENT          +
+  K            +-----------------------+
+               +  NUM_CONNECTIONS      +
+  K+2          +-----------------------+
+               +  TITLE_LOCALE         +
+  K+66         +-----------------------+
+               +  TITLE_LENGTH         +
+  K+78         +-----------------------+
+               +  TITLE_CONTENT        +
+               +-----------------------+
+```
+
+- `PRESENTATION_ID` is a null (zero-byte) terminated ASCII string of 128 bytes
+  that communicates the ID for the presentation.  Values shorter than 128 bytes
+  should be zero-byte padded.  If omitted, it should be all zeros.
+- `URL_LENGTH` is an unsigned positive 32-bit integer with the length, in bytes,
+  of the presentation URL.  The presentation URL is omitted, it should be zero.
+- `URL_CONTENT` is the presentation URL, encoded according to RFC 3986.  This
+  field must be exactly `URL_LENGTH` bytes in length.  If the presentation URL
+  is omitted, this field is not present.
+- `NUM_CONNECTIONS` is an unsigned 2-byte integer that holds the number of
+  presentation connections that are in a `connected` state.  If omitted, this
+  field is zero.
+- `TITLE_LOCALE` is is a 64-byte, zero terminated ASCII value with the BCP-47
+  language code of the friendly name.  If it is shorter than 64 bytes, it should
+  be right-padded by zeroes.  If the presentation title omitted, it is all
+  zeros.
+- `TITLE_LENGTH` is a 2-byte positive unsigned integer with the length
+  of `TITLE_CONTENT`.  If the presentation title is omitted, this is zero.
+- `TITLE_CONTENT` is a valid UTF-8 encoded string with the [title of the
+  presentation document](https://html.spec.whatwg.org/multipage/semantics.html#the-title-element).
+  It is exactly `TITLE_LENGTH` bytes in length.  If the presentation title is
+  omitted, this field is not present.
+
+**NOTE**: We could add a status flag to tell controlling user agents the status
+of the presentation (loading/ready/terminating/terminated).
+
+**NOTE:** We could allow the receiver to broadcast only the origin of the
+presentation, not the full URL, for display purposes in the controlling user
+agent.  In that case, we would need to add a flag to convey this so the
+controller knows not to attempt reconnection with just the origin.
 
 ## Remote Playback API Control Protocol
 
-**TODO:** Fill in when Remote Playback requirements are
-known. See [Issue #3](issues/3).
+**TODO:** Fill in when Remote Playback requirements are known. See [Issue
+#3](issues/3).
 
 ## Design Discussion
 
@@ -760,3 +883,7 @@ exchange so that each party knows what roles the other may assume (controlling
 user agent, receiver, or both).
 
 **TODO**: Add protocol support for capability/role advertisement.
+
+### Language Tags
+
+