le_voicecall_interface.h

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