le_mcc_interface.h File Reference

#include "legato.h"
#include "le_mdmDefs_interface.h"

Go to the source code of this file.

Typedefs
typedef struct le_mcc_Call *	le_mcc_CallRef_t
typedef struct le_mcc_CallEventHandler *	le_mcc_CallEventHandlerRef_t
typedef void(*	le_mcc_CallEventHandlerFunc_t) (le_mcc_CallRef_t callRef, le_mcc_Event_t event, void *contextPtr)

Enumerations
enum	le_mcc_Event_t {   LE_MCC_EVENT_SETUP, LE_MCC_EVENT_INCOMING, LE_MCC_EVENT_ORIGINATING, LE_MCC_EVENT_ALERTING,   LE_MCC_EVENT_CONNECTED, LE_MCC_EVENT_TERMINATED, LE_MCC_EVENT_WAITING, LE_MCC_EVENT_ON_HOLD,   LE_MCC_EVENT_MAX }
enum	le_mcc_TerminationReason_t {   LE_MCC_TERM_LOCAL_ENDED, LE_MCC_TERM_REMOTE_ENDED, LE_MCC_TERM_NETWORK_FAIL, LE_MCC_TERM_UNASSIGNED_NUMBER,   LE_MCC_TERM_NO_ROUTE_TO_DESTINATION, LE_MCC_TERM_CHANNEL_UNACCEPTABLE, LE_MCC_TERM_OPERATOR_DETERMINED_BARRING, LE_MCC_TERM_USER_BUSY,   LE_MCC_TERM_NO_USER_RESPONDING, LE_MCC_TERM_USER_ALERTING_NO_ANSWER, LE_MCC_TERM_CALL_REJECTED, LE_MCC_TERM_NUMBER_CHANGED,   LE_MCC_TERM_PREEMPTION, LE_MCC_TERM_DESTINATION_OUT_OF_ORDER, LE_MCC_TERM_INVALID_NUMBER_FORMAT, LE_MCC_TERM_FACILITY_REJECTED,   LE_MCC_TERM_RESP_TO_STATUS_ENQUIRY, LE_MCC_TERM_NORMAL_UNSPECIFIED, LE_MCC_TERM_NO_CIRCUIT_OR_CHANNEL_AVAILABLE, LE_MCC_TERM_NETWORK_OUT_OF_ORDER,   LE_MCC_TERM_TEMPORARY_FAILURE, LE_MCC_TERM_SWITCHING_EQUIPMENT_CONGESTION, LE_MCC_TERM_ACCESS_INFORMATION_DISCARDED, LE_MCC_TERM_REQUESTED_CIRCUIT_OR_CHANNEL_NOT_AVAILABLE,   LE_MCC_TERM_RESOURCES_UNAVAILABLE_OR_UNSPECIFIED, LE_MCC_TERM_QOS_UNAVAILABLE, LE_MCC_TERM_REQUESTED_FACILITY_NOT_SUBSCRIBED, LE_MCC_TERM_INCOMING_CALLS_BARRED_WITHIN_CUG,   LE_MCC_TERM_BEARER_CAPABILITY_NOT_AUTH, LE_MCC_TERM_BEARER_CAPABILITY_UNAVAILABLE, LE_MCC_TERM_SERVICE_OPTION_NOT_AVAILABLE, LE_MCC_TERM_ACM_LIMIT_EXCEEDED,   LE_MCC_TERM_BEARER_SERVICE_NOT_IMPLEMENTED, LE_MCC_TERM_REQUESTED_FACILITY_NOT_IMPLEMENTED, LE_MCC_TERM_ONLY_DIGITAL_INFORMATION_BEARER_AVAILABLE, LE_MCC_TERM_SERVICE_OR_OPTION_NOT_IMPLEMENTED,   LE_MCC_TERM_INVALID_TRANSACTION_IDENTIFIER, LE_MCC_TERM_USER_NOT_MEMBER_OF_CUG, LE_MCC_TERM_INCOMPATIBLE_DESTINATION, LE_MCC_TERM_INVALID_TRANSIT_NW_SELECTION,   LE_MCC_TERM_SEMANTICALLY_INCORRECT_MESSAGE, LE_MCC_TERM_INVALID_MANDATORY_INFORMATION, LE_MCC_TERM_MESSAGE_TYPE_NON_IMPLEMENTED, LE_MCC_TERM_MESSAGE_TYPE_NOT_COMPATIBLE_WITH_PROTOCOL_STATE,   LE_MCC_TERM_INFORMATION_ELEMENT_NON_EXISTENT, LE_MCC_TERM_CONDITONAL_IE_ERROR, LE_MCC_TERM_MESSAGE_NOT_COMPATIBLE_WITH_PROTOCOL_STATE, LE_MCC_TERM_RECOVERY_ON_TIMER_EXPIRY,   LE_MCC_TERM_PROTOCOL_ERROR_UNSPECIFIED, LE_MCC_TERM_INTERWORKING_UNSPECIFIED, LE_MCC_TERM_SERVICE_TEMPORARILY_OUT_OF_ORDER, LE_MCC_TERM_NOT_ALLOWED,   LE_MCC_TERM_FDN_ACTIVE, LE_MCC_TERM_NO_SERVICE, LE_MCC_TERM_PLATFORM_SPECIFIC, LE_MCC_TERM_UNDEFINED }

Functions
void	le_mcc_ConnectService (void)
void	le_mcc_DisconnectService (void)
le_mcc_CallRef_t	le_mcc_Create (const char *phoneNumPtr)
le_result_t	le_mcc_Delete (le_mcc_CallRef_t callRef)
le_result_t	le_mcc_Start (le_mcc_CallRef_t callRef)
bool	le_mcc_IsConnected (le_mcc_CallRef_t callRef)
le_result_t	le_mcc_GetRemoteTel (le_mcc_CallRef_t callRef, char *telPtr, size_t telPtrNumElements)
le_mcc_TerminationReason_t	le_mcc_GetTerminationReason (le_mcc_CallRef_t callRef)
int32_t	le_mcc_GetPlatformSpecificTerminationCode (le_mcc_CallRef_t callRef)
le_result_t	le_mcc_Answer (le_mcc_CallRef_t callRef)
le_result_t	le_mcc_HangUp (le_mcc_CallRef_t callRef)
le_result_t	le_mcc_HangUpAll (void)
le_result_t	le_mcc_GetCallerIdRestrict (le_mcc_CallRef_t callRef, le_onoff_t *clirStatusPtrPtr)
le_result_t	le_mcc_SetCallerIdRestrict (le_mcc_CallRef_t callRef, le_onoff_t clirStatus)
le_mcc_CallEventHandlerRef_t	le_mcc_AddCallEventHandler (le_mcc_CallEventHandlerFunc_t handlerPtr, void *contextPtr)
void	le_mcc_RemoveCallEventHandler (le_mcc_CallEventHandlerRef_t addHandlerRef)

Detailed Description

Legato Modem Call Control include file.

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

Typedef Documentation

typedef void(* le_mcc_CallEventHandlerFunc_t) (le_mcc_CallRef_t callRef, le_mcc_Event_t event, void *contextPtr)

Handler for call state changes.

Note

The callRef has to be deleted using le_mcc_Delete() when LE_MCC_TERMINATED event is received, except if is has to be used for a future usage (with le_mcc_profile handler for instance, or dialing again the same number).

Parameters

callRef	The call reference.
event	Call event.
contextPtr

typedef struct le_mcc_CallEventHandler* le_mcc_CallEventHandlerRef_t

Reference type used by Add/Remove functions for EVENT 'le_mcc_CallEvent'

typedef struct le_mcc_Call* le_mcc_CallRef_t

Reference type for managing active calls.

Enumeration Type Documentation

enum le_mcc_Event_t

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

Enumerator
LE_MCC_EVENT_SETUP	Call is being set up.
LE_MCC_EVENT_INCOMING	Incoming call attempt (new call).
LE_MCC_EVENT_ORIGINATING	Outgoing call attempt.
LE_MCC_EVENT_ALERTING	Far end is now alerting its user (outgoing call).
LE_MCC_EVENT_CONNECTED	Call has been established, and is media is active.
LE_MCC_EVENT_TERMINATED	Call has terminated.
LE_MCC_EVENT_WAITING	Call is waiting.
LE_MCC_EVENT_ON_HOLD	Remote party has put the call on hold.
LE_MCC_EVENT_MAX	Enumerate max value.

enum le_mcc_TerminationReason_t

Enumeration of the possible reasons for call termination.

Enumerator
LE_MCC_TERM_LOCAL_ENDED	Local party ended the call (Normal Call Clearing).
LE_MCC_TERM_REMOTE_ENDED	Remote party ended the call (Normal Call Clearing).
LE_MCC_TERM_NETWORK_FAIL	Network could not complete the call.
LE_MCC_TERM_UNASSIGNED_NUMBER	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_NO_ROUTE_TO_DESTINATION	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_CHANNEL_UNACCEPTABLE	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_OPERATOR_DETERMINED_BARRING	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_USER_BUSY	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_NO_USER_RESPONDING	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_USER_ALERTING_NO_ANSWER	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_CALL_REJECTED	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_NUMBER_CHANGED	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_PREEMPTION	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_DESTINATION_OUT_OF_ORDER	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_INVALID_NUMBER_FORMAT	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_FACILITY_REJECTED	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_RESP_TO_STATUS_ENQUIRY	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_NORMAL_UNSPECIFIED	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_NO_CIRCUIT_OR_CHANNEL_AVAILABLE	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_NETWORK_OUT_OF_ORDER	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_TEMPORARY_FAILURE	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_SWITCHING_EQUIPMENT_CONGESTION	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_ACCESS_INFORMATION_DISCARDED	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_REQUESTED_CIRCUIT_OR_CHANNEL_NOT_AVAILABLE	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_RESOURCES_UNAVAILABLE_OR_UNSPECIFIED	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_QOS_UNAVAILABLE	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_REQUESTED_FACILITY_NOT_SUBSCRIBED	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_INCOMING_CALLS_BARRED_WITHIN_CUG	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_BEARER_CAPABILITY_NOT_AUTH	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_BEARER_CAPABILITY_UNAVAILABLE	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_SERVICE_OPTION_NOT_AVAILABLE	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_ACM_LIMIT_EXCEEDED	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_BEARER_SERVICE_NOT_IMPLEMENTED	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_REQUESTED_FACILITY_NOT_IMPLEMENTED	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_ONLY_DIGITAL_INFORMATION_BEARER_AVAILABLE	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_SERVICE_OR_OPTION_NOT_IMPLEMENTED	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_INVALID_TRANSACTION_IDENTIFIER	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_USER_NOT_MEMBER_OF_CUG	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_INCOMPATIBLE_DESTINATION	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_INVALID_TRANSIT_NW_SELECTION	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_SEMANTICALLY_INCORRECT_MESSAGE	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_INVALID_MANDATORY_INFORMATION	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_MESSAGE_TYPE_NON_IMPLEMENTED	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_MESSAGE_TYPE_NOT_COMPATIBLE_WITH_PROTOCOL_STATE	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_INFORMATION_ELEMENT_NON_EXISTENT	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_CONDITONAL_IE_ERROR	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_MESSAGE_NOT_COMPATIBLE_WITH_PROTOCOL_STATE	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_RECOVERY_ON_TIMER_EXPIRY	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_PROTOCOL_ERROR_UNSPECIFIED	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_INTERWORKING_UNSPECIFIED	cf. 3GPP 24.008 Annex H
LE_MCC_TERM_SERVICE_TEMPORARILY_OUT_OF_ORDER	cf. 3GPP 24.008 10.5.3.6
LE_MCC_TERM_NOT_ALLOWED	Call operations not allowed (i.e. Radio off).
LE_MCC_TERM_FDN_ACTIVE	FDN is active and number is not in the FDN.
LE_MCC_TERM_NO_SERVICE	No service or bad signal quality.
LE_MCC_TERM_PLATFORM_SPECIFIC	Platform specific code.
LE_MCC_TERM_UNDEFINED	Undefined reason.

Function Documentation

le_mcc_CallEventHandlerRef_t le_mcc_AddCallEventHandler	(	le_mcc_CallEventHandlerFunc_t	handlerPtr,
		void *	contextPtr
	)

Add handler function for EVENT 'le_mcc_CallEvent'

Register an event handler that will be notified when an call's event occurs.

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]	handlerPtr
[in]	contextPtr

le_result_t le_mcc_Answer

(

le_mcc_CallRef_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

The call reference.

void le_mcc_ConnectService

(

void

)

Connect the current client thread to the service providing this API.

This function must be called before any other functions in this API. Normally, it's automatically called for the main thread, but must be explicitly called for other threads. For details, see Client-specific Functions.

This function is created automatically.

le_mcc_CallRef_t le_mcc_Create

(

const char *

phoneNumPtr

)

Create a call reference.

Note

Return NULL if call reference can't be created

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

Parameters

[in]

phoneNumPtr

The target number we are going to call.

le_result_t le_mcc_Delete

(

le_mcc_CallRef_t

callRef

)

Call to free up a call reference.

Returns

• LE_OK The function succeed.
• LE_NOT_FOUND The call reference was not found.
• LE_FAULT The function failed.

Parameters

[in]

callRef

The call object to free.

void le_mcc_DisconnectService

(

void

)

Disconnect the current client thread from the service providing this API.

Normally, this function doesn't need to be called. After this function is called, there's no longer a connection to the service, and the functions in this API can't be used. For details, see Client-specific Functions.

This function is created automatically.

le_result_t le_mcc_GetCallerIdRestrict	(	le_mcc_CallRef_t	callRef,
		le_onoff_t *	clirStatusPtrPtr
	)

This function return the Calling Line Identification Restriction (CLIR) status on the specific call.

The output parameter is updated with the CLIR status.

• LE_ON Disable presentation of own phone number to remote.
• LE_OFF Enable presentation of own phone number to remote.

Returns

• LE_OK The function succeed.
• LE_NOT_FOUND The call reference was not found.

Parameters

[in]	callRef	The call reference.
[out]	clirStatusPtrPtr	the Calling Line Identification Restriction (CLIR) status

int32_t le_mcc_GetPlatformSpecificTerminationCode

(

le_mcc_CallRef_t

callRef

)

Called to get the platform specific termination code.

Returns

The platform specific termination code.

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

The call reference to read from.

le_result_t le_mcc_GetRemoteTel	(	le_mcc_CallRef_t	callRef,
		char *	telPtr,
		size_t	telPtrNumElements
	)

Read out 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 that 'len' sould be at least equal to LE_MDMDEFS_PHONE_NUM_MAX_BYTES, 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	The call reference to read from.
[out]	telPtr	The telephone number string.
[in]	telPtrNumElements

le_mcc_TerminationReason_t le_mcc_GetTerminationReason

(

le_mcc_CallRef_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

The call reference to read from.

le_result_t le_mcc_HangUp

(

le_mcc_CallRef_t

callRef

)

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

Returns

LE_FAULT The function failed.

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

The call to end.

le_result_t le_mcc_HangUpAll

(

void

)

This function will disconnect, or hang up all the ongoing calls. Any active call handlers will be notified.

Returns

LE_FAULT The function failed.

LE_TIMEOUT No response was received from the Modem.

LE_OK The function succeeded.

bool le_mcc_IsConnected

(

le_mcc_CallRef_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

The call reference to read.

void le_mcc_RemoveCallEventHandler

(

le_mcc_CallEventHandlerRef_t

addHandlerRef

)

Remove handler function for EVENT 'le_mcc_CallEvent'

Parameters

[in]

addHandlerRef

le_result_t le_mcc_SetCallerIdRestrict	(	le_mcc_CallRef_t	callRef,
		le_onoff_t	clirStatus
	)

This function set the Calling Line Identification Restriction (CLIR) status on the specific call. Default value is LE_OFF (Enable presentation of own phone number to remote).

Returns

• LE_OK The function succeed.
• LE_NOT_FOUND The call reference was not found.

Parameters

[in]	callRef	The call reference.
[in]	clirStatus	The Calling Line Identification Restriction (CLIR) status.

le_result_t le_mcc_Start

(

le_mcc_CallRef_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.