CSS-CII Clients¶

Module: dvbcss.protocol.client.cii

Using CIIClient
Using CIIClientConnection
Classes
- CIIClient
- CIIClientConnection

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() and disconnect() methods connect and disconnect the connection to the server and getStatusSummary() 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 server
latestCII is the most recently CII message received from the server
connected 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”)

connected[source]¶: True if currently connected to the server, otherwise False.

cii[source]¶: (CII) CII object representing the CII state at the server

latestCII[source]¶: (CII or None) 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.

disconnect()[source]¶: Disconnect from the server.

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` of `str` names of the properties that have changed. Query the `cii` 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:	code – (`int`) The connection closure code to be sent in the WebSocket disconnect frame reason – (`str` or `None`) The human readable reason for the closure

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.

onTsUrlChange(newValue)[source]¶

Called when the tsUrl 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.

onWcUrlChange(newValue)[source]¶

Called when the wcUrl 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:

onConnected()
onDisconnected()
onCII()
onProtocolError()

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.

connected[source]¶: True if the connection is connect, otherwise False

disconnect(code=1001, reason='')[source]¶

Close the connection.

Parameters:	code – (optional `int`) The connection closure code to be sent in the WebSocket disconnect frame reason – (optional `str`) The human readable reason for the closure

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.

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:	code – (`int`) The connection closure code to be sent in the WebSocket disconnect frame reason – (`str` or `None`) The human readable reason for the closure

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.

CSS-CII Clients¶

Using CIIClient¶

Using CIIClientConnection¶

Classes¶

CIIClient¶

CIIClientConnection¶

Using CIIClient ¶

Using CIIClientConnection ¶

Classes ¶