Subject: Re: [MMUSIC] Gen-art additional LC review of draft-ietf-mmusic-rfc2326bis-34

From: Magnus Westerlund <[email-masked]>
Date: Fri, 23 Aug 2013 10:52:15 +0200

Hi,

Continuing with the issues after Section 11.

Once more a big thanks for the work you have put into this. It is really
helpful, both from clarity point of view and finding some actual
protocol issues.

On 2013-06-06 02:11, Elwyn Davies wrote:

 >
> s13.4.1, para 2:
>> Upon receipt of the PLAY request, the server MUST position the normal
>>    play time to the beginning of the range specified in the received
>>    Range header 
> 
> Should this mention the caveat that (if I understood earlier statements
> correctly) the server may not be able to deliver exactly on this MUST
> and then sets it the nearest it can manage? This is borne out by the
> example later in this section where the server sets the start point back
> 10ms (and says so), etc.  Seek-Style affects the interpreation of MUST!

Yes, I have added that this needs to happen ".. within the limits of the
media resource and in accordance with the Seek-Style header (Section
X.Y) ..".

> 
> s13.4.4/.5/.7/.8: In these sections the Media-Property random access
> property is stated as being required to be Random-Access.  Is
> Conditional Random Access a possible value for this property? The
> confusion in s4.9.1 does not allow me to conclude that this shouldn't be
> a value for the property (sorry for the double negative but this looks a
> bit confused).

These section lists the Media-Properties for the media resource one
request delivery for. Thus from a PLAY request perspective using a
Seek-Style: CoRAP header is fine for the ones that has Random Access
property as Random-Access in these section.

> 
> s13.5.1:  Apologies if this question is stupid - I am not a media stream
> wxpert.  Suppose we have an aggregated stream with (say) a number of
> recorded media items making up the aggregate.  The client sets it on to
> play to the end.  What happens if not all the streams end at the same
> time?  Do we get PLAY_NOTIFY End-of-Stream notifications for each
> individual stream as it ends or just one when the complete aggregate
> ends?

Not at all a stupid question. This should have been clearly specified
for all usages of PLAY_NOTIFY in regards to aggregated sessions. Thus I
have added both a general requirement on PLAY_NOTIFY level:

PLAY_NOTIFY requests MAY use both aggregate control URI and individual
media resource URIs depending on scope of the notification. This scope
may have important distinctions for aggregated sessions, and each reason
for a PLAY_NOTIFY request needs to specify the interpretation and if
aggregated control URIs or individual URIs may be used in requests.

And specified the following for end-of-stream:

For RTSP Session where media resources under aggregated control the
media resources will normally end at approximately the same time,
although some small differences may exist, on the scale of  a few
hundred of milliseconds. In those cases a RTSP session under aggregated
control SHOULD send only a single PLAY_NOTIFY request. By using the
aggregate control URI in the PLAY_NOTIFY request the RTSP server
indicates that this applies to all media resources within the session.
In cases RTP is used for media delivery corresponding RTP-Info needs to
be included for all media resources. In cases where one or more media
resource has significantly shorter duration than some other resources in
the aggregated session the server MAY send end-of-stream notifications
using individual media resource URIs to indicate to agents that there
will be no more media for this particular media resource related to the
current active PLAY request. In such cases when the remaining media
resources comes to end-of-stream they MUST send a PLAY_NOTIFY request
using the aggregate control URI to indicate that no more resources remains.

And the following for Media-Properties-Update

The Media-Properties header has session scope, thus for aggregated
sessions the PLAY_NOTIFY request MUST be using the aggregated control URI.

And for Scale-Change

PLAY_NOTIFY requests for aggregated sessions MUST use the aggregated
control URI in the request. The scale change for any aggregated session
do apply to all media streams part of the aggregate.

> 
> s13.5.2, para 2:
>> that changes the basis for making
>>    estimates on how the media range progress. 
> I can't parse the last part of this and I am not sure what it should be.

I hope this is better

This notification MUST be sent for media that are Time-Progressing every
time an event happens that changes the basis for making estimates on how
the available for play-back media range will progress with wall clock time.

> 
> s14: What happens if the upper layer PDU is longer than (2^16 - 1)?

I have added this note:

Note that this mechanism does not support larger PDUs than 65535 bytes,
which is the same that regular IPv4 and IPv6 is capable. If the media
delivery protocol intended to be used has larger PDUs than that, the
definition of such mechanisms usage of this mechanism will require the
definition of a PDU fragmentation mechanism.

> 
> s18.10, private para:  Is there any way in RTSP for the cache to know
> whether this is a private cache for the user that should cache this
> content?

To my understanding this is something the cache itself knows through its
behavior and deployment.

> s18.10, last para:  I am not absolutely certain, but I think this para
> is specific to the max-age cache type rather than being generic as
> implied by the indentation. [If so use the <vspace blankLines=1/> trick
> to provide a pseudo-paragraph break]

Yes, you are correct. I did the equally easy choice for hanging lists to
simply make a new paragraph without any paragraph text.

> s18.14: Consider adding the 'identity' value explicitly to the ABNF.

If I understand you correctly what you are requesting is that "identity"
is listed as an construct in the content-coding ABNF construction that
are used by Accept-Encoding and Content-Encoding headers.

Accept-Encoding   =  "Accept-Encoding" HCOLON
                     [ encoding *(COMMA encoding) ]
encoding          =  codings [SEMI accept-params]
codings           =  content-coding / "*"
content-coding    =  "identity" / token
Content-Encoding   =  "Content-Encoding" HCOLON
                      content-coding *(COMMA content-coding)

> 
> s18.29, para 2: Are (or should there be) constraints on the ordering of
> media ranges for a non-continuous media stream?  It would probably make
> the client's job easier if they were in incresing order. 

This is a interesting question. If one simply expresses what pieces of
media that are currently available then using a requirement that the
first ranges end-time must be prior any of the subsequent ranges start
times would work. However, my head gets stuck on considering when
desired playback is non linear. But that is probably a higher function
question.

So a possible addition after this existing sentence:

The server MAY include more than one range specification of any given
time format to indicate media that has non-continuous range.

would be:
The range specifications shall be ordered with the range with the lowest
value or earliest start time first, followed by ranges with increasingly
higher values or later start time.

Comments on this?

> s18.41: It appears from a literal interpretation (the third sentence is
> an unqualified MUST) that the responder has to respond with error code
> 551 and an (empty?) list of Unsupported features if it actually does
> support all the features.  I suspect this is not what is wanted.

Correct, reformulated proposal is:

In case any of the feature-tags listed by the Require header are not
supported by the server or client receiving the request, it MUST respond
to the request using the error code 551 (Option Not Supported) and
include  the Unsupported header listing those feature-tags which are NOT
supported.

> s18.45, para 4: Harummph! Political Correctness strikes again.  Every
> protocol should (and probably does) have a CRAP policy. ;-)

Yes, the lower case o is silent here ;-).

> 
> s18.52, 'setup' section:  There seems to be some inconsistency in the
> spcification of the 'active/passive/actpass' values.  a) Is there some
> reason for specifying them in square brackets?

Not, that I can remember. Removing both brackets and quotes.

 b) should they say
> ["active:"] or ["active":] - both formats are used?  The ABNF has the
> plain words with no brackets or quotes.

The later would be correct, but now it will only say
active: <description>

The ABNF is clear that it will be
RTP/SAVPF/TCP;unicast;setup=active;connection=new

> 
> 18.52, 'connection' section, 1st line:
> s/Clients use the setup parameter/Clients use the connection parameter/
> (I assume).

Had to tweak that sentence a bit more:

Clients use the connection parameter in a transport specification part
of the Transport header in a SETUP request, to indicate the client's
preference for either reusing an existing connection between client and
server (in which case the client sets the "connection" parameter to
"existing"), or requesting the creation of a new connection between
client and server (in which cast the client sets the "connection"
parameter to "new").

> 
> s21.1, transfer of sensitive info: Is there an equivalent of the Referer
> header in RTSP?  Not sure there is but it would be good to explain one
> way or the other (either there isn't one so it's less of a problem or
> this is the equivalent...)

Yes, the Referer header is retained also in RTSP.

> 
> s21.1, DNS Spoofing:  Presumably RTSP will interact significantly with
> content delivery networks.  Some of these work by DNS 'spoofing' that
> was in its infancy when RFC 2616 was published.  Are there any other
> issues that come out of the greater prevalence of CDNs since 1999?

I have no experience with large scale deployment of RTSP. To my
knowledge there hasn't been the same development with CDNs for RTSP as
HTTP. This I think is dependent on several factors. One has been the
issues with deploying RTSP on global scale due to NAT traversal etc,
instead progressive download and HTTP adaptive streaming has mostly
taken this market. Thus most large scale deployments has been in
contexts within single operators providing Video On Demand services etc.

Thus, I don't really know of any additional issues around this.

> 
> s21.1, Session Hijacking:  The last part of this is written so that it
> appears to mandate authentication in all cases.  As far as I understand
> it is up to the client to decide if it needs authentication etc and some
> content will be offered on unsecured URIs.  I think this needs to be
> clearer that authentication will mitigate the problem but whether it is
> done is up to the client if the server doesn't care.

Is this better?

Another choice for preventing session hijacking is to use client
authentication and only allow the authenticated client creating the
session to access that session.

> 
> s21.1, Persistently suspicious behaviour:  There seems to be a mismatch
> between the title (persistently..) and the first sentence (a single
> instance).  Do we have examples of the sort of security risk which is
> supposed to be met with a 403 response the first time?

Yes, it is a bit inconsistent. I propose:

Suspicious behavior: RTSP servers upon detecting intances of behavior
which is deemed a security risk SHOULD return error code 403
(Forbidden). RTSP servers SHOULD also be aware of attempts to probe the
server for weaknesses and entry points and MAY arbitrarily disconnect
and ignore further requests from clients which are deemed to be in
violation of local security policy.

> 
> s21.1, last sentence:
>>    Some of the above threats are such that
>>    the implementation of the RTSP functionality itself needs to consider
>>    which policy and strategy it uses to mitigate them.
> It strikes me that this is not very helpful to a prospective
> implementer.  The point of this section is at least in part to provide
> that policy and strategy.  I am not quite sure how to rewrite this (or
> if indeed other people think it does need rewriting). 

No, it is not helpful in other ways then, you need to think about this
and consider what mitigations you think should be implemented and how
that affects your implementation design.

For now I am leaving this as it is.

> s22.3:  The rules about allocating in the sections above x50 should be
> explained here (see s8.1.1).  The  numbers below x50 in each section
> should be marked as a special category of reserved so they are only
> allocated to HTTP analogues.  Is an experimental/private segment in each
> category desirable?   

Yes I think adding something like the below to at least make clear the
intention that RTSP specific status codes should first be registered in
the x50-x99 range.

New RTSP functionality requiring Status Codes should first be registered
in the range x50-x99. Only when the range is full should registrations
be done in the x00-x49 range, unless it is to adopt an HTTP extension
also to RTSP. The reason is to enable any HTTP extension to be adopted
to RTSP without needing to renumber any related status codes.

Regarding experimental and private I am very torn about such range.
Unless someone else in the WG thinks this is worth the work I will leave
it out.

> 
> s22.9: Being allowed to register new Range header formats will currently
> be restricted to times specified by NPT, SMPTE or UTC because no
> registry is defined for Accept-Ranges.  Is this what is intended?

No, the intention is that Range header format registry is shared between
Range and Accept-Ranges. However, I see the description is not clear on
this and needs to be amended.

I have sent a separate email on this.

Cheers

Magnus Westerlund

----------------------------------------------------------------------
Multimedia Technologies, Ericsson Research EAB/TVM
----------------------------------------------------------------------
Ericsson AB                | Phone  +46 10 7148287
Färögatan 6                | Mobile +46 73 0949079
SE-164 80 Stockholm, Sweden| mailto: [email-masked]
----------------------------------------------------------------------

---

From: Magnus Westerlund <[email-masked]>
Date: Fri, 23 Aug 2013 15:54:32 +0200

Hi,

Now getting to implement your response in our source.

Some few additional comments or notes below.

On 2013-06-25 14:47, Elwyn Davies wrote:
> 
> On Mon, 2013-06-24 at 16:51 +0200, Magnus Westerlund wrote:
>> Elwyn,
>>
>> Follow up on some of the nits that is not simply to implement or where I
>> disagree or want to provide feedback.
>>
>> This email covers all issues up to and including Section 11. That is as
>> far as I have managed to process them yet. I will now handle over the
>> rest of this list to my co-authors.
>>

>>>
>>>
>>> ss4.4/4.5/4.6: If I read the ABNF in s20.2.1 correctly, the unqualified 
>>> values "smpte", "npt" and "clock" are valid  in the Range parameter.  
>>> What is the meaning of such an unqualified value?
>>
>> You are correct about that the basic definition in ABNF allows for
>> empty. The reason for this is the following stated in Section 18.38:
>>
>>     It MAY be
>>    included in GET_PARAMETER requests from the client to the server with
>>    only a Range format and no value to request the current media
>>    position, whether the session is in Play or Ready state in the
>>    included format.
>>
> Two points:
> - A suggestion: Make ss4.4/4.5/4.6 into subsections of a new s4.4.  Add
> a bit of text in the new s4.4 saying that the range specifiers are used
> in the RANGE header and pointing to s18.38 for the unqualified use.
> (consistent with s2.7 which gives usage).
> - An issue I hadn't spotted: I haven't checked but are the unqualified
> values allowed in the SDP extension case (s20.3)?
>>
>>

I think your suggestion is a good one and I have written such a section,
initial proposal below:

4.4.  Media Time Formats

   RTSP currently supports three different media time formats defined
   below.  Additional time formats may be specified in the future.
   These time formats can be used with the Range header (Section 18.38)
   to request playback and specify at which media position protocol
   requests actually will or has taken place.  They are also used in
   description of the media's properties using the Media-Range header
   (Section 18.29).  The format identifier only are used in Accept-
   Ranges header (Section 18.5) to declare supported time formats and
   also in the Range header (Section 18.38) to request the time format
   used in the response.

4.4.1.  SMPTE Relative Timestamps

Regarding the SDP a=range attribute. The ABNF allows the unqualified
usage. The textual specification of a=range attribute in D.1.6 is silent
on unqualified usage.

The only usage of unqualified usage in a=range would be to indicate that
although this media has unknown or time-progressing properties it does
support the time formats for the a=range with unqualified values that
has been included.

>>
>>>
>>> s10.2, para 6 and following note:  I can't see that the note following 
>>> para 6 can be justified: since the restriction on multiple connections 
>>> from a client to a server is only a SHOULD, an interoperable server MUST 
>>> be capable of handling multiple connections from a client unless the 
>>> server can explicitly send back a TOO MANY CONNECTIONS status.
>>
>> See separate email
> 
> Should I have had this already?

It was sent to the MMUSIC WG mailing list on the 24th of June. I have
forwarded if to you personally.

> 
>>
>>>
>>> s10.6: RFC 3986 has capability for dealing with IP versions beyond 6... 
>>> should these be carried over into RTSP?  The IANA registry says they are.
>>
>> I am uncertain what you want here? Yes, the URI format allows for future
>> definitions of literal IP address versions. However, RTSP does contain
>> explicit IPv4 and IPv6 address fields that aren't URIs. Thus, future IP
>> versions will require some extension definition to function.
> 
> Perhaps an excess of zeal on my behalf.  Perhaps a (non-normative) note
> saying what you just wrote: 'Although the general URI format envisages 
> potential future new versions of the literal IP address, usage of any
> such new version would require other modifications to the RTSP
> specofication (e.g., ...[any relevant section(s)]).' 

Yes, I added such text.

>>
>>>
>>> s10.7, last para: Should the doubling of the wait timer have an upper limit?
>>
>> Yes, I added an upper limit of 30 minutes. This is way beyond what any
>> human will accept, only robots will keep on going at this timeout value.
>> And I think that is large enough to avoid any issues.
> 
> Agreed
> 
>>
>> I also propose to clarify the range for the variations and added the
>> classical 0.5 to 1.5 times the deterministic value.
>>
>> Text proposal.
>>
>> That timer MUST be doubled for each additional failure to connect or
>> receive response until the value exceeds 30 minutes when the timers
>> deterministic value may be set to 30 minutes. It is RECOMMENDED to not
>   ^^^^^^^^^^^^^
>   base?
>> set the same value in the timer for each scheduling, but instead to add
>> a variation to the mean value, resulting in picking a random value
>> within the range of 0.5 to 1.5 of the mean value.

This has gotten changed a bit more and currently reads:

A more complex case may arise when a load balancing RTSP proxy is in
use, i.e., where an RTSP proxy is used to select amongst a set of RTSP
servers to handle the requests, or when multiple server addresses are
available for a given server name. The proxy or client may receive a 503
(Service Unavailable) or 553 (Proxy Unavailable) from one of its RTSP
servers or proxies, or a TCP timeout (if the server is even unable to
handle the request message). The proxy or client simply retries the
other addresses or configured proxies, but may also receive a 503
(Service Unavailable) or 553 (Proxy Unavailable) response or TCP
timeouts from those addresses. In such a situation, where none of the
RTSP servers/proxies/addresses can handle the request, the RTSP agent
has to wait before it can send any new requests to the RTSP server. Any
additional request to a specific address MUST be delayed according to
the Retry-After headers received. For addresses where no response was
received or TCP timeout occurred, an initial wait timer SHOULD be set to
5 seconds. That timer MUST be doubled for each additional failure to
connect or receive response until the value exceeds 30 minutes when the
timers mean value may be set to 30 minutes. It is REQUIRED to not set
the same value in the timer for each scheduling, but instead to add a
variation to the mean value, resulting in picking a random value within
the range of 0.5 to 1.5 of the mean value.

>>
>>>
>>> s11, para 4: According to s22.1.3, play.basic, play.scale and play.speed
>>> are 'defined' in this draft.  The nearest thing to a definition of
>>> play.basic that I can find is the last sentence of para 4 in this
>>> section.  I am not convinced that I could produce an interoperable
>>> implementation of a server with this feature-tag with the one sentence
>>> 'definition'.  References to where play.xxx are defined would be useful
>>> (play.scale in s18.44, play.speed in s18.48).
>>>
>>
>> Hmmm, the other feature-tags than play.basic are pretty straightforward
>> and well contained. play-basic is really a minimal RTSP server
>> implementation according to the whole spec for media playback.
>>
>> This can probably be more clearly expressed somewhere, but it can't
>> really be enumerated. Then we are back to the issue we had with RFC 2326
>> minimal implementation list that was incomplete and lacked a lot of
>> things really necessary.
>>
>> This issue still haven't resulted in any changes to our source.
> 
> Ah!  I see I have (re-)opened a can of worms!  One thought for providing
> the proverbial larger can into which the worms can be stuffed back:
> 
> Define 'play.basic' as the default that you get back if none of the
> others apply.  How's that for weasel words!

After my leave I have written a bit of definition for play.basic:

11.1.  Feature Tag: play.basic

   The play.basic feature tag represents an RTSP implementation
   according to all normative RTSP protocol features specified in this
   specification.  This specification is both a RTSP core specification
   as well intended to enable setup and control of playback of media.
   Thus following all normative parts in the main sections (the ones
   with numbers), not the appendices (starting with letters), unless
   explicitly specified in a main section for being a required appendix.

      Note: This feature tag does not mandate any media delivery
      protocol, such as RTP.

      In RTSP 1.0 there was a minimal implementation section.  However,
      that was not consistent with the rest of the specification.  So
      rather than making an attempt to explicitly enumerate the features
      for play.basic this specification have to be read in completeness
      and the necessary features normatively defined as being required
      are included.

>>
>>
>>> s11, Supported (and Proxy-Supported) bullets: 
>>> OLD:
>>>          This results in the
>>>          receiver is learning the requester's feature support.
>>> NEW:
>>>          This results in the
>>>          receiver learning the requester's feature support 
>>>          relevant to the specified resource.
>>> [Note: I added 'specified resource' here and then thought about whether
>>> this made any sense.  It probably needs to be clearer what set of
>>> features are included in the Supported list for both requester and
>>> responder.  Are they restricted to those relevant to the specified
>>> resource that might of course be the whole server, proxy - or client?? -
>>> in which case there isn't an issue, but it might be a specific
>>> presentation - what happens then?  Affects s13.1, para 3 also.]
>>
>> Actually, I don't think it is specific to the media resource. The issue
>> with making it specific to a media resource is that a RTSP client needs
>> to be able to look into the future and supply an answer for a media
>> resource it may not yet know sufficient to provide a tailored response
>> for. I think it is simpler and better to provide general capabilities in
>> the supported header and then later determine how well they apply for
>> the media resource itself.
> 
> So maybe make it clear that feature support returned is just what the
> responder can do generally and is not specific to the URI provided.

Yes, I have tried to make it clear that it is not resource specific.

   Supported:  This header is used to determine the complete set of
         functionality that both client and server have in general and
         is not dependent on specific resource.  The intended usage is
         to determine before one needs to use a functionality that it is
         supported.  It can be used in any method, but OPTIONS is the
         most suitable one as it at the same time determines all methods
         that are implemented.  When sending a request the requester
         declares all its capabilities by including all supported
         feature-tags.  This results in the receiver is learning the
         requester's feature support.  The receiver then includes its
         set of features in the response.

   Proxy-Supported:  This header is used similarly to the Supported
         header, but instead of giving the supported functionality of
         the client or server it provides both the requester and the
         responder a view of the common functionality supported in
         general by all members of the proxy chain between the two
         supports and not dependent on the resource.  Proxies are
         required to add this header whenever the Supported header is
         present, but proxies may also add it independently of the
         requester.

I also added variations of this sentence to the Supported and
Proxy-Supported headers description:

These feature tags are the ones the server or client support in general,
and is not specific to the request resource.

> 
> Either that or make the request valid only for non-specific URIs (i.e.
> at the server/client level) if that is possible (not sure how that would
> work for server asking client if that is allowed).

Doesn't really work as supported is intended to be possible to add to
any request to determine the functionality supported by the replying agent.

cheers

Magnus Westerlund

---

From: Magnus Westerlund <[email-masked]>
Date: Wed, 28 Aug 2013 11:45:25 +0200

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
> 

-- 

Magnus Westerlund