le_mdc_interface.h File Reference

#include "legato.h"

Go to the source code of this file.

Macros
#define	LE_MDC_INTERFACE_NAME_MAX_LEN   10
#define	LE_MDC_INTERFACE_NAME_MAX_BYTES   11
#define	LE_MDC_IPV4_ADDR_MAX_LEN   15
#define	LE_MDC_IPV4_ADDR_MAX_BYTES   16
#define	LE_MDC_IPV6_ADDR_MAX_LEN   39
#define	LE_MDC_IPV6_ADDR_MAX_BYTES   40
#define	LE_MDC_APN_NAME_MAX_LEN   100
#define	LE_MDC_APN_NAME_MAX_BYTES   101
#define	LE_MDC_USER_NAME_MAX_LEN   64
#define	LE_MDC_USER_NAME_MAX_BYTES   65
#define	LE_MDC_PASSWORD_NAME_MAX_LEN   100
#define	LE_MDC_PASSWORD_NAME_MAX_BYTES   101

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, LE_MDC_DATA_BEARER_TECHNOLOGY_GSM, LE_MDC_DATA_BEARER_TECHNOLOGY_GPRS, LE_MDC_DATA_BEARER_TECHNOLOGY_EGPRS,   LE_MDC_DATA_BEARER_TECHNOLOGY_WCDMA, LE_MDC_DATA_BEARER_TECHNOLOGY_HSPA, LE_MDC_DATA_BEARER_TECHNOLOGY_HSPA_PLUS, LE_MDC_DATA_BEARER_TECHNOLOGY_DC_HSPA_PLUS,   LE_MDC_DATA_BEARER_TECHNOLOGY_LTE, LE_MDC_DATA_BEARER_TECHNOLOGY_TD_SCDMA, LE_MDC_DATA_BEARER_TECHNOLOGY_CDMA2000_1X, LE_MDC_DATA_BEARER_TECHNOLOGY_CDMA2000_EVDO,   LE_MDC_DATA_BEARER_TECHNOLOGY_CDMA2000_EVDO_REVA, LE_MDC_DATA_BEARER_TECHNOLOGY_CDMA2000_EHRPD }
enum	le_mdc_Pdp_t { LE_MDC_PDP_UNKNOWN, LE_MDC_PDP_IPV4, LE_MDC_PDP_IPV6, LE_MDC_PDP_IPV4V6 }
enum	le_mdc_Auth_t { LE_MDC_AUTH_NONE, LE_MDC_AUTH_PAP, LE_MDC_AUTH_CHAP }

Functions
void	le_mdc_ConnectService (void)
void	le_mdc_DisconnectService (void)
le_mdc_SessionStateHandlerRef_t	le_mdc_AddSessionStateHandler (le_mdc_ProfileRef_t profileRef, le_mdc_SessionStateHandlerFunc_t handlerPtr, void *contextPtr)
void	le_mdc_RemoveSessionStateHandler (le_mdc_SessionStateHandlerRef_t addHandlerRef)
le_mdc_ProfileRef_t	le_mdc_GetProfile (uint32_t index)
le_result_t	le_mdc_RemoveProfile (le_mdc_ProfileRef_t profileRef)
uint32_t	le_mdc_GetProfileIndex (le_mdc_ProfileRef_t profileRef)
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_result_t	le_mdc_GetInterfaceName (le_mdc_ProfileRef_t profileRef, char *interfaceName, size_t interfaceNameNumElements)
le_result_t	le_mdc_GetIPv4Address (le_mdc_ProfileRef_t profileRef, char *ipAddr, size_t ipAddrNumElements)
le_result_t	le_mdc_GetIPv4GatewayAddress (le_mdc_ProfileRef_t profileRef, char *gatewayAddr, size_t gatewayAddrNumElements)
le_result_t	le_mdc_GetIPv4DNSAddresses (le_mdc_ProfileRef_t profileRef, char *dns1AddrStr, size_t dns1AddrStrNumElements, char *dns2AddrStr, size_t dns2AddrStrNumElements)
le_result_t	le_mdc_GetIPv6Address (le_mdc_ProfileRef_t profileRef, char *ipAddr, size_t ipAddrNumElements)
le_result_t	le_mdc_GetIPv6GatewayAddress (le_mdc_ProfileRef_t profileRef, char *gatewayAddr, size_t gatewayAddrNumElements)
le_result_t	le_mdc_GetIPv6DNSAddresses (le_mdc_ProfileRef_t profileRef, char *dns1AddrStr, size_t dns1AddrStrNumElements, char *dns2AddrStr, size_t dns2AddrStrNumElements)
bool	le_mdc_IsIPv4 (le_mdc_ProfileRef_t profileRef)
bool	le_mdc_IsIPv6 (le_mdc_ProfileRef_t profileRef)
le_result_t	le_mdc_GetDataBearerTechnology (le_mdc_ProfileRef_t profileRef, le_mdc_DataBearerTechnology_t *downlinkDataBearerTechPtrPtr, le_mdc_DataBearerTechnology_t *uplinkDataBearerTechPtrPtr)
le_result_t	le_mdc_GetBytesCounters (uint64_t *rxBytesPtr, uint64_t *txBytesPtr)
le_result_t	le_mdc_ResetBytesCounter (void)
le_result_t	le_mdc_SetPDP (le_mdc_ProfileRef_t profileRef, le_mdc_Pdp_t pdp)
le_mdc_Pdp_t	le_mdc_GetPDP (le_mdc_ProfileRef_t profileRef)
le_result_t	le_mdc_SetAPN (le_mdc_ProfileRef_t profileRef, const char *apnStr)
le_result_t	le_mdc_GetAPN (le_mdc_ProfileRef_t profileRef, char *apnStr, size_t apnStrNumElements)
le_result_t	le_mdc_SetAuthentication (le_mdc_ProfileRef_t profileRef, le_mdc_Auth_t type, const char *userName, const char *password)
le_result_t	le_mdc_GetAuthentication (le_mdc_ProfileRef_t profileRef, le_mdc_Auth_t *typePtr, char *userName, size_t userNameNumElements, char *password, size_t passwordNumElements)
uint32_t	le_mdc_NumProfiles (void)
le_result_t	le_mdc_GetAvailableProfile (le_mdc_ProfileRef_t *profileRefPtr)

Detailed Description

Legato Modem Data Control include file.

Copyright (C) Sierra Wireless, Inc. 2014. Use of this work is subject to license.

Typedef Documentation

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

Handler for Data session connection state changes.

Parameters

isConnected	Data session connection status.
contextPtr

typedef struct le_mdc_SessionStateHandler* le_mdc_SessionStateHandlerRef_t

Reference type for le_mdc_SessionStateHandler handler ADD/REMOVE functions

Enumeration Type Documentation

enum le_mdc_Auth_t

Enumerator
LE_MDC_AUTH_NONE	no authentication
LE_MDC_AUTH_PAP	PAP protocol.
LE_MDC_AUTH_CHAP	CHAP protocol.

enum le_mdc_DataBearerTechnology_t

Enumerator
LE_MDC_DATA_BEARER_TECHNOLOGY_UNKNOWN	Unknown.
LE_MDC_DATA_BEARER_TECHNOLOGY_GSM	GSM.
LE_MDC_DATA_BEARER_TECHNOLOGY_GPRS	GPRS.
LE_MDC_DATA_BEARER_TECHNOLOGY_EGPRS	Enhanced GPRS (EDGE)
LE_MDC_DATA_BEARER_TECHNOLOGY_WCDMA	WCDMA (UMTS)
LE_MDC_DATA_BEARER_TECHNOLOGY_HSPA	HSPA.
LE_MDC_DATA_BEARER_TECHNOLOGY_HSPA_PLUS	HSPA+.
LE_MDC_DATA_BEARER_TECHNOLOGY_DC_HSPA_PLUS	Dual Cell - HSPA+.
LE_MDC_DATA_BEARER_TECHNOLOGY_LTE	LTE.
LE_MDC_DATA_BEARER_TECHNOLOGY_TD_SCDMA	TD-SCDMA.
LE_MDC_DATA_BEARER_TECHNOLOGY_CDMA2000_1X	CDMA2000 1X.
LE_MDC_DATA_BEARER_TECHNOLOGY_CDMA2000_EVDO	CDMA2000 HRPD (1xEV-DO)
LE_MDC_DATA_BEARER_TECHNOLOGY_CDMA2000_EVDO_REVA	CDMA2000 HRPD (1xEV-DO RevA)
LE_MDC_DATA_BEARER_TECHNOLOGY_CDMA2000_EHRPD	CDMA2000 EHRPD.

enum le_mdc_Pdp_t

Enumerator
LE_MDC_PDP_UNKNOWN	Unknown.
LE_MDC_PDP_IPV4	IPv4.
LE_MDC_PDP_IPV6	IPv6.
LE_MDC_PDP_IPV4V6	IPv4 and IPv6.

Function Documentation

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

le_mdc_SessionStateHandler handler ADD function

Parameters

[in]	profileRef	The profile object of interest
[in]	handlerPtr
[in]	contextPtr

void le_mdc_ConnectService

(

void

)

Connect the client to the service

void le_mdc_DisconnectService

(

void

)

Disconnect the client from the service

le_result_t le_mdc_GetAPN	(	le_mdc_ProfileRef_t	profileRef,
		char *	apnStr,
		size_t	apnStrNumElements
	)

Get the Access Point Name (APN) for the given profile.

Returns

• LE_OK on success
• LE_OVERFLOW if the APN is is too long
• LE_NOT_POSSIBLE on failed

Note

The process exits, if an invalid profile object is given

Parameters

[in]	profileRef	Query this profile object
[out]	apnStr	The Access Point Name
[in]	apnStrNumElements

le_result_t le_mdc_GetAuthentication	(	le_mdc_ProfileRef_t	profileRef,
		le_mdc_Auth_t *	typePtr,
		char *	userName,
		size_t	userNameNumElements,
		char *	password,
		size_t	passwordNumElements
	)

Get authentication property

Returns

• LE_OK on success
• LE_OVERFLOW userName or password are too small
• LE_NOT_POSSIBLE on failed

Note

The process exits, if an invalid profile object is given

Parameters

[in]	profileRef	Query this profile object
[out]	typePtr	Authentication type
[out]	userName	UserName used by authentication
[in]	userNameNumElements
[out]	password	Password used by authentication
[in]	passwordNumElements

le_result_t le_mdc_GetAvailableProfile

(

le_mdc_ProfileRef_t *

profileRefPtr

)

Get an available profile.

Returns

• LE_OK if a profileRef has been found
• LE_FAULT otherwise

Parameters

[out]

profileRefPtr

Profile reference

le_result_t le_mdc_GetBytesCounters	(	uint64_t *	rxBytesPtr,
		uint64_t *	txBytesPtr
	)

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]	rxBytesPtr	bytes amount received since the last counter reset
[out]	txBytesPtr	bytes amount transmitted since the last counter reset

le_result_t le_mdc_GetDataBearerTechnology	(	le_mdc_ProfileRef_t	profileRef,
		le_mdc_DataBearerTechnology_t *	downlinkDataBearerTechPtrPtr,
		le_mdc_DataBearerTechnology_t *	uplinkDataBearerTechPtrPtr
	)

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]	downlinkDataBearerTechPtrPtr	downlink data bearer technology
[out]	uplinkDataBearerTechPtrPtr	uplink data bearer technology

le_result_t le_mdc_GetInterfaceName	(	le_mdc_ProfileRef_t	profileRef,
		char *	interfaceName,
		size_t	interfaceNameNumElements
	)

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]	interfaceName	The name of the network interface
[in]	interfaceNameNumElements

le_result_t le_mdc_GetIPv4Address	(	le_mdc_ProfileRef_t	profileRef,
		char *	ipAddr,
		size_t	ipAddrNumElements
	)

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]	ipAddr	The IP address in dotted format
[in]	ipAddrNumElements

le_result_t le_mdc_GetIPv4DNSAddresses	(	le_mdc_ProfileRef_t	profileRef,
		char *	dns1AddrStr,
		size_t	dns1AddrStrNumElements,
		char *	dns2AddrStr,
		size_t	dns2AddrStrNumElements
	)

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	The primary DNS IP address in dotted format
[in]	dns1AddrStrNumElements
[out]	dns2AddrStr	The secondary DNS IP address in dotted format
[in]	dns2AddrStrNumElements

le_result_t le_mdc_GetIPv4GatewayAddress	(	le_mdc_ProfileRef_t	profileRef,
		char *	gatewayAddr,
		size_t	gatewayAddrNumElements
	)

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]	gatewayAddr	The gateway IP address in dotted format
[in]	gatewayAddrNumElements

le_result_t le_mdc_GetIPv6Address	(	le_mdc_ProfileRef_t	profileRef,
		char *	ipAddr,
		size_t	ipAddrNumElements
	)

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]	ipAddr	The IP address in dotted format
[in]	ipAddrNumElements

le_result_t le_mdc_GetIPv6DNSAddresses	(	le_mdc_ProfileRef_t	profileRef,
		char *	dns1AddrStr,
		size_t	dns1AddrStrNumElements,
		char *	dns2AddrStr,
		size_t	dns2AddrStrNumElements
	)

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	The primary DNS IP address in dotted format
[in]	dns1AddrStrNumElements
[out]	dns2AddrStr	The secondary DNS IP address in dotted format
[in]	dns2AddrStrNumElements

le_result_t le_mdc_GetIPv6GatewayAddress	(	le_mdc_ProfileRef_t	profileRef,
		char *	gatewayAddr,
		size_t	gatewayAddrNumElements
	)

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]	gatewayAddr	The gateway IP address in dotted format
[in]	gatewayAddrNumElements

le_mdc_Pdp_t le_mdc_GetPDP

(

le_mdc_ProfileRef_t

profileRef

)

Get the Packet Data Protocol (PDP) for the given profile.

Returns

• packet data protocol value

Note

The process exits, if an invalid profile object is given

Parameters

[in]

profileRef

Query this profile object

le_mdc_ProfileRef_t le_mdc_GetProfile

(

uint32_t

index

)

Get Profile Reference for index

Warning

Ensure to check the list of supported data profiles for your specific platform.

Returns

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

Parameters

[in]

index

index of the profile.

uint32_t le_mdc_GetProfileIndex

(

le_mdc_ProfileRef_t

profileRef

)

Get the index for the given Profile.

Returns

• index of the profile in the modem

Note

The process exits, if an invalid profile object is given

Parameters

[in]

profileRef

Query this profile object

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	The 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

uint32_t le_mdc_NumProfiles

(

void

)

Get the number of profiles on the modem.

Returns

• number of profiles existing on modem

le_result_t le_mdc_RemoveProfile

(

le_mdc_ProfileRef_t

profileRef

)

Remove the data profile

Returns

• LE_OK on success
• LE_FAULT if input parameter is incorrect
• LE_NOT_POSSIBLE for errors

Note

A profile can't be removed until a handler is subscribed on this profile, or a session is started

Parameters

[in]

profileRef

profile to remove.

void le_mdc_RemoveSessionStateHandler

(

le_mdc_SessionStateHandlerRef_t

addHandlerRef

)

le_mdc_SessionStateHandler handler REMOVE function

Parameters

[in]

addHandlerRef

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_SetAPN	(	le_mdc_ProfileRef_t	profileRef,
		const char *	apnStr
	)

Set the Access Point Name (APN) for the given profile.

The APN must be an ASCII string.

Returns

• LE_OK on success
• LE_NOT_POSSIBLE if the data session is currently connected for the given profile

Note

If APN is too long (max APN_NAME_MAX_LEN digits), it is a fatal error, the function will not return.

The process exits, if an invalid profile object is given

Parameters

[in]	profileRef	Query this profile object
[in]	apnStr	The Access Point Name

le_result_t le_mdc_SetAuthentication	(	le_mdc_ProfileRef_t	profileRef,
		le_mdc_Auth_t	type,
		const char *	userName,
		const char *	password
	)

Set authentication property

Returns

• LE_OK on success

Note

• The process exits, if userName or password are NULL when type is not PA_MDC_AUTH_NONE
• The process exits, if an invalid profile object is given

If userName is too long (max USER_NAME_MAX_LEN digits), it is a fatal error, the function will not return.

If password is too long (max PASSWORD_NAME_MAX_LEN digits), it is a fatal error, the function will not return.

Parameters

[in]	profileRef	Query this profile object
[in]	type	Authentication type
[in]	userName	UserName used by authentication
[in]	password	Password used by authentication

le_result_t le_mdc_SetPDP	(	le_mdc_ProfileRef_t	profileRef,
		le_mdc_Pdp_t	pdp
	)

Set the Packet Data Protocol (PDP) for the given profile.

Returns

• LE_OK on success
• LE_BAD_PARAMETER if the PDP is not supported
• LE_NOT_POSSIBLE if the data session is currently connected for the given profile

Note

The process exits, if an invalid profile object is given

Parameters

[in]	profileRef	Query this profile object
[in]	pdp	The Packet Data Protocol

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_FAULT if the input parameter is not valid
• 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