le_mdc.h File Reference

#include "legato.h"

Go to the source code of this file.

Macros
#define	LE_MDC_PROFILE_NAME_MAX_LEN   50
#define	LE_MDC_PROFILE_NAME_MAX_BYTES   (LE_MDC_PROFILE_NAME_MAX_LEN+1)

Typedefs
typedef struct le_mdc_Profile *	le_mdc_ProfileRef_t
typedef struct le_mdc_SessionStateHandler *	le_mdc_SessionStateHandlerRef_t
typedef void(*	le_mdc_SessionStateHandlerFunc_t )(bool isConnected, void *contextPtr)

Enumerations
enum	le_mdc_dataBearerTechnology_t {   LE_MDC_DATA_BEARER_TECHNOLOGY_UNKNOWN = 0, LE_MDC_DATA_BEARER_TECHNOLOGY_CDMA2000_1X, LE_MDC_DATA_BEARER_TECHNOLOGY_CDMA2000_HRPD, LE_MDC_DATA_BEARER_TECHNOLOGY_GSM,   LE_MDC_DATA_BEARER_TECHNOLOGY_UMTS, LE_MDC_DATA_BEARER_TECHNOLOGY_CDMA200_HRPD, LE_MDC_DATA_BEARER_TECHNOLOGY_EDGE, LE_MDC_DATA_BEARER_TECHNOLOGY_HSDPA_WCDMA,   LE_MDC_DATA_BEARER_TECHNOLOGY_WCDMA_HSUPA, LE_MDC_DATA_BEARER_TECHNOLOGY_HSDPA_HSUPA, LE_MDC_DATA_BEARER_TECHNOLOGY_LTE, LE_MDC_DATA_BEARER_TECHNOLOGY_CDMA2000_EHRPD,   LE_MDC_DATA_BEARER_TECHNOLOGY_HSDPAPLUS_WCDMA, LE_MDC_DATA_BEARER_TECHNOLOGY_HSDPAPLUS_HSUPA, LE_MDC_DATA_BEARER_TECHNOLOGY_DC_HSDPAPLUS_WCDMA, LE_MDC_DATA_BEARER_TECHNOLOGY_DC_HSDPAPLUS_HSUPA,   LE_MDC_DATA_BEARER_TECHNOLOGY_HSDPAPLUS_64QAM, LE_MDC_DATA_BEARER_TECHNOLOGY_HSDPAPLUS_64QAM_HSUPA, LE_MDC_DATA_BEARER_TECHNOLOGY_TDSCDMA, LE_MDC_DATA_BEARER_TECHNOLOGY_TDSCDMA_HSDPA,   LE_MDC_DATA_BEARER_TECHNOLOGY_TDSCDMA_HSUPA }

Functions
le_mdc_ProfileRef_t	le_mdc_LoadProfile (const char *nameStr)
le_result_t	le_mdc_GetProfileName (le_mdc_ProfileRef_t profileRef, char *nameStr, size_t nameStrSize)
le_result_t	le_mdc_StartSession (le_mdc_ProfileRef_t profileRef)
le_result_t	le_mdc_StopSession (le_mdc_ProfileRef_t profileRef)
le_result_t	le_mdc_GetSessionState (le_mdc_ProfileRef_t profileRef, bool *isConnectedPtr)
le_mdc_SessionStateHandlerRef_t	le_mdc_AddSessionStateHandler (le_mdc_ProfileRef_t profileRef, le_mdc_SessionStateHandlerFunc_t handler, void *contextPtr)
void	le_mdc_RemoveSessionStateHandler (le_mdc_SessionStateHandlerRef_t handlerRef)
le_result_t	le_mdc_GetInterfaceName (le_mdc_ProfileRef_t profileRef, char *interfaceNameStr, size_t interfaceNameStrSize)
le_result_t	le_mdc_GetIPv4Address (le_mdc_ProfileRef_t profileRef, char *ipAddrStr, size_t ipAddrStrSize)
le_result_t	le_mdc_GetIPv4GatewayAddress (le_mdc_ProfileRef_t profileRef, char *gatewayAddrStr, size_t gatewayAddrStrSize)
le_result_t	le_mdc_GetIPv4DNSAddresses (le_mdc_ProfileRef_t profileRef, char *dns1AddrStr, size_t dns1AddrStrSize, char *dns2AddrStr, size_t dns2AddrStrSize)
le_result_t	le_mdc_GetIPv6Address (le_mdc_ProfileRef_t profileRef, char *ipAddrStr, size_t ipAddrStrSize)
le_result_t	le_mdc_GetIPv6GatewayAddress (le_mdc_ProfileRef_t profileRef, char *gatewayAddrStr, size_t gatewayAddrStrSize)
le_result_t	le_mdc_GetIPv6DNSAddresses (le_mdc_ProfileRef_t profileRef, char *dns1AddrStr, size_t dns1AddrStrSize, char *dns2AddrStr, size_t dns2AddrStrSize)
bool	le_mdc_IsIPv4 (le_mdc_ProfileRef_t profileRef)
bool	le_mdc_IsIPv6 (le_mdc_ProfileRef_t profileRef)
le_result_t	le_mdc_GetBytesCounters (uint64_t *rxBytes, uint64_t *txBytes)
le_result_t	le_mdc_ResetBytesCounter (void)
le_result_t	le_mdc_GetAccessPointName (le_mdc_ProfileRef_t profileRef, char *apnNameStr, size_t apnNameStrSize)
le_result_t	le_mdc_GetDataBearerTechnology (le_mdc_ProfileRef_t profileRef, le_mdc_dataBearerTechnology_t *dataBearerTechnologyPtr)

Detailed Description

Legato Modem Data Control include file.

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

Macro Definition Documentation

#define LE_MDC_PROFILE_NAME_MAX_LEN   50

Define the maximum size of various profile related fields.

Typedef Documentation

typedef struct le_mdc_Profile* le_mdc_ProfileRef_t

Data profile object

typedef void(* le_mdc_SessionStateHandlerFunc_t)(bool isConnected, void *contextPtr)

Prototype for data session state change handler.

Parameters

isConnected	Data session connection status.
contextPtr	Whatever context information the event handler may require.

typedef struct le_mdc_SessionStateHandler* le_mdc_SessionStateHandlerRef_t

Reference type for Data Session State's Changes Handler references.

Enumeration Type Documentation

enum le_mdc_dataBearerTechnology_t

Enumeration to convey Data Bearer Technology.

Enumerator
LE_MDC_DATA_BEARER_TECHNOLOGY_UNKNOWN	Unknown.
LE_MDC_DATA_BEARER_TECHNOLOGY_CDMA2000_1X	cdma2000 1X
LE_MDC_DATA_BEARER_TECHNOLOGY_CDMA2000_HRPD	cdma2000 HRPD (1xEV-DO)
LE_MDC_DATA_BEARER_TECHNOLOGY_GSM	GSM.
LE_MDC_DATA_BEARER_TECHNOLOGY_UMTS	UMTS.
LE_MDC_DATA_BEARER_TECHNOLOGY_CDMA200_HRPD	cdma200 HRPD (1xEV-DO RevA)
LE_MDC_DATA_BEARER_TECHNOLOGY_EDGE	EDGE.
LE_MDC_DATA_BEARER_TECHNOLOGY_HSDPA_WCDMA	HSDPA and WCDMA.
LE_MDC_DATA_BEARER_TECHNOLOGY_WCDMA_HSUPA	WCDMA and HSUPA.
LE_MDC_DATA_BEARER_TECHNOLOGY_HSDPA_HSUPA	HSDPA and HSUPA.
LE_MDC_DATA_BEARER_TECHNOLOGY_LTE	LTE.
LE_MDC_DATA_BEARER_TECHNOLOGY_CDMA2000_EHRPD	cdma2000 EHRPD
LE_MDC_DATA_BEARER_TECHNOLOGY_HSDPAPLUS_WCDMA	HSDPA+ and WCDMA.
LE_MDC_DATA_BEARER_TECHNOLOGY_HSDPAPLUS_HSUPA	HSDPA+ and HSUPA.
LE_MDC_DATA_BEARER_TECHNOLOGY_DC_HSDPAPLUS_WCDMA	DC_HSDPA+ and WCDMA.
LE_MDC_DATA_BEARER_TECHNOLOGY_DC_HSDPAPLUS_HSUPA	DC_HSDPA+ and HSUPA.
LE_MDC_DATA_BEARER_TECHNOLOGY_HSDPAPLUS_64QAM	HSDPA+ and 64QAM.
LE_MDC_DATA_BEARER_TECHNOLOGY_HSDPAPLUS_64QAM_HSUPA	HSDPA+, 64QAM and HSUPA.
LE_MDC_DATA_BEARER_TECHNOLOGY_TDSCDMA	TDSCDMA.
LE_MDC_DATA_BEARER_TECHNOLOGY_TDSCDMA_HSDPA	TDSCDMA and HSDPA.
LE_MDC_DATA_BEARER_TECHNOLOGY_TDSCDMA_HSUPA	TDSCDMA and HSUPA.

Function Documentation

le_mdc_SessionStateHandlerRef_t le_mdc_AddSessionStateHandler	(	le_mdc_ProfileRef_t	profileRef,
		le_mdc_SessionStateHandlerFunc_t	handler,
		void *	contextPtr
	)

Register a handler for session state changes on the given profile.

Returns

A handler reference, which is only needed for later removal of the handler.

Note

Process exits on failure.

Parameters

[in]	profileRef	Profile object of interest
[in]	handler	Handler function
[in]	contextPtr	Context pointer

le_result_t le_mdc_GetAccessPointName	(	le_mdc_ProfileRef_t	profileRef,
		char *	apnNameStr,
		size_t	apnNameStrSize
	)

Get the Access Point Name for the given profile, if the data session is connected.

Returns

• LE_OK on success
• LE_OVERFLOW if the Access Point Name would not fit in apnNameStr
• LE_NOT_POSSIBLE for all other errors

Note

The process exits, if an invalid profile object is given

Parameters

[in]	profileRef	Query this profile object
[out]	apnNameStr	The Access Point Name
[in]	apnNameStrSize	The size in bytes of the address buffer

le_result_t le_mdc_GetBytesCounters	(	uint64_t *	rxBytes,
		uint64_t *	txBytes
	)

Get number of bytes received/transmitted without error since the last reset.

Returns

• LE_OK on success
• LE_NOT_POSSIBLE for all other errors

Note

• The process exits, if an invalid pointer is given

Parameters

[out]	rxBytes	bytes amount received since the last counter reset
[out]	txBytes	bytes amount transmitted since the last counter reset

le_result_t le_mdc_GetDataBearerTechnology	(	le_mdc_ProfileRef_t	profileRef,
		le_mdc_dataBearerTechnology_t *	dataBearerTechnologyPtr
	)

Get the Data Bearer Technology for the given profile, if the data session is connected.

Returns

• LE_OK on success
• LE_NOT_POSSIBLE for all other errors

Note

The process exits, if an invalid profile object is given

Parameters

[in]	profileRef	Query this profile object
[out]	dataBearerTechnologyPtr	The data bearer technology

le_result_t le_mdc_GetInterfaceName	(	le_mdc_ProfileRef_t	profileRef,
		char *	interfaceNameStr,
		size_t	interfaceNameStrSize
	)

Get the network interface name, if the data session is connected.

Returns

• LE_OK on success
• LE_OVERFLOW if the interface name can't fit in interfaceNameStr
• LE_NOT_POSSIBLE on any other failure

Note

The process exits, if an invalid profile object is given

Parameters

[in]	profileRef	Query this profile object
[out]	interfaceNameStr	Network interface name
[in]	interfaceNameStrSize	Name buffer size in bytes

le_result_t le_mdc_GetIPv4Address	(	le_mdc_ProfileRef_t	profileRef,
		char *	ipAddrStr,
		size_t	ipAddrStrSize
	)

Get the IPv4 address for the given profile, if the data session is connected and has an IPv4 address.

Returns

• LE_OK on success
• LE_OVERFLOW if the IP address would not fit in ipAddrStr
• LE_NOT_POSSIBLE for all other errors

Note

The process exits, if an invalid profile object is given

Parameters

[in]	profileRef	Query this profile object
[out]	ipAddrStr	The IP address in dotted format
[in]	ipAddrStrSize	The size in bytes of the address buffer

le_result_t le_mdc_GetIPv4DNSAddresses	(	le_mdc_ProfileRef_t	profileRef,
		char *	dns1AddrStr,
		size_t	dns1AddrStrSize,
		char *	dns2AddrStr,
		size_t	dns2AddrStrSize
	)

Get the primary/secondary DNS v4 addresses for the given profile, if the data session is connected and has an IPv4 address.

Returns

• LE_OK on success
• LE_OVERFLOW if the IP address would not fit in buffer
• LE_NOT_POSSIBLE for all other errors

Note

• If only one DNS address is available, then it will be returned, and an empty string will be returned for the unavailable address
• The process exits, if an invalid profile object is given

Parameters

[in]	profileRef	Query this profile object
[out]	dns1AddrStr	Primary DNS IP address in dotted format
[in]	dns1AddrStrSize	dns1AddrStr buffer size in bytes
[out]	dns2AddrStr	Secondary DNS IP address in dotted format
[in]	dns2AddrStrSize	dns2AddrStr buffer size in bytes

le_result_t le_mdc_GetIPv4GatewayAddress	(	le_mdc_ProfileRef_t	profileRef,
		char *	gatewayAddrStr,
		size_t	gatewayAddrStrSize
	)

Get the gateway IPv4 address for the given profile, if the data session is connected and has an IPv4 address.

Returns

• LE_OK on success
• LE_OVERFLOW if the IP address would not fit in gatewayAddrStr
• LE_NOT_POSSIBLE for all other errors

Note

The process exits, if an invalid profile object is given

Parameters

[in]	profileRef	Query this profile object
[out]	gatewayAddrStr	Gateway IP address in dotted format
[in]	gatewayAddrStrSize	Address buffer size in bytes

le_result_t le_mdc_GetIPv6Address	(	le_mdc_ProfileRef_t	profileRef,
		char *	ipAddrStr,
		size_t	ipAddrStrSize
	)

Get the IPv6 address for the given profile, if the data session is connected and has an IPv6 address.

Returns

• LE_OK on success
• LE_OVERFLOW if the IP address would not fit in ipAddrStr
• LE_NOT_POSSIBLE for all other errors

Note

The process exits, if an invalid profile object is given

Parameters

[in]	profileRef	Query this profile object
[out]	ipAddrStr	The IP address in dotted format
[in]	ipAddrStrSize	The size in bytes of the address buffer

le_result_t le_mdc_GetIPv6DNSAddresses	(	le_mdc_ProfileRef_t	profileRef,
		char *	dns1AddrStr,
		size_t	dns1AddrStrSize,
		char *	dns2AddrStr,
		size_t	dns2AddrStrSize
	)

Get the primary/secondary DNS v6 addresses, if the data session is connected and has an IPv6 address.

Returns

• LE_OK on success
• LE_OVERFLOW if the IP address can't fit in buffer
• LE_NOT_POSSIBLE for all other errors

Note

• If only one DNS address is available, it will be returned, and an empty string will be returned for the unavailable address.
• The process exits, if an invalid profile object is given

Parameters

[in]	profileRef	Query this profile object
[out]	dns1AddrStr	Primary DNS IP address in dotted format
[in]	dns1AddrStrSize	dns1AddrStr buffer size in bytes
[out]	dns2AddrStr	Secondary DNS IP address in dotted format
[in]	dns2AddrStrSize	dns2AddrStr buffer size in bytes

le_result_t le_mdc_GetIPv6GatewayAddress	(	le_mdc_ProfileRef_t	profileRef,
		char *	gatewayAddrStr,
		size_t	gatewayAddrStrSize
	)

Get the gateway IPv6 address for the given profile, if the data session is connected and has an IPv6 address.

Returns

• LE_OK on success
• LE_OVERFLOW if the IP address would not fit in gatewayAddrStr
• LE_NOT_POSSIBLE for all other errors

Note

The process exits, if an invalid profile object is given

Parameters

[in]	profileRef	Query this profile object
[out]	gatewayAddrStr	Gateway IP address in dotted format
[in]	gatewayAddrStrSize	Address buffer size in bytes

le_result_t le_mdc_GetProfileName	(	le_mdc_ProfileRef_t	profileRef,
		char *	nameStr,
		size_t	nameStrSize
	)

Get profile name.

Returns

• LE_OK on success
• LE_OVERFLOW if the name would not fit in buffer

Note

The process exits, if an invalid profile object is given

Parameters

[in]	profileRef	Query this profile object
[out]	nameStr	Profile name
[in]	nameStrSize	Name buffer size in bytes

le_result_t le_mdc_GetSessionState	(	le_mdc_ProfileRef_t	profileRef,
		bool *	isConnectedPtr
	)

Get the current data session state.

Returns

• LE_OK on success
• LE_NOT_POSSIBLE on failure

Note

The process exits, if an invalid profile object is given

Parameters

[in]	profileRef	Query this profile object
[out]	isConnectedPtr	Data session state

bool le_mdc_IsIPv4

(

le_mdc_ProfileRef_t

profileRef

)

Allow the caller to know if the given profile is actually supporting IPv4, if the data session is connected.

Returns

TRUE if PDP type is IPv4, FALSE otherwise.

Note

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

Parameters

[in]

profileRef

Query this profile object

bool le_mdc_IsIPv6

(

le_mdc_ProfileRef_t

profileRef

)

Allow the caller to know if the given profile is actually supporting IPv6, if the data session is connected.

Returns

TRUE if PDP type is IPv6, FALSE otherwise.

Note

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

Parameters

[in]

profileRef

Query this profile object

le_mdc_ProfileRef_t le_mdc_LoadProfile

(

const char *

nameStr

)

Load an existing data profile

Profile can either be pre-configured or stored on the modem

Returns

• Reference to the data profile
• NULL if the profile does not exist

Note

If profil name is too long is too long (max 50 digits) the function will not return.

Parameters

[in]

nameStr

Profile name

void le_mdc_RemoveSessionStateHandler

(

le_mdc_SessionStateHandlerRef_t

handlerRef

)

Remove a handler for session state changes

Note

Process exits on failure.

Parameters

[in]

handlerRef

Handler reference.

le_result_t le_mdc_ResetBytesCounter

(

void

)

Reset received/transmitted data flow statistics

• Returns

  • LE_OK on success
  • LE_NOT_POSSIBLE for all other errors

le_result_t le_mdc_StartSession

(

le_mdc_ProfileRef_t

profileRef

)

Start profile data session.

Returns

• LE_OK on success
• LE_DUPLICATE if the data session is already connected for the given profile
• LE_NOT_POSSIBLE for other failures

Note

The process exits, if an invalid profile object is given

Parameters

[in]

profileRef

Start data session for this profile object

le_result_t le_mdc_StopSession

(

le_mdc_ProfileRef_t

profileRef

)

Stop profile data session.

Returns

• LE_OK on success
• LE_DUPLICATE if the data session has already been stopped (i.e. it is disconnected)
• LE_NOT_POSSIBLE for other failures

Note

The process exits, if an invalid profile object is given

Parameters

[in]

profileRef

Stop data session for this profile object