SMSDomain API – device

Specs

The technical specification defining the payloads in this section can be found in the Service Delivery Platform API under the topic "SMS Domain API WSDL & XSD".

Device use cases

Pair

Pair a given smartcard, identified by a SmartCard Specification with a given set-top box, identified by a Device Specification. The appropriate CAS pairing command will be issued and the SDP device object will be set with the smartcard details.

Parameters

You must include the following parameters:

Parameter	Description
`deviceSpecification`	The set-top box with which to pair, identified via DeviceSpecification.
`smartCardSpecification`	The smartcard with which to pair, identified via SmartCard Specification.

Response

Empty response payload.

Example

Sample pair set-top box and smartcard request:

XML

   <soapenv:Header/>
   <soapenv:Body>
      <sms:Pair>
         <deviceSpecification>
            <uid>3421</uid>
         </deviceSpecification>
         <smartCardSpecification>
            <smartCardId>812341</smartCardId>
         </smartCardSpecification>
      </sms:Pair>
   </soapenv:Body>

Sample pair set-top box and Smartcard response:

XML

   <soapenv:Header/>
   <soapenv:Body/>

Unpair

Removes the existing smartcard association for a given set-top box, identified by a Device Specification.

Parameters

You must include the following parameters:

Parameter	Description
`deviceSpecification`	The set-top box to unpair, identified via DeviceSpecification.

Response

Empty response payload.

Example

Sample unpair set-top box request:

XML

   <soapenv:Header/>
   <soapenv:Body>
      <sms:Unpair>
         <deviceSpecification>
            <uid>3421</uid>
         </deviceSpecification>
      </sms:Unpair>
   </soapenv:Body>

Sample unpair set-top box response.

XML

   <soapenv:Header/>
   <soapenv:Body/>

Swap device

Swap out one set-top box for another, keeping the same account and smartcard (where present).

Parameters

You must include the following parameters:

Parameter	Description
`oldDeviceSpecification`	The set-top box to replace, identified via DeviceSpecification.
`newDeviceSpecification`	The set-top box to add, identified via DeviceSpecification.

Response

Empty response payload.

Example

Sample swap device request:

XML

   <soapenv:Header/>
   <soapenv:Body>
      <sms:SwapDevice >
         <oldDeviceSpecification>
            <uid>3421</uid>
         </oldDeviceSpecification>
         <newDeviceSpecification>
            <uid>3422</uid>
         </newDeviceSpecification>
      </sms:SwapDevice>
   </soapenv:Body>

Set PIN

Sets the PIN code and value to the smartcard associated to the set-top box, identified by a Device Specification.

Parameters

You must include the following parameters:

Parameter	Description
`deviceSpecification`	The set-top box identified via DeviceSpecification.
`pinCode`	Pin code integer value in the range 0-15.
`pinValue`	Pin value integer value in the range 0-9999.

Response

Empty response payload.

Example

Sample SetPIN device request:

XML

   <soapenv:Header/>
   <soapenv:Body>
      <sms:SetPin>
         <deviceSpecification>
            <uid>3421</uid>
         </deviceSpecification>
         <pinCode>5</pinCode>
         <pinValue>56</pinValue>
      </sms:SetPin>
   </soapenv:Body>

Reset PIN

Resets the pin code to the smartcard associated to the set-top box, identified by a Device Specification.

Parameters

You must include the following parameters:

Parameter	Description
`deviceSpecification`	The set-top box identified via DeviceSpecification.

Response

Empty response payload.

Example

Sample ResetPIN request:

XML

   <soapenv:Header/>
   <soapenv:Body>
      <sms:ResetPin>
         <deviceSpecification>
            <uid>3421</uid>
         </deviceSpecification>
      </sms:ResetPin>
   </soapenv:Body>

Set CASN

Updates the CASN (unique serial number used by the CAS to identify the device) to the set-top box, identified by a Device Specification.

Parameters

You must include the following parameters:

Parameter	Description
`deviceSpecification`	The set-top box identified via DeviceSpecification.
`newCASN`	New CASN value. Must not be in use by other STB.

Response

Empty response payload.

Example

Sample SetCASN request:

XML

   <soapenv:Header/>
   <soapenv:Body>
      <sms:SetCASN >
         <deviceSpecification>
            <uid>3421</uid>
         </deviceSpecification>
         <newCASN>355214344</newCASN>
      </sms:SetCASN >
   </soapenv:Body>

Key reset

Re-pairs the ICC and the set-top box, identified by a Device Specification, in order to force the device to synchronise all the keys of all the products.

Parameters

You must include the following parameters:

Parameter	Description
`deviceSpecification`	The set-top box identified via DeviceSpecification.

Response

Empty response payload.

Example

Sample KeyReset request:

XML

   <soapenv:Header/>
   <soapenv:Body>
      <sms:KeyReset >
         <deviceSpecification>
            <uid>3421</uid>
         </deviceSpecification>
      </sms:KeyReset >
   </soapenv:Body>

Key update

Similar to key reset but targets a delta/update of keys of all the products.

Parameters

You must include the following parameters:

Parameter	Description
`deviceSpecification`	The set-top box identified via DeviceSpecification.

Response

Empty response payload.

Example

Sample key update request:

XML

   <soapenv:Header/>
   <soapenv:Body>
      <sms:KeyUpdate >
         <deviceSpecification>
            <uid>3421</uid>
         </deviceSpecification>
      </sms:KeyUpdate >
   </soapenv:Body>

Initialise service

Sends a request to initialise service for a given account and smartcard. The request will be sent for all the existing enabled devices in the account.

The account will be created if not already present.
The smartcard will be created if not already present.
A new device holding the smartcard will be created using the provided CASN.
Account devices will be updated with the network value provided.
Account will be updated with the zip code and credit limit.

Parameters

You must include the following parameters:

Parameter	Description
`accountNumber`	Account alphanumeric identifier as given at account creation time.
`smartCardId`	Unique smartcard identifier.
`caSN`	Unique device serial number. Must not be already in use by another set-top box.
`zipCode`	Postal code of the subscriber (optional).
`network`	Network identifier to which the device belongs (operator-specific, numeric value in the range 0-999).
`creditLimit`	The credit limit to assign to the subscriber (optional).
`casInstanceName`	The name of the CAS Instance which manages the smartcard.

Response

Empty response payload.

Example

Sample InitialiseService request:

XML

   <soapenv:Header/>
   <soapenv:Body>
      <sms:InitialiseService>
         <accountNumber>4252345</accountNumber>
         <smartCardId>812341</smartCardId>
         <caSN>355214344</caSN>
         <network>555</network>
         <zipCode>1037</zipCode>
         <creditLimit>999</creditLimit>
         <casInstanceName>myCAS</casInstanceName>
      </sms:InitialiseService>
   </soapenv:Body>

Swap or provision

Sends a request to pair an account with a smartcard:

Looks up the account and creates it if it does not exist.
Updates the account with the provided AccessPoint and RolloutProfileId.
Looks up the device by CASN or NUID and creates it if it does not exist.
If the account, set-top box and smartcard are already linked, it returns.
If the smartcard is paired with another set-top box, it unpairs it.
Pairs the smartcard, the set-top box and the account and initialises the service for the triplet.
Sends a refresh command if needed.

Parameters

You must include all the following parameters:

Parameter	Description
`accountNumber`	Account alphanumeric identifier as given at account creation time.
`smartCardId`	Unique smartcard identifier.
`caSN`	Unique device serial number. Must not be already in use by another set-top box.
`nuid`	Unique chipset identifier, assigned by NAGRA.
`accessPoint`	Name of the account's AccessPoint.
`rolloutProfileUid`	Account's rollout profile UID.

Response

Empty response payload.

Example

Sample SwapOrProvision request:

XML

   <soapenv:Header/>
   <soapenv:Body>
      <sms:SwapOrProvision>
         <accountNumber>4252345</accountNumber>
         <smartCardId>812341</smartCardId>
         <caSN>355214344</caSN>
         <nuid>5432678924</network>
         <accessPoint>1037</accessPoint>
         <rolloutProfileUid>12345</rolloutProfileUid>
      </sms:SwapOrProvision>
   </soapenv:Body>

Terminate service

Sends a request to terminate all the services for all devices associated to the given account.

All devices are disabled, their smartcards unlinked.
Account status is set to CANCELLED.
ACLs are removed from the account.
A terminate service command is sent for each smartcard.

Parameters

You must include the following parameters:

Parameter	Description
`accountSpecification`	The account identified via AccountSpecification.

Response

Empty response payload.

Example

Sample TerminateService request:

XML

   <soapenv:Header/>
   <soapenv:Body>
      <sms:TerminateService >
         <accountSpecification>
            <accountNumber>130</accountNumber>
         </accountSpecification>
     </sms:TerminateService >
   </soapenv:Body>