Telematics SDK - Interface Specification  v1.26.3
Remote SIM Provisioning

Data Structures

struct  telux::rsp::CustomHeader
 
class  telux::rsp::IHttpTransactionListener
 The interface listens for indication to perform HTTP request and send back the response for HTTP request to modem. More...
 
class  telux::rsp::IHttpTransactionManager
 IHttpTransactionManager is the interface to service HTTP related requests from the modem, for Sim profile update related operations. More...
 
class  telux::rsp::SimProfile
 SimProfile class represents single eUICC profile on the card. More...
 
class  telux::rsp::SimProfileFactory
 SimProfileFactory is the central factory to create all eUICC manager class instances. More...
 
class  telux::rsp::ISimProfileListener
 The interface listens for profile download indication and keep track of download and install progress of profile. More...
 
class  telux::rsp::ISimProfileManager
 ISimProfileManager is a primary interface for remote eUICCs (eSIMs or embedded SIMs) provisioning.This interface provides APIs to add, delete, set profile on the eUICC. More...
 

Typedefs

using telux::rsp::PolicyRuleMask = std::bitset< 16 >
 

Enumerations

enum  telux::rsp::HttpResult {
  telux::rsp::HttpResult::TRANSACTION_SUCCESSFUL = 0, telux::rsp::HttpResult::UNKNOWN_ERROR = 1, telux::rsp::HttpResult::HTTP_SERVER_ERROR = 2, telux::rsp::HttpResult::HTTP_TLS_ERROR = 3,
  telux::rsp::HttpResult::HTTP_NETWORK_ERROR = 4
}
 
enum  telux::rsp::ProfileType { telux::rsp::ProfileType::UNKNOWN = -1, telux::rsp::ProfileType::REGULAR = 0, telux::rsp::ProfileType::EMERGENCY }
 
enum  telux::rsp::IconType { telux::rsp::IconType::NONE = 0, telux::rsp::IconType::JPEG, telux::rsp::IconType::PNG }
 
enum  telux::rsp::ProfileClass { telux::rsp::ProfileClass::UNKNOWN = -1, telux::rsp::ProfileClass::TEST = 0, telux::rsp::ProfileClass::PROVISIONING, telux::rsp::ProfileClass::OPERATIONAL }
 
enum  telux::rsp::DownloadStatus {
  telux::rsp::DownloadStatus::DOWNLOAD_ERROR = 1, telux::rsp::DownloadStatus::DOWNLOAD_IN_PROGRESS, telux::rsp::DownloadStatus::DOWNLOAD_COMPLETE_INSTALLATION_IN_PROGRESS, telux::rsp::DownloadStatus::INSTALLATION_COMPLETE,
  telux::rsp::DownloadStatus::USER_CONSENT_REQUIRED
}
 
enum  telux::rsp::DownloadErrorCause { telux::rsp::DownloadErrorCause::GENERIC = 1, telux::rsp::DownloadErrorCause::SIM, telux::rsp::DownloadErrorCause::NETWORK, telux::rsp::DownloadErrorCause::MEMORY }
 
enum  telux::rsp::PolicyRuleType { telux::rsp::PROFILE_DISABLE_NOT_ALLOWED = (1 << 0), telux::rsp::PROFILE_DELETE_NOT_ALLOWED = (1 << 1), telux::rsp::PROFILE_DELETE_ON_DISABLE = (1 << 2) }
 

Detailed Description

This section contains APIs related to Remote SIM provisioning.


Data Structure Documentation

struct telux::rsp::CustomHeader

Header information to be sent along with HTTP post request.

Data Fields
string name

Header name

string value

Header value

class telux::rsp::IHttpTransactionListener

The interface listens for indication to perform HTTP request and send back the response for HTTP request to modem.

The methods in the listener can be invoked from multiple threads. It is client's responsibility to make sure the implementation is thread safe.

Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.

Public Member Functions

virtual void onNewHttpRequest (int slotId, const std::string &url, int tokenId, const std::vector< CustomHeader > &headers, const std::string &reqPayload)
 
virtual ~IHttpTransactionListener ()
 
- Public Member Functions inherited from telux::common::IServiceStatusListener
virtual void onServiceStatusChange (ServiceStatus status)
 
virtual ~IServiceStatusListener ()
 

Constructor & Destructor Documentation

virtual telux::rsp::IHttpTransactionListener::~IHttpTransactionListener ( )
virtual

Destructor of IHttpTransactionListener

Member Function Documentation

virtual void telux::rsp::IHttpTransactionListener::onNewHttpRequest ( int  slotId,
const std::string &  url,
int  tokenId,
const std::vector< CustomHeader > &  headers,
const std::string &  reqPayload 
)
virtual

An application handling this indication should perform the HTTP request and call the IHttpTransactionManager::sendHttpTransactionReq to provide the result of the HTTP transaction.

Parameters
[in]slotIdSlot identifier corresponding to the card.
[in]urlURL to sent HTTP post request.
[in]tokenIdToken identifier.
[in]headersHeader information to be sent along with HTTP post request.
[in]reqPayloadRequest payload.
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.
class telux::rsp::IHttpTransactionManager

IHttpTransactionManager is the interface to service HTTP related requests from the modem, for Sim profile update related operations.

Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.

Public Member Functions

virtual bool isSubsystemReady ()=0
 
virtual std::future< bool > onSubsystemReady ()=0
 
virtual telux::common::Status sendHttpTransactionResult (uint32_t token, HttpResult result, const std::vector< CustomHeader > &headers, const std::vector< uint8_t > &response, common::ResponseCallback callback=nullptr, int slotId=DEFAULT_SLOT_ID)=0
 
virtual telux::common::Status registerListener (std::weak_ptr< IHttpTransactionListener > listener)=0
 
virtual telux::common::Status deregisterListener (std::weak_ptr< IHttpTransactionListener > listener)=0
 
virtual ~IHttpTransactionManager ()
 

Constructor & Destructor Documentation

virtual telux::rsp::IHttpTransactionManager::~IHttpTransactionManager ( )
virtual

Destructor for IHttpTransactionManager

Member Function Documentation

virtual bool telux::rsp::IHttpTransactionManager::isSubsystemReady ( )
pure virtual

Checks if the eUICC subsystem is ready.

Returns
True if EuiccManager is ready for service, otherwise returns false.
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.
virtual std::future<bool> telux::rsp::IHttpTransactionManager::onSubsystemReady ( )
pure virtual

Wait for eUICC subsystem to be ready.

Returns
A future that caller can wait on to be notified when card manager is ready.
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.
virtual telux::common::Status telux::rsp::IHttpTransactionManager::sendHttpTransactionResult ( uint32_t  token,
HttpResult  result,
const std::vector< CustomHeader > &  headers,
const std::vector< uint8_t > &  response,
common::ResponseCallback  callback = nullptr,
int  slotId = DEFAULT_SLOT_ID 
)
pure virtual

Send the result of HTTP Post request transaction to modem.

Parameters
[in]tokenToken identifier for request and response pair.
[in]resultHTTP transaction request result.
[in]headersCustom Headers in HTTP Response.
[in]responseHTTP response payload.
[in]callbackCallback function to get the result of send HTTP transaction request.
[in]slotIdSlot identifier corresponding to the card.
Returns
Status of send HTTP transaction request i.e. success or suitable error code.
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.
virtual telux::common::Status telux::rsp::IHttpTransactionManager::registerListener ( std::weak_ptr< IHttpTransactionListener listener)
pure virtual

Register a listener for specific events like perform HTTP Post request.

Parameters
[in]listenerPointer of IHttpTransactionListener object that processes the notification.
Returns
Status of registerHttpListener success or suitable status code.
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.
virtual telux::common::Status telux::rsp::IHttpTransactionManager::deregisterListener ( std::weak_ptr< IHttpTransactionListener listener)
pure virtual

De-register the listener.

Parameters
[in]listenerPointer of IHttpTransactionListener object that needs to be removed.
Returns
Status of deregisterHttpListener success or suitable status code.
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.
class telux::rsp::SimProfile

SimProfile class represents single eUICC profile on the card.

Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.

Public Member Functions

 SimProfile (int profileId, const std::string &iccid, bool isActive, const std::string &nickName, const std::string &spn, const std::string &name, IconType iconType, std::vector< uint8_t > icon, ProfileClass profileClass, PolicyRuleMask policyRuleMask)
 
int getSlotId ()
 
int getProfileId ()
 
const std::string & getIccid ()
 
bool isActive ()
 
const std::string & getNickName ()
 
const std::string & getSPN ()
 
const std::string & getName ()
 
IconType getIconType ()
 
std::vector< uint8_t > getIcon ()
 
ProfileClass getClass ()
 
PolicyRuleMask getPolicyRule ()
 
std::string toString ()
 

Constructor & Destructor Documentation

telux::rsp::SimProfile::SimProfile ( int  profileId,
const std::string &  iccid,
bool  isActive,
const std::string &  nickName,
const std::string &  spn,
const std::string &  name,
IconType  iconType,
std::vector< uint8_t >  icon,
ProfileClass  profileClass,
PolicyRuleMask  policyRuleMask 
)

Member Function Documentation

int telux::rsp::SimProfile::getSlotId ( )

Get slot id associated for this profile

Returns
SlotId
Note
Eval: This is a new API and is being evaluated.It is subject to change and could break backwards compatibility.
int telux::rsp::SimProfile::getProfileId ( )

Get profile identifier.

Returns
unique identifier for the profile
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.
const std::string& telux::rsp::SimProfile::getIccid ( )

Get profile ICCID.

Returns
profile ICCID coded as in EF-ICCID
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.
bool telux::rsp::SimProfile::isActive ( )

Indicates the profile state whether active or not.

Returns
true if profile is Active
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.
const std::string& telux::rsp::SimProfile::getNickName ( )

Get profile nick name.

Returns
profile nick name
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.
const std::string& telux::rsp::SimProfile::getSPN ( )

Get profile service provider name.

Returns
profile service provider name.
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.
const std::string& telux::rsp::SimProfile::getName ( )

Get profile name.

Returns
profile name
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.
IconType telux::rsp::SimProfile::getIconType ( )

Get profile icon type.

Returns
profile icon type
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.
std::vector<uint8_t> telux::rsp::SimProfile::getIcon ( )

Get profile icon content.

Returns
profile icon content
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.
ProfileClass telux::rsp::SimProfile::getClass ( )

Get profile class.

Returns
profile class
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.
PolicyRuleMask telux::rsp::SimProfile::getPolicyRule ( )

Get profile policy rules.

Returns
mask of profile policy rules
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.
std::string telux::rsp::SimProfile::toString ( )

Get the text related informative representation of this object.

Returns
String containing informative string.
class telux::rsp::SimProfileFactory

SimProfileFactory is the central factory to create all eUICC manager class instances.

Public Member Functions

std::shared_ptr< ISimProfileManagergetSimProfileManager ()
 
std::shared_ptr< IHttpTransactionManagergetHttpTransactionManager ()
 

Static Public Member Functions

static SimProfileFactorygetInstance ()
 

Member Function Documentation

static SimProfileFactory& telux::rsp::SimProfileFactory::getInstance ( )
static

Get SIM Profile Factory instance.

std::shared_ptr<ISimProfileManager> telux::rsp::SimProfileFactory::getSimProfileManager ( )

Get SimProfileManager. SimProfileManager is a primary interface for remote eUICC(eSIM) provisioning and local profile assistance.

Returns
instance of ISimProfileManager
Note
Eval: This is a new API and is being evaluated.It is subject to change and could break backwards compatibility.
std::shared_ptr<IHttpTransactionManager> telux::rsp::SimProfileFactory::getHttpTransactionManager ( )

Get HttpTransactionManager. HttpTransactionManager is a primary interface for sending the response for HTTP post request to modem and listen for indication for HTTP post request to download the profile.

Returns
instance of IHttpTransactionManager
Note
Eval: This is a new API and is being evaluated.It is subject to change and could break backwards compatibility.
class telux::rsp::ISimProfileListener

The interface listens for profile download indication and keep track of download and install progress of profile.

The methods in the listener can be invoked from multiple threads. It is client's responsibility to make sure the implementation is thread safe.

Note
Eval: This is a new API and is being evaluated.It is subject to change and could break backwards compatibility.

Public Member Functions

virtual void onAddProfileUpdate (int slotId, bool userConsentRequired, DownloadStatus status, uint8_t percentage, DownloadErrorCause cause, PolicyRuleMask mask)
 
virtual ~ISimProfileListener ()
 
- Public Member Functions inherited from telux::common::IServiceStatusListener
virtual void onServiceStatusChange (ServiceStatus status)
 
virtual ~IServiceStatusListener ()
 

Constructor & Destructor Documentation

virtual telux::rsp::ISimProfileListener::~ISimProfileListener ( )
virtual

Destructor of ISimProfileListener

Member Function Documentation

virtual void telux::rsp::ISimProfileListener::onAddProfileUpdate ( int  slotId,
bool  userConsentRequired,
DownloadStatus  status,
uint8_t  percentage,
DownloadErrorCause  cause,
PolicyRuleMask  mask 
)
virtual

This function is called when indication about status of profile download and installation comes.

Parameters
[in]slotIdSlot on which profile get downloaded and installed.
[in]userConsentRequiredUser consent required or not.
[in]statusProfileDownloadStatus.
[in]percentageDownload and installation percentage.
[in]causeProfileDownloadErrorCause.
[in]maskPprMask (Profile policy rules Mask)
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.
class telux::rsp::ISimProfileManager

ISimProfileManager is a primary interface for remote eUICCs (eSIMs or embedded SIMs) provisioning.This interface provides APIs to add, delete, set profile on the eUICC.

Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.

Public Member Functions

virtual bool isSubsystemReady ()=0
 
virtual std::future< bool > onSubsystemReady ()=0
 
virtual telux::common::Status addProfile (const std::string &activationCode, common::ResponseCallback callback=nullptr, const std::string &confirmationCode="", bool userConsentSupported=false, int slotId=DEFAULT_SLOT_ID)=0
 
virtual telux::common::Status deleteProfile (int profileId, common::ResponseCallback callback=nullptr, int slotId=DEFAULT_SLOT_ID)=0
 
virtual telux::common::Status setProfile (int profileId, bool enable, common::ResponseCallback callback=nullptr, int slotId=DEFAULT_SLOT_ID)=0
 
virtual telux::common::Status updateNickName (int profileId, const std::string &nickName, common::ResponseCallback callback=nullptr, int slotId=DEFAULT_SLOT_ID)=0
 
virtual telux::common::Status requestProfileList (ProfileListResponseCb=nullptr, int slotId=DEFAULT_SLOT_ID)=0
 
virtual telux::common::Status registerListener (std::weak_ptr< ISimProfileListener > listener)=0
 
virtual telux::common::Status deregisterListener (std::weak_ptr< ISimProfileListener > listener)=0
 
virtual ~ISimProfileManager ()
 

Constructor & Destructor Documentation

virtual telux::rsp::ISimProfileManager::~ISimProfileManager ( )
virtual

Destructor for ISimProfileManager

Member Function Documentation

virtual bool telux::rsp::ISimProfileManager::isSubsystemReady ( )
pure virtual

Checks if the eUICC subsystem is ready.

Returns
True if ISimProfileManager is ready for service, otherwise returns false.
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.
virtual std::future<bool> telux::rsp::ISimProfileManager::onSubsystemReady ( )
pure virtual

Wait for eUICC subsystem to be ready.

Returns
A future that caller can wait on to be notified when card manager is ready.
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.
virtual telux::common::Status telux::rsp::ISimProfileManager::addProfile ( const std::string &  activationCode,
common::ResponseCallback  callback = nullptr,
const std::string &  confirmationCode = "",
bool  userConsentSupported = false,
int  slotId = DEFAULT_SLOT_ID 
)
pure virtual

Add new profile to eUICC card and download and install the profile on eUICC.

Parameters
[in]activationCodeActivation code.
[in]callbackCallback function to get the result of add profile.
[in]confirmationCodeOptional confirmation code required for downloading the profile.
[in]userConsentSupportedOptional User consent supported or not.
[in]slotIdSlot identifier corresponding to the card.
Returns
Status of add profile i.e. success or suitable error code.
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.
virtual telux::common::Status telux::rsp::ISimProfileManager::deleteProfile ( int  profileId,
common::ResponseCallback  callback = nullptr,
int  slotId = DEFAULT_SLOT_ID 
)
pure virtual

Delete profile from eUICC card.

Parameters
[in]profileIdProfile identifier
[in]callbackCallback function to get the result of delete profile.
[in]slotIdSlot identifier corresponding to the card.
Returns
Status of delete profile i.e. success or suitable error code.
Note
Eval: This is a new API and is being evaluated.It is subject to change and could break backwards compatibility.
virtual telux::common::Status telux::rsp::ISimProfileManager::setProfile ( int  profileId,
bool  enable,
common::ResponseCallback  callback = nullptr,
int  slotId = DEFAULT_SLOT_ID 
)
pure virtual

Enable or disable profile which allows to switch to other profile on eUICC card.

Parameters
[in]profileIdProfile identifier.
[in]enableIndicates whether a profile must be enabled or disabled. true - Enable and false - Disable.
[in]callbackCallback function to get the result of set profile.
[in]slotIdSlot identifier corresponding to the card.
Returns
Status of set profile i.e. success or suitable error code.
Note
Eval: This is a new API and is being evaluated.It is subject to change and could break backwards compatibility.
virtual telux::common::Status telux::rsp::ISimProfileManager::updateNickName ( int  profileId,
const std::string &  nickName,
common::ResponseCallback  callback = nullptr,
int  slotId = DEFAULT_SLOT_ID 
)
pure virtual

Update nick name of the profile

Parameters
[in]profileIdProfile identifier
[in]nickNameNew nick name for profile.
[in]callbackCallback function to get the result of update nickname.
[in]slotIdSlot identifier corresponding to the card.
Returns
Status of update nick name i.e. success or suitable error code.
Note
Eval: This is a new API and is being evaluated.It is subject to change and could break backwards compatibility.
virtual telux::common::Status telux::rsp::ISimProfileManager::requestProfileList ( ProfileListResponseCb  = nullptr,
int  slotId = DEFAULT_SLOT_ID 
)
pure virtual

Request list of profiles supported by the eUICC card.

Parameters
[in]callbackCallback function to get the result of request profile list.
[in]slotIdSlot identifier corresponding to the card.
Returns
Status of request profile list i.e. success or suitable error code.
Note
Eval: This is a new API and is being evaluated.It is subject to change and could break backwards compatibility.
virtual telux::common::Status telux::rsp::ISimProfileManager::registerListener ( std::weak_ptr< ISimProfileListener listener)
pure virtual

Register a listener to listen for status of specific events like download and installation of profile on eUICC.

Parameters
[in]listenerPointer of ISimProfileListener object that processes the notification.
Returns
Status of registerListener success or suitable status code
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.
virtual telux::common::Status telux::rsp::ISimProfileManager::deregisterListener ( std::weak_ptr< ISimProfileListener listener)
pure virtual

De-register the listener.

Parameters
[in]listenerPointer of ISimProfileListener object that needs to be removed
Returns
Status of deregisterListener success or suitable status code
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backwards compatibility.

Typedef Documentation

using telux::rsp::PolicyRuleMask = typedef std::bitset<16>

16 bit mask that denotes which of the profile policy rules(PPR) defined in Policy Rule Type enum are used.

Enumeration Type Documentation

Defines the HTTP request result.

Enumerator
TRANSACTION_SUCCESSFUL 

HTTP request successful

UNKNOWN_ERROR 

Unknown error

HTTP_SERVER_ERROR 

Server error

HTTP_TLS_ERROR 

TLS error

HTTP_NETWORK_ERROR 

Network error

Indicates profile type of card

Enumerator
UNKNOWN 
REGULAR 

Regular profile

EMERGENCY 

Emergency profile

enum telux::rsp::IconType
strong

Indicates profile icon type.

Enumerator
NONE 

No icon information

JPEG 

JPEG icon

PNG 

PNG icon

Indicates profile class.

Enumerator
UNKNOWN 

No info about profile class

TEST 

Test profile

PROVISIONING 

Provisioning profile

OPERATIONAL 

Operational profile

Indicates profile download status.

Enumerator
DOWNLOAD_ERROR 

Profile download error

DOWNLOAD_IN_PROGRESS 

Profile download in progress with download percentage

DOWNLOAD_COMPLETE_INSTALLATION_IN_PROGRESS 

Profile download is complete and installation is in progress

INSTALLATION_COMPLETE 

Profile installation is complete

USER_CONSENT_REQUIRED 

User consent is required for proceeding with download/installation of profile

Indicates profile download error cause.

Enumerator
GENERIC 

Generic error

SIM 

Error from the SIM card

NETWORK 

Error from the network

MEMORY 

Error due to no memory

Defines profile policy rules(PPR). Each value represents corresponding bit for PprMask bitset.

Enumerator
PROFILE_DISABLE_NOT_ALLOWED 

Disabling of the profile is not allowed

PROFILE_DELETE_NOT_ALLOWED 

Deletion of the profile is not allowed

PROFILE_DELETE_ON_DISABLE 

Deletion of the profile is required on successful disabling