[MMUSIC] RTSP 2.0: Body format negotiation

[Magnus Westerlund <[e-mail]>]

WG,

As a result of the below quoted discussion I have created a proposed
text change to make the format negotiation more explicit and clear and
linked to the RTSP methods that have need for it.

The changes I have done in an attempt to address this can be summarized as:
- Create a general negotiation description in a sub-section to the
Message Body section
- Updated GET_PARAMETER and SET_PARAMETER methods to reference this and
be more explicit about handling request formats and returning the same
format.
- Mandate that anyone capable of responding to a GET_PARAMETER and
SET_PARAMETER request MUST support text/parameters
- Updating the Accept header to actually contain description of how you
use it. Missed import from HTTP spec when removing reference.

Please review these changes and provide comments.

Actual text proposal below including whole sections:

9.3.  Message Body Format Negotiation

   The content format of the message body is provided using the Content-
   Type header (Section 18.18).  To enable the responder of a request to
   determine which media type it should use, the requestor may include
   the Accept header (Section 18.1) in a request to identify supported
   media types or media type ranges suitable to the response.  In cases
   the responder is not supporting any of the specified formats, then
   the request response will be a 406 (Not Acceptable) error code.

   The media types that may be used on requests with message bodies
   needs to be determined through the use of feature-tags, specification
   requirement or trial and error.  Trial and error works in the regards
   that in case the responder is not supporting the media type of the
   message body it will respond with a 415 (Unsupported Media Type).

   The formats supported and their negotiation is done individually on a
   per method and direction (request or response body) direction.
   Requirements on supporting particular media types for use as message
   bodies in requests and response SHALL also be specified on per method
   and direction basis.


13.8.  GET_PARAMETER

   The GET_PARAMETER request retrieves the value of any specified
   parameter or parameters for a presentation or stream specified in the
   URI.  If the Session header is present in a request, the value of a
   parameter MUST be retrieved in the specified session context.  There
   are two ways of specifying the parameters to be retrieved.

   The first is by including headers which have been defined such that
   you can use them for this purpose.  Headers for this purpose should
   allow empty, or stripped value parts to avoid having to specify bogus
   data when indicating the desire to retrieve a value.  The successful
   completion of the request should also be evident from any filled out
   values in the response.  The headers in this specification that MAY
   be used for retrieving their current value using GET_PARAMETER below.
   Additional headers MAY be specified in the future:

   o  Accept-Ranges

   o  Media-Range

   o  Media-Properties

   o  Range

   o  RTP-Info

   The other way is to specify a message body that lists the
   parameter(s) that are desired to be retrieved.  The Content-Type
   header (Section 18.18) is used to specify which format the message
   body has.  If the receiver of the request is not supporting the media
   type used for the message body, it SHALL respond using the error code
   415 (Unsupported Media Type).  The responder to a GET_PARAMETER
   request MUST use the media type of the request for the response.  For
   additional considerations regarding message body negotiation see
   Section 9.3.

   RTSP Agents implementing support for responding to GET_PARAMETER
   requests SHALL implement the text/parameters format (Appendix F).
   This to ensure that at least one known format for parameter are
   implemented and thus prevent parameter format negotiation failure.

   Parameters specified within the body of the message must all be
   understood by the request receiving agent.  If one or more parameters
   are not understood a 451 (Parameter Not Understood) MUST be sent
   including a body listing these parameters that weren't understood.
   If all parameters are understood their values are filled in and
   returned in the response message body.

   The method MAY also be used without a message body or any header that
   requests parameters for keep-alive purpose.  The keep-alive timer has
   been updated for any request that is successful, i.e., a 200 OK
   response is received.  Any non-required header present in such a
   request may or may not have been processed.  Normally the presence of
   filled out values in the header will be indication that the header
   has been processed.  However, for cases when this is difficult to
   determine, it is recommended to use a feature-tag and the Require
   header.  For this reason it is usually easier if any parameters to be
   retrieved are sent in the body, rather than using any header.

   Example:

     S->C: GET_PARAMETER rtsp://example.com/fizzle/foo RTSP/2.0
           CSeq: 431
           User-Agent: PhonyClient/1.2
           Session: 12345678
           Content-Length: 26
           Content-Type: text/parameters

           packets_received
           jitter

     C->S: RTSP/2.0 200 OK
           CSeq: 431
           Session: 12345678
           Server: PhonyServer/1.1
           Date: Mon, 08 Mar 2010 13:43:23 GMT
           Content-Length: 38
           Content-Type: text/parameters

           packets_received: 10
           jitter: 0.3838


13.9.  SET_PARAMETER

   This method requests to set the value of a parameter or a set of
   parameters for a presentation or stream specified by the URI.  The
   method MAY also be used without a message body.  It is the
   RECOMMENDED method to be used in a request sent for the sole purpose
   of updating the keep-alive timer.  If this request is successful,
   i.e., a 200 OK response is received, then the keep-alive timer has
   been updated.  Any non-required header present in such a request may
   or may not have been processed.  To allow a client to determine if
   any such header has been processed, it is necessary to use a feature
   tag and the Require header.  Due to this reason it is RECOMMENDED
   that any parameters are sent in the body, rather than using any
   header.

   When using a message body to list the parameter(s) that are desired
   to be set the Content-Type header (Section 18.18) is used to specify
   which format the message body has.  If the receiver of the request is
   not supporting the media type used for the message body, it SHALL
   respond using the error code 415 (Unsupported Media Type).  For
   additional considerations regarding message body negotiation see
   Section 9.3.

   RTSP Agents implementing support for responding to SET_PARAMETER
   requests SHALL implement the text/parameters format (Appendix F).
   This to ensure that at least one known format for parameters are
   implemented and thus prevent parameter format negotiation failure.

   A request is RECOMMENDED to only contain a single parameter to allow
   the client to determine why a particular request failed.  If the
   request contains several parameters, the server MUST only act on the
   request if all of the parameters can be set successfully.  A server
   MUST allow a parameter to be set repeatedly to the same value, but it
   MAY disallow changing parameter values.  If the receiver of the
   request does not understand or cannot locate a parameter, error 451
   (Parameter Not Understood) MUST be used.  When a parameter is not
   allowed to change, the error code is 458 (Parameter Is Read-Only).
   The response body MUST contain only the parameters that have errors.
   Otherwise no body MUST be returned.  The response body MUST use the
   media type of the request for the response.

   Note: transport parameters for the media stream MUST only be set with
   the SETUP command.

      Restricting setting transport parameters to SETUP is for the
      benefit of firewalls.

      The parameters are split in a fine-grained fashion so that there
      can be more meaningful error indications.  However, it may make
      sense to allow the setting of several parameters if an atomic
      setting is desirable.  Imagine device control where the client
      does not want the camera to pan unless it can also tilt to the
      right angle at the same time.

   Example:

     C->S: SET_PARAMETER rtsp://example.com/fizzle/foo RTSP/2.0
           CSeq: 421
           User-Agent: PhonyClient/1.2
           Session: iixT43KLc
           Date: Mon, 08 Mar 2010 14:45:04 GMT
           Content-length: 20
           Content-type: text/parameters

           barparam: barstuff

     S->C: RTSP/2.0 451 Parameter Not Understood
           CSeq: 421
           Session: iixT43KLc
           Server: PhonyServer/1.0
           Date: Mon, 08 Mar 2010 14:44:56 GMT
           Content-length: 20
           Content-type: text/parameters

           barparam: barstuff



18.1.  Accept

   The Accept request-header field can be used to specify certain
   presentation description and parameter media types [RFC6838] which
   are acceptable for the response to DESCRIBE and GET_PARAMETER
   requests.

   See Section 20.2.3 for the syntax.

   The asterisk "*" character is used to group media types into ranges,
   with "*/*" indicating all media types and "type/*" indicating all
   subtypes of that type.  The media-range MAY include media type
   parameters that are applicable to that range.

   Each media-range MAY be followed by one or more accept-params,
   beginning with the "q" parameter for indicating a relative quality
   factor.  The first "q" parameter (if any) separates the media-range
   parameter(s) from the accept-params.  Quality factors allow the user
   or user agent to indicate the relative degree of preference for that
   media-range, using the qvalue scale from 0 to 1 (section 3.9).  The
   default value is q=1.

   Example of use:

     Accept: application/example ;q=0.7, application/sdp

   Indicates that the requesting agent prefers the media type
   application/sdp through the default 1.0 rating but also accepts
   the application/example media type with 0.7 quality rating.

   If no Accept header field is present, then it is assumed that the
   client accepts all media types.  If an Accept header field is
   present, and if the server cannot send a response which is acceptable
   according to the combined Accept field value, then the server SHOULD
   send a 406 (not acceptable) response.


On 2013-06-10 09:52, Magnus Westerlund wrote:
> On 2013-06-07 17:40, Elwyn Davies wrote:
>> On Fri, 2013-06-07 at 16:05 +0200, Magnus Westerlund wrote:
>>
>>>> Appendix F: I missed that the text/parameter format appeared in the
>>>> examples for GET_PARAMETER and SET_PARAMETER. It isn't stated in the
>>>> definitions of these methods what encodings are acceptable for the
>>>> message bodies that may go with these methods and their responses.
>>>
>>> Exactly, that is intentional. These methods can use anything that has a
>>> MIME type. Also it has HTTP's mechanisms for determining what formats
>>> one supports.
>>>
>>>> Clearly the new text/parameter MIME format is one.  Is it the only one?
>>>
>>> It is the only one defined by IETF for this purpose. That is why it is
>>> in the appendix so that RTSP users shall have something to define the
>>> parameters they want in. However, they have to accept the limitations of
>>> a basic text format.
>>>
>>>> I guess you could use a application/json or an XML format but I guess
>>>> these would also either have to be called out explicitly in the method
>>>> descriptions or put in as feature extensions.  This needs to be
>>>> clarified in the method descriptions (s13).  The upshot of all this is
>>>> that I think Appendix F needs to be pulled back into Section 20 as
>>>> currently it is the only way to encode the message bodies.
>>>
>>> I can agree that the format negotiation for the bodies of
>>> GET/SET_PARAMETER is not clear. I will look at proposing some
>>> improvements of the text related to the handling of method bodies and
>>> their format negotiation.
>> Good. I don't see where the server tells what formats it accepts for
>> either GET_PARAMETER or SET_PARAMETER.  Also the Accept spec doesn't say
>> anything about SET_PARAMETER.  AFAICS the client could tell the server
>> what formats it accepts as a side-effect of DESCRIBE but that's a bit
>> arcane - and it is not clear how you would separate the formats for
>> DESCRIBE from those for GET_PARAM and SET_PARAM.
> 
> Yes, I think this negotiation should happen on per methods basis.
>>>
>>> However, I am not pulling in Appendix F. It is an optional to use format
>>> for parameter value pairs that can be used in these methods, it is not
>>> required. Nor, does the specification define any parameters that are
>>> transferred using this interface. The things that are in the appendix
>>> are not core protocol, they represent either informational things, like
>>> the examples and the state machine. The other appendices are normative
>>> definitions of particular choices for things that can be combined or
>>> used with RTSP, like RTP as media transport.
>>>
>> OK, it is possible to use GET_PARAM for basic requirements without using
>> message bodies, so you can get away without defining a lowest common
>> denominator format. However, the use of message bodies for SET_PARAM is
>> RECOMMENDED so it seems a little odd not to ensure that server and
>> client will have at least one format in common. (And its not as if we
>> are dealing with a hugely complicated bit of spec for
>> text/parameters! :-) ).  Then, given the example in GET_PARAMETER it
>> seems sensible to advise implementing text/parameters as the default for
>> GET_PARAM also.
> 
> Sure, I personally don't have any issue with making it at least SHOULD
> implement text/parameters. But from my horizon a forward pointer with
> the normative requirements is sufficient to accomplish that.
> 
> Cheers
> 
> Magnus Westerlund
> 
> ----------------------------------------------------------------------
> Multimedia Technologies, Ericsson Research EAB/TVM
> ----------------------------------------------------------------------
> Ericsson AB                | Phone  [phone]
> Färögatan 6                | Mobile [phone]
> SE-164 80 Stockholm, Sweden| mailto: [e-mail]
> ----------------------------------------------------------------------
> 
> 
> 


-- 

Magnus Westerlund

----------------------------------------------------------------------
Multimedia Technologies, Ericsson Research EAB/TVM
----------------------------------------------------------------------
Ericsson AB                | Phone  [phone]
Färögatan 6                | Mobile [phone]
SE-164 80 Stockholm, Sweden| mailto: [e-mail]
----------------------------------------------------------------------