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 /** @addtogroup le_voicecall le_voicecall API Reference
  122  * @{
  123  * @file le_voicecall_common.h
  124  * @file le_voicecall_interface.h **/
  125 //--------------------------------------------------------------------------------------------------
  126 /**
  127  * Type for handler called when a server disconnects.
  128  */
  129 //--------------------------------------------------------------------------------------------------
  130 typedef void (*le_voicecall_DisconnectHandler_t)(void *);
  131 
  132 //--------------------------------------------------------------------------------------------------
  133 /**
  134  *
  135  * Connect the current client thread to the service providing this API. Block until the service is
  136  * available.
  137  *
  138  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  139  * called before any other functions in this API.  Normally, ConnectService is automatically called
  140  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  141  *
  142  * This function is created automatically.
  143  */
  144 //--------------------------------------------------------------------------------------------------
  145 void le_voicecall_ConnectService
  146 (
  147     void
  148 );
  149 
  150 //--------------------------------------------------------------------------------------------------
  151 /**
  152  *
  153  * Try to connect the current client thread to the service providing this API. Return with an error
  154  * if the service is not available.
  155  *
  156  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  157  * called before any other functions in this API.  Normally, ConnectService is automatically called
  158  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  159  *
  160  * This function is created automatically.
  161  *
  162  * @return
  163  *  - LE_OK if the client connected successfully to the service.
  164  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  165  *    bound.
  166  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  167  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  168  */
  169 //--------------------------------------------------------------------------------------------------
  170 le_result_t le_voicecall_TryConnectService
  171 (
  172     void
  173 );
  174 
  175 //--------------------------------------------------------------------------------------------------
  176 /**
  177  * Set handler called when server disconnection is detected.
  178  *
  179  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  180  * to continue without exiting, it should call longjmp() from inside the handler.
  181  */
  182 //--------------------------------------------------------------------------------------------------
  183 LE_FULL_API void le_voicecall_SetServerDisconnectHandler
  184 (
  185     le_voicecall_DisconnectHandler_t disconnectHandler,
  186     void *contextPtr
  187 );
  188 
  189 //--------------------------------------------------------------------------------------------------
  190 /**
  191  *
  192  * Disconnect the current client thread from the service providing this API.
  193  *
  194  * Normally, this function doesn't need to be called. After this function is called, there's no
  195  * longer a connection to the service, and the functions in this API can't be used. For details, see
  196  * @ref apiFilesC_client.
  197  *
  198  * This function is created automatically.
  199  */
  200 //--------------------------------------------------------------------------------------------------
  201 void le_voicecall_DisconnectService
  202 (
  203     void
  204 );
  205 
  206 
  207 //--------------------------------------------------------------------------------------------------
  208 /**
  209  * Reference returned by Start function and used by End function
  210  */
  211 //--------------------------------------------------------------------------------------------------
  212 
  213 
  214 //--------------------------------------------------------------------------------------------------
  215 /**
  216  * Voice call establishment states.
  217  */
  218 //--------------------------------------------------------------------------------------------------
  219 
  220 
  221 //--------------------------------------------------------------------------------------------------
  222 /**
  223  * Voice call termination reason.
  224  */
  225 //--------------------------------------------------------------------------------------------------
  226 
  227 
  228 //--------------------------------------------------------------------------------------------------
  229 /**
  230  * Handler for voice call state changes.
  231  */
  232 //--------------------------------------------------------------------------------------------------
  233 
  234 
  235 //--------------------------------------------------------------------------------------------------
  236 /**
  237  * Reference type used by Add/Remove functions for EVENT 'le_voicecall_State'
  238  */
  239 //--------------------------------------------------------------------------------------------------
  240 
  241 
  242 //--------------------------------------------------------------------------------------------------
  243 /**
  244  * Add handler function for EVENT 'le_voicecall_State'
  245  *
  246  * This event provides information on voice call state changes
  247  *
  248  */
  249 //--------------------------------------------------------------------------------------------------
  250 le_voicecall_StateHandlerRef_t le_voicecall_AddStateHandler
  251 (
  252     le_voicecall_StateHandlerFunc_t handlerPtr,
  253         ///< [IN]
  254     void* contextPtr
  255         ///< [IN]
  256 );
  257 
  258 //--------------------------------------------------------------------------------------------------
  259 /**
  260  * Remove handler function for EVENT 'le_voicecall_State'
  261  */
  262 //--------------------------------------------------------------------------------------------------
  263 void le_voicecall_RemoveStateHandler
  264 (
  265     le_voicecall_StateHandlerRef_t handlerRef
  266         ///< [IN]
  267 );
  268 
  269 //--------------------------------------------------------------------------------------------------
  270 /**
  271  * Start a voice call.
  272  *
  273  * @return
  274  *      - Reference to the voice call (to be used later for releasing the voice call)
  275  *      - NULL if the voice call could not be processed
  276  */
  277 //--------------------------------------------------------------------------------------------------
  278 le_voicecall_CallRef_t le_voicecall_Start
  279 (
  280     const char* LE_NONNULL DestinationID
  281         ///< [IN] Destination identifier for the voice
  282         ///< call establishment.
  283 );
  284 
  285 //--------------------------------------------------------------------------------------------------
  286 /**
  287  * Release a voice call.
  288  *
  289  * @return
  290  *      - LE_OK if the end of voice call can be processed.
  291  *      - LE_NOT_FOUND if the voice call object reference is not found.
  292  */
  293 //--------------------------------------------------------------------------------------------------
  294 le_result_t le_voicecall_End
  295 (
  296     le_voicecall_CallRef_t reference
  297         ///< [IN] Voice call object reference to hang-up.
  298 );
  299 
  300 //--------------------------------------------------------------------------------------------------
  301 /**
  302  * Delete voice call object reference create by le_voicecall_Start() or an incoming voice call.
  303  *
  304  * @return
  305  *      - LE_OK if the delete of voice call can be processed.
  306  *      - LE_FAULT if the voice call is not terminated.
  307  *      - LE_NOT_FOUND if the voice call object reference is not found.
  308  */
  309 //--------------------------------------------------------------------------------------------------
  310 le_result_t le_voicecall_Delete
  311 (
  312     le_voicecall_CallRef_t reference
  313         ///< [IN] Voice call object reference to delete.
  314 );
  315 
  316 //--------------------------------------------------------------------------------------------------
  317 /**
  318  * Answer to incoming voice call.
  319  *
  320  * @return
  321  *      - LE_OK if the incoming voice call can be answered
  322  *      - LE_NOT_FOUND if the incoming voice call object reference is not found.
  323  */
  324 //--------------------------------------------------------------------------------------------------
  325 le_result_t le_voicecall_Answer
  326 (
  327     le_voicecall_CallRef_t reference
  328         ///< [IN] Incoming voice call object reference to answer.
  329 );
  330 
  331 //--------------------------------------------------------------------------------------------------
  332 /**
  333  * Get the termination reason of a voice call reference.
  334  *
  335  * @return
  336  *      - LE_OK if the termination reason is got
  337  *      - LE_NOT_FOUND if the incoming voice call object reference is not found.
  338  *      - LE_FAULT if the voice call is not terminated.
  339  */
  340 //--------------------------------------------------------------------------------------------------
  341 le_result_t le_voicecall_GetTerminationReason
  342 (
  343     le_voicecall_CallRef_t reference,
  344         ///< [IN] Voice call object reference to read from.
  345     le_voicecall_TerminationReason_t* reasonPtr
  346         ///< [OUT] Termination reason of the voice call.
  347 );
  348 
  349 //--------------------------------------------------------------------------------------------------
  350 /**
  351  * Called to get the transmitted audio stream. All audio generated on this
  352  * end of the call is sent on this stream.
  353  *
  354  * @return Transmitted audio stream reference.
  355  */
  356 //--------------------------------------------------------------------------------------------------
  357 le_audio_StreamRef_t le_voicecall_GetTxAudioStream
  358 (
  359     le_voicecall_CallRef_t reference
  360         ///< [IN] Voice call object reference to read from.
  361 );
  362 
  363 //--------------------------------------------------------------------------------------------------
  364 /**
  365  * Called to get the received audio stream. All audio received from the
  366  * other end of the call is received on this stream.
  367  *
  368  * @return Received audio stream reference.
  369  */
  370 //--------------------------------------------------------------------------------------------------
  371 le_audio_StreamRef_t le_voicecall_GetRxAudioStream
  372 (
  373     le_voicecall_CallRef_t reference
  374         ///< [IN] Voice call object reference to read from.
  375 );
  376 
  377 /** @} **/
  378 
  379 #endif // LE_VOICECALL_INTERFACE_H_INCLUDE_GUARD
le_voicecall_TryConnectService
le_result_t le_voicecall_TryConnectService(void)
le_mdmDefs_interface.h
le_voicecall_GetRxAudioStream
le_audio_StreamRef_t le_voicecall_GetRxAudioStream(le_voicecall_CallRef_t reference)
le_voicecall_TerminationReason_t
le_voicecall_TerminationReason_t
Definition: le_voicecall_common.h:75
le_result_t
le_result_t
Definition: le_basics.h:46
le_voicecall_Delete
le_result_t le_voicecall_Delete(le_voicecall_CallRef_t reference)
le_voicecall_Start
le_voicecall_CallRef_t le_voicecall_Start(const char *LE_NONNULL DestinationID)
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_common.h:107
le_voicecall_AddStateHandler
le_voicecall_StateHandlerRef_t le_voicecall_AddStateHandler(le_voicecall_StateHandlerFunc_t handlerPtr, void *contextPtr)
le_voicecall_GetTxAudioStream
le_audio_StreamRef_t le_voicecall_GetTxAudioStream(le_voicecall_CallRef_t reference)
le_voicecall_Answer
le_result_t le_voicecall_Answer(le_voicecall_CallRef_t reference)
le_voicecall_DisconnectService
void le_voicecall_DisconnectService(void)
le_audio_interface.h
le_voicecall_RemoveStateHandler
void le_voicecall_RemoveStateHandler(le_voicecall_StateHandlerRef_t handlerRef)
le_voicecall_GetTerminationReason
le_result_t le_voicecall_GetTerminationReason(le_voicecall_CallRef_t reference, le_voicecall_TerminationReason_t *reasonPtr)
LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40
legato.h
le_audio_StreamRef_t
struct le_audio_Stream * le_audio_StreamRef_t
Definition: le_audio_common.h:191
le_voicecall_DisconnectHandler_t
void(* le_voicecall_DisconnectHandler_t)(void *)
Definition: le_voicecall_interface.h:130
le_voicecall_CallRef_t
struct le_voicecall_Call * le_voicecall_CallRef_t
Definition: le_voicecall_common.h:37
le_voicecall_ConnectService
void le_voicecall_ConnectService(void)
le_voicecall_common.h
le_voicecall_SetServerDisconnectHandler
LE_FULL_API void le_voicecall_SetServerDisconnectHandler(le_voicecall_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_voicecall_End
le_result_t le_voicecall_End(le_voicecall_CallRef_t reference)
le_voicecall_StateHandlerRef_t
struct le_voicecall_StateHandler * le_voicecall_StateHandlerRef_t
Definition: le_voicecall_common.h:98