le_voicecall_interface.h

    1 /*
    2  * ====================== WARNING ======================
    3  *
    4  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    5  * DO NOT MODIFY IN ANY WAY.
    6  *
    7  * ====================== WARNING ======================
    8  */
    9 
   10 /**
   11  * @page c_le_voicecall Voice Call Service
   12  *
   13  * @ref le_voicecall_interface.h "API Reference"
   14  *
   15  * <HR>
   16  *
   17  * A voice call is needed for applications that want to establish a voice communication with
   18  *  a remote party.  The voice call can be over a mobile network, or over VoIP.
   19  *
   20  * @section le_voicecall_binding IPC interfaces binding
   21  *
   22  * All the functions of this API are provided by the @b voiceCallService application service.
   23  *
   24  * Here's a code sample binding to Voice Call services:
   25  * @verbatim
   26    bindings:
   27    {
   28       clientExe.clientComponent.le_voicecall -> voiceCallService.le_voicecall
   29    }
   30    @endverbatim
   31  *
   32  * @section c_le_voicecall_outgoing Starting a Voice call
   33  *
   34  * A voice call can be started using le_voicecall_Start() with the destination identifier passed as
   35  *  a parameter.
   36  *
   37  * @note Available interfaces depend on used platform.
   38  *
   39  * Before the voice call is started, an application registers a state handler using
   40  * le_voicecall_AddStateHandler(). Once the voice call is established, the handler will be called
   41  *  indicating it's now connected. If the state of the voice call changes, then the handler will be
   42  *  called with the new state. To release a voice call, an application can use le_voicecall_End().
   43  * Application must use le_voicecall_Delete() to release @ref le_voicecall_CallRef_t voice call
   44  *  reference object when it is no more used.
   45  *
   46  * If le_voicecall_End() failed a @ref LE_VOICECALL_EVENT_END_FAILED event will be sent.
   47  *
   48  * If a voice call is already started when le_voicecall_Start() is called(), a
   49  * new voice call will not be established. Instead, @ref LE_VOICECALL_EVENT_RESOURCE_BUSY event
   50  *  will be sent. This event means call was not processed, while a
   51  *  @ref LE_VOICECALL_EVENT_TERMINATED event means that the call was not processed and then
   52  *  terminated or failed.
   53  *
   54  * Once an application makes a voice call request, it should monitor the establishment state
   55  * reported to the registered state handler.
   56  *
   57  * Once the @ref LE_VOICECALL_EVENT_CONNECTED voice call event is received by the application, it
   58  *  must get the Rx and Tx audio streams with le_voicecall_GetRxAudioStream() and
   59  *  le_voicecall_GetTxAudioStream() functions in order to set up the audio path. The audio path
   60  *  can be set up thanks to the audio API (cf. @ref c_audio).
   61  *
   62  * If a @ref LE_VOICECALL_EVENT_TERMINATED event is received, application can get the termination
   63  *  reason by using le_voicecall_GetTerminationReason().
   64  *
   65  * @note The voice call use the mobile network. VoIP is not yet supported.
   66  *
   67  * @section c_le_voicecall_incoming Answering a Voice call
   68  *
   69  * An Incoming voice call will be notified by an @ref LE_VOICECALL_EVENT_INCOMING event on state
   70  *  handler with a Call reference le_voicecall_CallRef_t().
   71  *
   72  * Application can answer the call by using le_voicecall_Answer() or reject the call by using
   73  *  le_voicecall_End() passing the call reference @ref le_voicecall_CallRef_t.
   74  *
   75  * If le_voicecall_End() failed a @ref LE_VOICECALL_EVENT_END_FAILED event will be sent. If
   76  *  le_voicecall_Answer() failed a @ref LE_VOICECALL_EVENT_ANSWER_FAILED event will be sent.
   77  *
   78  * Application have to use le_voicecall_Delete() to release @ref le_voicecall_CallRef_t voice call
   79  *  reference object when it is no more used.
   80  *
   81  * <HR>
   82  *
   83  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   84  */
   85 /**
   86  * @file le_voicecall_interface.h
   87  *
   88  * Legato @ref c_le_voicecall include file.
   89  *
   90  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   91  */
   92 
   93 #ifndef LE_VOICECALL_INTERFACE_H_INCLUDE_GUARD
   94 #define LE_VOICECALL_INTERFACE_H_INCLUDE_GUARD
   95 
   96 
   97 #include "legato.h"
   98 
   99 // Interface specific includes
  100 #include "le_mdmDefs_interface.h"
  101 #include "le_audio_interface.h"
  102 
  103 
  104 //--------------------------------------------------------------------------------------------------
  105 /**
  106  *
  107  * Connect the current client thread to the service providing this API. Block until the service is
  108  * available.
  109  *
  110  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  111  * called before any other functions in this API.  Normally, ConnectService is automatically called
  112  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  113  *
  114  * This function is created automatically.
  115  */
  116 //--------------------------------------------------------------------------------------------------
  117 void le_voicecall_ConnectService
  118 (
  119     void
  120 );
  121 
  122 //--------------------------------------------------------------------------------------------------
  123 /**
  124  *
  125  * Try to connect the current client thread to the service providing this API. Return with an error
  126  * if the service is not available.
  127  *
  128  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  129  * called before any other functions in this API.  Normally, ConnectService is automatically called
  130  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  131  *
  132  * This function is created automatically.
  133  *
  134  * @return
  135  *  - LE_OK if the client connected successfully to the service.
  136  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
  137  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  138  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  139  */
  140 //--------------------------------------------------------------------------------------------------
  141 le_result_t le_voicecall_TryConnectService
  142 (
  143     void
  144 );
  145 
  146 //--------------------------------------------------------------------------------------------------
  147 /**
  148  *
  149  * Disconnect the current client thread from the service providing this API.
  150  *
  151  * Normally, this function doesn't need to be called. After this function is called, there's no
  152  * longer a connection to the service, and the functions in this API can't be used. For details, see
  153  * @ref apiFilesC_client.
  154  *
  155  * This function is created automatically.
  156  */
  157 //--------------------------------------------------------------------------------------------------
  158 void le_voicecall_DisconnectService
  159 (
  160     void
  161 );
  162 
  163 
  164 //--------------------------------------------------------------------------------------------------
  165 /**
  166  * Reference returned by Start function and used by End function
  167  */
  168 //--------------------------------------------------------------------------------------------------
  169 typedef struct le_voicecall_Call* le_voicecall_CallRef_t;
  170 
  171 
  172 //--------------------------------------------------------------------------------------------------
  173 /**
  174  * Voice call establishment states.
  175  */
  176 //--------------------------------------------------------------------------------------------------
  177 typedef enum
  178 {
  179     LE_VOICECALL_EVENT_ALERTING = 0,
  180         ///< Voice call establishment in progress.
  181         ///< Far end is now alerting its user (outgoing call).
  182 
  183     LE_VOICECALL_EVENT_CONNECTED = 1,
  184         ///< Call has been established, and is media is active.
  185 
  186     LE_VOICECALL_EVENT_TERMINATED = 2,
  187         ///< Call has terminated.
  188 
  189     LE_VOICECALL_EVENT_OFFLINE = 3,
  190         ///< NO Service available to try establish a voice call.
  191 
  192     LE_VOICECALL_EVENT_BUSY = 4,
  193         ///< Remote party (callee) is busy.
  194 
  195     LE_VOICECALL_EVENT_RESOURCE_BUSY = 5,
  196         ///< All local connection resources (lines/channels) are in use.
  197 
  198     LE_VOICECALL_EVENT_CALL_END_FAILED = 6,
  199         ///< Call ending failed.
  200 
  201     LE_VOICECALL_EVENT_CALL_ANSWER_FAILED = 7,
  202         ///< Call answering failed.
  203 
  204     LE_VOICECALL_EVENT_INCOMING = 8
  205         ///< Incoming voice call in progress.
  206 }
  207 le_voicecall_Event_t;
  208 
  209 
  210 //--------------------------------------------------------------------------------------------------
  211 /**
  212  * Voice call termination reason.
  213  */
  214 //--------------------------------------------------------------------------------------------------
  215 typedef enum
  216 {
  217     LE_VOICECALL_TERM_NETWORK_FAIL = 0,
  218         ///< Network could not complete the call.
  219 
  220     LE_VOICECALL_TERM_BAD_ADDRESS = 1,
  221         ///< Remote address could not be resolved.
  222 
  223     LE_VOICECALL_TERM_BUSY = 2,
  224         ///< Caller is currently busy and cannot take the call.
  225 
  226     LE_VOICECALL_TERM_LOCAL_ENDED = 3,
  227         ///< Local party ended the call.
  228 
  229     LE_VOICECALL_TERM_REMOTE_ENDED = 4,
  230         ///< Remote party ended the call.
  231 
  232     LE_VOICECALL_TERM_UNDEFINED = 5
  233         ///< Undefined reason.
  234 }
  235 le_voicecall_TerminationReason_t;
  236 
  237 
  238 //--------------------------------------------------------------------------------------------------
  239 /**
  240  * Reference type used by Add/Remove functions for EVENT 'le_voicecall_State'
  241  */
  242 //--------------------------------------------------------------------------------------------------
  243 typedef struct le_voicecall_StateHandler* le_voicecall_StateHandlerRef_t;
  244 
  245 
  246 //--------------------------------------------------------------------------------------------------
  247 /**
  248  * Handler for voice call state changes.
  249  *
  250  * @param reference
  251  *        Event voice call object reference.
  252  * @param identifier
  253  *        Identifier of the remote party
  254  * @param event
  255  *        Voice call event.
  256  * @param contextPtr
  257  */
  258 //--------------------------------------------------------------------------------------------------
  259 typedef void (*le_voicecall_StateHandlerFunc_t)
  260 (
  261     le_voicecall_CallRef_t reference,
  262     const char* identifier,
  263     le_voicecall_Event_t event,
  264     void* contextPtr
  265 );
  266 
  267 //--------------------------------------------------------------------------------------------------
  268 /**
  269  * Add handler function for EVENT 'le_voicecall_State'
  270  *
  271  * This event provides information on voice call state changes
  272  */
  273 //--------------------------------------------------------------------------------------------------
  274 le_voicecall_StateHandlerRef_t le_voicecall_AddStateHandler
  275 (
  276     le_voicecall_StateHandlerFunc_t handlerPtr,
  277         ///< [IN]
  278 
  279     void* contextPtr
  280         ///< [IN]
  281 );
  282 
  283 //--------------------------------------------------------------------------------------------------
  284 /**
  285  * Remove handler function for EVENT 'le_voicecall_State'
  286  */
  287 //--------------------------------------------------------------------------------------------------
  288 void le_voicecall_RemoveStateHandler
  289 (
  290     le_voicecall_StateHandlerRef_t addHandlerRef
  291         ///< [IN]
  292 );
  293 
  294 //--------------------------------------------------------------------------------------------------
  295 /**
  296  * Start a voice call.
  297  *
  298  * @return
  299  *      - Reference to the voice call (to be used later for releasing the voice call)
  300  *      - NULL if the voice call could not be processed
  301  */
  302 //--------------------------------------------------------------------------------------------------
  303 le_voicecall_CallRef_t le_voicecall_Start
  304 (
  305     const char* DestinationID
  306         ///< [IN] Destination identifier for the voice
  307 );
  308 
  309 //--------------------------------------------------------------------------------------------------
  310 /**
  311  * Release a voice call.
  312  *
  313  * @return
  314  *      - LE_OK if the end of voice call can be processed.
  315  *      - LE_NOT_FOUND if the voice call object reference is not found.
  316  */
  317 //--------------------------------------------------------------------------------------------------
  318 le_result_t le_voicecall_End
  319 (
  320     le_voicecall_CallRef_t reference
  321         ///< [IN] Voice call object reference to hang-up.
  322 );
  323 
  324 //--------------------------------------------------------------------------------------------------
  325 /**
  326  * Delete voice call object reference create by le_voicecall_Start() or an incoming voice call.
  327  *
  328  * @return
  329  *      - LE_OK if the delete of voice call can be processed.
  330  *      - LE_FAULT if the voice call is not terminated.
  331  *      - LE_NOT_FOUND if the voice call object reference is not found.
  332  */
  333 //--------------------------------------------------------------------------------------------------
  334 le_result_t le_voicecall_Delete
  335 (
  336     le_voicecall_CallRef_t reference
  337         ///< [IN] Voice call object reference to delete.
  338 );
  339 
  340 //--------------------------------------------------------------------------------------------------
  341 /**
  342  * Answer to incoming voice call.
  343  *
  344  * @return
  345  *      - LE_OK if the incoming voice call can be answered
  346  *      - LE_NOT_FOUND if the incoming voice call object reference is not found.
  347  */
  348 //--------------------------------------------------------------------------------------------------
  349 le_result_t le_voicecall_Answer
  350 (
  351     le_voicecall_CallRef_t reference
  352         ///< [IN] Incoming voice call object reference to answer.
  353 );
  354 
  355 //--------------------------------------------------------------------------------------------------
  356 /**
  357  * Get the termination reason of a voice call reference.
  358  *
  359  * @return
  360  *      - LE_OK if the termination reason is got
  361  *      - LE_NOT_FOUND if the incoming voice call object reference is not found.
  362  *      - LE_FAULT if the voice call is not terminated.
  363  */
  364 //--------------------------------------------------------------------------------------------------
  365 le_result_t le_voicecall_GetTerminationReason
  366 (
  367     le_voicecall_CallRef_t reference,
  368         ///< [IN] Voice call object reference to read from.
  369 
  370     le_voicecall_TerminationReason_t* reasonPtr
  371         ///< [OUT] Termination reason of the voice call.
  372 );
  373 
  374 //--------------------------------------------------------------------------------------------------
  375 /**
  376  * Called to get the transmitted audio stream. All audio generated on this
  377  * end of the call is sent on this stream.
  378  *
  379  * @return Transmitted audio stream reference.
  380   */
  381 //--------------------------------------------------------------------------------------------------
  382 le_audio_StreamRef_t le_voicecall_GetTxAudioStream
  383 (
  384     le_voicecall_CallRef_t reference
  385         ///< [IN] Voice call object reference to read from.
  386 );
  387 
  388 //--------------------------------------------------------------------------------------------------
  389 /**
  390  * Called to get the received audio stream. All audio received from the
  391  * other end of the call is received on this stream.
  392  *
  393  * @return Received audio stream reference.
  394  */
  395 //--------------------------------------------------------------------------------------------------
  396 le_audio_StreamRef_t le_voicecall_GetRxAudioStream
  397 (
  398     le_voicecall_CallRef_t reference
  399         ///< [IN] Voice call object reference to read from.
  400 );
  401 
  402 
  403 #endif // LE_VOICECALL_INTERFACE_H_INCLUDE_GUARD
  404 
le_voicecall_TryConnectService
le_result_t le_voicecall_TryConnectService(void)
LE_VOICECALL_TERM_LOCAL_ENDED
Local party ended the call. 
Definition: le_voicecall_interface.h:226
le_voicecall_End
le_result_t le_voicecall_End(le_voicecall_CallRef_t reference)
le_result_t
le_result_t
Definition: le_basics.h:35
le_voicecall_Delete
le_result_t le_voicecall_Delete(le_voicecall_CallRef_t reference)
LE_VOICECALL_EVENT_RESOURCE_BUSY
All local connection resources (lines/channels) are in use. 
Definition: le_voicecall_interface.h:195
le_mdmDefs_interface.h
le_audio_StreamRef_t
struct le_audio_Stream * le_audio_StreamRef_t
Definition: le_audio_interface.h:584
le_voicecall_AddStateHandler
le_voicecall_StateHandlerRef_t le_voicecall_AddStateHandler(le_voicecall_StateHandlerFunc_t handlerPtr, void *contextPtr)
le_voicecall_RemoveStateHandler
void le_voicecall_RemoveStateHandler(le_voicecall_StateHandlerRef_t addHandlerRef)
LE_VOICECALL_EVENT_ALERTING
Definition: le_voicecall_interface.h:179
LE_VOICECALL_TERM_BAD_ADDRESS
Remote address could not be resolved. 
Definition: le_voicecall_interface.h:220
le_voicecall_StateHandlerRef_t
struct le_voicecall_StateHandler * le_voicecall_StateHandlerRef_t
Definition: le_voicecall_interface.h:243
le_voicecall_StateHandlerFunc_t
void(* le_voicecall_StateHandlerFunc_t)(le_voicecall_CallRef_t reference, const char *identifier, le_voicecall_Event_t event, void *contextPtr)
Definition: le_voicecall_interface.h:260
le_voicecall_Start
le_voicecall_CallRef_t le_voicecall_Start(const char *DestinationID)
le_voicecall_CallRef_t
struct le_voicecall_Call * le_voicecall_CallRef_t
Definition: le_voicecall_interface.h:169
le_voicecall_GetRxAudioStream
le_audio_StreamRef_t le_voicecall_GetRxAudioStream(le_voicecall_CallRef_t reference)
LE_VOICECALL_EVENT_TERMINATED
Call has terminated. 
Definition: le_voicecall_interface.h:186
le_voicecall_GetTxAudioStream
le_audio_StreamRef_t le_voicecall_GetTxAudioStream(le_voicecall_CallRef_t reference)
le_voicecall_Event_t
le_voicecall_Event_t
Definition: le_voicecall_interface.h:177
le_voicecall_GetTerminationReason
le_result_t le_voicecall_GetTerminationReason(le_voicecall_CallRef_t reference, le_voicecall_TerminationReason_t *reasonPtr)
LE_VOICECALL_EVENT_CONNECTED
Call has been established, and is media is active. 
Definition: le_voicecall_interface.h:183
le_voicecall_ConnectService
void le_voicecall_ConnectService(void)
LE_VOICECALL_TERM_BUSY
Caller is currently busy and cannot take the call. 
Definition: le_voicecall_interface.h:223
le_audio_interface.h
LE_VOICECALL_EVENT_CALL_ANSWER_FAILED
Call answering failed. 
Definition: le_voicecall_interface.h:201
LE_VOICECALL_EVENT_OFFLINE
NO Service available to try establish a voice call. 
Definition: le_voicecall_interface.h:189
LE_VOICECALL_TERM_UNDEFINED
Undefined reason. 
Definition: le_voicecall_interface.h:232
LE_VOICECALL_EVENT_INCOMING
Incoming voice call in progress. 
Definition: le_voicecall_interface.h:204
LE_VOICECALL_EVENT_CALL_END_FAILED
Call ending failed. 
Definition: le_voicecall_interface.h:198
legato.h
LE_VOICECALL_EVENT_BUSY
Remote party (callee) is busy. 
Definition: le_voicecall_interface.h:192
LE_VOICECALL_TERM_NETWORK_FAIL
Network could not complete the call. 
Definition: le_voicecall_interface.h:217
le_voicecall_DisconnectService
void le_voicecall_DisconnectService(void)
le_voicecall_TerminationReason_t
le_voicecall_TerminationReason_t
Definition: le_voicecall_interface.h:215
LE_VOICECALL_TERM_REMOTE_ENDED
Remote party ended the call. 
Definition: le_voicecall_interface.h:229
le_voicecall_Answer
le_result_t le_voicecall_Answer(le_voicecall_CallRef_t reference)