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_Obj *	le_mcc_profile_ObjRef_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_Obj *	le_mcc_call_ObjRef_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_ObjRef_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 }
enum	le_mcc_call_Event_t {   LE_MCC_EVENT_INCOMING, LE_MCC_EVENT_ALERTING, LE_MCC_EVENT_EARLY_MEDIA, LE_MCC_EVENT_CONNECTED,   LE_MCC_EVENT_TERMINATED, LE_MCC_EVENT_ON_HOLD, LE_MCC_EVENT_TRANSFERED }
enum	le_mcc_call_TerminationReason_t {   LE_MCC_TERM_NETWORK_FAIL, LE_MCC_TERM_BAD_ADDRESS, LE_MCC_TERM_BUSY, LE_MCC_TERM_LOCAL_ENDED,   LE_MCC_TERM_REMOTE_ENDED, LE_MCC_TERM_NOT_DEFINED }

Functions
le_mcc_profile_ObjRef_t	le_mcc_profile_GetByName (const char *profileNamePtr)
void	le_mcc_profile_Release (le_mcc_profile_ObjRef_t profileRef)
le_mcc_profile_State_t	le_mcc_profile_GetState (le_mcc_profile_ObjRef_t profileRef)
le_mcc_profile_StateChangeHandlerRef_t	le_mcc_profile_AddStateChangeHandler (le_mcc_profile_ObjRef_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_ObjRef_t profileRef, le_mcc_profile_CallEventHandlerFunc_t handlerFuncPtr, void *contextPtr)
void	le_mcc_profile_RemoveCallEventHandler (le_mcc_profile_CallEventHandlerRef_t handlerRef)
le_mcc_call_ObjRef_t	le_mcc_profile_CreateCall (le_mcc_profile_ObjRef_t profileRef, const char *destinationPtr)
void	le_mcc_call_Delete (le_mcc_call_ObjRef_t callRef)
le_result_t	le_mcc_call_Start (le_mcc_call_ObjRef_t callRef)
bool	le_mcc_call_IsConnected (le_mcc_call_ObjRef_t callRef)
le_result_t	le_mcc_call_GetRemoteTel (le_mcc_call_ObjRef_t callRef, char *telPtr, size_t len)
le_mcc_call_TerminationReason_t	le_mcc_call_GetTerminationReason (le_mcc_call_ObjRef_t callRef)
le_audio_StreamRef_t	le_mcc_call_GetTxAudioStream (le_mcc_call_ObjRef_t callRef)
le_audio_StreamRef_t	le_mcc_call_GetRxAudioStream (le_mcc_call_ObjRef_t callRef)
le_result_t	le_mcc_call_Answer (le_mcc_call_ObjRef_t callRef)
le_result_t	le_mcc_call_HangUp (le_mcc_call_ObjRef_t callRef)

Detailed Description

Legato Modem Call Control 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_Obj* le_mcc_call_ObjRef_t

Reference type for managing active calls.

typedef void(* le_mcc_profile_CallEventHandlerFunc_t)(le_mcc_call_ObjRef_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_Obj* le_mcc_profile_ObjRef_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_call_Event_t

Enumeration of the possible events that may be reported to a call event handler.

Enumerator
LE_MCC_EVENT_INCOMING	Incoming call attempt (new call).
LE_MCC_EVENT_ALERTING	Far end is now alerting its user (outgoing call).
LE_MCC_EVENT_EARLY_MEDIA	Callee has not accepted the call, but a media stream is available.
LE_MCC_EVENT_CONNECTED	Call has been established, and is media is active.
LE_MCC_EVENT_TERMINATED	Call has terminated.
LE_MCC_EVENT_ON_HOLD	Remote party has put the call on hold.
LE_MCC_EVENT_TRANSFERED	Remote party transferred or forwarded the call.

enum le_mcc_call_TerminationReason_t

Enumeration of the possible reasons for call termination.

Enumerator
LE_MCC_TERM_NETWORK_FAIL	Network could not complete the call.
LE_MCC_TERM_BAD_ADDRESS	Remote address could not be resolved.
LE_MCC_TERM_BUSY	Callee is currently busy and cannot take the call.
LE_MCC_TERM_LOCAL_ENDED	Local party ended the call.
LE_MCC_TERM_REMOTE_ENDED	Remote party ended the call.
LE_MCC_TERM_NOT_DEFINED	Undefined reason.

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_ObjRef_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_ObjRef_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_ObjRef_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_ObjRef_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_ObjRef_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_ObjRef_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_ObjRef_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_ObjRef_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_ObjRef_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_ObjRef_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_ObjRef_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_ObjRef_t le_mcc_profile_CreateCall	(	le_mcc_profile_ObjRef_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.

If destination number is too long (max 17 digits), it is a fatal error, the function will not return.

Parameters

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

le_mcc_profile_ObjRef_t le_mcc_profile_GetByName

(

const char *

profileNamePtr

)

Access a particular profile by name.

Returns

The profileRef or NULL if profileName is not found.

Note

If profil name is too long (max 100 digits), it is a fatal error, the function will not return.

Parameters

[in]

profileNamePtr

Profile name to search

le_mcc_profile_State_t le_mcc_profile_GetState

(

le_mcc_profile_ObjRef_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_ObjRef_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