le_mrc_interface.h File Reference

Mobile Country Code length One extra byte is added for the null character.

Mobile Country Code length

Mobile Network Code length One extra byte is added for the null character.

Mobile Network Code length

Cellular Network length.

Reference type for one Cell Information.

Handler for cellular asynchronous network scan Sending result. Returns the reference to the List object. Null pointer if the scan failed.

Parameters

listRef	Reference to the List object. Null pointer if the scan failed.
contextPtr

Handler for asynchronous manual selection response

Parameters

result	Manual selection response
contextPtr

Reference type for the signal metrics.

Reference type for all Neighboring Cells Information.

Reference type used by Add/Remove functions for EVENT 'le_mrc_NetRegStateEvent'

Handler for Network registration state changes.

Parameters

state	Parameter ready to receive the Network Registration state.
contextPtr

Reference type for Preferred Operator Listing.

Reference type for referring to the Preferred Operator objects.

Handler for Radio Access Technology changes.

Parameters

rat	Parameter ready to receive the Radio Access Technology.
contextPtr

Reference type used by Add/Remove functions for EVENT 'le_mrc_RatChange'

Reference type for Scan Information Listing.

Reference type for referring to MRC Scan Information objects.

Handler for Signal Strength value changes.

Parameters

ss	Signal strength in dBm
contextPtr

Reference type used by Add/Remove functions for EVENT 'le_mrc_SignalStrengthChange'

2G/3G Band Bit Mask (64 bits)

LTE Band Bit Mask (32bits)

Network Registration states.

Radio Access Technology enum

Radio Bitmask Access Technology Bit Mask

TDSCDMA Band Bit Mask

Add handler function for EVENT 'le_mrc_NetRegStateEvent'

This event provides information on network registration state changes.

Note

multi-app safe

Parameters

[in]	handlerPtr
[in]	contextPtr

Add a preferred operator by specifying the MCC/MNC and the Radio Access Technology.

Returns

• LE_NOT_FOUND User Preferred operator list is not available.
• LE_FAULT Function failed.
• LE_BAD_PARAMETER RAT mask is invalid.
• LE_OK Function succeeded.

Note

If one code is too long (max LE_MRC_MCC_LEN/LE_MRC_MNC_LEN digits), it's a fatal error, the function won't return.

NOT multi-app safe

Parameters

[in]	mcc	Mobile Country Code
[in]	mnc	Mobile Network Code
[in]	ratMask	Bit mask for the Radio Access Technology preferences.

Add handler function for EVENT 'le_mrc_RatChange'

This event provides information on Radio Access Technology changes.

Note

multi-app safe

Parameters

[in]	handlerPtr
[in]	contextPtr

Add handler function for EVENT 'le_mrc_SignalStrengthChange'

This event provides information on Signal Strength value changes.

Note

NOT multi-app safe

Parameters

[in]	rat	Radio Access Technology
[in]	lowerRangeThreshold	lower-range Signal strength threshold in dBm
[in]	upperRangeThreshold	upper-range Signal strength threshold in dBm
[in]	handlerPtr
[in]	contextPtr

Connect the current client thread to the service providing this API. Block until the service is available.

For each thread that wants to use this API, either ConnectService or TryConnectService must be called before any other functions in this API. Normally, ConnectService is automatically called for the main thread, but not for any other thread. For details, see Client-specific Functions.

This function is created automatically.

This function must be called to delete the list of the Scan Information retrieved with le_mrc_PerformCellularNetworkScan().

Note

On failure, the process exits, so you don't have to worry about checking the returned reference for validity.

multi-app safe

Parameters

[in]

scanInformationListRef

The list of scan information.

This function must be called to delete the Neighboring Cells information.

Note

On failure, the process exits, so you don't have to worry about checking the returned reference for validity.

multi-app safe

Parameters

[in]

ngbrCellsRef

Neighboring Cells reference.

This function must be called to delete the list of the preferred operators retrieved with le_mrc_GetPreferredOperators().

Note

On failure, the process exits, so you don't have to worry about checking the returned reference for validity.

multi-app safe

Parameters

[in]

preferredOperatorListRef

The list of the preferred operators.

This function must be called to delete the the signal metrics.

Note

On failure, the process exits, so you don't have to worry about checking the returned reference for validity.

multi-app safe

Parameters

[in]

MetricsRef

Signal metrics reference.

Disconnect the current client thread from the service providing this API.

Normally, this function doesn't need to be called. After this function is called, there's no longer a connection to the service, and the functions in this API can't be used. For details, see Client-specific Functions.

This function is created automatically.

Get the Bit mask for 2G/3G Band capabilities.

Returns

• LE_FAULT Function failed.
• LE_OK Function succeeded.

Note

multi-app safe

Parameters

[out]

bandMaskPtrPtr

Bit mask for 2G/3G Band capabilities.

Get the Bit mask for 2G/3G Band preferences.

Returns

• LE_FAULT Function failed.
• LE_OK Function succeeded.

Note

multi-app safe

Parameters

[out]

bandMaskPtrPtr

Bit mask for 2G/3G Band preferences.

This function returns the signal metrics measured on CDMA network.

Returns

• LE_OK on success
• LE_FAULT on failure
• rscpPtr and sinrPtr return 0xFFFFFFFF when the value isn't available.

Note

If the caller is passing a bad pointer into this function, it's a fatal error, the function won't return.

multi-app safe

Parameters

[in]	MetricsRef	Signal metrics reference.
[out]	ssPtr	Signal strength in dBm
[out]	erPtr	Frame/Packet error rate
[out]	ecioPtr	ECIO value in dB with 1 decimal place (15 = 1.5 dB)
[out]	sinrPtr	SINR level in dB with 1 decimal place, (only applicable for 1xEV-DO).
[out]	ioPtr	Received IO in dBm (only applicable for 1xEV-DO)

This function must be called to get the Cellular Network Code [mcc:mnc]

Returns

• LE_OK on success
• LE_OVERFLOW if the mcc or mnc would not fit in buffer
• LE_FAULT for all other errors

Note

On failure, the process exits, so you don't have to worry about checking the returned reference for validity.

multi-app safe

Parameters

[in]	scanInformationRef	Scan information reference
[out]	mccPtr	Mobile Country Code
[in]	mccPtrNumElements
[out]	mncPtr	Mobile Network Code
[in]	mncPtrNumElements

This function must be called to get the Cellular Network Name.

Returns

• LE_OK on success
• LE_OVERFLOW if the operator name would not fit in buffer
• LE_FAULT for all other errors

Note

On failure, the process exits, so you don't have to worry about checking the returned reference for validity.

multi-app safe

Parameters

[in]	scanInformationRef	Scan information reference
[out]	namePtr	Name of operator
[in]	namePtrNumElements

This function must be called to get the radio access technology of a scanInformationRef.

Returns

the radio access technology

Note

On failure, the process exits.

multi-app safe

Parameters

[in]

scanInformationRef

Scan information reference

This function must be called to get the current network PLMN information.

Returns

• LE_OK on success
• LE_FAULT on any other failure

Note

multi-app safe

Parameters

[out]	mccStr	the mobile country code
[in]	mccStrNumElements
[out]	mncStr	the mobile network code
[in]	mncStrNumElements

This function must be called to get the current network name information.

Returns

• LE_OK on success
• LE_BAD_PARAMETER if nameStr is NULL
• LE_OVERFLOW if the Home Network Name can't fit in nameStr
• LE_FAULT on any other failure

Note

If the caller is passing a bad pointer into this function, it's a fatal error, the function won't return.

multi-app safe

Parameters

[out]	nameStr	the home network Name
[in]	nameStrNumElements

This function must be called to get the first Scan Information object reference in the list of scan Information retrieved with le_mrc_PerformCellularNetworkScan().

Returns

NULL No scan information found.

le_mrc_ScanInformationRef_t The Scan Information object reference.

Note

If the caller is passing a bad pointer into this function, it's a fatal error, the function won't return.

multi-app safe

Parameters

[in]

scanInformationListRef

The list of scan information.

This function must be called to get the first Cell Information reference in the list of Neighboring Cells information retrieved with le_mrc_GetNeighborCellsInfo().

Returns

NULL No Cell information object found.

le_mrc_CellInfoRef_t The Cell information object reference.

Note

If the caller is passing a bad pointer into this function, it's a fatal error, the function won't return.

multi-app safe

Parameters

[in]

ngbrCellsRef

Neighboring Cells reference.

This function must be called to get the first Operator object reference in the list of the preferred operators retrieved with le_mrc_GetPreferredOperators().

Returns

• NULL No operator information found.
• le_mrc_PreferredOperatorRef The Operator object reference.

Note

If the caller is passing a bad reference into this function, it's a fatal error, the function won't return.

multi-app safe

Parameters

[in]

preferredOperatorListRef

The list of the preferred operators.

This function returns the signal strength in dBm and the bit error rate measured on GSM network.

Returns

• LE_OK on success
• LE_FAULT on failure

Note

If the caller is passing a bad pointer into this function, it's a fatal error, the function won't return.

multi-app safe

Parameters

[in]	MetricsRef	Signal metrics reference.
[out]	rssiPtr	Signal strength in dBm
[out]	berPtr	Bit error rate.

Get the Bit mask for LTE Band capabilities.

Returns

• LE_FAULT Function failed.
• LE_OK Function succeeded.

Note

multi-app safe

Parameters

[out]

bandMaskPtrPtr

Bit mask for LTE Band capabilities.

Get the Bit mask for LTE Band preferences.

Returns

• LE_FAULT Function failed.
• LE_OK Function succeeded.

Note

multi-app safe

Parameters

[out]

bandMaskPtrPtr

Bit mask for LTE Band preferences.

This function returns the signal metrics measured on LTE network.

Returns

• LE_OK on success
• LE_FAULT on failure
• sinrPtr and ioPtr return 0xFFFFFFFF when the value isn't available.

Note

If the caller is passing a bad pointer into this function, it's a fatal error, the function won't return.

multi-app safe

Parameters

[in]	MetricsRef	Signal metrics reference.
[out]	ssPtr	Signal strength in dBm
[out]	blerPtr	Block error rate
[out]	rsrqPtr	RSRQ value in dB as measured by L1 with 1 decimal place
[out]	rsrpPtr	Current RSRP in dBm as measured by L1 with 1 decimal place
[out]	snrPtr	SNR level in dB with 1 decimal place (15 = 1.5 dB)

This function must be called to get the Cell Identifier.

Returns

The Cell Identifier.

Note

If the caller is passing a bad pointer into this function, it's a fatal error, the function won't return.

multi-app safe

Parameters

[in]

ngbrCellInfoRef

Cell information reference.

This function must be called to get the Location Area Code of a cell.

Returns

The Location Area Code of a cell. 0xFFFF value is returned if the value is not available.

Note

If the caller is passing a bad pointer into this function, it's a fatal error, the function won't return.

multi-app safe

Parameters

[in]

ngbrCellInfoRef

Cell information reference.

This function must be called to get the RSRP and RSRQ of the Interfrequency of a LTE cell.

Returns

• LE_OK on success
• LE_FAULT on failure

Note

If the caller is passing a bad pointer into this function, it's a fatal error, the function won't return.

multi-app safe

Parameters

[in]	ngbrCellInfoRef	Cell information reference.
[out]	rsrqPtr	Reference Signal Received Quality value in dB with 1 decimal place
[out]	rsrpPtr	Reference Signal Receiver Power value in dBm with 1 decimal place

This function must be called to get the RSRP and RSRQ of the Intrafrequency of a LTE cell.

Returns

• LE_OK on success
• LE_FAULT on failure

Note

If the caller is passing a bad pointer into this function, it's a fatal error, the function won't return.

multi-app safe

Parameters

[in]	ngbrCellInfoRef	Cell information reference.
[out]	rsrqPtr	Reference Signal Received Quality value in dB with 1 decimal place
[out]	rsrpPtr	Reference Signal Receiver Power value in dBm with 1 decimal place

This function must be called to get the Radio Access Technology of a cell.

Returns

The Radio Access Technology of a cell.

Note

If the caller is passing a bad pointer into this function, it's a fatal error, the function won't return.

multi-app safe

Parameters

[in]

ngbrCellInfoRef

Cell information reference.

This function must be called to get the signal strength of a cell.

Returns

The signal strength of a cell in dBm.

Note

If the caller is passing a bad pointer into this function, it's a fatal error, the function won't return.

multi-app safe

Parameters

[in]

ngbrCellInfoRef

Cell information reference.

This function must be called to retrieve the Neighboring Cells information. It creates and returns a reference to the Neighboring Cells information.

Returns

A reference to the Neighboring Cells information.

NULL if no Cells Information are available.

Note

multi-app safe

This function must be called to get the Ec/Io; the received energy per chip divided by the power density in the band measured in dBm on the primary CPICH channel of serving cell.

Returns

• The Ec/Io of a cell given in dB with 1 decimal place. (only applicable for UMTS network).
• 0xFFFFFFFF when the value isn't available.

Note

If the caller is passing a bad pointer into this function, it's a fatal error, the function won't return.

multi-app safe

Parameters

[in]

ngbrCellInfoRef

Cell information reference.

Get the network registration state.

Returns

LE_FAULT The function failed to get the Network registration state.

LE_BAD_PARAMETER A bad parameter was passed.

LE_OK The function succeeded.

Note

If the caller is passing a bad pointer into this function, it's a fatal error, the function won't return.

multi-app safe

Parameters

[out]

statePtr

Network Registration state.

This function must be called to get the next Scan Information object reference in the list of scan Information retrieved with le_mrc_PerformCellularNetworkScan().

Returns

NULL No scan information found.

le_mrc_ScanInformationRef_t The Scan Information object reference.

Note

If the caller is passing a bad pointer into this function, it's a fatal error, the function won't return.

multi-app safe

Parameters

[in]

scanInformationListRef

The list of scan information.

This function must be called to get the next Cell Information reference in the list of Neighboring Cells information retrieved with le_mrc_GetNeighborCellsInfo().

Returns

NULL No Cell information object found.

le_mrc_CellInfoRef_t Cell information object reference.

Note

If the caller is passing a bad pointer into this function, it's a fatal error, the function won't return.

multi-app safe

Parameters

[in]

ngbrCellsRef

Neighboring Cells reference.

This function must be called to get the next Operator object reference in the list of the preferred operators retrieved with le_mrc_GetPreferredOperators().

Returns

• NULL No operator information found.
• le_mrc_PreferredOperatorRef The Operator object reference.

Note

If the caller is passing a bad reference into this function, it's a fatal error, the function won't return.

multi-app safe

Parameters

[in]

preferredOperatorListRef

The list of the preferred operators.

Get the platform specific network registration error code.

Returns

the platform specific registration error code

This function must be called to get the Operator information details.

Returns

LE_FAULT Function failed.

LE_OK Function succeeded.

Note

multi-app safe

Parameters

[in]	preferredOperatorRef	Operator object reference.
[out]	mccPtr	Mobile Country Code.
[in]	mccPtrNumElements
[out]	mncPtr	Mobile Network Code.
[in]	mncPtrNumElements
[out]	ratMaskPtr	Bit mask for the RAT preferences.

This function must be called to retrieve a list of the preferred operators.

Returns

• Reference to the List object.
• Null pointer if there is no preferences list.

Note

multi-app safe

This function must be called to get the current Radio Access Technology in use.

Returns

LE_FAULT Function failed to get the Radio Access Technology.

LE_BAD_PARAMETER A bad parameter was passed.

LE_OK Function succeeded.

Note

If the caller is passing a bad pointer into this function, it's a fatal error, the function won't return.

multi-app safe

Parameters

[out]

ratPtr

The Radio Access Technology.

Must be called to get the Radio Module power state.

Returns

LE_FAULT The function failed to get the Radio Module power state.

LE_BAD_PARAMETER if powerPtr is NULL.

LE_OK The function succeed.

Note

If the caller is passing a bad pointer into this function, it's a fatal error, the function won't return.

multi-app safe

Parameters

[out]

powerPtr

Power state.

This function returns the Radio Access Technology of the signal metrics.

Returns

The Radio Access Technology of the signal measure.

Note

If the caller is passing a bad pointer into this function, it's a fatal error, the function won't return.

multi-app safe

Parameters

[in]

MetricsRef

Signal metrics reference.

Get the Radio Access Technology preferences

Returns

• LE_FAULT Function failed.
• LE_OK Function succeeded.

Note

multi-app safe

Parameters

[out]

ratMaskPtrPtr

Bit mask for the Radio Access Technology preferences.

Get the selected Selection Register mode.

Returns

• LE_FAULT Function failed.
• LE_OK Function succeeded.

Note

multi-app safe

Parameters

[out]	isManualPtrPtr	true if the scan mode is manual, false if the scan mode is automatic.
[out]	mccPtr	Mobile Country Code
[in]	mccPtrNumElements
[out]	mncPtr	Mobile Network Code
[in]	mncPtrNumElements

This function must be called to get the serving Cell Identifier.

Returns

The Cell Identifier. 0xFFFFFFFF value is returned if the value is not available.

Note

multi-app safe

This function must be called to get the Location Area Code of the serving cell.

Returns

The Location Area Code. 0xFFFFFFFF value is returned if the value is not available.

Note

multi-app safe

This function must be called to get the Tracking Area Code of the serving cell (LTE only).

Returns

The Tracking Area Code. 0xFFFF value is returned if the value is not available.

Note

multi-app safe

Get the signal quality.

Returns

LE_FAULT The function failed to get the Signal Quality information.

LE_BAD_PARAMETER A bad parameter was passed.

LE_OK The function succeeded.

Note

If the caller is passing a bad pointer into this function, it's a fatal error, the function won't return.

multi-app safe

Parameters

[out]

qualityPtr

[OUT] Received signal strength quality (0 = no signal strength, 5 = very good signal strength).

Get the Bit mask for TD-SCDMA Band capabilities.

Returns

• LE_FAULT Function failed.
• LE_OK Function succeeded.

Note

multi-app safe

Parameters

[out]

bandMaskPtrPtr

Bit mask for TD-SCDMA Band capabilities.

Get the Bit mask for TD-SCDMA Band preferences.

Returns

• LE_FAULT Function failed.
• LE_OK Function succeeded.

Note

multi-app safe

Parameters

[out]

bandMaskPtrPtr

Bit mask for TD-SCDMA Band preferences.

This function returns the signal metrics measured on UMTS network.

Returns

• LE_OK on success
• LE_FAULT on failure

Note

If the caller is passing a bad pointer into this function, it's a fatal error, the function won't return.

multi-app safe

Parameters

[in]	MetricsRef	Signal metrics reference.
[out]	ssPtr	Signal strength in dBm
[out]	blerPtr	Block error rate
[out]	ecioPtr	Ec/Io value in dB with 1 decimal place (15 = 1.5 dB)
[out]	rscpPtr	Measured RSCP in dBm (only applicable for TD-SCDMA network)
[out]	sinrPtr	Measured SINR in dB (only applicable for TD-SCDMA network)

This function must be called to check if a cellular network is available.

Returns

true The network is available

false The network isn't available

Note

On failure, the process exits, so you don't have to worry about checking the returned reference for validity.

multi-app safe

Parameters

[in]

scanInformationRef

Scan information reference

This function must be called to check if a cellular network is forbidden by the operator.

Returns

true The network is forbidden

false The network is allowed

Note

On failure, the process exits, so you don't have to worry about checking the returned reference for validity.

multi-app safe

Parameters

[in]

scanInformationRef

Scan information reference

This function must be called to check if a cellular network is currently in home mode.

Returns

true The network is home

false The network is roaming

Note

On failure, the process exits, so you don't have to worry about checking the returned reference for validity.

multi-app safe

Parameters

[in]

scanInformationRef

Scan information reference

This function must be called to check if a cellular network is currently in use.

Returns

true The network is in use

false The network isn't in use

Note

On failure, the process exits, so you don't have to worry about checking the returned reference for validity.

multi-app safe

Parameters

[in]

scanInformationRef

Scan information reference

This function must be called to measure the signal metrics. It creates and returns a reference to the signal metrics.

Returns

A reference to the signal metrics.

NULL if no signal metrics are available.

Note

multi-app safe

This function must be called to perform a cellular network scan.

Returns

Reference to the List object. Null pointer if the scan failed.

Note

multi-app safe

Parameters

[in]

ratMask

Radio Access Technology mask

This function must be called to perform a cellular network scan asynchronously. This function is not blocking, the response will be returned with a handler function.

Note

multi-app safe

Parameters

[in]	ratMask	Radio Access Technology mask
[in]	handlerPtr
[in]	contextPtr

Remove handler function for EVENT 'le_mrc_NetRegStateEvent'

Parameters

[in]

addHandlerRef

Remove a preferred operator by specifying the MCC/MNC.

Returns

• LE_NOT_FOUND User Preferred operator list is not available.
• LE_FAULT Function failed.
• LE_OK Function succeeded.

Note

If one code is too long (max LE_MRC_MCC_LEN/LE_MRC_MNC_LEN digits), it's a fatal error, the function won't return.

NOT multi-app safe

Parameters

[in]	mcc	Mobile Country Code
[in]	mnc	Mobile Network Code

Remove handler function for EVENT 'le_mrc_RatChange'

Parameters

[in]

addHandlerRef

Remove handler function for EVENT 'le_mrc_SignalStrengthChange'

Parameters

[in]

addHandlerRef

Enable the automatic Selection Register mode.

Returns

• LE_FAULT Function failed.
• LE_OK Function succeeded.

Note

NOT multi-app safe

Set the 2G/3G Band preferences by using a bit mask.

Returns

• LE_FAULT Function failed.
• LE_OK Function succeeded.

Note

NOT multi-app safe

Parameters

[in]

bandMask

Bit mask for 2G/3G Band preferences.

Set the LTE Band preferences by using a bit mask.

Returns

• LE_FAULT Function failed.
• LE_OK Function succeeded.

Note

NOT multi-app safe

Parameters

[in]

bandMask

Bit mask for LTE Band preferences.

Set the manual Selection Register mode with the MCC/MNC parameters.

Returns

• LE_FAULT Function failed.
• LE_OK Function succeeded.

Note

If one code is too long (max LE_MRC_MCC_LEN/LE_MRC_MNC_LEN digits), it's a fatal error, the function won't return.

NOT multi-app safe

Parameters

[in]	mcc	Mobile Country Code
[in]	mnc	Mobile Network Code

Set the manual selection register mode asynchronously. This function is not blocking, the response will be returned with a handler function.

Note

If one code is too long (max LE_MRC_MCC_LEN/LE_MRC_MNC_LEN digits), it's a fatal error, the function won't return.

NOT multi-app safe

Parameters

[in]	mcc	Mobile Country Code
[in]	mnc	Mobile Network Code
[in]	handlerPtr
[in]	contextPtr

Set the power of the Radio Module.

Returns

LE_BAD_PARAMETER Bad power mode specified.

LE_FAULT Function failed.

LE_OK Function succeed.

Note

NOT multi-app safe

Parameters

[in]

power

The power state.

Set the Radio Access Technology preferences by using a bit mask.

Returns

• LE_FAULT Function failed.
• LE_OK Function succeeded.

Note

NOT multi-app safe

Parameters

[in]

ratMask

Bit mask for the Radio Access Technology preferences.

Set the TD-SCDMA Band preferences by using a bit mask.

Returns

• LE_FAULT Function failed.
• LE_OK Function succeeded.

Note

NOT multi-app safe

Parameters

[in]

bandMask

Bit mask for TD-SCDMA Band preferences.

Try to connect the current client thread to the service providing this API. Return with an error if the service is not available.

For each thread that wants to use this API, either ConnectService or TryConnectService must be called before any other functions in this API. Normally, ConnectService is automatically called for the main thread, but not for any other thread. For details, see Client-specific Functions.

This function is created automatically.

Returns

• LE_OK if the client connected successfully to the service.
• LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
• LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
• LE_COMM_ERROR if the Service Directory cannot be reached.