CSS-CII Clients¶
Module: dvbcss.protocol.client.cii
There are two classes provided for implementing CSS-CII clients:
CIIClient
connects to a CII server and provides a CII message object representing the complete state of the server and notifies you of changes of state.CIIClientConnection
provides a lower level connection to a CII server and only provides the messages received from the server. It does not maintain a model of the server state and does not work out when a received message constitutes a change.
An example client is provided in this package that uses the CIIClient
class.
Using CIIClient¶
This is the simplest class to use. Create it, passing the URL of the server to connect to,
then call connect()
and disconnect()
to connect and disconnect from the server.
CIIClient maintains a local copy of the state of CII data the CIIClient.cii
property and the most
recently received CII message in CIIClient.latestCII
.
You can use the class either by subclassing and overriding the various stub methods or by creating an instance and replacing the stub methods with your own function handlers dynamically.
Pass the WebSocket URL of the CII server when creating the CIIClient then call the connect()
and disconnect()
methods to connect and disconnect from the server. The onXXX() methods
can be overriden to find out when connection or disconnection takes place, if there is a protocol error (e.g.
a message was received that could not be parsed as CII) or when properties of the CII data change.
The CII state is kept in the cii
property of the object. This is updated with properties
in CII messages that are received. Properties not included in a CII message are left unchanged.
Properties of the CII state whose value is dvbcss.protocol.OMIT
have not been defined by the CII server.
from dvbcss.protocol.client.cii import CIIClient
class MyCIIClient(CIIClient):
def onConnected(self):
print "Connected!"
def onDisconnected(self, code, reason):
print "Disconnected :-("
def onChange(self, propertyNames):
print "The following CII properties have changed:
for name in propertyNames:
value = getattr(conn.cii, name)
print " "+name+" is now: "+str(value)
# one example of a handler for changes to a particular property 'contentId' in CII
def onContentIdChange(self, newValue):
print "The contentId property has changed to now be: "+str(newValue)
client = MyCIIClient("ws://127.0.0.1/cii")
client.connect()
time.sleep(60)
print "The current contentId is "+client.cii.contentId
time.sleep(60) # wait only 60 more seconds then disconnect
client.disconnect()
The client runs in a separate thread managed by the websocket client library, so the onXXX methods are called while the main thread sleeps.
Using CIIClientConnection¶
This is a lower level class, that only implements parsing of the incoming CII messages from the server. It does not detect if a message actually constitutes a change of state or not.
You can use the class either by subclassing and overriding the various stub methods or by creating an instance and replacing the stub methods with your own function handlers dynamically.
Pass the WebSocket URL of the CII server when creating the CIIClientConnection object then call the connect()
and disconnect()
methods to connect and disconnect from the server. The onXXX() methods
can be overridden to find out when connection or disconnection takes place, if there is a protocol error (e.g.
a message was received that could not be parsed as CII) or when a new CII message is received.
from dvbcss.protocol.client.cii import CIIClientConnection
class MyCIIClientConnection(CIIClientConnection):
def onConnected(self):
print "Connected!"
def onDisconnected(self, code, reason):
print "Disconnected :-("
def onCii(self, cii):
print "Received a CII message: "+str(cii)
client = MyCIIClientConnection("ws://127.0.0.1/cii")
client.connect()
time.sleep(60) # run only for 60 seconds then disconnect
client.disconnect()
Classes¶
CIIClient¶
-
class
dvbcss.protocol.client.cii.
CIIClient
(ciiUrl)[source]¶ Manages a CSS-CII protocol connection to a CSS-CII Server and notifies of changes to CII state.
Use by subclassing and overriding the following methods:
onConnected()
onDisconnected()
onChange()
- individual onXXXXChange() methods named after each CII property
onCiiReceived()
(do not use, by preference)
If you do not wish to subclass, you can instead create an instance of this class and replace the methods listed above with your own functions dynamically.
The
connect()
anddisconnect()
methods connect and disconnect the connection to the server andgetStatusSummary()
provides a human readable summary of CII state.This object also provides properties you can query:
cii
represents the current state of CII at the serverlatestCII
is the most recently CII message received from the serverconnected
indicates whether the connection is currently connect
Initialisation takes the following parameters:
Parameters: ciiUrl – ( str
) The WebSocket URL of the CSS-CII Server (e.g. “ws://127.0.0.1/myservice/cii”)-
latestCII
[source]¶ (
CII
orNone
) The most recent CII message received from the server or None if nothing has yet been received.
-
connect
()[source]¶ Start the client by trying to open the connection.
Throws ConnectionError: There was a problem that meant it was not possible to connect.
-
onChange
(changedPropertyNames)[source]¶ This method is called when a CII message is received from the server that causes one or more of the CII properties to change to a different value.
Parameters: changedPropertyNames – A list
ofstr
names of the properties that have changed. Query thecii
attribute to find out the new values.
-
onCiiReceived
(newCii)[source]¶ This method is called when a CII message is received, but before any ‘onXXXXChange()’ handlers (if any) are called. It is called even if the message does not result in a change to CII state held locally.
By preference is recommended to use the ‘onXXXXChange()’ handlers instead since these will only be called if there is an actual change to the value of a property in CII state.
This is a stub for this method. Sub-classes should implement it.
Parameters: cii – A CII
object representing the received message.
-
onConnected
()[source]¶ This method is called when the connection is opened.
This is a stub for this method. Sub-classes should implement it.
-
onContentIdChange
(newValue)[source]¶ Called when the contentId property of the CII message has been changed by a state update from the CII Server.
This is a stub for this method. Sub-classes should implement it.
Parameters: newValue – The new value for this property.
-
onContentIdStatusChange
(newValue)[source]¶ Called when the contentIdStatus property of the CII message has been changed by a state update from the CII Server.
This is a stub for this method. Sub-classes should implement it.
Parameters: newValue – The new value for this property.
-
onDisconnected
(code, reason=None)[source]¶ This method is called when the connection is closed.
This is a stub for this method. Sub-classes should implement it.
Parameters:
-
onMrsUrlChange
(newValue)[source]¶ Called when the mrsUrl property of the CII message has been changed by a state update from the CII Server.
This is a stub for this method. Sub-classes should implement it.
Parameters: newValue – The new value for this property.
-
onPresentationStatusChange
(newValue)[source]¶ Called when the presentationStatus property of the CII message has been changed by a state update from the CII Server.
This is a stub for this method. Sub-classes should implement it.
Parameters: newValue – The new value for this property.
-
onPrivateChange
(newValue)[source]¶ Called when the private property of the CII message has been changed by a state update from the CII Server.
This is a stub for this method. Sub-classes should implement it.
Parameters: newValue – The new value for this property.
-
onProtocolError
(msg)[source]¶ This method is called when there has been an error in the use of the CII protocol - e.g. receiving the wrong kind of message.
This is a stub for this method. Sub-classes should implement it.
Parameters: msg – A str
description of the problem.
-
onProtocolVersionChange
(newValue)[source]¶ Called when the protocolVersion property of the CII message has been changed by a state update from the CII Server.
This is a stub for this method. Sub-classes should implement it.
Parameters: newValue – The new value for this property.
-
onTeUrlChange
(newValue)[source]¶ Called when the teUrl property of the CII message has been changed by a state update from the CII Server.
This is a stub for this method. Sub-classes should implement it.
Parameters: newValue – The new value for this property.
-
onTimelinesChange
(newValue)[source]¶ Called when the timelines property of the CII message has been changed by a state update from the CII Server.
This is a stub for this method. Sub-classes should implement it.
Parameters: newValue – The new value for this property.
CIIClientConnection¶
-
class
dvbcss.protocol.client.cii.
CIIClientConnection
(url)[source]¶ Simple object for connecting to a CSS-CII server and handling the connection.
Use by subclassing and overriding the following methods:
If you do not wish to subclass, you can instead create an instance of this class and replace the methods listed above with your own functions dynamically.
Initialisation takes the following parameters:
Param: url ( str
) The WebSocket URL of the CII Server to connect to. E.g. “ws://127.0.0.1/mysystem/cii”-
connect
()[source]¶ Open the connection.
:throws
ConnectionError
if there was a problem and the connection could not be opened.
-
onCII
(cii)[source]¶ This method is called when a CII message is received from the server.
This is a stub for this method. Sub-classes should implement it.
Parameters: cii – A CII
object representing the received message.
-
onConnected
()[source]¶ This method is called when the connection is opened.
This is a stub for this method. Sub-classes should implement it.
-