/pps/services/cellular/uicc/card0/control

General purpose UICC-related functions

Publishers
UICC service; clients of the UICC service
Subscribers
UICC service; clients of the UICC service
Note: This type of object is known as a server object, a special PPS object designed for point-to-point communication between a server and one or more clients. For details, see "Server objects" in the Persistent Publish/Subscribe Developer's Guide.

Message/response format

Commands sent to the /pps/services/cellular/uicc/card0/control object are of the form:

msg::command_string\nid::msg_ID\ndat:json:{JSON_data}

Responses always reflect the command_string and msg_ID that were sent in the message, along with any errors:

res::command_string
id::msg_ID
dat:json:{JSON_data}
error::error_description

The response includes either the dat attribute (on success) or the err attribute (on error).

pin command

Request UICC service to enable/disable the PIN lock for CHV1.

The pin command has the following form:
msg::pin
id::msg_ID
dat:json:
{
    "mode":operation_mode,
    "password":chv1_password
}
where mode is either ENABLE or DISABLE and password is the personal identification number (PIN) for CHV1. Both parameters are required.

pin response

The UICC service sends the following response to the CHV1 pin request with the same ID:
res::pin
id::msg_ID
err:n:error_code
where err_code is one of the following codes:
  • -1—General failure that is not related specifically to UICC (STATUS_FAILURE)
  • -7—Invalid PIN/PUK (STATUS_INVALID_CHV). If an invalid password is is entered, the unlock_retries_left field is decremented until the CHV is blocked (see Fields in chv1_status and chv2_status for more information).
  • -8—General UICC error (STATUS_UICC_ERROR)

pin_code command

Request UICC service to verify and unlock the SIM for CHV1 using a PIN.

The pin_code command has the following format:
msg::pin_code
id::msg_ID
dat:json:
{
    "chv_number":chv_number,
    "password":password
}
where chv_number is CHV1 and password is the PIN for the specified CHV number. Both parameters are required.

pin_code response

The UICC service sends the following response to the pin_code request with the same ID:
res::pin_code
id::msg_ID
err:n:error_code
where err_code is one of the following codes:
  • -1—General failure that is not related specifically to UICC (STATUS_FAILURE)
  • -7—Invalid PIN/PUK (STATUS_INVALID_CHV). If an invalid password is is entered, the unlock_retries_left field is decremented until the CHV is blocked (see Fields in chv1_status and chv2_status for more information).
  • -8—General UICC error (STATUS_UICC_ERROR)

puk_code command

Request the UICC service to unblock the SIM (CHV1) using a PIN unlock key (PUK), and set the PIN to a new value.

The puk_code command has the following format:
msg::puk_code
id::msg_ID
dat:json:
{
    "chv_number":chv_number,
    "puk_password":puk_password
    "new_password":new_password
}
The puk_code command has the following parameters, all of which are required:
chv_number
CHV1
puk_password
The PUK for the SIM.
new_password
The new PIN for the SIM.

puk_code response

The UICC service sends the following response to the puk_code request with the same ID:
res::puk_code
id::msg_ID
err:n:error_code
where err_code is one of the following codes:
  • -1—General failure that is not related specifically to UICC (STATUS_FAILURE)
  • -7—Invalid PIN/PUK (STATUS_INVALID_CHV). If an invalid PUK password is is entered, the unblock_retries_left field is decremented until the SIM is permanently blocked (see Fields in chv1_status and chv2_status for more information)
  • -8—General UICC error (STATUS_UICC_ERROR)

pin_new command

Request UICC service to change the PIN for CHV1.

The pin_new command has the following format:
msg::pin_new
id::msg_ID
dat:json:
{
    "chv_number":chv_number,
    "old_password":old_password
    "new_password":new_password
}
The pin_new command has the following parameters, all of which are required:
chv_number
CHV1
old_password
The old PIN.
new_password
The new PIN.

pin_new response

The UICC service sends the following response to the pin_new request with the same ID:
res::pin_new
id::msg_ID
err:n:error_code
where err_code is one of the following values:
  • -1—General failure that is not related specifically to UICC (STATUS_FAILURE)
  • -7—Invalid PIN/PUK (STATUS_INVALID_CHV). If an invalid password is is entered, the unlock_retries_left field is decremented until the CHV is blocked (see Fields in chv1_status and chv2_status for more information).
  • -8—General UICC error (STATUS_UICC_ERROR)

ef_req_info command

Request UICC service to get the file information for the specified UICC elementary file (EF).

The ef_req_info command has the following format:
msg::ef_req_info
id::msg_ID
dat::EF_ID
where EF_ID (required) is the string representation of the ID of the UICC EF. See IDs for UICC Elementary Files for the list of IDs.

ef_req_info response

The UICC service sends the following response to the ef_req_info request with the same ID:
res::ef_req_info
id::msg_ID
dat:json:
{
    "type":EF_type_string,
    "size":EF_size,
    "rec_length":EF_record_length,
    "num_rec":number_of_records
}
err:n:error_code
The ef_req_info response returns the following fields in the dat attribute:
type
A string representing the type of the elementary file. One the following values:
  • TRANS—Transparent Type - binary
  • LIN—Linear Fixed Record Type
  • CYCLIC—Cyclic Record Type
  • INVALID—Invalid EF Type
size
An integer string representing the total EF size. Required.
rec_length
An integer string representing the EF record size. Required.
num_rec
An integer string representing the number of records. Required.
err
The err attribute is returned only in an error condition and is one of the following values:
  • -1—General failure that is not related specifically to UICC (STATUS_FAILURE)
  • -2—EF not present (STATUS_FILE_NOT_PRESENT)
  • -3—EF ID invalid (STATUS_FILE_INVALID)
  • -4—Data Buffer too small (STATUS_DATA_BUFFER_TOO_SMALL)
  • -6—CHV is blocked (STATUS_ACCESS_DENIED)

ef_read command

Request the UICC service to read the specified UICC elementary file (EF).

The ef_read command has the following format:

msg::ef_read
id::msg_ID
dat:json:
{
    "efid":EF_ID,
    "rec_num":EF_record_number,
    "len":EF_record_length
>

The parameters are as follows:

efid
The string representation of the ID of the UICC EF. Required.
rec_num
The index of the EF record to read. Required.
len
The length of the EF record. Required.

ef_read response

The UICC service sends the following response to the ef_read request with the same ID:
res::ef_read
id::msg_ID
dat:json:EF_data
err:n:error_code
where EF_data is a binary hexadecimal string of the EF record data and err_code (returned only on error) is one of the following codes:
  • -1—General failure that is not related specifically to UICC (STATUS_FAILURE)
  • -2—EF not present (STATUS_FILE_NOT_PRESENT)
  • -3—EF ID invalid (STATUS_FILE_INVALID)
  • -4—Data buffer too small (STATUS_DATA_BUFFER_TOO_SMALL)
  • -6—CHV is blocked (STATUS_ACCESS_DENIED)

fdn command

Request UICC service to enable or disable Fixed Dialing Number (FDN).

The fdn command has the following format:

msg::fdn
id::msg_ID
dat:json:
{
    "mode":FDN_mode,
    "password":password
}

where mode is either "ENABLE" or "DISABLE" and password is the PIN .

fdn response

The UICC service sends the following response to the fdn request with the same ID:
res::fdn
id::msg_ID
err:n:error_code
where err_code is one of the following codes:
  • -1—General failure that is not related specifically to UICC (STATUS_FAILURE)
  • -7—Invalid PIN/PUK (STATUS_INVALID_CHV)
  • -8—General UICC error (STATUS_UICC_ERROR)

pb_get_info command

Get the phonebook information of the specifiied type.

The pb_get_info command has the following format:

msg::pb_get_info
id::msg_ID
dat:json:
{
    "type":"pb_type"
}
where type (required) is one of:
  • FDN—FDN Phonebook
  • ADN—ADN Phonebook - SIM Phonebook
  • SDN—SDN Phonebook - Service Dialing Number

pb_get_info response

The UICC service sends the pb_get_info response to the client in reply to the pb_get_info command. The response has the following form:
res::pb_get_info
id:msg_ID
dat:json:
{
    "type":"pb_type,
    "rec_total":num_entries,
    "available":true|false,
    "mode":ENABLE|DISABLE,
    "name_length":max_name_length,
    "number_length":max_digits,
    "email_length":max_email_length
}
err:n:error_code

The following parameters and attributes may be returned in the response:

type
The phonebook type. One of:
  • FDN—FDN Phonebook
  • ADN—ADN Phonebook - SIM Phonebook
  • SDN—SDN Phonebook - Service Dialing Number
rec_total
An integer representing the total number of phonebook entries.
available
A Boolean indicating whether the phonebook type is available.
mode
A string representing the mode. Either ENABLE or DISABLE.
name_length
An integer representing the maximum length in bytes supported for the phonebook alpha string name attribute.
number_length
An integer representing the maximum number of digits supported for the number attribute.
email_length
An integer representing the maximum length in bytes supported for the phonebook alpha string email attribute.
err
The following code may be returned in the err attribute in the case of an error:
  • -1—General failure that is not related specifically to UICC (STATUS_FAILURE).

pb_read_entry command

Read a phonebook entry.

The pb_read_entry command has the following form:

msg::pb_read_entry
id::msg_ID
dat:json:
{
    "type":"phonebook_type",
    "rec_num":"record_number",
}

The parameters are as follows:

type
The phonebook type (required). One of:
  • FDN—FDN Phonebook
  • ADN—ADN Phonebook - SIM Phonebook
  • SDN—SDN Phonebook - Service Dialing Number
rec_num
The index of the phonebook record to read.

pb_read_entry response

The UICC service sends the pb_read_entry response to the client in reply to the pb_read_entry command. The response has the following form:

res::pb_read_entry
id::msg_ID
dat:json:
{
    "type":phonebook_type,
    "rec_num":record_number,
    "name":entry_name,
    "number":entry_number,
    "hidden":true|false",
    "second_name":second_entry_name",
    "group":["group1","group2", ... ]
    "email":["email1","email2", ... ]
    "extended":[ 
        {"alpha":"name1","number":"number1"},
        {"alpha":"name2","number":"number2"},
        ...
        ]
}
err:n:error_code

The following parameters and attributes may be returned in the response:

type
The phonebook type. One of:
  • FDN—FDN Phonebook
  • ADN—ADN Phonebook - SIM Phonebook
  • SDN—SDN Phonebook - Service Dialing Number
rec_num
The record index of the phonebook entry.
name
The name string of the phonebook entry.
number
The phone number string of the phonebook entry.
hidden
An optional Boolean that indicates whether this entry is hidden. Applies only for extended phonebook (ADN) in USIM.
second_name
An optional second name (SNE), represented as a UTF-8 string (null terminated) that contains either GSM 7-bit or UCS2 character sets. Applies only for extended phonebook (ADN) in USIM.
group
A JSON array of UTF-8 strings representing the group names for this phonebook entry. Applies only for extended phonebook (ADN) in USIM.
email
A JSON array of UTF-8 strings representing the email addresses for this phonebook entry. Applies only for extended phonebook (ADN) in USIM.
extended
A JSON array of alpha and number fields, each containing UTF-8 strings, that represents additional name and number attributes for this phonebook entry. Applies only for extended phonebook (ADN) in USIM.
err
One of the following codes may be returned in the err attribute in the case of an error:
  • -1—General failure that is not related specifically to UICC (STATUS_FAILURE).
  • -2—EF not present (STATUS_FILE_NOT_PRESENT).
  • -3—EF ID invalid (STATUS_FILE_INVALID).
  • -4—Data Buffer too small (STATUS_DATA_BUFFER_TOO_SMALL).
  • -6—CHV is blocked (STATUS_ACCESS_DENIED).

pb_update_entry command

Create or update a phonebook entry.

The pb_update_entry requests the UICC service to update the specified phonebook entry. If the entry doesn't exist, it will be created. The command has the following form:

msg::pb_update_entry
id::msg_ID
dat:json:
{
    "type":phonebook_type,
    "rec_num":record_number,
    "name":entry_name,
    "number":entry_number,
    "hidden":true|false,
    "second_name":second_entry_name,
    "group":["group1","group2", ... ]
    "email":["email1","email2", ... ]
    "extended":[ 
        {"alpha":"name1","number":"number1"},
        {"alpha":"name2","number":"number2"},
        ...
        ]
}

where the attributes and parameters are as described for the pb_read_entry response.

pb_update_entry response

The UICC service sends the pb_update_entry response to the client in reply to the pb_update_entry command. The response has the following form:

res::pb_update_entry
id::msg_ID
err:n:error_code
One of the following codes may be returned in the err attribute in the case of an error:
  • -1—General failure that is not related specifically to UICC (STATUS_FAILURE).
  • -2—EF not present (STATUS_FILE_NOT_PRESENT).
  • -3—EF ID invalid (STATUS_FILE_INVALID).
  • -5—Data Buffer too large (STATUS_DATA_ TOO_LARGE).
  • -6—CHV is blocked (STATUS_ACCESS_DENIED).
  • -7—General UICC error (STATUS_UICC_ERROR)
  • -8—Invalid PIN/PUK (STATUS_INVALID_CHV)

pb_delete_entry command

Delete a phonebook entry.

The pb_delete_entry command has the following form:

msg::pb_delete_entry
id::msg_ID
dat:json:
{
    "type":phonebook_type
    "rec_num":record_number
}

where:

  • type is required and is one of:
    • FDN—FDN Phonebook
    • ADN—ADN Phonebook - SIM Phonebook
    • SDN—SDN Phonebook - Service Dialing Number
  • rec_num (required) is the index of the phonebook record to delete.

pb_delete_entry response

The UICC service sends the pb_delete_entry response to the client in reply to the pb_delete_entry command. The response has the following form:

res::pb_delete_entry
id::msg_ID
err:n:error_code
One of the following codes may be returned in the err attribute in the case of an error:
  • -1—General failure that is not related specifically to UICC (STATUS_FAILURE).
  • -2—EF not present (STATUS_FILE_NOT_PRESENT).
  • -3—EF ID invalid (STATUS_FILE_INVALID).
  • -5—Data Buffer too large (STATUS_DATA_ TOO_LARGE).
  • -6—CHV is blocked (STATUS_ACCESS_DENIED).
  • -7—General UICC error (STATUS_UICC_ERROR)
  • -8—Invalid PIN/PUK (STATUS_INVALID_CHV)

ons_get_network_names command

Get the network name.

This command requests the UICC ONS service to get the network name based on the inputs of MCC, MNC and roaming status. This function uses the ONS logic to resolve the network names based on:
  1. EF OPL/PNN, SPN, SPDI, CPHS ON, CPHS ONS
  2. NITZ Names
  3. SE13 Table
  4. MCC-MNC

The ons_get_network_names command has the following form:

msg::ons_get_network_names
id::msg_ID
dat:json:
{
    "mcc":"mcc_string",
    "mnc":"mnc_string",
    "lac":location_area_code,
    "hplmn":true|false
}

where:

  • mcc (required) is the Mobile Country Code string, such as 310.
  • mnc (required) is the Mobile Network Code string, such as 410.
  • lac (required) is the integer Locaton Area Code in decimal form, such as 12997.
  • hplmn (required) is a Boolean that indicates whether the specified PLMN is home (true) or roaming (false).

ons_get_network_names response

The UICC service sends the ons_get_network_names response to the client in reply to the ons_get_network_names command. The response has the following form:

res::ons_get_network_names
id::msg_ID
dat:json:
{
    "name_long":"operator_long_name",
    "name_short":"operator_short_name",
}
err:n:error_code

The following parameters and attributes may be returned in the response:

name_long
The operator name (long format) as a UTF-8 string.
name_short
The operator name (short format) as a UTF-8 string.
err
The following code may be returned in the err attribute in the case of an error:
  • -1—General Error.

se13_get_network_names command

Resolve the network name from SE13 table and BBSE network override table. If not found, empty strings will be returned.

The se13_get_network_names command has the following form:

msg::se13_get_network_names
id::msg_ID
dat:json:
{
    "mcc":"mcc_string",
    "mnc":"mnc_string",
}

where:

  • mcc (required) is the Mobile Country Code string, such as 310.
  • mnc (required) is the Mobile Network Code string, such as 410.

se13_get_network_names response

The UICC service sends the se13_get_network_names response to the client in reply to the se13_get_network_names command. The response has the following form:

res::se13_get_network_names
id::msg_ID
dat:json:
{
    "name_long":"operator_long_name",
    "name_short":"operator_short_name",
}
err:n:error_code

The following parameters and attributes may be returned in the response:

name_long
The operator name (long format) as an ASCII string.
name_short
The operator name (short format) as an ASCII string.
err
The following code may be returned in the err attribute in the case of an error:
  • -1—General Error.

set_msisdn command

Set the MSISDN.

The set_msisdn command has the following form:

msg::set_msisdn
id::msg_ID
dat::msisdn_phone_number

where the dat attribute contains a string representing the MSISDN to set.

set_msisdn response

The UICC service sends the set_msisdn response to the client in reply to the set_msisdn command. The response has the following form:

res::set_msisdn
id::msg_ID
err:n:error_code
The following code may be returned in the err attribute in the case of an error:
  • -1—General Error.