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  * @snippet "apps/sample/voiceCallApp/voiceCallComponent/voiceCallApp.c" Starting a voicecall
   40  *
   41  * @note Available interfaces depend on used platform.
   42  *
   43  * Before the voice call is started, an application registers a state handler using
   44  * le_voicecall_AddStateHandler(). Once the voice call is established, the handler will be called
   45  *  indicating it's now connected. If the state of the voice call changes, then the handler will be
   46  *  called with the new state.
   47  *
   48  * @snippet "apps/sample/voiceCallApp/voiceCallComponent/voiceCallApp.c" AddStateHandler
   49  *
   50  * To release a voice call, an application can use le_voicecall_End().
   51  *
   52  * @snippet "apps/sample/voiceCallApp/voiceCallComponent/voiceCallApp.c" Ending a voicecall
   53  *
   54  * Application must use le_voicecall_Delete() to release @ref le_voicecall_CallRef_t voice call
   55  *  reference object when it is no more used.
   56  *
   57  * If le_voicecall_End() failed a @ref LE_VOICECALL_EVENT_CALL_END_FAILED event will be sent.
   58  *
   59  * If a voice call is already started when le_voicecall_Start() is called(), a
   60  * new voice call will not be established. Instead, @ref LE_VOICECALL_EVENT_RESOURCE_BUSY event
   61  *  will be sent. This event means call was not processed, while a
   62  *  @ref LE_VOICECALL_EVENT_TERMINATED event means that the call was not processed and then
   63  *  terminated or failed.
   64  *
   65  * Once an application makes a voice call request, it should monitor the establishment state
   66  * reported to the registered state handler.
   67  *
   68  * Once the @ref LE_VOICECALL_EVENT_CONNECTED voice call event is received by the application, it
   69  *  must get the Rx and Tx audio streams with le_voicecall_GetRxAudioStream() and
   70  *  le_voicecall_GetTxAudioStream() functions in order to set up the audio path. The audio path
   71  *  can be set up thanks to the audio API (cf. @ref c_audio). An example of how to set up the audio path:
   72  *
   73  * @snippet "apps/sample/voiceCallApp/voiceCallComponent/voiceCallApp.c" setup audio path
   74  *
   75  *
   76  * If a @ref LE_VOICECALL_EVENT_TERMINATED event is received, application can get the termination
   77  *  reason by using le_voicecall_GetTerminationReason().
   78  *
   79  * @note The voice call use the mobile network. VoIP is not yet supported.
   80  *
   81  * @section c_le_voicecall_incoming Answering a Voice call
   82  *
   83  * An Incoming voice call will be notified by an @ref LE_VOICECALL_EVENT_INCOMING event on state
   84  *  handler with a Call reference le_voicecall_CallRef_t().
   85  *
   86  * Application can answer the call by using le_voicecall_Answer() or reject the call by using
   87  *  le_voicecall_End() passing the call reference @ref le_voicecall_CallRef_t.
   88  *
   89  * @snippet "apps/sample/voiceCallApp/voiceCallComponent/voiceCallApp.c" answer
   90  *
   91  * If le_voicecall_End() failed a @ref LE_VOICECALL_EVENT_CALL_END_FAILED event will be sent. If
   92  *  le_voicecall_Answer() failed a @ref LE_VOICECALL_EVENT_CALL_ANSWER_FAILED event will be sent.
   93  *
   94  * Application have to use le_voicecall_Delete() to release @ref le_voicecall_CallRef_t voice call
   95  *  reference object when it is no more used.
   96  *
   97  * <HR>
   98  *
   99  * Copyright (C) Sierra Wireless Inc.
  100  */
  101 /**
  102  * @file le_voicecall_interface.h
  103  *
  104  * Legato @ref c_le_voicecall include file.
  105  *
  106  * Copyright (C) Sierra Wireless Inc.
  107  */
  108 
  109 #ifndef LE_VOICECALL_INTERFACE_H_INCLUDE_GUARD
  110 #define LE_VOICECALL_INTERFACE_H_INCLUDE_GUARD
  111 
  112 
  113 #include "legato.h"
  114 
  115 // Interface specific includes
  116 #include "le_mdmDefs_interface.h"
  117 #include "le_audio_interface.h"
  118 
  119 // Internal includes for this interface
  120 #include "le_voicecall_common.h"
  121 //--------------------------------------------------------------------------------------------------
  122 /**
  123  * Type for handler called when a server disconnects.
  124  */
  125 //--------------------------------------------------------------------------------------------------
  126 typedef void (*le_voicecall_DisconnectHandler_t)(void *);
  127 
  128 //--------------------------------------------------------------------------------------------------
  129 /**
  130  *
  131  * Connect the current client thread to the service providing this API. Block until the service is
  132  * available.
  133  *
  134  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  135  * called before any other functions in this API.  Normally, ConnectService is automatically called
  136  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  137  *
  138  * This function is created automatically.
  139  */
  140 //--------------------------------------------------------------------------------------------------
  141 void le_voicecall_ConnectService
  142 (
  143     void
  144 );
  145 
  146 //--------------------------------------------------------------------------------------------------
  147 /**
  148  *
  149  * Try to connect the current client thread to the service providing this API. Return with an error
  150  * if the service is not available.
  151  *
  152  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  153  * called before any other functions in this API.  Normally, ConnectService is automatically called
  154  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  155  *
  156  * This function is created automatically.
  157  *
  158  * @return
  159  *  - LE_OK if the client connected successfully to the service.
  160  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  161  *    bound.
  162  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  163  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  164  */
  165 //--------------------------------------------------------------------------------------------------
  166 le_result_t le_voicecall_TryConnectService
  167 (
  168     void
  169 );
  170 
  171 //--------------------------------------------------------------------------------------------------
  172 /**
  173  * Set handler called when server disconnection is detected.
  174  *
  175  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  176  * to continue without exiting, it should call longjmp() from inside the handler.
  177  */
  178 //--------------------------------------------------------------------------------------------------
  179 LE_FULL_API void le_voicecall_SetServerDisconnectHandler
  180 (
  181     le_voicecall_DisconnectHandler_t disconnectHandler,
  182     void *contextPtr
  183 );
  184 
  185 //--------------------------------------------------------------------------------------------------
  186 /**
  187  *
  188  * Disconnect the current client thread from the service providing this API.
  189  *
  190  * Normally, this function doesn't need to be called. After this function is called, there's no
  191  * longer a connection to the service, and the functions in this API can't be used. For details, see
  192  * @ref apiFilesC_client.
  193  *
  194  * This function is created automatically.
  195  */
  196 //--------------------------------------------------------------------------------------------------
  197 void le_voicecall_DisconnectService
  198 (
  199     void
  200 );
  201 
  202 
  203 //--------------------------------------------------------------------------------------------------
  204 /**
  205  * Reference returned by Start function and used by End function
  206  */
  207 //--------------------------------------------------------------------------------------------------
  208 
  209 
  210 //--------------------------------------------------------------------------------------------------
  211 /**
  212  * Voice call establishment states.
  213  */
  214 //--------------------------------------------------------------------------------------------------
  215 
  216 
  217 //--------------------------------------------------------------------------------------------------
  218 /**
  219  * Voice call termination reason.
  220  */
  221 //--------------------------------------------------------------------------------------------------
  222 
  223 
  224 //--------------------------------------------------------------------------------------------------
  225 /**
  226  * Handler for voice call state changes.
  227  */
  228 //--------------------------------------------------------------------------------------------------
  229 
  230 
  231 //--------------------------------------------------------------------------------------------------
  232 /**
  233  * Reference type used by Add/Remove functions for EVENT 'le_voicecall_State'
  234  */
  235 //--------------------------------------------------------------------------------------------------
  236 
  237 
  238 //--------------------------------------------------------------------------------------------------
  239 /**
  240  * Add handler function for EVENT 'le_voicecall_State'
  241  *
  242  * This event provides information on voice call state changes
  243  *
  244  */
  245 //--------------------------------------------------------------------------------------------------
  246 le_voicecall_StateHandlerRef_t le_voicecall_AddStateHandler
  247 (
  248     le_voicecall_StateHandlerFunc_t handlerPtr,
  249         ///< [IN]
  250     void* contextPtr
  251         ///< [IN]
  252 );
  253 
  254 //--------------------------------------------------------------------------------------------------
  255 /**
  256  * Remove handler function for EVENT 'le_voicecall_State'
  257  */
  258 //--------------------------------------------------------------------------------------------------
  259 void le_voicecall_RemoveStateHandler
  260 (
  261     le_voicecall_StateHandlerRef_t handlerRef
  262         ///< [IN]
  263 );
  264 
  265 //--------------------------------------------------------------------------------------------------
  266 /**
  267  * Start a voice call.
  268  *
  269  * @return
  270  *      - Reference to the voice call (to be used later for releasing the voice call)
  271  *      - NULL if the voice call could not be processed
  272  */
  273 //--------------------------------------------------------------------------------------------------
  274 le_voicecall_CallRef_t le_voicecall_Start
  275 (
  276     const char* LE_NONNULL DestinationID
  277         ///< [IN] Destination identifier for the voice
  278         ///< call establishment.
  279 );
  280 
  281 //--------------------------------------------------------------------------------------------------
  282 /**
  283  * Release a voice call.
  284  *
  285  * @return
  286  *      - LE_OK if the end of voice call can be processed.
  287  *      - LE_NOT_FOUND if the voice call object reference is not found.
  288  */
  289 //--------------------------------------------------------------------------------------------------
  290 le_result_t le_voicecall_End
  291 (
  292     le_voicecall_CallRef_t reference
  293         ///< [IN] Voice call object reference to hang-up.
  294 );
  295 
  296 //--------------------------------------------------------------------------------------------------
  297 /**
  298  * Delete voice call object reference create by le_voicecall_Start() or an incoming voice call.
  299  *
  300  * @return
  301  *      - LE_OK if the delete of voice call can be processed.
  302  *      - LE_FAULT if the voice call is not terminated.
  303  *      - LE_NOT_FOUND if the voice call object reference is not found.
  304  */
  305 //--------------------------------------------------------------------------------------------------
  306 le_result_t le_voicecall_Delete
  307 (
  308     le_voicecall_CallRef_t reference
  309         ///< [IN] Voice call object reference to delete.
  310 );
  311 
  312 //--------------------------------------------------------------------------------------------------
  313 /**
  314  * Answer to incoming voice call.
  315  *
  316  * @return
  317  *      - LE_OK if the incoming voice call can be answered
  318  *      - LE_NOT_FOUND if the incoming voice call object reference is not found.
  319  */
  320 //--------------------------------------------------------------------------------------------------
  321 le_result_t le_voicecall_Answer
  322 (
  323     le_voicecall_CallRef_t reference
  324         ///< [IN] Incoming voice call object reference to answer.
  325 );
  326 
  327 //--------------------------------------------------------------------------------------------------
  328 /**
  329  * Get the termination reason of a voice call reference.
  330  *
  331  * @return
  332  *      - LE_OK if the termination reason is got
  333  *      - LE_NOT_FOUND if the incoming voice call object reference is not found.
  334  *      - LE_FAULT if the voice call is not terminated.
  335  */
  336 //--------------------------------------------------------------------------------------------------
  337 le_result_t le_voicecall_GetTerminationReason
  338 (
  339     le_voicecall_CallRef_t reference,
  340         ///< [IN] Voice call object reference to read from.
  341     le_voicecall_TerminationReason_t* reasonPtr
  342         ///< [OUT] Termination reason of the voice call.
  343 );
  344 
  345 //--------------------------------------------------------------------------------------------------
  346 /**
  347  * Called to get the transmitted audio stream. All audio generated on this
  348  * end of the call is sent on this stream.
  349  *
  350  * @return Transmitted audio stream reference.
  351  */
  352 //--------------------------------------------------------------------------------------------------
  353 le_audio_StreamRef_t le_voicecall_GetTxAudioStream
  354 (
  355     le_voicecall_CallRef_t reference
  356         ///< [IN] Voice call object reference to read from.
  357 );
  358 
  359 //--------------------------------------------------------------------------------------------------
  360 /**
  361  * Called to get the received audio stream. All audio received from the
  362  * other end of the call is received on this stream.
  363  *
  364  * @return Received audio stream reference.
  365  */
  366 //--------------------------------------------------------------------------------------------------
  367 le_audio_StreamRef_t le_voicecall_GetRxAudioStream
  368 (
  369     le_voicecall_CallRef_t reference
  370         ///< [IN] Voice call object reference to read from.
  371 );
  372 
  373 #endif // LE_VOICECALL_INTERFACE_H_INCLUDE_GUARD
le_mdmDefs_interface.h
le_voicecall_TryConnectService
le_result_t le_voicecall_TryConnectService(void)
le_voicecall_End
le_result_t le_voicecall_End(le_voicecall_CallRef_t reference)
le_result_t
le_result_t
Definition: le_basics.h:45
le_voicecall_Delete
le_result_t le_voicecall_Delete(le_voicecall_CallRef_t reference)
le_voicecall_AddStateHandler
le_voicecall_StateHandlerRef_t le_voicecall_AddStateHandler(le_voicecall_StateHandlerFunc_t handlerPtr, void *contextPtr)
le_voicecall_GetRxAudioStream
le_audio_StreamRef_t le_voicecall_GetRxAudioStream(le_voicecall_CallRef_t reference)
le_voicecall_SetServerDisconnectHandler
LE_FULL_API void le_voicecall_SetServerDisconnectHandler(le_voicecall_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_voicecall_GetTxAudioStream
le_audio_StreamRef_t le_voicecall_GetTxAudioStream(le_voicecall_CallRef_t reference)
le_voicecall_GetTerminationReason
le_result_t le_voicecall_GetTerminationReason(le_voicecall_CallRef_t reference, le_voicecall_TerminationReason_t *reasonPtr)
le_voicecall_ConnectService
void le_voicecall_ConnectService(void)
le_audio_interface.h
LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_voicecall_RemoveStateHandler
void le_voicecall_RemoveStateHandler(le_voicecall_StateHandlerRef_t handlerRef)
le_voicecall_DisconnectHandler_t
void(* le_voicecall_DisconnectHandler_t)(void *)
Definition: le_voicecall_interface.h:126
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_Answer
le_result_t le_voicecall_Answer(le_voicecall_CallRef_t reference)