interfaces/modemServices/c/le_mcc.h File Reference

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

Go to the source code of this file.

Typedefs
typedef struct le_mcc_Profile *	le_mcc_profile_Ref_t
typedef struct le_mcc_profile_StateChangeHandler *	le_mcc_profile_StateChangeHandlerRef_t
typedef struct le_mcc_profile_CallEventHandler *	le_mcc_profile_CallEventHandlerRef_t
typedef struct le_mcc_Call *	le_mcc_call_Ref_t
typedef void(*	le_mcc_profile_StateChangeHandlerFunc_t )(le_mcc_profile_State_t newState, void *contextPtr)
typedef void(*	le_mcc_profile_CallEventHandlerFunc_t )(le_mcc_call_Ref_t callRef, le_mcc_call_Event_t event, void *contextPtr)
Enumerations
enum	le_mcc_profile_State_t {   LE_MCC_PROFILE_NOT_AVAILABLE, LE_MCC_PROFILE_IDLE, LE_MCC_PROFILE_FORWARDED, LE_MCC_PROFILE_DND,   LE_MCC_PROFILE_IN_USE }
Functions
le_mcc_profile_Ref_t	le_mcc_profile_GetByName (const char *profileNamePtr)
void	le_mcc_profile_Release (le_mcc_profile_Ref_t profileRef)
le_mcc_profile_State_t	le_mcc_profile_GetState (le_mcc_profile_Ref_t profileRef)
le_mcc_profile_StateChangeHandlerRef_t	le_mcc_profile_AddStateChangeHandler (le_mcc_profile_Ref_t profileRef, le_mcc_profile_StateChangeHandlerFunc_t handlerFuncPtr, void *contextPtr)
void	le_mcc_profile_RemoveStateChangeHandler (le_mcc_profile_StateChangeHandlerRef_t handlerRef)
le_mcc_profile_CallEventHandlerRef_t	le_mcc_profile_AddCallEventHandler (le_mcc_profile_Ref_t profileRef, le_mcc_profile_CallEventHandlerFunc_t handlerFuncPtr, void *contextPtr)
void	le_mcc_profile_RemoveCallEventHandler (le_mcc_profile_CallEventHandlerRef_t handlerRef)
le_mcc_call_Ref_t	le_mcc_profile_CreateCall (le_mcc_profile_Ref_t profileRef, const char *destinationPtr)
void	le_mcc_call_Delete (le_mcc_call_Ref_t callRef)
le_result_t	le_mcc_call_Start (le_mcc_call_Ref_t callRef)
bool	le_mcc_call_IsConnected (le_mcc_call_Ref_t callRef)
le_result_t	le_mcc_call_GetRemoteTel (le_mcc_call_Ref_t callRef, char *telPtr, size_t len)
le_mcc_call_TerminationReason_t	le_mcc_call_GetTerminationReason (le_mcc_call_Ref_t callRef)
le_audio_StreamRef_t	le_mcc_call_GetTxAudioStream (le_mcc_call_Ref_t callRef)
le_audio_StreamRef_t	le_mcc_call_GetRxAudioStream (le_mcc_call_Ref_t callRef)
le_result_t	le_mcc_call_Answer (le_mcc_call_Ref_t callRef)
le_result_t	le_mcc_call_HangUp (le_mcc_call_Ref_t callRef)

---

Detailed Description

Legato Modem Call 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_mcc_Call* le_mcc_call_Ref_t

Reference type for managing active calls.

typedef void(* le_mcc_profile_CallEventHandlerFunc_t)(le_mcc_call_Ref_t callRef, le_mcc_call_Event_t event, void *contextPtr)

Handler called whenever an event is received by a profile on the device.

Parameters:

callRef	Call associated with the event.
event	Call event.
contextPtr	Context information that the event handler may require.

typedef struct le_mcc_profile_CallEventHandler* le_mcc_profile_CallEventHandlerRef_t

Reference type for Call Event Handler references.

typedef struct le_mcc_Profile* le_mcc_profile_Ref_t

Reference type to represent profiles capable sending and receiving calls.

typedef void(* le_mcc_profile_StateChangeHandlerFunc_t)(le_mcc_profile_State_t newState, void *contextPtr)

Handler is called whenever the state of a specified profile changes.

Parameters:

newState	New state profile.
contextPtr	Whatever context information the event handler may require.

typedef struct le_mcc_profile_StateChangeHandler* le_mcc_profile_StateChangeHandlerRef_t

Reference type for Profile State's Changes Handler references.

---

Enumeration Type Documentation

enum le_mcc_profile_State_t

Enumeration to convey current status of a given profile.

Enumerator:

LE_MCC_PROFILE_NOT_AVAILABLE	This profile is not available.
LE_MCC_PROFILE_IDLE	This profile is available, nothing is currently happening on it.
LE_MCC_PROFILE_FORWARDED	This profile is currently being forwarded to another number.
LE_MCC_PROFILE_DND	This profile is in "Do Not Disturb" mode.
LE_MCC_PROFILE_IN_USE	This profile is currently in use.

---

Function Documentation

le_result_t le_mcc_call_Answer

(

le_mcc_call_Ref_t

callRef

)

Answers incoming call.

Returns:

LE_TIMEOUT No response was received from the Modem.

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

[in]

callRef

Call reference

void le_mcc_call_Delete

(

le_mcc_call_Ref_t

callRef

)

Call to free up a call reference.

Note:

This frees up the reference, but remains active if other holders reference it.

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

Parameters:

[in]

callRef

Call object to free

le_result_t le_mcc_call_GetRemoteTel	(	le_mcc_call_Ref_t	callRef,
		char *	telPtr,
		size_t	len
	)

Display the remote party telephone number associated with the call.

Output parameter is updated with the telephone number. If the Telephone number string length exceeds the value of 'len' parameter, the LE_OVERFLOW error code is returned and 'telPtr' is used until 'len-1' characters and a null-character is implicitly appended at the end of 'telPtr'. Note the 'len' parameter sould be at least equal to LE_TEL_NMBR_MAX_LEN, otherwise LE_OVERFLOW error code will be common.

Returns:

LE_OVERFLOW The Telephone number length exceed the maximum length.

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

[in]	callRef	Call reference to read
[out]	telPtr	Telephone number string
[in]	len	Telephone number string length

le_audio_StreamRef_t le_mcc_call_GetRxAudioStream

(

le_mcc_call_Ref_t

callRef

)

Called to get the received audio stream. All audio received from the other end of the call is received on this stream.

Returns:

Received audio stream 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]

callRef

Call reference to read

le_mcc_call_TerminationReason_t le_mcc_call_GetTerminationReason

(

le_mcc_call_Ref_t

callRef

)

Called to get the termination reason.

Returns:

The termination reason.

Note:

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

Parameters:

[in]

callRef

Call reference to read

le_audio_StreamRef_t le_mcc_call_GetTxAudioStream

(

le_mcc_call_Ref_t

callRef

)

Called to get the transmitted audio stream. All audio generated on this end of the call is sent on this stream.

Returns:

Transmitted audio stream 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]

callRef

Call reference to read

le_result_t le_mcc_call_HangUp

(

le_mcc_call_Ref_t

callRef

)

Disconnect, or hang up, the specifed call. Any active call handlers will be notified.

Returns:

LE_TIMEOUT No response was received from the Modem.

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:

[in]

callRef

Call to end

bool le_mcc_call_IsConnected

(

le_mcc_call_Ref_t

callRef

)

Allow the caller to know if the given call is actually connected or not.

Returns:

TRUE if the call is connected, 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]

callRef

Call reference to read

le_result_t le_mcc_call_Start

(

le_mcc_call_Ref_t

callRef

)

Start a call attempt.

Asynchronous due to possible time to connect.

As the call attempt proceeds, the profile's registered call event handler receives events.

Returns:

LE_OK Function succeed.

*

Note:

As this is an asynchronous call, a successful only confirms a call has been started. Don't assume a call has been successful yet.

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

Parameters:

[in]

callRef

Reference to the call object.

le_mcc_profile_CallEventHandlerRef_t le_mcc_profile_AddCallEventHandler	(	le_mcc_profile_Ref_t	profileRef,
		le_mcc_profile_CallEventHandlerFunc_t	handlerFuncPtr,
		void *	contextPtr
	)

Register an event handler to be notified when an event occurs on a call associated with a given profile.

Registered handler will receive events for both incoming and outgoing calls.

Returns:

A reference to the new event handler object.

Note:

It is a fatal error if this function does succeed. If this function fails, it will not return.

Parameters:

[in]	profileRef	Profile to update
[in]	handlerFuncPtr	Event handler function
[in]	contextPtr	Handler's context

le_mcc_profile_StateChangeHandlerRef_t le_mcc_profile_AddStateChangeHandler	(	le_mcc_profile_Ref_t	profileRef,
		le_mcc_profile_StateChangeHandlerFunc_t	handlerFuncPtr,
		void *	contextPtr
	)

Add an event handler for profile state changes.

Returns:

Reference to the new event handler object.

Note:

It is a fatal error if this function does succeed. If this function fails, it will not return.

Parameters:

[in]	profileRef	The profile reference.
[in]	handlerFuncPtr	The event handler function.
[in]	contextPtr	The handlers context.

le_mcc_call_Ref_t le_mcc_profile_CreateCall	(	le_mcc_profile_Ref_t	profileRef,
		const char *	destinationPtr
	)

Create a new call object with a destination telephone number.

le_mcc_call_Start() must still initiate the call when ready.

Returns:

A reference to the new Call object.

Note:

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

Parameters:

[in]	profileRef	Profile for new call.
[in]	destinationPtr	Target number to call.

le_mcc_profile_Ref_t le_mcc_profile_GetByName

(

const char *

profileNamePtr

)

Access a particular profile by name.

Returns:

The profileRef or NULL if profileName is not found.

Parameters:

[in]

profileNamePtr

Profile name to search

le_mcc_profile_State_t le_mcc_profile_GetState

(

le_mcc_profile_Ref_t

profileRef

)

Used to determine the current state of a given profile.

Returns:

Current state of the profile.

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

Profile reference to read

void le_mcc_profile_Release

(

le_mcc_profile_Ref_t

profileRef

)

Must be called to release a Call Profile.

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

Call profile reference

void le_mcc_profile_RemoveCallEventHandler

(

le_mcc_profile_CallEventHandlerRef_t

handlerRef

)

Remove the registered event handler to no longer be notified of events on calls.

Note:

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

Parameters:

[in]

handlerRef

Handler object to remove

void le_mcc_profile_RemoveStateChangeHandler

(

le_mcc_profile_StateChangeHandlerRef_t

handlerRef

)

Remove the registered event handler, to no longer receive state change events.

Note:

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

Parameters:

[in]

handlerRef

Handler object to remove