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 = 0, LE_MCC_EVENT_INCOMING = 1, LE_MCC_EVENT_ORIGINATING = 2, LE_MCC_EVENT_ALERTING = 3,
  LE_MCC_EVENT_CONNECTED = 4, LE_MCC_EVENT_TERMINATED = 5, LE_MCC_EVENT_WAITING = 6, LE_MCC_EVENT_ON_HOLD = 7,
  LE_MCC_EVENT_MAX = 8
}
 
enum  le_mcc_TerminationReason_t {
  LE_MCC_TERM_LOCAL_ENDED = 0, LE_MCC_TERM_REMOTE_ENDED = 1, LE_MCC_TERM_NETWORK_FAIL = 2, LE_MCC_TERM_UNASSIGNED_NUMBER = 3,
  LE_MCC_TERM_NO_ROUTE_TO_DESTINATION = 4, LE_MCC_TERM_CHANNEL_UNACCEPTABLE = 5, LE_MCC_TERM_OPERATOR_DETERMINED_BARRING = 6, LE_MCC_TERM_USER_BUSY = 7,
  LE_MCC_TERM_NO_USER_RESPONDING = 8, LE_MCC_TERM_USER_ALERTING_NO_ANSWER = 9, LE_MCC_TERM_CALL_REJECTED = 10, LE_MCC_TERM_NUMBER_CHANGED = 11,
  LE_MCC_TERM_PREEMPTION = 12, LE_MCC_TERM_DESTINATION_OUT_OF_ORDER = 13, LE_MCC_TERM_INVALID_NUMBER_FORMAT = 14, LE_MCC_TERM_FACILITY_REJECTED = 15,
  LE_MCC_TERM_RESP_TO_STATUS_ENQUIRY = 16, LE_MCC_TERM_NORMAL_UNSPECIFIED = 17, LE_MCC_TERM_NO_CIRCUIT_OR_CHANNEL_AVAILABLE = 18, LE_MCC_TERM_NETWORK_OUT_OF_ORDER = 19,
  LE_MCC_TERM_TEMPORARY_FAILURE = 20, LE_MCC_TERM_SWITCHING_EQUIPMENT_CONGESTION = 21, LE_MCC_TERM_ACCESS_INFORMATION_DISCARDED = 22, LE_MCC_TERM_REQUESTED_CIRCUIT_OR_CHANNEL_NOT_AVAILABLE = 23,
  LE_MCC_TERM_RESOURCES_UNAVAILABLE_OR_UNSPECIFIED = 24, LE_MCC_TERM_QOS_UNAVAILABLE = 25, LE_MCC_TERM_REQUESTED_FACILITY_NOT_SUBSCRIBED = 26, LE_MCC_TERM_INCOMING_CALLS_BARRED_WITHIN_CUG = 27,
  LE_MCC_TERM_BEARER_CAPABILITY_NOT_AUTH = 28, LE_MCC_TERM_BEARER_CAPABILITY_UNAVAILABLE = 29, LE_MCC_TERM_SERVICE_OPTION_NOT_AVAILABLE = 30, LE_MCC_TERM_ACM_LIMIT_EXCEEDED = 31,
  LE_MCC_TERM_BEARER_SERVICE_NOT_IMPLEMENTED = 32, LE_MCC_TERM_REQUESTED_FACILITY_NOT_IMPLEMENTED = 33, LE_MCC_TERM_ONLY_DIGITAL_INFORMATION_BEARER_AVAILABLE = 34, LE_MCC_TERM_SERVICE_OR_OPTION_NOT_IMPLEMENTED = 35,
  LE_MCC_TERM_INVALID_TRANSACTION_IDENTIFIER = 36, LE_MCC_TERM_USER_NOT_MEMBER_OF_CUG = 37, LE_MCC_TERM_INCOMPATIBLE_DESTINATION = 38, LE_MCC_TERM_INVALID_TRANSIT_NW_SELECTION = 39,
  LE_MCC_TERM_SEMANTICALLY_INCORRECT_MESSAGE = 40, LE_MCC_TERM_INVALID_MANDATORY_INFORMATION = 41, LE_MCC_TERM_MESSAGE_TYPE_NON_IMPLEMENTED = 42, LE_MCC_TERM_MESSAGE_TYPE_NOT_COMPATIBLE_WITH_PROTOCOL_STATE = 43,
  LE_MCC_TERM_INFORMATION_ELEMENT_NON_EXISTENT = 44, LE_MCC_TERM_CONDITONAL_IE_ERROR = 45, LE_MCC_TERM_MESSAGE_NOT_COMPATIBLE_WITH_PROTOCOL_STATE = 46, LE_MCC_TERM_RECOVERY_ON_TIMER_EXPIRY = 47,
  LE_MCC_TERM_PROTOCOL_ERROR_UNSPECIFIED = 48, LE_MCC_TERM_INTERWORKING_UNSPECIFIED = 49, LE_MCC_TERM_SERVICE_TEMPORARILY_OUT_OF_ORDER = 50, LE_MCC_TERM_NOT_ALLOWED = 51,
  LE_MCC_TERM_FDN_ACTIVE = 52, LE_MCC_TERM_NO_SERVICE = 53, LE_MCC_TERM_PLATFORM_SPECIFIC = 54, LE_MCC_TERM_UNDEFINED = 55
}
 

Functions

void le_mcc_ConnectService (void)
 
le_result_t le_mcc_TryConnectService (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)
 
le_result_t le_mcc_SetCallWaitingService (bool active)
 
le_result_t le_mcc_GetCallWaitingService (bool *activePtr)
 
le_result_t le_mcc_ActivateCall (le_mcc_CallRef_t callRef)
 

Detailed Description

Legato Modem Call Control include file.

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
callRefThe call reference.
eventCall 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

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.

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_result_t le_mcc_ActivateCall ( le_mcc_CallRef_t  callRef)

This function activates the specified call. Other calls are placed on hold.

Returns
  • LE_OK The function succeed.
  • LE_FAULT The function failed.
Parameters
[in]callRefThe call reference.
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.
A call waiting call must be answered using SetCallActive() API. This API doesn't manage call waiting supplementary service.
Parameters
[in]callRefThe call reference.
void le_mcc_ConnectService ( void  )

Connect the current client thread to the service providing this API. Block until the service is available.

For each thread that wants to use this API, either ConnectService or TryConnectService must be called before any other functions in this API. Normally, ConnectService is automatically called for the main thread, but not for any other thread. 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]phoneNumPtrThe 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]callRefThe 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]callRefThe call reference.
[out]clirStatusPtrPtrthe Calling Line Identification Restriction (CLIR) status
le_result_t le_mcc_GetCallWaitingService ( bool *  activePtr)

This function gets the call waiting service status.

Returns
  • LE_OK The function succeed.
  • LE_FAULT The function failed.
Parameters
[out]activePtrThe call waiting activation.
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]callRefThe 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]callRefThe call reference to read from.
[out]telPtrThe 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]callRefThe 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.
this API can also be used to disconnect a waiting or on hold call.
Parameters
[in]callRefThe 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]callRefThe 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]callRefThe call reference.
[in]clirStatusThe Calling Line Identification Restriction (CLIR) status.
le_result_t le_mcc_SetCallWaitingService ( bool  active)

This function activates or deactivates the call waiting service.

Returns
  • LE_OK The function succeed.
  • LE_FAULT The function failed.
Parameters
[in]activeThe call waiting activation.
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.
  • LE_BUSY The call is already in progress
  • 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]callRefReference to the call object.
le_result_t le_mcc_TryConnectService ( void  )

Try to connect the current client thread to the service providing this API. Return with an error if the service is not available.

For each thread that wants to use this API, either ConnectService or TryConnectService must be called before any other functions in this API. Normally, ConnectService is automatically called for the main thread, but not for any other thread. For details, see Client-specific Functions.

This function is created automatically.

Returns
  • LE_OK if the client connected successfully to the service.
  • LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
  • LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  • LE_COMM_ERROR if the Service Directory cannot be reached.