[MRCPv2 protocol introduction] Generic Message Headers

MRCPv2 is the abbreviation of Media Resource Control Protocol Version 2 (MRCPv2). This article translates RFC6787 section 6.2. Generic Message Headers

6.2. Generic Message Headers

All MRCPv2 header fields, including the generic headers defined in the following subsections and the resource-specific header fields defined later, follow the same general format as given in Section 3.1 of RFC 5322 [RFC5322].

Each header field consists of a name followed by a colon (":") and value. Header field names are not case sensitive. The value can be preceded by any number of LWS (linear whitespace), but a single SP (space) is preferred.

Header fields can extend over multiple lines by using at least one SP or HT (horizontal tab) before each additional line.

   generic-field  = field-name ":" [ field-value ]
   field-name     = token
   field-value    = *LWS field-content *( CRLF 1*LWS field-content)
   field-content  = <the OCTETs making up the field-value
                    and consisting of either *TEXT or combinations
                    of token, separators, and quoted-string>

The field content does not include any leading or trailing LWS (that is, linear white space that occurs before the first non-white-space character of a field value or after the last non-white-space character of a field value). Such leading or trailing LWS can be removed without changing the field value semantics.
Any LWS occurring between field contents may be replaced with a single SP before interpreting the field value or forwarding the message downstream.

MRCPv2 servers and clients MUST NOT rely on header field order . It is recommended to send the general header fields first, then the request or response header fields, and finally the entity header fields.
However, MRCPv2 servers and clients MUST be prepared to process header fields in any order. The only exception to this rule is when there are multiple header fields with the same name in the message.

Multiple header fields with the same name may appear in a message if and only if the entire value of that header field is defined as a comma-separated list.

Since vendor/vendor-specific parameters may be order-dependent, it must be possible to combine multiple header fields of the same name into a single "name:value" pair without changing the semantics of the message, by appending each subsequent value to the first, each separated by a comma. Therefore, the order in which header fields with the same name are received is important for the interpretation of composite header field values, so intermediaries MUST NOT change the order of these values ​​when forwarding messages.

generic-header      =    channel-identifier
                       /    accept
                       /    active-request-id-list
                       /    proxy-sync-id
                       /    accept-charset
                       /    content-type
                       /    content-id
                       /    content-base
                       /    content-encoding
                       /    content-location
                       /    content-length
                       /    fetch-timeout
                       /    cache-control
                       /    logging-tag
                       /    set-cookie
                       /    vendor-specific

6.2.1. Channel-Identifier

All MRCPv2 requests, responses and events MUST contain a Channel-Identifier header field . This value is assigned by the server when the control channel is added to the session and communicated to the client via the " a=channel " attribute in the SDP reply from the server.

The header field value consists of two parts separated by the "@" symbol. The first part is an unambiguous string used to identify the MRCPv2 session. The second part is a string tag specifying one of the media processing resource types listed in Section 3.1.
The unambiguous string (first part) must be hard to guess, unique within the resource instance managed by the server, and common to all resource channels established with that server over a single SIP conversation.

   channel-identifier  = "Channel-Identifier" ":" channel-id CRLF
   channel-id          = 1*alphanum "@" 1*alphanum

6.2.2. Accept

The Accept header field follows the syntax defined in [H14.1]. The semantics are also the same, except that if the Accept header field is absent, the server MUST assume a default value specific to the resource type being controlled. This default can be changed for resources in the session by sending this header field in the SET-PARAMS method. The current default value of this header field for resources in the session can be found via the GET-PARAMS method. This header field may be present in any request.

6.2.3. Active-Request-Id-List

In a request, this header field indicates the list of request IDs to which the request applies. This is useful when there are multiple requests in PENDING or IN-PROGRESS and the client wants this request to apply exclusively to one or more of them.

In responses, this header field returns a list of request IDs modified or affected by this method. There may be one or more requests in PENDING or IN-PROGRESS request status. When a method affecting one or more PENDING or IN-PROGRESS requests is sent from a client to a server, the response MUST contain in its headers a list of request IDs affected or modified by this command.

Active-Request-Id-List is only used for requests and responses, not for events .

For example, if a STOP request without an Active-Request-Id-List is sent to a (speech) synthesis resource that has one or more SPEAK requests in the PENDING or IN-PROGRESS state , all SPEAK requests MUST be canceled, Including status is IN-PROGRESS. The response to a STOP request contains the Request-IDs of all terminated SPEAK requests in the Active-Request-Id-List value. After sending a STOP response, the server MUST NOT send any SPEAK-COMPLETE or RECOGNITION-COMPLETE events for the terminated request .

active-request-id-list  =  "Active-Request-Id-List" ":"
                             request-id *("," request-id) CRLF

6.2.4. Proxy-Sync-Id

When any server resource generates a " barge -in-able " event , it also generates a unique tag . The token is sent to the client in the event as the value of this header field. The client then acts as an intermediary between the server resources and sends a BARGE-IN-OCCURRED method to the (speech) synthesis server resource using the Proxy-Sync-Id received from the server resource . When (speech) recognizer and (speech) synthesizer resources belong to the same session, they may choose to work together for faster interaction and response. Here, the Proxy-Sync-Id helps the resource receiving the event (mediated by the client) to decide whether this event has been handled by the resource's direct interaction.

This header field may only appear on **event (event)** and BARGE-IN-OCCURRED methods. The name of this header field contains the word "proxy" for historical reasons only, and is not meant to imply that a proxy server is involved.

proxy-sync-id    =  "Proxy-Sync-Id" ":" 1*VCHAR CRLF

6.2.5. Accept-Charset

See [H14.2]. This specifies the acceptable character set for entities returned in responses or events associated with this request. This is useful for specifying the character set to be used in Natural Language Semantic Markup Language (NLSML) results of RECOGNITION-COMPLETE events. This header field is only used for requests .

6.2.6. Content-Type

See [H14.17]. MRCPv2 supports a restricted set of media types for content registration, including speech markup , grammar (gramma) and recognition results (recognition results) . The content types applicable to each MRCPv2 resource type are specified in the corresponding section of the document and registered in the MIME Media Type Registry maintained by IANA. The multipart content type " multipart/mixed " is supported to convey multiples of the above content, in which case the body part MUST NOT contain any MRCPv2 specific header fields. This header field may be present in all messages .

  content-type     =    "Content-Type" ":" media-type-value CRLF

   media-type-value =    type "/" subtype *( ";" parameter )

   type             =    token

   subtype          =    token

   parameter        =    attribute "=" value

   attribute        =    token

   value            =    token / quoted-string

6.2.7. Content-ID

This header field contains the ID or name of the referable content. This header field operates according to the specifications in RFC 2392 [RFC2392] and is required for content disambiguation in multipart messages. In MRCPv2, whenever the client or server stores the relevant content, it must be retrievable using this ID. Such content can be referenced later in a session by addressing it using the "session" URI scheme described in Section 13.6. This header field may be present in all messages .

6.2.8. Content-Base

The Content-Base entity header can be used to specify the base URI used to resolve relative URIs within the entity.

content-base      = "Content-Base" ":" absoluteURI CRLF

Note, however, that the base URI for content in an entity body can be redefined within that entity body. An example of this is multipart media, which in turn can contain multiple entities within it. This header field may be present in all messages .

6.2.9. Content-Encoding

The Content-Encoding entity header is used as a modifier for the Content-Type. If present, its value indicates which additional content encodings have been applied to the entity-body, and thus which decoding mechanisms must be applied to obtain the media type referenced by the Content-Type header field. Content encoding is primarily used to allow compression of documents without losing the identity of their underlying media type. Note that SIP sessions can be used to determine accepted encodings (see Section 7). This header field may be present in all messages.

content-encoding  = "Content-Encoding" ":"
                       *WSP content-coding
                       *(*WSP "," *WSP content-coding *WSP )
                       CRLF

Content-encodings are defined in [H3.5]. An example of its usage is Content-Encoding:gzip

If multiple encodings have been applied to an entity, the content encodings MUST be listed in the order in which they were applied.

6.2.10. Content-Location

The Content-Location entity header MAY be used to provide the resource location for the entity contained in the message when the entity is accessible from a location separate from the URI of the requested resource. Refer to [H14.14].

content-location  =  "Content-Location" ":"
                        ( absoluteURI / relativeURI ) CRLF

The Content-Location value is a declaration of the location of the resource corresponding to this particular entity at the time of the request. This header field is used for optimization purposes only. Recipients of this header MAY assume that the entity being sent is the same entity that was or might have been retrieved from the Content-Location URI .

For example, if the client provides an inline syntax markup and it has previously retrieved it from a URI, the URI can be provided as part of the entity using the Content-Location header field. This allows a resource like a recognizer to look into its cache to see if this grammar has been previously retrieved, compiled and cached. In this case, it may use previously compiled syntax objects for optimization.

If the Content-Location is a relative URI, the relative URI is interpreted relative to the Content-Base URI . This header field may be present in all messages.

6.2.11. Content-Length

This header field contains the length of the message body content (ie, after the double CRLF after the last header field). Unlike HTTP, it must be included in all messages that carry content beyond the headers. If missing, a default value of zero is assumed . Otherwise, interpret as in [H14.13]. When a message with no use for the message body contains a message, ie the Content-Length is non-zero, the receiver MUST ignore the contents of the message body. This header field may be present in all messages.

content-length  =  "Content-Length" ":" 1*19DIGIT CRLF

6.2.12. Fetch Timeout

When a (speech) recognizer or (speech) synthesizer needs to retrieve a document or other resource, this header field controls the corresponding URI access attributes. This defines a timeout for content that the server may need to fetch over the network. The value is interpreted as milliseconds and ranges from 0 to an implementation-specific maximum value. Servers are advised to be cautious about accepting long timeout values. The default value of this header field is implementation specific. This header field may appear in DEFINE-GRAMMAR, RECOGNIZE, SPEAK, SET-PARAMS or GET-PARAMS.

fetch-timeout       =   "Fetch-Timeout" ":" 1*19DIGIT CRLF

6.2.13. Cache-Control

If a server implements content caching, it MUST obey the cache-correctness rules of HTTP 1.1 [ RFC2616 ] when accessing and caching stored content . In particular, the "expires" and "cache-control" header fields of cached URIs or documents MUST be respected, taking precedence over the Cache-Control defaults set by this header field.

The Cache-Control directive is used to define the default caching algorithm on the server for a session or request. The scope of a command is based on the method by which it is sent. If this directive is sent on the SET-PARAMS method, it applies to all requests made by the server for external documents during that session, unless it is overridden by an individual request's Cache-Control header field.

If directives are sent for any other request, they apply only to external document requests made by the server for that request. An empty Cache-Control header field in the GET-PARAMS method is a request to the server to return the current Cache-Control directive settings on the server. This header field may only be present on request.

   cache-control    =    "Cache-Control" ":"
                         [*WSP cache-directive
                         *( *WSP "," *WSP cache-directive *WSP )]
                         CRLF

   cache-directive     = "max-age" "=" delta-seconds
                       / "max-stale" [ "=" delta-seconds ]
                       / "min-fresh" "=" delta-seconds

   delta-seconds       = 1*19DIGIT

Here, delta-seconds is a decimal time value specifying the number of seconds elapsed from the moment the server received the message response or data.

Different cache directive options allow clients to ask the server to override the default cache expiration mechanism:

   max-age        Indicates that the client can tolerate the server
                  using content whose age is no greater than the
                  specified time in seconds.  Unless a "max-stale"
                  directive is also included, the client is not willing
                  to accept a response based on stale data.

   min-fresh      Indicates that the client is willing to accept a
                  server response with cached data whose expiration is
                  no less than its current age plus the specified time
                  in seconds.  If the server's cache time-to-live
                  exceeds the client-supplied min-fresh value, the
                  server MUST NOT utilize cached content.

   max-stale      Indicates that the client is willing to allow a server
                  to utilize cached data that has exceeded its
                  expiration time.  If "max-stale" is assigned a value,
                  then the client is willing to allow the server to use
                  cached data that has exceeded its expiration time by
                  no more than the specified number of seconds.  If no
                  value is assigned to "max-stale", then the client is
                  willing to allow the server to use stale data of any
                  age.

If a server cache is requested to use unvalidated stale responses/data, it will only do so if this does not conflict with any "must" level requirements regarding cache validation (e.g. "must revalidate" cache-control directives). This can only be done according to the HTTP 1.1 specification associated with the corresponding URI).

If both the MRCPv2 Cache-Control directive and the cache entry on the server contain a "max-age" directive, the lesser of the two values ​​is used to determine the freshness of the cache entry for that request.

6.2.14. Logging-Tag

This header field can be sent as part of the SET-PARAMS/GET-PARAMS methods to set or retrieve logging tags for server-generated logs. Once set, the value persists until a new value is set or the session ends. MRCPv2 servers can provide a mechanism to create subsets of their output logs so that system administrators can examine or extract only the portion of the log file during which the log flag is set to a specific value.

Clients are advised to include information identifying the MRCPv2 client user agent in the logging tag information so that it can determine which MRCPv2 client request generated a given log message on the server. MRCPv2 clients are also advised not to log personally identifiable information, such as credit card numbers and national identification numbers.

logging-tag    = "Logging-Tag" ":" 1*UTFCHAR CRLF

6.2.15. Set-Cookie

Since the associated HTTP client on the MRCPv2 server fetches documents for processing on behalf of the MRCPv2 client, the cookie storage in the HTTP client of the MRCPv2 server is considered an extension of the cookie storage in the HTTP client of the MRCPv2 client.

This requires MRCPv2 clients and servers to be able to synchronize their common cookie stores as needed. In order for an MRCPv2 client to be able to push its stored cookie to the MRCPv2 server and get a new cookie from the MRCPv2 server to store back to the MRCPv2 client, the Set-Cookie entity header field can be included in the MRCPv2 request to update the cookie stored on the server and in Returned in the final MRCPv2 response or event to subsequently update the client's own cookie store. Cookies stored on the server persist for the duration of an MRCPv2 session and must be destroyed at the end of the session. To ensure cookie support, MRCPv2 clients and servers must support the Set-Cookie entity header field.

Note that it is the MRCPv2 client that decides which cookies (if any) are sent to the server. Not all cookies are required to be shared. Instead, it is recommended that MRCPv2 clients transmit only the cookies that the MRCPv2 server needs to process its requests.

 set-cookie      =       "Set-Cookie:" cookies CRLF
 cookies         =       cookie *("," *LWS cookie)
 cookie          =       attribute "=" value *(";" cookie-av)
 cookie-av       =       "Comment" "=" value
                 /       "Domain" "=" value
                 /       "Max-Age" "=" value
                 /       "Path" "=" value
                 /       "Secure"
                 /       "Version" "=" 1*19DIGIT
                 /       "Age" "=" delta-seconds
 set-cookie        = "Set-Cookie:" SP set-cookie-string
 set-cookie-string = cookie-pair *( ";" SP cookie-av )
 cookie-pair       = cookie-name "=" cookie-value
 cookie-name       = token
 cookie-value      = *cookie-octet / ( DQUOTE *cookie-octet DQUOTE )
 cookie-octet      = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E
 token             = <token, defined in [RFC2616], Section 2.2>
 cookie-av         = expires-av / max-age-av / domain-av /
                      path-av / secure-av / httponly-av /
                      extension-av / age-av
 expires-av        = "Expires=" sane-cookie-date
 sane-cookie-date  = <rfc1123-date, defined in [RFC2616], Section 3.3.1>
 max-age-av        = "Max-Age=" non-zero-digit *DIGIT
 non-zero-digit    = %x31-39
 domain-av         = "Domain=" domain-value
 domain-value      = <subdomain>
 path-av           = "Path=" path-value
 path-value        = <any CHAR except CTLs or ";">
 secure-av         = "Secure"
 httponly-av       = "HttpOnly"
 extension-av      = <any CHAR except CTLs or ";">
 age-av            = "Age=" delta-seconds

The Set-Cookie header field is specified in RFC 6265 [RFC6265]. The " Age " attribute is introduced in this specification to indicate the age of the cookie and is optional. An MRCPv2 client or server MUST calculate the cookie's age according to the age calculation rules in the HTTP/1.1 specification [RFC2616] and append the " Age " attribute accordingly . This property is provided because some time may have passed since the client received the cookie from the HTTP server.

Instead of having the client decrement the Max-Age by its actual age, it passes the Max-Age verbatim with an "Age" attribute appended, thus keeping the received cookie while still taking into account the fact that time has passed.

MRCPv2 clients or servers MUST provide default values ​​for the " Domain " and " Path " attributes, as specified in RFC 6265, if they are omitted by the HTTP origin server. Note that in this case there is no leading dot in the "Domain" attribute value. An MRCPv2 client or server MUST NOT modify the "domain" value when received over the MRCPv2 protocol, although an explicitly specified "domain" value received over the HTTP protocol may be modified to include a leading dot.

An MRCPv2 client or server MAY combine multiple cookie header fields of the same type into a "field name: field value" pair, as described in Section 6.2.

The Set-Cookie header field can be specified in any request that subsequently causes the server to perform an HTTP access. When a server receives new cookie information from an HTTP origin server, assuming the cookie store has been modified according to RFC 6265, the server MUST return new cookie information in an MRCPv2 COMPLETE response or event as needed to allow the client to update its own cookies shop.

A SET-PARAMS request may specify a Set-Cookie header field to update the cookie store on the server. A GET-PARAMS request can be used to return the entire cookie store for a "Set-Cookie" type cookie to the client.

6.2.16. Vendor-Specific Parameters

This set of header fields allows clients to set or retrieve vendor-specific parameters.

   vendor-specific          =    "Vendor-Specific-Parameters" ":"
                                 [vendor-specific-av-pair
                                 *(";" vendor-specific-av-pair)] CRLF

   vendor-specific-av-pair  = vendor-av-pair-name "="
                              value

   vendor-av-pair-name     = 1*UTFCHAR

This form of header field can be sent in any method (request) and is used to manage implementation-specific parameters on the server side.
vendor-av-pair-name follows reverse Internet domain name conventions (see Section 13.1.6 for syntax and registration information). The value of the vendor attribute is specified after the "=" sign and can be quoted. For example:

   com.example.companyA.paramxyz=256
   com.example.companyA.paramabc=High
   com.example.companyB.paramxyz=Low

When used in GET-PARAMS to obtain the current values ​​of these parameters from the server, this header field value may contain a semicolon-separated list of implementation-specific property names.