API Reference

A voice call is needed for applications that want to establish a voice communication with a remote party. The voice call can be over a mobile network, or over VoIP.

IPC interfaces binding

All the functions of this API are provided by the voiceCallService application service.

Here's a code sample binding to Voice Call services:

bindings:
{
   clientExe.clientComponent.le_voicecall -> voiceCallService.le_voicecall
}

Starting a Voice call

A voice call can be started using le_voicecall_Start() with the destination identifier passed as a parameter.

    myCallRef = le_voicecall_Start(DestinationNumber);
    if (!myCallRef)
    {
        res = le_voicecall_GetTerminationReason(myCallRef, &reason);
        LE_ASSERT(res == LE_OK);
        LE_INFO("Termination reason is: %d", reason);
        return LE_FAULT;
    }

Note

Available interfaces depend on used platform.

Before the voice call is started, an application registers a state handler using le_voicecall_AddStateHandler(). Once the voice call is established, the handler will be called indicating it's now connected. If the state of the voice call changes, then the handler will be called with the new state.

    VoiceCallHandlerRef = le_voicecall_AddStateHandler(MyCallEventHandler, NULL);

To release a voice call, an application can use le_voicecall_End().

        res = le_voicecall_End(myCallRef);
        if (res != LE_OK)
        {
            LE_INFO("Failed to end call.");
        }

Application must use le_voicecall_Delete() to release le_voicecall_CallRef_t voice call reference object when it is no more used.

If le_voicecall_End() failed a LE_VOICECALL_EVENT_CALL_END_FAILED event will be sent.

If a voice call is already started when le_voicecall_Start() is called(), a new voice call will not be established. Instead, LE_VOICECALL_EVENT_RESOURCE_BUSY event will be sent. This event means call was not processed, while a LE_VOICECALL_EVENT_TERMINATED event means that the call was not processed and then terminated or failed.

Once an application makes a voice call request, it should monitor the establishment state reported to the registered state handler.

Once the LE_VOICECALL_EVENT_CONNECTED voice call event is received by the application, it must get the Rx and Tx audio streams with le_voicecall_GetRxAudioStream() and le_voicecall_GetTxAudioStream() functions in order to set up the audio path. The audio path can be set up thanks to the audio API (cf. Audio). An example of how to set up the audio path:

static le_result_t OpenAudioMic
(
    le_voicecall_CallRef_t reference
)
{
    le_result_t res;
 
    MdmRxAudioRef = le_voicecall_GetRxAudioStream(reference);
    LE_ERROR_IF((MdmRxAudioRef==NULL), "le_voicecall_GetRxAudioStream returns NULL!");
    MdmTxAudioRef = le_voicecall_GetTxAudioStream(reference);
    LE_ERROR_IF((MdmTxAudioRef==NULL), "le_voicecall_GetTxAudioStream returns NULL!");
    LE_DEBUG("OpenAudio MdmRxAudioRef %p, MdmTxAudioRef %p", MdmRxAudioRef, MdmTxAudioRef);
    LE_INFO("Connect to Mic and Speaker");
 
    // Redirect audio to the in-built Microphone and Speaker.
    FeOutRef = le_audio_OpenSpeaker();
    LE_ERROR_IF((FeOutRef==NULL), "le_audio_OpenSpeaker returns NULL!");
    FeInRef = le_audio_OpenMic();
    LE_ERROR_IF((FeInRef==NULL), "le_audio_OpenMic returns NULL!");
    AudioInputConnectorRef = le_audio_CreateConnector();
    LE_ERROR_IF((AudioInputConnectorRef==NULL), "AudioInputConnectorRef is NULL!");
    AudioOutputConnectorRef = le_audio_CreateConnector();
    LE_ERROR_IF((AudioOutputConnectorRef==NULL), "AudioOutputConnectorRef is NULL!");
 
    if (MdmRxAudioRef && MdmTxAudioRef && FeOutRef && FeInRef && AudioInputConnectorRef && AudioOutputConnectorRef)
    {
        res = le_audio_Connect(AudioInputConnectorRef, FeInRef);
        LE_ERROR_IF((res!=LE_OK), "Failed to connect RX on Input connector!");
        res = le_audio_Connect(AudioInputConnectorRef, MdmTxAudioRef);
        LE_ERROR_IF((res!=LE_OK), "Failed to connect mdmTx on Input connector!");
        res = le_audio_Connect(AudioOutputConnectorRef, FeOutRef);
        LE_ERROR_IF((res!=LE_OK), "Failed to connect TX on Output connector!");
        res = le_audio_Connect(AudioOutputConnectorRef, MdmRxAudioRef);
        LE_ERROR_IF((res!=LE_OK), "Failed to connect mdmRx on Output connector!");
    }
 
    return LE_OK;
}

If a LE_VOICECALL_EVENT_TERMINATED event is received, application can get the termination reason by using le_voicecall_GetTerminationReason().

Note

The voice call use the mobile network. VoIP is not yet supported.

Answering a Voice call

An Incoming voice call will be notified by an LE_VOICECALL_EVENT_INCOMING event on state handler with a Call reference le_voicecall_CallRef_t().

Application can answer the call by using le_voicecall_Answer() or reject the call by using le_voicecall_End() passing the call reference le_voicecall_CallRef_t.

    res = le_voicecall_Answer(myCallRef);
    if (res == LE_OK)
    {
        LE_INFO("Incoming call has been answered, you may now talk with %s", DestinationNumber);
    }

If le_voicecall_End() failed a LE_VOICECALL_EVENT_CALL_END_FAILED event will be sent. If le_voicecall_Answer() failed a LE_VOICECALL_EVENT_CALL_ANSWER_FAILED event will be sent.

Application have to use le_voicecall_Delete() to release le_voicecall_CallRef_t voice call reference object when it is no more used.

Copyright (C) Sierra Wireless Inc.