Telematics SDK - API Reference  v1.54.0
Data Structures | Typedefs | Enumerations
SIM Card Services
Telematics SDK APIs » Telephony

Data Structures

class  telux::tel::ICardApp
 Represents a single card application. More...
 
struct  telux::tel::IccResult
 
struct  telux::tel::FileAttributes
 
class  telux::tel::ICardFileHandler
 ICardFileHandler provides APIs for reading from an elementary file(EF) on SIM and writing to EF on SIM. Provide API to get EF attributes like file size, record size, and the number of records in EF. More...
 
class  telux::tel::ICardManager
 
class  telux::tel::ICard
 ICard represents currently inserted UICC or eUICC. More...
 
class  telux::tel::ICardChannelCallback
 
class  telux::tel::ICardCommandCallback
 
class  telux::tel::ICardListener
 
struct  telux::tel::CardReaderStatus
 
class  telux::tel::ISapCardManager
 ISapCardManager provide APIs for SAP related operations. More...
 
class  telux::tel::IAtrResponseCallback
 
class  telux::tel::ISapCardCommandCallback
 
class  telux::tel::ICardReaderCallback
 
class  telux::tel::ISapCardListener
 

Typedefs

using telux::tel::PinOperationResponseCb = std::function< void(int retryCount, telux::common::ErrorCode error)>
 
using telux::tel::QueryFdnLockResponseCb = std::function< void(bool isAvailable, bool isEnabled, telux::common::ErrorCode error)>
 
using telux::tel::QueryPin1LockResponseCb = std::function< void(bool state, telux::common::ErrorCode error)>
 
using telux::tel::EfOperationCallback = std::function< void(telux::common::ErrorCode error, IccResult result)>
 
using telux::tel::EfReadAllRecordsCallback = std::function< void(telux::common::ErrorCode error, std::vector< IccResult > records)>
 
using telux::tel::EfGetFileAttributesCallback = std::function< void(telux::common::ErrorCode error, IccResult result, FileAttributes attributes)>
 
using telux::tel::EidResponseCallback = std::function< void(const std::string &eid, telux::common::ErrorCode error)>
 
using telux::tel::SapStateResponseCallback = std::function< void(SapState sapState, telux::common::ErrorCode error)>
 

Enumerations

enum  telux::tel::CardState {
  telux::tel::CardState::CARDSTATE_UNKNOWN = -1, telux::tel::CardState::CARDSTATE_ABSENT = 0, telux::tel::CardState::CARDSTATE_PRESENT = 1, telux::tel::CardState::CARDSTATE_ERROR = 2,
  telux::tel::CardState::CARDSTATE_RESTRICTED = 3
}
 
enum  telux::tel::CardError {
  telux::tel::CardError::UNKNOWN, telux::tel::CardError::POWER_DOWN, telux::tel::CardError::POLL_ERROR, telux::tel::CardError::NO_ATR_RECEIVED,
  telux::tel::CardError::VOLT_MISMATCH, telux::tel::CardError::PARITY_ERROR, telux::tel::CardError::POSSIBLY_REMOVED, telux::tel::CardError::TECHNICAL_PROBLEMS,
  telux::tel::CardError::NULL_BYTES, telux::tel::CardError::SAP_CONNECTED, telux::tel::CardError::CMD_TIMEOUT
}
 
enum  telux::tel::CardLockType {
  telux::tel::CardLockType::PIN1 = 0, telux::tel::CardLockType::PIN2 = 1, telux::tel::CardLockType::PUK1 = 2, telux::tel::CardLockType::PUK2 = 3,
  telux::tel::CardLockType::FDN = 4
}
 
enum  telux::tel::AppType {
  telux::tel::APPTYPE_UNKNOWN = 0, telux::tel::APPTYPE_SIM = 1, telux::tel::APPTYPE_USIM = 2, telux::tel::APPTYPE_RUIM = 3,
  telux::tel::APPTYPE_CSIM = 4, telux::tel::APPTYPE_ISIM = 5
}
 
enum  telux::tel::AppState {
  telux::tel::APPSTATE_UNKNOWN = 0, telux::tel::APPSTATE_DETECTED = 1, telux::tel::APPSTATE_PIN = 2, telux::tel::APPSTATE_PUK = 3,
  telux::tel::APPSTATE_SUBSCRIPTION_PERSO = 4, telux::tel::APPSTATE_READY = 5
}
 
enum  telux::tel::EfType { telux::tel::EfType::UNKNOWN = 0, telux::tel::EfType::TRANSPARENT, telux::tel::EfType::LINEAR_FIXED }
 
enum  telux::tel::SapState {
  telux::tel::SapState::SAP_STATE_NOT_ENABLED = 0x00, telux::tel::SapState::SAP_STATE_CONNECTING = 0x01, telux::tel::SapState::SAP_STATE_CONNECTED_SUCCESSFULLY = 0x02, telux::tel::SapState::SAP_STATE_CONNECTION_ERROR = 0x03,
  telux::tel::SapState::SAP_STATE_DISCONNECTING = 0x04, telux::tel::SapState::SAP_STATE_DISCONNECTED_SUCCESSFULLY = 0x05
}
 
enum  telux::tel::SapCondition { telux::tel::SapCondition::SAP_CONDITION_BLOCK_VOICE_OR_DATA = 0x00, telux::tel::SapCondition::SAP_CONDITION_BLOCK_DATA = 0x01, telux::tel::SapCondition::SAP_CONDITION_BLOCK_VOICE = 0x02, telux::tel::SapCondition::SAP_CONDITION_BLOCK_NONE = 0x03 }
 

Detailed Description

This section contains APIs related to Card Services.

Data Structure Documentation

class telux::tel::ICardApp

Represents a single card application.

Public Member Functions

virtual AppType getAppType ()=0
 
virtual AppState getAppState ()=0
 
virtual std::string getAppId ()=0
 
virtual telux::common::Status changeCardPassword (CardLockType lockType, std::string oldPwd, std::string newPwd, PinOperationResponseCb callback)=0
 
virtual telux::common::Status unlockCardByPuk (CardLockType lockType, std::string puk, std::string newPin, PinOperationResponseCb callback)=0
 
virtual telux::common::Status unlockCardByPin (CardLockType lockType, std::string pin, PinOperationResponseCb callback)=0
 
virtual telux::common::Status queryPin1LockState (QueryPin1LockResponseCb callback)=0
 
virtual telux::common::Status queryFdnLockState (QueryFdnLockResponseCb callback)=0
 
virtual telux::common::Status setCardLock (CardLockType lockType, std::string password, bool isEnabled, PinOperationResponseCb callback)=0
 
virtual ~ICardApp ()
 

Constructor & Destructor Documentation

virtual telux::tel::ICardApp::~ICardApp ( )
virtual

Member Function Documentation

virtual AppType telux::tel::ICardApp::getAppType ( )
pure virtual

Get Application type like SIM, USIM, RUIM, CSIM or ISIM.

Returns
AppType.
virtual AppState telux::tel::ICardApp::getAppState ( )
pure virtual

Get Application state like PIN1, PUK required and others.

Returns
AppState.
virtual std::string telux::tel::ICardApp::getAppId ( )
pure virtual

Get application identifier.

Returns
Application Id.
virtual telux::common::Status telux::tel::ICardApp::changeCardPassword ( CardLockType  lockType,
std::string  oldPwd,
std::string  newPwd,
PinOperationResponseCb  callback 
)
pure virtual

Change the password used in PIN1/PIN2 lock.

On platforms with access control enabled, caller needs to have TELUX_TEL_CARD_PRIVILEGED_OPS permission to invoke this API successfully.

Parameters
[in]lockTypeCardLockType. Applicable lock types are PIN1 and PIN2.
[in]oldPwdOld password
[in]newPwdNew password
[in]callbackCallback function to get the response of change pin password.
virtual telux::common::Status telux::tel::ICardApp::unlockCardByPuk ( CardLockType  lockType,
std::string  puk,
std::string  newPin,
PinOperationResponseCb  callback 
)
pure virtual

Unlock the Sim card for an app by entering PUK and new pin.

On platforms with access control enabled, caller needs to have TELUX_TEL_CARD_PRIVILEGED_OPS permission to invoke this API successfully.

Parameters
[in]lockTypeCardLockType. Applicable lock types are PUK1 and PUK2
[in]pukPUK1/PUK2
[in]newPinNew PIN1/PIN2
[in]callbackCallback function to get the response of unlock card lock.
virtual telux::common::Status telux::tel::ICardApp::unlockCardByPin ( CardLockType  lockType,
std::string  pin,
PinOperationResponseCb  callback 
)
pure virtual

Unlock the Sim card for an app by entering PIN.

On platforms with access control enabled, caller needs to have TELUX_TEL_CARD_PRIVILEGED_OPS permission to invoke this API successfully.

Parameters
[in]lockTypeCardLockType. Applicable lock types are PIN1 and PIN2.
[in]pinNew PIN1/PIN2
[in]callbackCallback function to get the response of unlock card lock.
virtual telux::common::Status telux::tel::ICardApp::queryPin1LockState ( QueryPin1LockResponseCb  callback)
pure virtual

Query Pin1 lock state.

On platforms with access control enabled, caller needs to have TELUX_TEL_CARD_OPS permission to invoke this API successfully.

Parameters
[in]callbackCallback function to get the response of query pin1 lock state.
virtual telux::common::Status telux::tel::ICardApp::queryFdnLockState ( QueryFdnLockResponseCb  callback)
pure virtual

Query FDN lock state.

On platforms with access control enabled, caller needs to have TELUX_TEL_CARD_OPS permission to invoke this API successfully.

Parameters
[in]callbackCallback function to get the response of query fdn lock state.
virtual telux::common::Status telux::tel::ICardApp::setCardLock ( CardLockType  lockType,
std::string  password,
bool  isEnabled,
PinOperationResponseCb  callback 
)
pure virtual

Enable or disable FDN or Pin1 lock.

On platforms with access control enabled, caller needs to have TELUX_TEL_CARD_PRIVILEGED_OPS permission to invoke this API successfully.

Parameters
[in]lockTypeCardLockType. Applicable lock type such as PIN1 and FDN
[in]passwordPassword of PIN1 and FDN
[in]isEnabledIf true then enable else disable.
[in]callbackCallback function to get the response of set card lock.
struct telux::tel::IccResult

The APDU response with status for transmit APDU operation.

Public Member Functions

const std::string toString () const
 

Data Fields

int sw1
 
int sw2
 
std::string payload
 
std::vector< int > data
 

Member Function Documentation

const std::string telux::tel::IccResult::toString ( ) const

Field Documentation

int telux::tel::IccResult::sw1

Status word 1 for command processing status

int telux::tel::IccResult::sw2

Status word 2 for command processing qualifier

std::string telux::tel::IccResult::payload

response as a hex string

std::vector<int> telux::tel::IccResult::data

vector of raw data received as part of response to the card services request

struct telux::tel::FileAttributes

SIM Elementary file attributes.

Data Fields
uint16_t fileSize

File size of transparent or linear fixed file.

uint16_t recordSize

Size of the file record. Applicable only for telux::tel::EfType::LINEAR_FIXED.

uint16_t recordCount

The number of records in a file. Applicable only for telux::tel::EfType::LINEAR_FIXED.

class telux::tel::ICardFileHandler

ICardFileHandler provides APIs for reading from an elementary file(EF) on SIM and writing to EF on SIM. Provide API to get EF attributes like file size, record size, and the number of records in EF.

Public Member Functions

virtual telux::common::Status readEFLinearFixed (std::string filePath, uint16_t fileId, int recordNum, std::string aid, EfOperationCallback callback)=0
 
virtual telux::common::Status readEFLinearFixedAll (std::string filePath, uint16_t fileId, std::string aid, EfReadAllRecordsCallback callback)=0
 
virtual telux::common::Status readEFTransparent (std::string filePath, uint16_t fileId, int size, std::string aid, EfOperationCallback callback)=0
 
virtual telux::common::Status writeEFLinearFixed (std::string filePath, uint16_t fileId, int recordNum, std::vector< uint8_t > data, std::string pin2, std::string aid, EfOperationCallback callback)=0
 
virtual telux::common::Status writeEFTransparent (std::string filePath, uint16_t fileId, std::vector< uint8_t > data, std::string aid, EfOperationCallback callback)=0
 
virtual telux::common::Status requestEFAttributes (EfType efType, std::string filePath, uint16_t fileId, std::string aid, EfGetFileAttributesCallback callback)=0
 
virtual SlotId getSlotId ()=0
 

Member Function Documentation

virtual telux::common::Status telux::tel::ICardFileHandler::readEFLinearFixed ( std::string  filePath,
uint16_t  fileId,
int  recordNum,
std::string  aid,
EfOperationCallback  callback 
)
pure virtual

Read a record from a SIM linear fixed elementary file (EF).

Parameters
[in]filePathFile path of the elementary file to be read Refer ETSI GTS GSM 11.11 V5.3.0 6.5. For example to read EF FDN corresponding to USIM app the file path is "3F007FFF"
[in]fileIdElementary file identifier. For example File Id for EF FDN is 0x6F3B
[in]recordNumRecord number is 1-based (not 0-based)
[in]aidApplication identifier is optional for reading EF that is not part of card application
[in]callbackCallback function to get the response of readEFLinearFixed request
Returns
- Status of readEFLinearFixed i.e. success or suitable status code
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backward compatibility.
virtual telux::common::Status telux::tel::ICardFileHandler::readEFLinearFixedAll ( std::string  filePath,
uint16_t  fileId,
std::string  aid,
EfReadAllRecordsCallback  callback 
)
pure virtual

Read all records from a SIM linear fixed elementary file (EF).

Parameters
[in]filePathFile path of the elementary file to be read Refer ETSI GTS GSM 11.11 V5.3.0 6.5. For example to read EF FDN corresponding to USIM app the file path is "3F007FFF"
[in]fileIdElementary file identifier. For example File Id for EF FDN is 0x6F3B
[in]aidApplication identifier is optional for reading EF that is not part of card application
[in]callbackCallback function to get the response of readEFLinearFixedAll request
Returns
- Status of readEFLinearFixedAll i.e. success or suitable status code
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backward compatibility.
virtual telux::common::Status telux::tel::ICardFileHandler::readEFTransparent ( std::string  filePath,
uint16_t  fileId,
int  size,
std::string  aid,
EfOperationCallback  callback 
)
pure virtual

Read from a SIM transparent elementary file (EF).

Parameters
[in]filePathFile path of the elementary file to be read Refer ETSI GTS GSM 11.11 V5.3.0 6.5. For example to read EF ICCID the file path is "3F00"
[in]fileIdElementary file identifier. For example File Id for EF ICCID is 0x2FE2
[in]sizeIf the size is zero then read the complete file otherwise, read the first size bytes from EF.
[in]aidApplication identifier is optional for reading EF that is not part of card application
[in]callbackCallback function to get the response of readEFTransparent request
Returns
- Status of readEFTransparent i.e. success or suitable status code
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backward compatibility.
virtual telux::common::Status telux::tel::ICardFileHandler::writeEFLinearFixed ( std::string  filePath,
uint16_t  fileId,
int  recordNum,
std::vector< uint8_t >  data,
std::string  pin2,
std::string  aid,
EfOperationCallback  callback 
)
pure virtual

Write a record in a SIM linear fixed elementary file (EF).

Parameters
[in]filePathFile path of the elementary file to be written. Refer ETSI GTS GSM 11.11 V5.3.0 6.5. For example to update record to EF FDN corresponding to USIM app the file path is "3F007FFF"
[in]fileIdElementary file identifier. For example File Id for EF FDN is 0x6F3B
[in]recordNumRecord number is 1-based (not 0-based)
[in]dataData represents record in the EF
[in]pin2Pin2 for card holder verification(CHV2) operations, otherwise must be empty.
[in]aidApplication identifier is optional for writing to EF that is not part of card application.
[in]callbackCallback function to get the response of writeEFLinearFixed request
Returns
- Status of writeEFLinearFixed i.e. success or suitable status code
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backward compatibility.
virtual telux::common::Status telux::tel::ICardFileHandler::writeEFTransparent ( std::string  filePath,
uint16_t  fileId,
std::vector< uint8_t >  data,
std::string  aid,
EfOperationCallback  callback 
)
pure virtual

Write in a SIM transparent elementary file (EF).

Parameters
[in]filePathFile path of the elementary file to be written Refer ETSI GTS GSM 11.11 V5.3.0 6.5. For example to write to EF ICCID the file path is "3F00"
[in]fileIdElementary file identifier. For example File Id for EF ICCID is 0x2FE2
[in]dataBinary data to be written on the EF
[in]aidApplication identifier is optional for writing to EF that is not part of card application.
[in]callbackCallback function to get the response of writeEFTransparent request
Returns
- Status of writeEFTransparent i.e. success or suitable status code
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backward compatibility.
virtual telux::common::Status telux::tel::ICardFileHandler::requestEFAttributes ( EfType  efType,
std::string  filePath,
uint16_t  fileId,
std::string  aid,
EfGetFileAttributesCallback  callback 
)
pure virtual

Get file attributes for SIM elementary file(EF).

Parameters
[in]efTypeElementary file type i.e. telux::tel::EfType
[in]filePathFile path of the elementary file to read file attributes Refer ETSI GTS GSM 11.11 V5.3.0 6.5. For example to read file attributes of EF ICCID the file path is "3F00"
[in]fileIdElementary file identifier. For example File Id for EF ICCID is 0x2FE2
[in]aidApplication identifier is optional for EF that is not part of card application.
[in]callbackCallback function to get the response of requestEFAttributes request
Returns
- Status of requestEFAttributes i.e. success or suitable status code
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backward compatibility.
virtual SlotId telux::tel::ICardFileHandler::getSlotId ( )
pure virtual

Get associated slot identifier for ICardFileHandler

Returns
telux::common::SlotId
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backward compatibility.
class telux::tel::ICardManager

ICardManager provide APIs for slot count, retrieve slot ids, get card state and get card.

Public Member Functions

virtual bool isSubsystemReady ()=0
 
virtual std::future< bool > onSubsystemReady ()=0
 
virtual telux::common::Status getSlotCount (int &count)=0
 
virtual telux::common::Status getSlotIds (std::vector< int > &slotIds)=0
 
virtual std::shared_ptr< ICard > getCard (int slotId=DEFAULT_SLOT_ID, telux::common::Status *status=nullptr)=0
 
virtual telux::common::Status cardPowerUp (SlotId slotId, telux::common::ResponseCallback callback=nullptr)=0
 
virtual telux::common::Status cardPowerDown (SlotId slotId, telux::common::ResponseCallback callback=nullptr)=0
 
virtual telux::common::Status registerListener (std::shared_ptr< ICardListener > listener)=0
 
virtual telux::common::Status removeListener (std::shared_ptr< ICardListener > listener)=0
 
virtual ~ICardManager ()
 

Constructor & Destructor Documentation

virtual telux::tel::ICardManager::~ICardManager ( )
virtual

Member Function Documentation

virtual bool telux::tel::ICardManager::isSubsystemReady ( )
pure virtual

Checks the status of telephony subsystems and returns the result.

Returns
If true then CardManager is ready for service.
virtual std::future<bool> telux::tel::ICardManager::onSubsystemReady ( )
pure virtual

Wait for telephony subsystem to be ready.

Returns
A future that caller can wait on to be notified when card manager is ready.
virtual telux::common::Status telux::tel::ICardManager::getSlotCount ( int &  count)
pure virtual

Get SIM slot count.

Parameters
[out]countSIM slot count.
Returns
Status of getSlotCount i.e. success or suitable status code.
virtual telux::common::Status telux::tel::ICardManager::getSlotIds ( std::vector< int > &  slotIds)
pure virtual

Get list of SIM slots.

Parameters
[out]slotIdsList of SIM slot ids.
Returns
Status of getSlotIds i.e. success or suitable status code.
virtual std::shared_ptr<ICard> telux::tel::ICardManager::getCard ( int  slotId = DEFAULT_SLOT_ID,
telux::common::Status *  status = nullptr 
)
pure virtual

Get the Card corresponding to SIM slot.

Parameters
[in]slotIdSlot id corresponding to the card.
[out]statusStatus of getCard i.e. success or suitable status code.
Returns
Pointer to ICard object.
virtual telux::common::Status telux::tel::ICardManager::cardPowerUp ( SlotId  slotId,
telux::common::ResponseCallback  callback = nullptr 
)
pure virtual

Power on the SIM card.

On platforms with access control enabled, caller needs to have TELUX_TEL_CARD_POWER permission to invoke this API successfully.

Parameters
[in]slotIdSlot identifier corresponding to the card which needs to be powered up.
[in]callbackOptional callback pointer to get the result of cardPowerUp
Returns
Status of cardPowerUp i.e. success or suitable status code.
virtual telux::common::Status telux::tel::ICardManager::cardPowerDown ( SlotId  slotId,
telux::common::ResponseCallback  callback = nullptr 
)
pure virtual

Power off the SIM card. When the SIM card is powered down, the card state is absent and the SIM IO operations, PIN management API's like unlock card by pin, change card pin will fail.

On platforms with access control enabled, caller needs to have TELUX_TEL_CARD_POWER permission to invoke this API successfully.

Parameters
[in]slotIdSlot identifier corresponding to the card which needs to be powered down.
[in]callbackOptional callback pointer to get the result of CardPowerDown
Returns
Status of cardPowerDown i.e. success or suitable status code.
virtual telux::common::Status telux::tel::ICardManager::registerListener ( std::shared_ptr< ICardListener >  listener)
pure virtual

Register a listener for card events.

Parameters
[in]listenerPointer to ICardListener object that processes the notification.
Returns
Status of registerListener i.e. success or suitable status code.
virtual telux::common::Status telux::tel::ICardManager::removeListener ( std::shared_ptr< ICardListener >  listener)
pure virtual

Remove a previously added listener.

Parameters
[in]listenerPointer to ICardListener object that needs to be removed.
Returns
Status of removeListener i.e. success or suitable status code.
class telux::tel::ICard

ICard represents currently inserted UICC or eUICC.

Public Member Functions

virtual telux::common::Status getState (CardState &cardState)=0
 
virtual std::vector< std::shared_ptr< ICardApp > > getApplications (telux::common::Status *status=nullptr)=0
 
virtual telux::common::Status openLogicalChannel (std::string applicationId, std::shared_ptr< ICardChannelCallback > callback=nullptr)=0
 
virtual telux::common::Status closeLogicalChannel (int channelId, std::shared_ptr< telux::common::ICommandResponseCallback > callback=nullptr)=0
 
virtual telux::common::Status transmitApduLogicalChannel (int channel, uint8_t cla, uint8_t instruction, uint8_t p1, uint8_t p2, uint8_t p3, std::vector< uint8_t > data, std::shared_ptr< ICardCommandCallback > callback=nullptr)=0
 
virtual telux::common::Status transmitApduBasicChannel (uint8_t cla, uint8_t instruction, uint8_t p1, uint8_t p2, uint8_t p3, std::vector< uint8_t > data, std::shared_ptr< ICardCommandCallback > callback=nullptr)=0
 
virtual telux::common::Status exchangeSimIO (uint16_t fileId, uint8_t command, uint8_t p1, uint8_t p2, uint8_t p3, std::string filePath, std::vector< uint8_t > data, std::string pin2, std::string aid, std::shared_ptr< ICardCommandCallback > callback=nullptr)=0
 
virtual int getSlotId ()=0
 
virtual telux::common::Status requestEid (EidResponseCallback callback)=0
 
virtual std::shared_ptr< ICardFileHandler > getFileHandler ()=0
 

Member Function Documentation

virtual telux::common::Status telux::tel::ICard::getState ( CardState &  cardState)
pure virtual

Get the card state for the slot id.

Parameters
[out]cardStateCardState - state of the card.
Returns
Status of getCardState i.e. success or suitable status code.
virtual std::vector<std::shared_ptr<ICardApp> > telux::tel::ICard::getApplications ( telux::common::Status *  status = nullptr)
pure virtual

Get card applications.

Parameters
[out]statusStatus of getApplications i.e. success or suitable status code.
Returns
List of card applications.
virtual telux::common::Status telux::tel::ICard::openLogicalChannel ( std::string  applicationId,
std::shared_ptr< ICardChannelCallback >  callback = nullptr 
)
pure virtual

Open a logical channel to the SIM.

On platforms with access control enabled, caller needs to have TELUX_TEL_CARD_OPS permission to invoke this API successfully.

Parameters
[in]applicationIdApplication Id.
[in]callbackOptional callback pointer to get the response of open logical channel request.
Returns
Status of openLogicalChannel i.e. success or suitable status code.
virtual telux::common::Status telux::tel::ICard::closeLogicalChannel ( int  channelId,
std::shared_ptr< telux::common::ICommandResponseCallback >  callback = nullptr 
)
pure virtual

Close a previously opened logical channel to the SIM.

On platforms with access control enabled, caller needs to have TELUX_TEL_CARD_OPS permission to invoke this API successfully.

Parameters
[in]channelIdThe channel ID to be closed.
[in]callbackOptional callback pointer to get the response of close logical channel request.
Returns
Status of closeLogicalChannel i.e. success or suitable status code.
virtual telux::common::Status telux::tel::ICard::transmitApduLogicalChannel ( int  channel,
uint8_t  cla,
uint8_t  instruction,
uint8_t  p1,
uint8_t  p2,
uint8_t  p3,
std::vector< uint8_t >  data,
std::shared_ptr< ICardCommandCallback >  callback = nullptr 
)
pure virtual

Transmit an APDU to the ICC card over a logical channel.

On platforms with access control enabled, caller needs to have TELUX_TEL_CARD_OPS permission to invoke this API successfully.

Parameters
[in]channelChannel Id of the channel to use for communication. Has to be greater than zero.
[in]claClass of the APDU command.
[in]instructionInstruction of the APDU command.
[in]p1Instruction Parameter 1 value of the APDU command.
[in]p2Instruction Parameter 2 value of the APDU command.
[in]p3Number of bytes present in the data field of the APDU command. If p3 is negative, a 4 byte APDU is sent to the SIM.
[in]dataData to be sent with the APDU.
[in]callbackOptional callback pointer to get the response of transmit APDU request.
Returns
Status of transmitApduLogicalChannel i.e. success or suitable status code.
virtual telux::common::Status telux::tel::ICard::transmitApduBasicChannel ( uint8_t  cla,
uint8_t  instruction,
uint8_t  p1,
uint8_t  p2,
uint8_t  p3,
std::vector< uint8_t >  data,
std::shared_ptr< ICardCommandCallback >  callback = nullptr 
)
pure virtual

Exchange APDUs with the SIM on a basic channel.

On platforms with access control enabled, caller needs to have TELUX_TEL_CARD_OPS permission to invoke this API successfully.

Parameters
[in]claClass of the APDU command.
[in]instructionInstruction of the APDU command.
[in]p1Instruction Param1 value of the APDU command.
[in]p2Instruction Param1 value of the APDU command.
[in]p3Number of bytes present in the data field of the APDU command. If p3 is negative, a 4 byte APDU is sent to the SIM.
[in]dataData to be sent with the APDU.
[in]callbackOptional callback pointer to get the response of transmit APDU request.
Returns
Status of transmitApduBasicChannel i.e. success or suitable status code.
virtual telux::common::Status telux::tel::ICard::exchangeSimIO ( uint16_t  fileId,
uint8_t  command,
uint8_t  p1,
uint8_t  p2,
uint8_t  p3,
std::string  filePath,
std::vector< uint8_t >  data,
std::string  pin2,
std::string  aid,
std::shared_ptr< ICardCommandCallback >  callback = nullptr 
)
pure virtual

Performs SIM IO operation, This is similar to the TS 27.007 "restricted SIM" operation where it assumes all of the EF selection will be done by the callee.

On platforms with access control enabled, caller needs to have TELUX_TEL_CARD_OPS permission to invoke this API successfully.

Parameters
[in]fileIdElementary File Identifier
[in]commandAPDU Command for SIM IO operation
[in]p1Instruction Param1 value of the APDU command
[in]p2Instruction Param2 value of the APDU command
[in]p3Number of bytes present in the data field of APDU command. If p3 is negative, a 4 byte APDU is sent to the SIM.
[in]filePathPath of the file
[in]dataData to be sent with the APDU, send empty or null string in case no data
[in]pin2Pin value of the SIM. Invalid attempt of PIN2 value will lock the SIM. send empty or null string in case of no Pin2 value
[in]aidApplication identifier, send empty or null string in case of no aid
[in]callbackOptional callback pointer to get the response of SIM IO request
Returns
- Status of exchangeSimIO i.e. success or suitable status code
virtual int telux::tel::ICard::getSlotId ( )
pure virtual

Get associated slot id for ICard

Returns
SlotId
virtual telux::common::Status telux::tel::ICard::requestEid ( EidResponseCallback  callback)
pure virtual

Request eUICC identifier (EID) of eUICC card.

On platforms with access control enabled, caller needs to have TELUX_TEL_PRIVATE_INFO_READ permission to invoke this API successfully.

Parameters
[in]callbackCallback function to get the result of request EID.
Returns
Status of request EID i.e. success or suitable error code.
Dependencies Card should be eUICC capable
virtual std::shared_ptr<ICardFileHandler> telux::tel::ICard::getFileHandler ( )
pure virtual

Get file handler for reading or writing to EF on SIM.

Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backward compatibility.
Returns
ICardFileHandler
class telux::tel::ICardChannelCallback

Interface for Card callback object. Client needs to implement this interface to get single shot responses for commands like open logical channel and close logical channel.

The methods in callback can be invoked from multiple different threads. The implementation should be thread safe.

Public Member Functions

virtual void onChannelResponse (int channel, IccResult result, telux::common::ErrorCode error)=0
 
- Public Member Functions inherited from telux::common::ICommandCallback
virtual ~ICommandCallback ()
 

Member Function Documentation

virtual void telux::tel::ICardChannelCallback::onChannelResponse ( int  channel,
IccResult  result,
telux::common::ErrorCode  error 
)
pure virtual

This function is called with the response to the open logical channel operation.

Parameters
[in]channelChannel Id for the logical channel.
[in]resultIccResult of open logical channel.
[in]errortelux::common::ErrorCode of the request.
class telux::tel::ICardCommandCallback

Public Member Functions

virtual void onResponse (IccResult result, telux::common::ErrorCode error)=0
 
- Public Member Functions inherited from telux::common::ICommandCallback
virtual ~ICommandCallback ()
 

Member Function Documentation

virtual void telux::tel::ICardCommandCallback::onResponse ( IccResult  result,
telux::common::ErrorCode  error 
)
pure virtual

This function is called when SIM Card transmit APDU over Logical, Basic Channel and Exchange Sim IO.

Parameters
[in]resultIccResult of transmit APDU command
[in]errortelux::common::ErrorCode of the request, Possible error codes are
class telux::tel::ICardListener

Interface for SIM Card Listener object. Client needs to implement this interface to get access to card services notifications on card state change.

The methods in listener can be invoked from multiple different threads. The implementation should be thread safe.

Public Member Functions

virtual void onCardInfoChanged (int slotId)
 
virtual ~ICardListener ()
 
- Public Member Functions inherited from telux::common::IServiceStatusListener
virtual void onServiceStatusChange (ServiceStatus status)
 
virtual ~IServiceStatusListener ()
 

Constructor & Destructor Documentation

virtual telux::tel::ICardListener::~ICardListener ( )
virtual

Member Function Documentation

virtual void telux::tel::ICardListener::onCardInfoChanged ( int  slotId)
virtual

This function is called when info of card gets updated.

Parameters
[in]slotIdSlot identifier.
struct telux::tel::CardReaderStatus

Structure contains identity of card reader status

Data Fields
int id

Card Reader ID

bool isRemovable

Card reader is removable

bool isPresent

Card reader is present

bool isID1size

Card reader present is ID-1 size

bool isCardPresent

Card is present in reader

bool isCardPoweredOn

Card in reader is powered

class telux::tel::ISapCardManager

ISapCardManager provide APIs for SAP related operations.

Public Member Functions

virtual bool isReady ()=0
 
virtual std::future< bool > onReady ()=0
 
virtual telux::common::Status getState (SapState &sapState)=0
 
virtual telux::common::Status requestSapState (SapStateResponseCallback callback)=0
 
virtual telux::common::Status openConnection (SapCondition sapCondition=SapCondition::SAP_CONDITION_BLOCK_VOICE_OR_DATA, std::shared_ptr< telux::common::ICommandResponseCallback > callback=nullptr)=0
 
virtual telux::common::Status closeConnection (std::shared_ptr< telux::common::ICommandResponseCallback > callback=nullptr)=0
 
virtual telux::common::Status requestAtr (std::shared_ptr< IAtrResponseCallback > callback=nullptr)=0
 
virtual telux::common::Status transmitApdu (uint8_t cla, uint8_t instruction, uint8_t p1, uint8_t p2, uint8_t lc, std::vector< uint8_t > data, uint8_t le=0, std::shared_ptr< ISapCardCommandCallback > callback=nullptr)=0
 
virtual telux::common::Status requestSimPowerOff (std::shared_ptr< telux::common::ICommandResponseCallback > callback=nullptr)=0
 
virtual telux::common::Status requestSimPowerOn (std::shared_ptr< telux::common::ICommandResponseCallback > callback=nullptr)=0
 
virtual telux::common::Status requestSimReset (std::shared_ptr< telux::common::ICommandResponseCallback > callback=nullptr)=0
 
virtual telux::common::Status requestCardReaderStatus (std::shared_ptr< ICardReaderCallback > callback=nullptr)=0
 
virtual int getSlotId ()=0
 
virtual telux::common::Status registerListener (std::shared_ptr< ISapCardListener > listener)=0
 
virtual telux::common::Status removeListener (std::shared_ptr< ISapCardListener > listener)=0
 
virtual ~ISapCardManager ()
 

Constructor & Destructor Documentation

virtual telux::tel::ISapCardManager::~ISapCardManager ( )
virtual

Member Function Documentation

virtual bool telux::tel::ISapCardManager::isReady ( )
pure virtual

Checks the status of SIM access profile(SAP) subsystem and returns the result.

Returns
If true then SapCardManager is ready for service.
virtual std::future<bool> telux::tel::ISapCardManager::onReady ( )
pure virtual

Wait for IM access profile(SAP) subsystem to be ready.

Returns
A future that caller can wait on to be notified when card manager is ready.
virtual telux::common::Status telux::tel::ISapCardManager::getState ( SapState &  sapState)
pure virtual

Get SIM access profile (SAP) client connection state.

Parameters
[out]sapStateSapState of the SIM Card
Returns
Status of getState i.e. success or suitable status code.
Deprecated
Use requestSapState() API below to get SAP state
virtual telux::common::Status telux::tel::ISapCardManager::requestSapState ( SapStateResponseCallback  callback)
pure virtual

Get SIM access profile(SAP) client connection state.

Parameters
[out]callbackCallback function pointer to get the response of requestSapState.
Returns
Status of requestSapState i.e. success or suitable status code.
virtual telux::common::Status telux::tel::ISapCardManager::openConnection ( SapCondition  sapCondition = SapCondition::SAP_CONDITION_BLOCK_VOICE_OR_DATA,
std::shared_ptr< telux::common::ICommandResponseCallback >  callback = nullptr 
)
pure virtual

Establishes SIM access profile (SAP) client connection with SIM Card.

Parameters
[in]sapConditionCondition to enable sap connection.
[in]callbackOptional callback to get the response of open sap connection request or possible error codes i.e.
Returns
Status of openConnection i.e. success or suitable status code.
virtual telux::common::Status telux::tel::ISapCardManager::closeConnection ( std::shared_ptr< telux::common::ICommandResponseCallback >  callback = nullptr)
pure virtual

Releases a SAP connection to SIM Card.

Parameters
[in]callbackOptional callback to get the response of close sap connection request or possible error codes i.e.
Returns
Status of closeConnection i.e. success or suitable status code
virtual telux::common::Status telux::tel::ISapCardManager::requestAtr ( std::shared_ptr< IAtrResponseCallback >  callback = nullptr)
pure virtual

Request for SAP Answer To Reset command.

Parameters
[in]callbackOptional callback to get the response of requestAtr.
Returns
Status of requestAtr i.e. success or suitable status code.
virtual telux::common::Status telux::tel::ISapCardManager::transmitApdu ( uint8_t  cla,
uint8_t  instruction,
uint8_t  p1,
uint8_t  p2,
uint8_t  lc,
std::vector< uint8_t >  data,
uint8_t  le = 0,
std::shared_ptr< ISapCardCommandCallback >  callback = nullptr 
)
pure virtual

Send the Apdu on SAP mode.

Parameters
[in]claClass of the APDU command.
[in]instructionInstruction of the APDU command.
[in]p1Instruction Parameter 1 value of the APDU command.
[in]p2Instruction Parameter 1 value of the APDU command.
[in]lcNumber of bytes present in the data field of the APDU command. If lc is negative, a 4 byte APDU is sent to the SIM.
[in]dataList of data to be sent with the APDU.
[in]leMaximum number of bytes expected in the data field of the response to the command.
[in]callbackOptional callback to send APDU in SAP mode.
Returns
Status of transmitApdu i.e. success or suitable status code.
virtual telux::common::Status telux::tel::ISapCardManager::requestSimPowerOff ( std::shared_ptr< telux::common::ICommandResponseCallback >  callback = nullptr)
pure virtual

Send the SAP SIM power off request.

Parameters
[in]callbackOptional callback to get the response for SIM power off.
Returns
Status of requestSimPowerOff i.e. success or suitable status code.
virtual telux::common::Status telux::tel::ISapCardManager::requestSimPowerOn ( std::shared_ptr< telux::common::ICommandResponseCallback >  callback = nullptr)
pure virtual

Send the SAP SIM power on request.

Parameters
[in]callbackOptional callback to get the response for SIM power on.
Returns
Status of requestSimPowerOn i.e. success or suitable status code.
virtual telux::common::Status telux::tel::ISapCardManager::requestSimReset ( std::shared_ptr< telux::common::ICommandResponseCallback >  callback = nullptr)
pure virtual

Send the SAP SIM reset request.

Parameters
[in]callbackOptional callback to get the response for SIM reset
Returns
Status of requestSimReset i.e. success or suitable status code.
virtual telux::common::Status telux::tel::ISapCardManager::requestCardReaderStatus ( std::shared_ptr< ICardReaderCallback >  callback = nullptr)
pure virtual

Send the SAP Card Reader Status request command.

Parameters
[in]callbackOptional callback to get the response for card reader status
Returns
Status of requestCardReaderStatus i.e. success or suitable status code.
virtual int telux::tel::ISapCardManager::getSlotId ( )
pure virtual

Get associated slot id for the SapCardManager.

Returns
SlotId
virtual telux::common::Status telux::tel::ISapCardManager::registerListener ( std::shared_ptr< ISapCardListener >  listener)
pure virtual

Register a listener for SAP events.

Parameters
[in]listenerPointer to ISapCardListener object that processes the notification.
Returns
Status of registerListener i.e. success or suitable status code.
virtual telux::common::Status telux::tel::ISapCardManager::removeListener ( std::shared_ptr< ISapCardListener >  listener)
pure virtual

Remove a previously added listener.

Parameters
[in]listenerPointer to ISapCardListener object that needs to be removed.
Returns
Status of removeListener i.e. success or suitable status code.
class telux::tel::IAtrResponseCallback

Public Member Functions

virtual void atrResponse (std::vector< int > responseAtr, telux::common::ErrorCode error)=0
 
- Public Member Functions inherited from telux::common::ICommandCallback
virtual ~ICommandCallback ()
 

Member Function Documentation

virtual void telux::tel::IAtrResponseCallback::atrResponse ( std::vector< int >  responseAtr,
telux::common::ErrorCode  error 
)
pure virtual

This function is called in response to requestAtr() request.

Parameters
[in]responseAtrresponse ATR values
[in]errortelux::common::ErrorCode of the request possible error codes are
class telux::tel::ISapCardCommandCallback

Public Member Functions

virtual void onResponse (IccResult result, telux::common::ErrorCode error)=0
 
- Public Member Functions inherited from telux::common::ICommandCallback
virtual ~ICommandCallback ()
 

Member Function Documentation

virtual void telux::tel::ISapCardCommandCallback::onResponse ( IccResult  result,
telux::common::ErrorCode  error 
)
pure virtual

This function is called when SIM Card transmit APDU on SAP mode.

Parameters
[in]resultIccResult of transmit APDU command
[in]errortelux::common::ErrorCode of the request, possible error codes are
class telux::tel::ICardReaderCallback

Public Member Functions

virtual void cardReaderResponse (CardReaderStatus cardReaderStatus, telux::common::ErrorCode error)=0
 
- Public Member Functions inherited from telux::common::ICommandCallback
virtual ~ICommandCallback ()
 

Member Function Documentation

virtual void telux::tel::ICardReaderCallback::cardReaderResponse ( CardReaderStatus  cardReaderStatus,
telux::common::ErrorCode  error 
)
pure virtual

This function is called in response to requestCardReaderStatus() method.

Parameters
[in]cardReaderStatusStructure contains the identity of the card reader
[in]errortelux::common::ErrorCode of the request
class telux::tel::ISapCardListener

Interface for SAP Listener object. Client needs to implement this interface to get access to SAP service notifications like service status change.

The methods in listener can be invoked from multiple different threads. The implementation should be thread safe.

Public Member Functions

virtual ~ISapCardListener ()
 
- Public Member Functions inherited from telux::common::IServiceStatusListener
virtual void onServiceStatusChange (ServiceStatus status)
 
virtual ~IServiceStatusListener ()
 

Constructor & Destructor Documentation

virtual telux::tel::ISapCardListener::~ISapCardListener ( )
virtual

Typedef Documentation

using telux::tel::PinOperationResponseCb = typedef std::function<void(int retryCount, telux::common::ErrorCode error)>

This function is called with the response to pin operations like change pin password, unlock card and set card lock.

Parameters
[in]retryCountNo of retry attempts left
[in]errorReturn code for whether the operation succeeded or failed
using telux::tel::QueryFdnLockResponseCb = typedef std::function<void(bool isAvailable, bool isEnabled, telux::common::ErrorCode error)>

This function is called with the response to queryFdnLockState API.

Parameters
[in]isAvailableDetermine FDN lock state availability
[in]isEnabledDetermine FDN lock state i.e enable or disable
[in]errorReturn code for whether the operation succeeded or failed
using telux::tel::QueryPin1LockResponseCb = typedef std::function<void(bool state, telux::common::ErrorCode error)>

This function is called with the response to queryPin1LockState API.

Parameters
[in]stateDetermine state whether enabled or disabled
[in]errorReturn code for whether the operation succeeded or failed
using telux::tel::EfOperationCallback = typedef std::function<void(telux::common::ErrorCode error, IccResult result)>

This function is invoked when elementary file(EF) operations like either reading/writing a single record to a linear fixed file or reading/writing the data to the transparent file are performed.

Parameters
[in]errortelux::common::ErrorCode
[in]resultFor read operation telux::tel::IccResult::data contains either record corresponding to linear fixed file or data corresponding to the transparent file. For write operation telux::tel::IccResult::data and telux::tel::IccResult::payload is empty.
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backward compatibility.
using telux::tel::EfReadAllRecordsCallback = typedef std::function<void(telux::common::ErrorCode error, std::vector<IccResult> records)>

This function is called when an elementary file(EF) operation like reading all records from a linear fixed file is performed.

Parameters
[in]errortelux::common::ErrorCode
[in]recordsList of records returned for EF read operation from a linear fixed file. If the reading of any of the records from the file fails then the records returned will be empty.
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backward compatibility.
using telux::tel::EfGetFileAttributesCallback = typedef std::function<void(telux::common::ErrorCode error, IccResult result, FileAttributes attributes)>

This function is called when an elementary file operation like getting file attributes is performed.

Parameters
[in]errortelux::common::ErrorCode
[in]resulttelux::tel::IccResult for elementary file operation like get SIM file attributes.
[in]attributestelux::tel::FileAttributes contain EF file information like file type and file size etc.
Note
Eval: This is a new API and is being evaluated. It is subject to change and could break backward compatibility.
using telux::tel::EidResponseCallback = typedef std::function<void(const std::string &eid, telux::common::ErrorCode error)>

This function is called with the response to requestEid API.

The callback can be invoked from multiple different threads. The implementation should be thread safe.

Parameters
[in]eideUICC identifier.
[in]errorReturn code which indicates whether the operation succeeded or not. ErrorCode
using telux::tel::SapStateResponseCallback = typedef std::function<void(SapState sapState, telux::common::ErrorCode error)>

This function is called with the response to requestSapState API.

The callback can be invoked from multiple different threads. The implementation should be thread safe.

Parameters
[in]sapStateSapState of SIM access profile (SAP) connection
[in]errorReturn code for whether the operation succeeded or failed

Enumeration Type Documentation

enum telux::tel::CardState
strong

Defines all state of Card like absent, present etc

Enumerator
CARDSTATE_UNKNOWN 

Unknown card state

CARDSTATE_ABSENT 

Card is absent

CARDSTATE_PRESENT 

Card is present

CARDSTATE_ERROR 

Card is having error, either card is removed and not readable

CARDSTATE_RESTRICTED 

Card is present but not usable due to carrier restrictions.

enum telux::tel::CardError
strong

Defines the reasons for error in CardState

Enumerator
UNKNOWN 

Unknown error

POWER_DOWN 

Power down

POLL_ERROR 

Poll error

NO_ATR_RECEIVED 

No ATR received

VOLT_MISMATCH 

Volt mismatch

PARITY_ERROR 

Parity error

POSSIBLY_REMOVED 

Unknown, possibly removed

TECHNICAL_PROBLEMS 

Card returned technical problems

NULL_BYTES 

Card returned NULL bytes

SAP_CONNECTED 

Terminal in SAP mode

CMD_TIMEOUT 

Command timeout error

enum telux::tel::CardLockType
strong

Defines all types of card locks which uses in PIN management APIs

Enumerator
PIN1 

Lock type is PIN1

PIN2 

Lock type is PIN2

PUK1 

Lock type is Pin Unblocking Key1

PUK2 

Lock type is Pin Unblocking Key2

FDN 

Lock type is Fixed Dialing Number

enum telux::tel::AppType

Defines all type of UICC application such as SIM, RUIM, USIM, CSIM and ISIM.

Enumerator
APPTYPE_UNKNOWN 

Unknown application type

APPTYPE_SIM 

UICC application type is SIM

APPTYPE_USIM 

UICC application type is USIM

APPTYPE_RUIM 

UICC application type is RSIM

APPTYPE_CSIM 

UICC application type is CSIM

APPTYPE_ISIM 

UICC application type is ISIM

enum telux::tel::AppState

Defines all application states.

Enumerator
APPSTATE_UNKNOWN 

Unknown application state

APPSTATE_DETECTED 

application state detected

APPSTATE_PIN 

If PIN1 or UPin is required

APPSTATE_PUK 

If PUK1 or Puk for UPin is required

APPSTATE_SUBSCRIPTION_PERSO 

PersoSubstate should be look at when application state is assigned to this value

APPSTATE_READY 

application State is ready

enum telux::tel::EfType
strong

Defines supported elementary file(EF) types.

Enumerator
UNKNOWN 

Unknown EF type

TRANSPARENT 

Transparent EF

LINEAR_FIXED 

Linear Fixed EF

enum telux::tel::SapState
strong

Defines all SIM access profile (SAP) connection states.

Enumerator
SAP_STATE_NOT_ENABLED 

SAP connection not enabled

SAP_STATE_CONNECTING 

SAP State is connecting

SAP_STATE_CONNECTED_SUCCESSFULLY 

SAP connection is successful

SAP_STATE_CONNECTION_ERROR 

SAP connection error

SAP_STATE_DISCONNECTING 

SAP state is disconnecting

SAP_STATE_DISCONNECTED_SUCCESSFULLY 

SAP state disconnection is successful

enum telux::tel::SapCondition
strong

Indicates type of connection required, default behavior is to block a SAP connection when a voice or data call is active.

Enumerator
SAP_CONDITION_BLOCK_VOICE_OR_DATA 

Block a SAP connection when a voice or data call is active (Default)

SAP_CONDITION_BLOCK_DATA 

Block a SAP connection when a data call is active

SAP_CONDITION_BLOCK_VOICE 

Block a SAP connection when a voice call is active

SAP_CONDITION_BLOCK_NONE 

Allow Sap connection in all cases