Tuner Reservation

Description

Tuner Reservation

The TunerReservation object represents a requested or granted tuner reservation. The reservation has a validity window that is indicated by startTime and duration. The requesting device is required to renew a reservation before its validity window disappears. If it is not renewed, the token will be released by TRM and all messages that follow bearing the token will be considered as MalformedRequest . For Record reservations, the requested startTime should be N seconds ahead of the actual recording start time (or should be left out so that the granted reservation starts at the time when it is granted by TRM), to give room in case a conflict needs to be resolved.

A same reservationToken can be reused if and only if values of {device, activity} are the same. In the case, the {serviceLocator, startTime, duration} of the reused token can be updated. This is useful during a channel change, where the TRM client can reuse a same Live tuner reservation by just updating the serviceLocator of it.

A reservation is renewed by requesting tunerRreservation with a same reservationToken.

TunerReservation :=
{
    "reservationToken" (optional) : [String] reservationToken,
    "device"                      : [String] device,
    "serviceLocator"              : [String] sourceLocator,
    "startTime" (optional)        : [long] startTime,
    "duration" (optional)         : [long] duration
    "activity"                    : <Activity>
    "customAttributes" (optional) : <CustomAttributes>
}

• token: a unique token generated when a reservation is created. After a reservation is created, this token is used in all messages to uniquely identify an existing reservation within TRM.
• device: the remote device requesting the reservation. For a hot recording, this should be the receiverId of the originating device.
• serviceLocator: locator of the service that the tuner will tune to.
• startTime:start time of the reservation in milliseconds from the epoch. If not present in a request message, this is set to when the reservation is granted or renewed. startTime is always included in a response message.
• duration: the reservation period measured from the start in milliseconds. If not present in a request message, the token is valid for a default duration. duration is always included in a response message.
• activity: the granted activity. Granted activity may or may not be the same as the requested. In the latter case the owner of the reservation will need to comply with the returned activity, or initiate conflict resolution.
  For example, when a client requests Live activity when EAS is in progress, the returned reservation will have the EAS activity.
• customAttributes: a set of attributes assigned by the application. These attributes are associated with the reservation token for the lifetime of the reservation.

Response Status

All response messages from TRM will provide information regarding the status of the response. Responses to recognized requests may contain additional information, as described in later sections of this document. Responses to unrecognized requests will contain only this status data, consisting of a status code and message signifying the request was unrecognized.

ResponseStatus := {
   "status"                   : [String] status,
   "statusMessage" [optional] : [String] statusMessage
}

Where the fields are defined as follows:
status: is an enumeration of strings indicating the status of the request.

• Ok Request was successful.
• GeneralError Request was unsuccessful.
• MalFormedRequest Unexpected/Invalid request data.
• UnRecognizedRequest Unrecognized request.
• InsufficientResource: there is no tuner available.
• UserCancellation: Token is released as result of user cancellation.
• InvalidToken: Token included in the message is invalid.
• InvalidState: Token is in invalid state.
• statusMessage: is a string containing additional information about the status.

Modules
	Tuner Reservation Classes