CSS-CII Message objects¶
Module: dvbcss.protocol.cii
A CII
object represents a CII message sent from server to client via the CSS-CII protocol.
A TimelineOption
object describes a timeline selector
and the tick rate of the timeline if that selector is used to request a
timeline from the CSS-TS server. It is carried in a list in the
timelines
property of a CII
message.
Examples¶
CII
messages:
>>> from dvbcss.protocol.cii import CII
>>> from dvbcss.protocol import OMIT
>>> jsonCiiMessage = \"""\
... { "protocolVersion":"1.1",
... "contentId":"dvb://1234.5678.01ab",
... "contentIdStatus":"partial"
... }
... \"""
>>> cii = CII.unpack(jsonCiiMessage)
>>> cii.contentId
'dvb://1234.5678.01ab'
>>> print cii.mrsUrl
OMIT
>>> cii.protocolVersion = OMIT
>>> cii.pack()
'{contentId":"dvb://1234.5678.01ab","contentIdStatus":"partial"}'
TimelineOption
within CII messages:
>>> from dvbcss.protocol.cii import CII, TimelineOption
>>> t1 = TimelineOption(timelineSelector="urn:dvb:css:timeline:pts", unitsPerTick=1, unitsPerSecond=90000)
>>> t2 = TimelineOption(timelineSelector="urn:dvb:css:timeline:temi:1:1", unitsPerTick=1, unitsPerSecond=1000)
>>> print t1.timelineSelector, t1.unitsPerTick, t1.unitsPerSecond, t1.accuracy
urn:dvb:css:timeline:pts 1 90000 OMIT
>>> cii = CII(presentationStatus="final", timelines=[t1, t2])
>>> cii.pack()
'{ "presentationStatus": "final",
"timelines": [ { "timelineProperties": {"unitsPerSecond": 90000, "unitsPerTick": 1},
"timelineSelector": "urn:dvb:css:timeline:pts"
},
{ "timelineProperties": {"unitsPerSecond": 1000, "unitsPerTick": 1},
"timelineSelector": "urn:dvb:css:timeline:temi:1:1"
}
]
}'
Classes¶
CII Message¶
- class
dvbcss.protocol.cii.
CII
(**kwargs)[source]¶Object representing a CII message used in the CSS-CII protocol.
Initialisation takes the following parameters, all of which are optional keyword arguments that default to
OMIT
:
Parameters:
- protocolVersion (
OMIT
or “1.1”) – The protocol version being used by the server.- mrsUrl (
OMIT
orstr
) – The URL of an MRS server known to the server.- contentId (
OMIT
orstr
) – Content identifier URI.- contentIdStatus (
OMIT
or “partial” or “final”) – Content identifier status.- presentationStatus (
OMIT
orlist
ofstr
) – Presentation status as alist
of one or more strings, e.g.[ "okay" ]
- wcUrl (
OMIT
orstr
) – CSS-WC server endpoint URL in the form “udp://<host>:<port>”- tsUrl (
OMIT
orstr
) – CSS-TS server endpoint WebSocket URL- teUrl (
OMIT
orstr
) – CSS-TE server endpoint WebSocket URL- timelines (
OMIT
orlist
ofTimelineOption
) – List of timeline options.- private (
OMIT
or Signalling that a property is to be omitted from a message) – Private data.The attributes of the object have the same name as the CII message properties:
protocolVersion
mrsUrl
contentId
contentIdStatus
presentationStatus
wcUrl
tsUrl
teUrl
timelines
private
Properties are accessed as attributes of this object using the same name as their JSON property name.
Converting to and from JSON representation is performed using the
pack()
method andunpack()
class method. Properties set to equalOMIT
will be omitted when the message is packed to a JSON representation.
protocolVersion
= OMIT[source]¶(read/write
OMIT
or “1.1”) The protocol version being used by the server.
presentationStatus
= OMIT[source]¶(read/write
OMIT
orlist
ofstr
) Presentation status, e.g.[ "okay" ]
wcUrl
= OMIT[source]¶(read/write
OMIT
orstr
) CSS-WC server endpoint URL in form “udp://<host>:<port>”
private
= OMIT[source]¶(
OMIT
orlist
ofdict
) Private data as alist
ofdict
objects that can be converted to JSON byjson.dumps()
. Each dict must contain at least a key called “type” with a URI string as its value.
combine
(diff)[source]¶Copies this CII object, and updates that copy with any properties (that are not omitted) in the CII object supplied as the diff argument. The updated copy is then returned.
Parameters: diff – ( CII
) A CII object whose properties (that are not omitted) will be used to update the copy before it is returned.new = old.combine(diff) is equivalent to the following operations:
new = old.copy() new.update(diff)
- classmethod
diff
(old, new)[source]¶
Parameters: Returns: CII object representing changes from old to new CII objects.
If in the new CII object a property is OMITted, it property won’t appear in the returned CII object that represents the changes.
If in the old CII object a property is OMITted, but it has a non-omitted value in the new object, then it is assumed to be a change.
pack
()[source]¶
Returns: string containing JSON representation of this message. Throws ValueError: if there are values for properties that are not permitted.
- classmethod
unpack
(msg)[source]¶Convert JSON string representation of this message encoded as a
CII
object.
Throws ValueError: if not possible.
update
(diff)[source]¶Updates this CII object with the values of any properties (that are not omitted) in the CII object provided as the diff argument.
Note that this changes this object.
Parameters: diff – ( CII
) A CII object whose properties (that are not omitted) will be used to update this CII object.
Timeline Option¶
- class
dvbcss.protocol.cii.
TimelineOption
(timelineSelector, unitsPerTick, unitsPerSecond, accuracy=OMIT, private=OMIT)[source]¶Object representing a CSS-CII Timeline Option used in the “timelines” property of a CII message.
Initialisation takes the following parameters:
Parameters:
- timelineSelector (str) – The timeline selector
- unitsPerTick (int) – Denominator of tick rate (in ticks per second) for the corresponding timeline
- unitsPerSecond (int) – Numerator of tick rate (in ticks per second) for the corresponding timeline
- accuracy (
OMIT
orfloat
) – Optional indication of timeline accuracy- private (
OMIT
or Signalling that a property is to be omitted from a message) – Optional private data.It represents a timeline selector and the tick rate of the timeline if that selector is used to request a timeline from the CSS-TS server. It is carried in a
list
in thetimelines
property of aCII
message.The tick rate of the timeline is expressed by the unitsPerTick and unitsPerSecond values. The tick rate in ticks per second is equal to unitsPerTick / unitsPerSecond.
Accuracy and private data are optional, but the other fields are mandatory.
The attributes of the object have the same name as the relevant CII message properties:
Converting to and from JSON representation is performed using the
pack()
method andunpack()
class method. Properties set to equalOMIT
will be omitted when the message is packed to a JSON representation.
accuracy
= OMIT[source]¶(
OMIT
orfloat
) The accuracy of the timeline with respect to the content in seconds.
private
= OMIT[source]¶(
OMIT
orlist
ofdict
) Private data as alist
ofdict
objects that can be converted to JSON byjson.dumps()
. Each dict must contain at least a key called “type” with a URI string as its value.
- classmethod
decode
(struct)[source]¶Internal method used by a
CII
message object when unpacking to JSON format.
- classmethod
encode
(item)[source]¶Internal class method used by a
CII
message object when packing to JSON format.
- classmethod
unpack
(msg)[source]¶Convert JSON string representation of this message encoded as a
TimelineOption
object.
Throws ValueError: if not possible.