interfaces/modemServices/c/le_mrc.h File Reference

#include "legato.h"
#include "le_mdm_defs.h"

Go to the source code of this file.

Typedefs
typedef struct le_mrc_ScanInformation *	le_mrc_ScanInformation_Ref_t
typedef struct le_mrc_ScanInformationList *	le_mrc_ScanInformation_ListRef_t
typedef struct le_mrc_NetRegStateHandler *	le_mrc_NetRegStateHandlerRef_t
typedef void(*	le_mrc_NetRegStateHandlerFunc_t )(le_mrc_NetRegState_t state, void *contextPtr)
Functions
le_mrc_NetRegStateHandlerRef_t	le_mrc_AddNetRegStateHandler (le_mrc_NetRegStateHandlerFunc_t handlerFuncPtr, void *contextPtr)
void	le_mrc_RemoveNetRegStateHandler (le_mrc_NetRegStateHandlerRef_t handlerRef)
le_result_t	le_mrc_SetRadioPower (le_onoff_t power)
le_result_t	le_mrc_GetRadioPower (le_onoff_t *powerPtr)
le_result_t	le_mrc_GetNetRegState (le_mrc_NetRegState_t *statePtr)
le_result_t	le_mrc_GetSignalQual (uint32_t *qualityPtr)
le_result_t	le_mrc_GetHomeNetworkName (char *nameStr, size_t nameStrSize)
le_result_t	le_mrc_ConnectCellularNetwork (const char *mccPtr, const char *mncPtr)
le_mrc_ScanInformation_ListRef_t	le_mrc_PerformCellularNetworkScan (le_mrc_Rat_t ratMask)
le_mrc_ScanInformation_Ref_t	le_mrc_GetFirstCellularNetworkScan (le_mrc_ScanInformation_ListRef_t scanInformationListRef)
le_mrc_ScanInformation_Ref_t	le_mrc_GetNextCellularNetworkScan (le_mrc_ScanInformation_ListRef_t scanInformationListRef)
void	le_mrc_DeleteCellularNetworkScan (le_mrc_ScanInformation_ListRef_t scanInformationListRef)
le_result_t	le_mrc_GetCellularNetworkMccMnc (le_mrc_ScanInformation_Ref_t scanInformationRef, char *mccPtr, size_t mccPtrSize, char *mncPtr, size_t mncPtrSize)
le_result_t	le_mrc_GetCellularNetworkName (le_mrc_ScanInformation_Ref_t scanInformationRef, char *namePtr, size_t nameSize)
bool	le_mrc_IsCellularNetworkRatAvailable (le_mrc_ScanInformation_Ref_t scanInformationRef, le_mrc_Rat_t rat)
bool	le_mrc_IsCellularNetworkInUse (le_mrc_ScanInformation_Ref_t scanInformationRef)
bool	le_mrc_IsCellularNetworkAvailable (le_mrc_ScanInformation_Ref_t scanInformationRef)
bool	le_mrc_IsCellularNetworkHome (le_mrc_ScanInformation_Ref_t scanInformationRef)
bool	le_mrc_IsCellularNetworkForbidden (le_mrc_ScanInformation_Ref_t scanInformationRef)

---

Detailed Description

Legato Modem Radio Control API include file.

Copyright (C) Sierra Wireless, Inc. 2013. All rights reserved. Use of this work is subject to license.

---

Typedef Documentation

typedef void(* le_mrc_NetRegStateHandlerFunc_t)(le_mrc_NetRegState_t state, void *contextPtr)

Prototype for handler functions used to report that the network registration state has changed.

Parameters:

state	Parameter ready to receive the Network Registration state.
contextPtr	Context information the event handler may require.

typedef struct le_mrc_NetRegStateHandler* le_mrc_NetRegStateHandlerRef_t

Reference type for Network Registration State's Changes Handler references.

typedef struct le_mrc_ScanInformationList* le_mrc_ScanInformation_ListRef_t

Opaque type for Scan Information Listing.

typedef struct le_mrc_ScanInformation* le_mrc_ScanInformation_Ref_t

Declare a reference type for referring to MRC Scan Information objects.

---

Function Documentation

le_mrc_NetRegStateHandlerRef_t le_mrc_AddNetRegStateHandler	(	le_mrc_NetRegStateHandlerFunc_t	handlerFuncPtr,
		void *	contextPtr
	)

Register an handler for network registration state change.

Returns:

Handler reference: only needed to remove the handler.

Note:

Doesn't return on failure, so there's no need to check the return value for errors.

Parameters:

[in]	handlerFuncPtr	The handler function.
[in]	contextPtr	The handler's context.

le_result_t le_mrc_ConnectCellularNetwork	(	const char *	mccPtr,
		const char *	mncPtr
	)

This function must be called to connect to a cellular network [mcc;mnc]

Returns:

LE_NOT_POSSIBLE The function failed to connect the network.

LE_OVERFLOW One code is too long.

LE_OK The function succeeded.

Parameters:

[in]	mccPtr	Mobile Country Code
[in]	mncPtr	Mobile Network Code

void le_mrc_DeleteCellularNetworkScan

(

le_mrc_ScanInformation_ListRef_t

scanInformationListRef

)

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

Note:

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

Parameters:

[in]

scanInformationListRef

The list of scan information.

le_result_t le_mrc_GetCellularNetworkMccMnc	(	le_mrc_ScanInformation_Ref_t	scanInformationRef,
		char *	mccPtr,
		size_t	mccPtrSize,
		char *	mncPtr,
		size_t	mncPtrSize
	)

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_NOT_POSSIBLE for all other errors

Note:

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

Parameters:

[in]	scanInformationRef	Scan information reference
[out]	mccPtr	Mobile Country Code
[in]	mccPtrSize	mccPtr buffer size
[out]	mncPtr	Mobile Network Code
[in]	mncPtrSize	mncPtr buffer size

le_result_t le_mrc_GetCellularNetworkName	(	le_mrc_ScanInformation_Ref_t	scanInformationRef,
		char *	namePtr,
		size_t	nameSize
	)

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_NOT_POSSIBLE for all other errors

Note:

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

Parameters:

[in]	scanInformationRef	Scan information reference
[out]	namePtr	Name of operator
[in]	nameSize	The size in bytes of the namePtr buffer

le_mrc_ScanInformation_Ref_t le_mrc_GetFirstCellularNetworkScan

(

le_mrc_ScanInformation_ListRef_t

scanInformationListRef

)

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

Returns:

NULL No scan information found.

le_mrc_ScanInformation_Ref_t The Scan Information object reference.

Note:

If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters:

[in]

scanInformationListRef

The list of scan information.

le_result_t le_mrc_GetHomeNetworkName	(	char *	nameStr,
		size_t	nameStrSize
	)

This function must be called to get the Home Network Name information.

Returns:

• LE_OK on success
• LE_OVERFLOW if the Home Network Name can't fit in nameStr
• LE_NOT_POSSIBLE on any other failure

Note:

If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters:

[out]	nameStr	the home network Name
[in]	nameStrSize	the nameStr size

le_result_t le_mrc_GetNetRegState

(

le_mrc_NetRegState_t *

statePtr

)

Get the network registration state.

Returns:

LE_NOT_POSSIBLE Function failed to get the Network registration state.

LE_OK Function succeeded.

Note:

If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters:

[out]

statePtr

Network Registration state.

le_mrc_ScanInformation_Ref_t le_mrc_GetNextCellularNetworkScan

(

le_mrc_ScanInformation_ListRef_t

scanInformationListRef

)

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

Returns:

NULL No scan information found.

le_mrc_ScanInformation_Ref_t The Scan Information object reference.

Note:

If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters:

[in]

scanInformationListRef

The list of scan information.

le_result_t le_mrc_GetRadioPower

(

le_onoff_t *

powerPtr

)

Must be called to get the Radio Module power state.

Returns:

LE_NOT_POSSIBLE Function failed to get the Radio Module power state.

LE_OK Function succeeded.

Note:

If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters:

[out]

powerPtr

Power state.

le_result_t le_mrc_GetSignalQual

(

uint32_t *

qualityPtr

)

Get the signal quality.

Returns:

LE_NOT_POSSIBLE Function failed to obtain the signal quality.

LE_OK Function succeeded.

Note:

If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters:

[out]

qualityPtr

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

bool le_mrc_IsCellularNetworkAvailable

(

le_mrc_ScanInformation_Ref_t

scanInformationRef

)

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

Returns:

true The network is available

false The network is not available

Note:

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

Parameters:

[in]

scanInformationRef

Scan information reference

bool le_mrc_IsCellularNetworkForbidden

(

le_mrc_ScanInformation_Ref_t

scanInformationRef

)

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.

Parameters:

[in]

scanInformationRef

Scan information reference

bool le_mrc_IsCellularNetworkHome

(

le_mrc_ScanInformation_Ref_t

scanInformationRef

)

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.

Parameters:

[in]

scanInformationRef

Scan information reference

bool le_mrc_IsCellularNetworkInUse

(

le_mrc_ScanInformation_Ref_t

scanInformationRef

)

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 is not in use

Note:

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

Parameters:

[in]

scanInformationRef

Scan information reference

bool le_mrc_IsCellularNetworkRatAvailable	(	le_mrc_ScanInformation_Ref_t	scanInformationRef,
		le_mrc_Rat_t	rat
	)

This function must be called to know if the radio control access is in scanInformationRef.

Returns:

• true the radio access technology is available
• false otherwise

Note:

On failure, the process exits.

Parameters:

[in]	scanInformationRef	Scan information reference
[in]	rat	The Radio Access Technology

le_mrc_ScanInformation_ListRef_t le_mrc_PerformCellularNetworkScan

(

le_mrc_Rat_t

ratMask

)

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

Returns:

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

Parameters:

[in]

ratMask

Technology mask

void le_mrc_RemoveNetRegStateHandler

(

le_mrc_NetRegStateHandlerRef_t

handlerRef

)

Remove a handler for network registration state changes.

Parameters:

[in]

handlerRef

The handler reference.

le_result_t le_mrc_SetRadioPower

(

le_onoff_t

power

)

Set the power of the Radio Module.

Returns:

LE_FAULT Function failed.

LE_OK Function succeed.

Parameters:

[in]

power

The power state.