interfaces/modemServices/c/le_mdc.h File Reference

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

Go to the source code of this file.

Typedefs
typedef struct le_mdc_Profile *	le_mdc_Profile_Ref_t
typedef struct le_mdc_SessionStateHandler *	le_mdc_SessionStateHandlerRef_t
typedef void(*	le_mdc_SessionStateHandlerFunc_t )(bool isConnected, void *contextPtr)
Functions
le_mdc_Profile_Ref_t	le_mdc_LoadProfile (const char *nameStr)
le_result_t	le_mdc_GetProfileName (le_mdc_Profile_Ref_t profileRef, char *nameStr, size_t nameStrSize)
le_result_t	le_mdc_StartSession (le_mdc_Profile_Ref_t profileRef)
le_result_t	le_mdc_StopSession (le_mdc_Profile_Ref_t profileRef)
le_result_t	le_mdc_GetSessionState (le_mdc_Profile_Ref_t profileRef, bool *isConnectedPtr)
le_mdc_SessionStateHandlerRef_t	le_mdc_AddSessionStateHandler (le_mdc_Profile_Ref_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_Profile_Ref_t profileRef, char *interfaceNameStr, size_t interfaceNameStrSize)
le_result_t	le_mdc_GetIPAddress (le_mdc_Profile_Ref_t profileRef, char *ipAddrStr, size_t ipAddrStrSize)
le_result_t	le_mdc_GetGatewayAddress (le_mdc_Profile_Ref_t profileRef, char *gatewayAddrStr, size_t gatewayAddrStrSize)
le_result_t	le_mdc_GetDNSAddresses (le_mdc_Profile_Ref_t profileRef, char *dns1AddrStr, size_t dns1AddrStrSize, char *dns2AddrStr, size_t dns2AddrStrSize)
bool	le_mdc_IsIPV4 (le_mdc_Profile_Ref_t profileRef)
bool	le_mdc_IsIPV6 (le_mdc_Profile_Ref_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_Profile_Ref_t profileRef, char *apnNameStr, size_t apnNameStrSize)
le_result_t	le_mdc_GetDataBearerTechnology (le_mdc_Profile_Ref_t profileRef, le_mdc_dataBearerTechnology_t *dataBearerTechnologyPtr)

---

Detailed Description

Legato Modem Data Control API include file.

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

---

Typedef Documentation

typedef struct le_mdc_Profile* le_mdc_Profile_Ref_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.

---

Function Documentation

le_mdc_SessionStateHandlerRef_t le_mdc_AddSessionStateHandler	(	le_mdc_Profile_Ref_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_Profile_Ref_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_Profile_Ref_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_GetDNSAddresses	(	le_mdc_Profile_Ref_t	profileRef,
		char *	dns1AddrStr,
		size_t	dns1AddrStrSize,
		char *	dns2AddrStr,
		size_t	dns2AddrStrSize
	)

Get the primary/secondary DNS addresses, if the data session is connected.

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_GetGatewayAddress	(	le_mdc_Profile_Ref_t	profileRef,
		char *	gatewayAddrStr,
		size_t	gatewayAddrStrSize
	)

Get the gateway IP address, if the data session is connected.

Returns:

• LE_OK on success
• LE_OVERFLOW if the IP address can't 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_GetInterfaceName	(	le_mdc_Profile_Ref_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_GetIPAddress	(	le_mdc_Profile_Ref_t	profileRef,
		char *	ipAddrStr,
		size_t	ipAddrStrSize
	)

Get the IP address for the given profile, if the data session is connected.

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_GetProfileName	(	le_mdc_Profile_Ref_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_Profile_Ref_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_Profile_Ref_t

profileRef

)

Allow the caller to know if the given profile is actually supporting IPv4.

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_Profile_Ref_t

profileRef

)

Allow the caller to know if the given profile is actually supporting IPv6.

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

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