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 or str) – The URL of an MRS server known to the server.
  • contentId (OMIT or str) – Content identifier URI.
  • contentIdStatus (OMIT or “partial” or “final”) – Content identifier status.
  • presentationStatus (OMIT or list of str) – Presentation status as a list of one or more strings, e.g. [ "okay" ]
  • wcUrl (OMIT or str) – CSS-WC server endpoint URL in the form “udp://<host>:<port>”
  • tsUrl (OMIT or str) – CSS-TS server endpoint WebSocket URL
  • teUrl (OMIT or str) – CSS-TE server endpoint WebSocket URL
  • timelines (OMIT or list of TimelineOption) – 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:

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 and unpack() class method. Properties set to equal OMIT 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.

mrsUrl = OMIT[source]

(read/write OMIT or str) The URL of an MRS server known to the server

contentId = OMIT[source]

(read/write OMIT or str) Content identifier (URL)

contentIdStatus = OMIT[source]

(read/write OMIT or “partial” or “final”) Content identifier status

presentationStatus = OMIT[source]

(read/write OMIT or list of str) Presentation status, e.g. [ "okay" ]

wcUrl = OMIT[source]

(read/write OMIT or str) CSS-WC server endpoint URL in form “udp://<host>:<port>”

tsUrl = OMIT[source]

(read/write OMIT or str) CSS-TS server endpoint WebSocket URL

teUrl = OMIT[source]

(read/write OMIT or str) CSS-TE server endpoint WebSocket URL

timelines = OMIT[source]

(read/write OMIT or list`(:class:`TimelineOption)) Timeline options

private = OMIT[source]

(OMIT or list of dict ) Private data as a list of dict objects that can be converted to JSON by json.dumps(). Each dict must contain at least a key called “type” with a URI string as its value.

classmethod allProperties()[source]

Returns a list of all property names, whether OMITted or not

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)
copy()[source]
Returns:a copy of this CII object. The copy is a deep copy.
definedProperties()[source]

Returns a list of the names of properties whose value is not OMIT

classmethod diff(old, new)[source]
Parameters:
  • old – (CII) A CII object
  • new – (CII) A CII object
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 or float) – 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 the timelines property of a CII 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 and unpack() class method. Properties set to equal OMIT will be omitted when the message is packed to a JSON representation.

timelineSelector = OMIT[source]

(str) The timeline selector

unitsPerTick = OMIT[source]

(int) The units per tick of the timeline

unitsPerSecond = OMIT[source]

(int) The units per second of the timeline

accuracy = OMIT[source]

(OMIT or float) The accuracy of the timeline with respect to the content in seconds.

private = OMIT[source]

(OMIT or list of dict ) Private data as a list of dict objects that can be converted to JSON by json.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.

pack()[source]
Returns:string containing JSON presentation of this message.
classmethod unpack(msg)[source]

Convert JSON string representation of this message encoded as a TimelineOption object.

Throws ValueError:
 if not possible.