le_mcc_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_mcc Modem Call Control
   14  *
   15  * @ref le_mcc_interface.h "API Reference"
   16  *
   17  * <HR>
   18  *
   19  * The Modem Call Control (mcc) API functions of this API are provided by the @b modemService
   20  * service.
   21  *
   22  * @section le_mcc_binding IPC interfaces binding
   23  *
   24  * Here's a code sample binding to modem services:
   25  * @verbatim
   26    bindings:
   27    {
   28       clientExe.clientComponent.le_mcc -> modemService.le_mcc
   29    }
   30    @endverbatim
   31  *
   32  * @section le_mcc_starting_a_call Starting a Call
   33  *
   34  * To initiate a call, create a new call object with a destination telephone
   35  * number calling the le_mcc_Create() function.
   36  *
   37  * le_mcc_Start() must still initiate the call when ready.
   38  *
   39  * The le_mcc_Start() function initiates a call attempt (it's asynchronous because it can take
   40  * time for a call to connect). If function failed, the le_mcc_GetTerminationReason() API can be
   41  * used to retrieve the terminal reason.
   42  *
   43  * It's essential to register a handler function to get the call events. Use
   44  * le_mcc_AddCallEventHandler() API to install that handler function. The handler will be
   45  * called for all calls' events (incoming and outgoing).
   46  *
   47  * The le_mcc_RemoveCallEventHandler() API uninstalls the handler function.
   48  *
   49  * The following APIs can be used to manage incoming or outgoing calls:
   50  * - le_mcc_GetTerminationReason() - termination reason.
   51  * - le_mcc_GetPlatformSpecificTerminationCode() - let you get the platform specific
   52  *   termination code by retrieving the termination code from @c le_mcc_CallRef_t.
   53  * Please refer to @ref platformConstraintsSpecificErrorCodes for platform specific
   54  * termination code description.
   55  *
   56  * - le_mcc_IsConnected() - connection status.
   57  * - le_mcc_GetRemoteTel() - displays remote party telephone number associated with the call.
   58  * - le_mcc_HangUp() will disconnect this call.
   59  *
   60  * When finished with the call object, call le_mcc_Delete() to free all the allocated resources
   61  * associated with the object.
   62  *
   63  * Multi-threading/multi-application behaviour: the callRef is linked to a specific client
   64  * (i.e. connection with the mcc service). Each client will have its own callRef for a same call.
   65  * That is, if a call event handler is registered by one thread but le_mcc_Create() is called by
   66  * another thread, they will each get different call references for the same call. So, when multiple
   67  * threads are being used to work with the same call, a comparison of the call references themselves
   68  * can't be used to tell whether or not they refer to the same call.
   69  *
   70  * The Adaptive Multi Rate (AMR) is an audio compression format optimized for speech coding and used
   71  * during a voice call. Two AMRs are supported:
   72  * An AMR Narrowband that encodes a bandwidth of 200--3400 Hz signals at variable bitrates ranging
   73  * from 4.75 to 12.2 kbit/s and an AMR Wideband that encodes a wider bandwidth of 50--7000 Hz and
   74  * thus improves the speech quality.
   75  *
   76  * le_mcc_SetAmrWbCapability() function enables or disables the AMR Wideband supported capability.
   77  * le_mcc_GetAmrWbCapability() function returns the AMR Wideband capability status.
   78  *
   79  * @section le_mcc_answering_a_call Answering a call
   80  *
   81  * Receiving calls is similar sending calls. Add a handler through le_mcc_AddCallEventHandler()
   82  * to be notified of incoming calls.
   83  *
   84  * To answer, call le_mcc_Answer(). To reject it, call le_mcc_HangUp().
   85  *
   86  *
   87  * @section le_mcc_ending_all_call Ending all calls
   88  *
   89  * A special function can be used to hang-up all the ongoing calls: le_mcc_HangUpAll().
   90  * This function can be used to hang-up any calls that have been initiated through another client
   91  * like AT commands.
   92  *
   93  *
   94  *
   95  * @section le_mcc_ss Supplementary service
   96  *
   97  * Calling Line Identification Restriction (CLIR) can be activated or deactivated by
   98  * le_mcc_SetCallerIdRestrict() API. The status is independent for each call object reference.
   99  * Status can be read with the le_mcc_GetCallerIdRestrict() API. If the status is not set,
  100  * le_mcc_GetCallerIdRestrict() API returns LE_UNAVAILABLE.
  101  * By default the CLIR status is not set.
  102  *
  103  * Call waiting supplementary service can be activated or deactivated by
  104  * le_mcc_SetCallWaitingService(). Its status can be given by le_mcc_GetCallWaitingService().
  105  * A call waiting can be answered using le_mcc_ActivateCall() API. This API is also used to
  106  * activate an on hold call (current call is then placed on hold).
  107  * An activated, waiting or on hold call can be released using le_mcc_HangUp() function.
  108  * See 3GPP TS 02.83 / 22.083 for any details concerning call waiting / call hold supplementary
  109  * services.
  110  *
  111  * @todo Other Supplementary services will be available in a future release. Create simpler examples.
  112  *
  113  *  @section le_mcc_samples Sample codes
  114  *
  115  * A sample code that implements a dialing call can be found in \b le_mccTest.c file (please refer
  116  * to @ref c_mccTest page).
  117  *
  118  *
  119  * <HR>
  120  *
  121  * Copyright (C) Sierra Wireless Inc.
  122  */
  123 /**
  124  * @file le_mcc_interface.h
  125  *
  126  * Legato @ref c_mcc include file.
  127  *
  128  * Copyright (C) Sierra Wireless Inc.
  129  */
  130 /**
  131  * @page c_mccTest Sample code of Modem Call control
  132  *
  133  * @include "apps/test/modemServices/mcc/mccIntegrationTest/mccTest/le_mccTest.c"
  134  */
  135 
  136 #ifndef LE_MCC_INTERFACE_H_INCLUDE_GUARD
  137 #define LE_MCC_INTERFACE_H_INCLUDE_GUARD
  138 
  139 
  140 #include "legato.h"
  141 
  142 // Interface specific includes
  143 #include "le_mdmDefs_interface.h"
  144 
  145 
  146 //--------------------------------------------------------------------------------------------------
  147 /**
  148  * Type for handler called when a server disconnects.
  149  */
  150 //--------------------------------------------------------------------------------------------------
  151 typedef void (*le_mcc_DisconnectHandler_t)(void *);
  152 
  153 //--------------------------------------------------------------------------------------------------
  154 /**
  155  *
  156  * Connect the current client thread to the service providing this API. Block until the service is
  157  * available.
  158  *
  159  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  160  * called before any other functions in this API.  Normally, ConnectService is automatically called
  161  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  162  *
  163  * This function is created automatically.
  164  */
  165 //--------------------------------------------------------------------------------------------------
  166 void le_mcc_ConnectService
  167 (
  168     void
  169 );
  170 
  171 //--------------------------------------------------------------------------------------------------
  172 /**
  173  *
  174  * Try to connect the current client thread to the service providing this API. Return with an error
  175  * if the service is not available.
  176  *
  177  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  178  * called before any other functions in this API.  Normally, ConnectService is automatically called
  179  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  180  *
  181  * This function is created automatically.
  182  *
  183  * @return
  184  *  - LE_OK if the client connected successfully to the service.
  185  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  186  *    bound.
  187  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  188  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  189  */
  190 //--------------------------------------------------------------------------------------------------
  191 le_result_t le_mcc_TryConnectService
  192 (
  193     void
  194 );
  195 
  196 //--------------------------------------------------------------------------------------------------
  197 /**
  198  * Set handler called when server disconnection is detected.
  199  *
  200  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  201  * to continue without exiting, it should call longjmp() from inside the handler.
  202  */
  203 //--------------------------------------------------------------------------------------------------
  204 void le_mcc_SetServerDisconnectHandler
  205 (
  206     le_mcc_DisconnectHandler_t disconnectHandler,
  207     void *contextPtr
  208 );
  209 
  210 //--------------------------------------------------------------------------------------------------
  211 /**
  212  *
  213  * Disconnect the current client thread from the service providing this API.
  214  *
  215  * Normally, this function doesn't need to be called. After this function is called, there's no
  216  * longer a connection to the service, and the functions in this API can't be used. For details, see
  217  * @ref apiFilesC_client.
  218  *
  219  * This function is created automatically.
  220  */
  221 //--------------------------------------------------------------------------------------------------
  222 void le_mcc_DisconnectService
  223 (
  224     void
  225 );
  226 
  227 
  228 //--------------------------------------------------------------------------------------------------
  229 /**
  230  *  Enumeration of the possible events that may be reported to a call event handler.
  231  */
  232 //--------------------------------------------------------------------------------------------------
  233 typedef enum
  234 {
  235     LE_MCC_EVENT_SETUP = 0,
  236         ///< Call is being set up.
  237     LE_MCC_EVENT_INCOMING = 1,
  238         ///< Incoming call attempt (new call).
  239     LE_MCC_EVENT_ORIGINATING = 2,
  240         ///< Outgoing call attempt.
  241     LE_MCC_EVENT_ALERTING = 3,
  242         ///< Far end is now alerting its user (outgoing call).
  243     LE_MCC_EVENT_CONNECTED = 4,
  244         ///< Call has been established, and is media is active.
  245     LE_MCC_EVENT_TERMINATED = 5,
  246         ///< Call has terminated.
  247     LE_MCC_EVENT_WAITING = 6,
  248         ///< Call is waiting
  249     LE_MCC_EVENT_ON_HOLD = 7,
  250         ///< Remote party has put the call on hold.
  251     LE_MCC_EVENT_MAX = 8
  252         ///< Enumerate max value.
  253 }
  254 le_mcc_Event_t;
  255 
  256 
  257 //--------------------------------------------------------------------------------------------------
  258 /**
  259  *  Enumeration of the possible reasons for call termination.
  260  */
  261 //--------------------------------------------------------------------------------------------------
  262 typedef enum
  263 {
  264     LE_MCC_TERM_LOCAL_ENDED = 0,
  265         ///< Local party ended the call (Normal Call Clearing).
  266     LE_MCC_TERM_REMOTE_ENDED = 1,
  267         ///< Remote party ended the call (Normal Call Clearing).
  268     LE_MCC_TERM_NETWORK_FAIL = 2,
  269         ///< Network could not complete the call.
  270     LE_MCC_TERM_UNASSIGNED_NUMBER = 3,
  271         ///< cf. 3GPP 24.008 Annex H
  272     LE_MCC_TERM_NO_ROUTE_TO_DESTINATION = 4,
  273         ///< cf. 3GPP 24.008 Annex H
  274     LE_MCC_TERM_CHANNEL_UNACCEPTABLE = 5,
  275         ///< cf. 3GPP 24.008 Annex H
  276     LE_MCC_TERM_OPERATOR_DETERMINED_BARRING = 6,
  277         ///< cf. 3GPP 24.008 Annex H
  278     LE_MCC_TERM_USER_BUSY = 7,
  279         ///< cf. 3GPP 24.008 Annex H
  280     LE_MCC_TERM_NO_USER_RESPONDING = 8,
  281         ///< cf. 3GPP 24.008 Annex H
  282     LE_MCC_TERM_USER_ALERTING_NO_ANSWER = 9,
  283         ///< cf. 3GPP 24.008 Annex H
  284     LE_MCC_TERM_CALL_REJECTED = 10,
  285         ///< cf. 3GPP 24.008 Annex H
  286     LE_MCC_TERM_NUMBER_CHANGED = 11,
  287         ///< cf. 3GPP 24.008 Annex H
  288     LE_MCC_TERM_PREEMPTION = 12,
  289         ///< cf. 3GPP 24.008 Annex H
  290     LE_MCC_TERM_DESTINATION_OUT_OF_ORDER = 13,
  291         ///< cf. 3GPP 24.008 Annex H
  292     LE_MCC_TERM_INVALID_NUMBER_FORMAT = 14,
  293         ///< cf. 3GPP 24.008 Annex H
  294     LE_MCC_TERM_FACILITY_REJECTED = 15,
  295         ///< cf. 3GPP 24.008 Annex H
  296     LE_MCC_TERM_RESP_TO_STATUS_ENQUIRY = 16,
  297         ///< cf. 3GPP 24.008 Annex H
  298     LE_MCC_TERM_NORMAL_UNSPECIFIED = 17,
  299         ///< cf. 3GPP 24.008 Annex H
  300     LE_MCC_TERM_NO_CIRCUIT_OR_CHANNEL_AVAILABLE = 18,
  301         ///< cf. 3GPP 24.008 Annex H
  302     LE_MCC_TERM_NETWORK_OUT_OF_ORDER = 19,
  303         ///< cf. 3GPP 24.008 Annex H
  304     LE_MCC_TERM_TEMPORARY_FAILURE = 20,
  305         ///< cf. 3GPP 24.008 Annex H
  306     LE_MCC_TERM_SWITCHING_EQUIPMENT_CONGESTION = 21,
  307         ///< cf. 3GPP 24.008 Annex H
  308     LE_MCC_TERM_ACCESS_INFORMATION_DISCARDED = 22,
  309         ///< cf. 3GPP 24.008 Annex H
  310     LE_MCC_TERM_REQUESTED_CIRCUIT_OR_CHANNEL_NOT_AVAILABLE = 23,
  311         ///< cf. 3GPP 24.008 Annex H
  312     LE_MCC_TERM_RESOURCES_UNAVAILABLE_OR_UNSPECIFIED = 24,
  313         ///< cf. 3GPP 24.008 Annex H
  314     LE_MCC_TERM_QOS_UNAVAILABLE = 25,
  315         ///< cf. 3GPP 24.008 Annex H
  316     LE_MCC_TERM_REQUESTED_FACILITY_NOT_SUBSCRIBED = 26,
  317         ///< cf. 3GPP 24.008 Annex H
  318     LE_MCC_TERM_INCOMING_CALLS_BARRED_WITHIN_CUG = 27,
  319         ///< cf. 3GPP 24.008 Annex H
  320     LE_MCC_TERM_BEARER_CAPABILITY_NOT_AUTH = 28,
  321         ///< cf. 3GPP 24.008 Annex H
  322     LE_MCC_TERM_BEARER_CAPABILITY_UNAVAILABLE = 29,
  323         ///< cf. 3GPP 24.008 Annex H
  324     LE_MCC_TERM_SERVICE_OPTION_NOT_AVAILABLE = 30,
  325         ///< cf. 3GPP 24.008 Annex H
  326     LE_MCC_TERM_ACM_LIMIT_EXCEEDED = 31,
  327         ///< cf. 3GPP 24.008 Annex H
  328     LE_MCC_TERM_BEARER_SERVICE_NOT_IMPLEMENTED = 32,
  329         ///< cf. 3GPP 24.008 Annex H
  330     LE_MCC_TERM_REQUESTED_FACILITY_NOT_IMPLEMENTED = 33,
  331         ///< cf. 3GPP 24.008 Annex H
  332     LE_MCC_TERM_ONLY_DIGITAL_INFORMATION_BEARER_AVAILABLE = 34,
  333         ///< cf. 3GPP 24.008 Annex H
  334     LE_MCC_TERM_SERVICE_OR_OPTION_NOT_IMPLEMENTED = 35,
  335         ///< cf. 3GPP 24.008 Annex H
  336     LE_MCC_TERM_INVALID_TRANSACTION_IDENTIFIER = 36,
  337         ///< cf. 3GPP 24.008 Annex H
  338     LE_MCC_TERM_USER_NOT_MEMBER_OF_CUG = 37,
  339         ///< cf. 3GPP 24.008 Annex H
  340     LE_MCC_TERM_INCOMPATIBLE_DESTINATION = 38,
  341         ///< cf. 3GPP 24.008 Annex H
  342     LE_MCC_TERM_INVALID_TRANSIT_NW_SELECTION = 39,
  343         ///< cf. 3GPP 24.008 Annex H
  344     LE_MCC_TERM_SEMANTICALLY_INCORRECT_MESSAGE = 40,
  345         ///< cf. 3GPP 24.008 Annex H
  346     LE_MCC_TERM_INVALID_MANDATORY_INFORMATION = 41,
  347         ///< cf. 3GPP 24.008 Annex H
  348     LE_MCC_TERM_MESSAGE_TYPE_NON_IMPLEMENTED = 42,
  349         ///< cf. 3GPP 24.008 Annex H
  350     LE_MCC_TERM_MESSAGE_TYPE_NOT_COMPATIBLE_WITH_PROTOCOL_STATE = 43,
  351         ///< cf. 3GPP 24.008 Annex H
  352     LE_MCC_TERM_INFORMATION_ELEMENT_NON_EXISTENT = 44,
  353         ///< cf. 3GPP 24.008 Annex H
  354     LE_MCC_TERM_CONDITONAL_IE_ERROR = 45,
  355         ///< cf. 3GPP 24.008 Annex H
  356     LE_MCC_TERM_MESSAGE_NOT_COMPATIBLE_WITH_PROTOCOL_STATE = 46,
  357         ///< cf. 3GPP 24.008 Annex H
  358     LE_MCC_TERM_RECOVERY_ON_TIMER_EXPIRY = 47,
  359         ///< cf. 3GPP 24.008 Annex H
  360     LE_MCC_TERM_PROTOCOL_ERROR_UNSPECIFIED = 48,
  361         ///< cf. 3GPP 24.008 Annex H
  362     LE_MCC_TERM_INTERWORKING_UNSPECIFIED = 49,
  363         ///< cf. 3GPP 24.008 Annex H
  364     LE_MCC_TERM_SERVICE_TEMPORARILY_OUT_OF_ORDER = 50,
  365         ///< cf. 3GPP 24.008 10.5.3.6
  366     LE_MCC_TERM_NOT_ALLOWED = 51,
  367         ///< Call operations not allowed
  368         ///<  (i.e. Radio off).
  369     LE_MCC_TERM_FDN_ACTIVE = 52,
  370         ///< FDN is active and number is not
  371         ///< in the FDN.
  372     LE_MCC_TERM_NO_SERVICE = 53,
  373         ///< No service or bad signal quality
  374     LE_MCC_TERM_PLATFORM_SPECIFIC = 54,
  375         ///< Platform specific code.
  376     LE_MCC_TERM_UNDEFINED = 55
  377         ///< Undefined reason.
  378 }
  379 le_mcc_TerminationReason_t;
  380 
  381 
  382 //--------------------------------------------------------------------------------------------------
  383 /**
  384  *  Reference type for managing active calls.
  385  */
  386 //--------------------------------------------------------------------------------------------------
  387 typedef struct le_mcc_Call* le_mcc_CallRef_t;
  388 
  389 
  390 //--------------------------------------------------------------------------------------------------
  391 /**
  392  * Reference type used by Add/Remove functions for EVENT 'le_mcc_CallEvent'
  393  */
  394 //--------------------------------------------------------------------------------------------------
  395 typedef struct le_mcc_CallEventHandler* le_mcc_CallEventHandlerRef_t;
  396 
  397 
  398 //--------------------------------------------------------------------------------------------------
  399 /**
  400  * Handler for call state changes.
  401  *
  402  * @note The callRef has to be deleted using le_mcc_Delete() when LE_MCC_TERMINATED event
  403  * is received, except if is has to be used for a future usage (with le_mcc_profile handler for
  404  * instance, or dialing again the same number).
  405  *
  406  */
  407 //--------------------------------------------------------------------------------------------------
  408 typedef void (*le_mcc_CallEventHandlerFunc_t)
  409 (
  410     le_mcc_CallRef_t callRef,
  411         ///< The call reference.
  412     le_mcc_Event_t event,
  413         ///< Call event.
  414     void* contextPtr
  415         ///<
  416 );
  417 
  418 //--------------------------------------------------------------------------------------------------
  419 /**
  420  * Create a call reference.
  421  *
  422  * @note Return NULL if call reference can't be created
  423  *
  424  * @note If destination number is too long (max LE_MDMDEFS_PHONE_NUM_MAX_LEN digits),
  425  * it is a fatal error, the function will not return.
  426  *
  427  */
  428 //--------------------------------------------------------------------------------------------------
  429 le_mcc_CallRef_t le_mcc_Create
  430 (
  431     const char* LE_NONNULL phoneNumPtr
  432         ///< [IN] The target number we are going to
  433         ///< call.
  434 );
  435 
  436 //--------------------------------------------------------------------------------------------------
  437 /**
  438  * Call to free up a call reference.
  439  *
  440  * @return
  441  *     - LE_OK        The function succeed.
  442  *     - LE_NOT_FOUND The call reference was not found.
  443  *     - LE_FAULT      The function failed.
  444  *
  445  *
  446  */
  447 //--------------------------------------------------------------------------------------------------
  448 le_result_t le_mcc_Delete
  449 (
  450     le_mcc_CallRef_t callRef
  451         ///< [IN] The call object to free.
  452 );
  453 
  454 //--------------------------------------------------------------------------------------------------
  455 /**
  456  * Start a call attempt.
  457  *
  458  * Asynchronous due to possible time to connect.
  459  *
  460  * As the call attempt proceeds, the profile's registered call event handler receives events.
  461  *
  462  * @return
  463  *      - LE_OK            Function succeed.
  464  *      - LE_BUSY          The call is already in progress
  465  *
  466  * * @note As this is an asynchronous call, a successful only confirms a call has been
  467  *       started. Don't assume a call has been successful yet.
  468  *
  469  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
  470  *       function will not return.
  471  */
  472 //--------------------------------------------------------------------------------------------------
  473 le_result_t le_mcc_Start
  474 (
  475     le_mcc_CallRef_t callRef
  476         ///< [IN] Reference to the call object.
  477 );
  478 
  479 //--------------------------------------------------------------------------------------------------
  480 /**
  481  * Allow the caller to know if the given call is actually connected or not.
  482  *
  483  * @return TRUE if the call is connected, FALSE otherwise.
  484  *
  485  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
  486  *       function will not return.
  487  */
  488 //--------------------------------------------------------------------------------------------------
  489 bool le_mcc_IsConnected
  490 (
  491     le_mcc_CallRef_t callRef
  492         ///< [IN] The call reference to read.
  493 );
  494 
  495 //--------------------------------------------------------------------------------------------------
  496 /**
  497  * Read out the remote party telephone number associated with the call.
  498  *
  499  * Output parameter is updated with the telephone number. If the Telephone number string length exceeds
  500  * the value of 'len' parameter, the LE_OVERFLOW error code is returned and 'telPtr' is used until
  501  * 'len-1' characters and a null-character is implicitly appended at the end of 'telPtr'.
  502  * Note that 'len' sould be at least equal to LE_MDMDEFS_PHONE_NUM_MAX_BYTES, otherwise LE_OVERFLOW
  503  * error code will be common.
  504  *
  505  * @return LE_OVERFLOW      The Telephone number length exceed the maximum length.
  506  * @return LE_OK            The function succeeded.
  507  *
  508  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
  509  *       function will not return.
  510  */
  511 //--------------------------------------------------------------------------------------------------
  512 le_result_t le_mcc_GetRemoteTel
  513 (
  514     le_mcc_CallRef_t callRef,
  515         ///< [IN]  The call reference to read from.
  516     char* telPtr,
  517         ///< [OUT] The telephone number string.
  518     size_t telPtrSize
  519         ///< [IN]
  520 );
  521 
  522 //--------------------------------------------------------------------------------------------------
  523 /**
  524  * Called to get the termination reason.
  525  *
  526  * @return The termination reason.
  527  *
  528  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
  529  *       function will not return.
  530  */
  531 //--------------------------------------------------------------------------------------------------
  532 le_mcc_TerminationReason_t le_mcc_GetTerminationReason
  533 (
  534     le_mcc_CallRef_t callRef
  535         ///< [IN] The call reference to read from.
  536 );
  537 
  538 //--------------------------------------------------------------------------------------------------
  539 /**
  540  * Called to get the platform specific termination code.
  541  *
  542  * Refer to @ref platformConstraintsSpecificErrorCodes for platform specific
  543  * termination code description.
  544  *
  545  * @return The platform specific termination code.
  546  *
  547  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
  548  *       function will not return.
  549  */
  550 //--------------------------------------------------------------------------------------------------
  551 int32_t le_mcc_GetPlatformSpecificTerminationCode
  552 (
  553     le_mcc_CallRef_t callRef
  554         ///< [IN] The call reference to read from.
  555 );
  556 
  557 //--------------------------------------------------------------------------------------------------
  558 /**
  559  *  Answers incoming call.
  560  *
  561  * @return LE_TIMEOUT       No response was received from the Modem.
  562  * @return LE_OK            The function succeeded.
  563  *
  564  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
  565  *       function will not return.
  566  * @note A call waiting call must be answered using SetCallActive() API. This API doesn't manage
  567  * call waiting supplementary service.
  568  */
  569 //--------------------------------------------------------------------------------------------------
  570 le_result_t le_mcc_Answer
  571 (
  572     le_mcc_CallRef_t callRef
  573         ///< [IN] The call reference.
  574 );
  575 
  576 //--------------------------------------------------------------------------------------------------
  577 /**
  578  * Disconnect, or hang up, the specifed call. Any active call handlers
  579  * will be notified.
  580  *
  581  * @return LE_FAULT         The function failed.
  582  * @return LE_TIMEOUT       No response was received from the Modem.
  583  * @return LE_OK            Function succeeded.
  584  *
  585  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
  586  *       function will not return.
  587  * @note this API can also be used to disconnect a waiting or on hold call.
  588  */
  589 //--------------------------------------------------------------------------------------------------
  590 le_result_t le_mcc_HangUp
  591 (
  592     le_mcc_CallRef_t callRef
  593         ///< [IN] The call to end.
  594 );
  595 
  596 //--------------------------------------------------------------------------------------------------
  597 /**
  598  * This function will disconnect, or hang up all the ongoing calls. Any active call handlers will
  599  * be notified.
  600  *
  601  * @return LE_FAULT         The function failed.
  602  * @return LE_TIMEOUT       No response was received from the Modem.
  603  * @return LE_OK            The function succeeded.
  604  */
  605 //--------------------------------------------------------------------------------------------------
  606 le_result_t le_mcc_HangUpAll
  607 (
  608     void
  609 );
  610 
  611 //--------------------------------------------------------------------------------------------------
  612 /**
  613  * This function return the Calling Line Identification Restriction (CLIR) status on the specific
  614  *  call.
  615  *
  616  * The output parameter is updated with the CLIR status.
  617  *    - LE_ON  Disable presentation of own phone number to remote.
  618  *    - LE_OFF Enable presentation of own phone number to remote.
  619  *
  620  * @return
  621  *    - LE_OK          The function succeed.
  622  *    - LE_NOT_FOUND   The call reference was not found.
  623  *    - LE_UNAVAILABLE CLIR status was not set.
  624  */
  625 //--------------------------------------------------------------------------------------------------
  626 le_result_t le_mcc_GetCallerIdRestrict
  627 (
  628     le_mcc_CallRef_t callRef,
  629         ///< [IN] The call reference.
  630     le_onoff_t* clirStatusPtrPtr
  631         ///< [OUT] the Calling Line Identification Restriction (CLIR) status
  632 );
  633 
  634 //--------------------------------------------------------------------------------------------------
  635 /**
  636  * This function set the Calling Line Identification Restriction (CLIR) status on the specific call.
  637  * By default the CLIR status is not set.
  638  *
  639  * @return
  640  *     - LE_OK        The function succeed.
  641  *     - LE_NOT_FOUND The call reference was not found.
  642  *
  643  */
  644 //--------------------------------------------------------------------------------------------------
  645 le_result_t le_mcc_SetCallerIdRestrict
  646 (
  647     le_mcc_CallRef_t callRef,
  648         ///< [IN] The call reference.
  649     le_onoff_t clirStatus
  650         ///< [IN] The Calling Line Identification Restriction (CLIR) status.
  651 );
  652 
  653 //--------------------------------------------------------------------------------------------------
  654 /**
  655  * Add handler function for EVENT 'le_mcc_CallEvent'
  656  *
  657  * Register an event handler that will be notified when an call's event occurs.
  658  *
  659  * @return A reference to the new event handler object.
  660  *
  661  * @note It is a fatal error if this function does succeed.  If this function fails, it will not
  662  *       return.
  663  *
  664  */
  665 //--------------------------------------------------------------------------------------------------
  666 le_mcc_CallEventHandlerRef_t le_mcc_AddCallEventHandler
  667 (
  668     le_mcc_CallEventHandlerFunc_t handlerPtr,
  669         ///< [IN]
  670     void* contextPtr
  671         ///< [IN]
  672 );
  673 
  674 //--------------------------------------------------------------------------------------------------
  675 /**
  676  * Remove handler function for EVENT 'le_mcc_CallEvent'
  677  */
  678 //--------------------------------------------------------------------------------------------------
  679 void le_mcc_RemoveCallEventHandler
  680 (
  681     le_mcc_CallEventHandlerRef_t handlerRef
  682         ///< [IN]
  683 );
  684 
  685 //--------------------------------------------------------------------------------------------------
  686 /**
  687  * This function activates or deactivates the call waiting service.
  688  *
  689  * @return
  690  *     - LE_OK        The function succeed.
  691  *     - LE_FAULT     The function failed.
  692  *
  693  */
  694 //--------------------------------------------------------------------------------------------------
  695 le_result_t le_mcc_SetCallWaitingService
  696 (
  697     bool active
  698         ///< [IN] The call waiting activation.
  699 );
  700 
  701 //--------------------------------------------------------------------------------------------------
  702 /**
  703  * This function gets the call waiting service status.
  704  *
  705  * @return
  706  *     - LE_OK        The function succeed.
  707  *     - LE_FAULT     The function failed.
  708  *
  709  */
  710 //--------------------------------------------------------------------------------------------------
  711 le_result_t le_mcc_GetCallWaitingService
  712 (
  713     bool* activePtr
  714         ///< [OUT] The call waiting activation.
  715 );
  716 
  717 //--------------------------------------------------------------------------------------------------
  718 /**
  719  * This function activates the specified call. Other calls are placed on hold.
  720  *
  721  * @return
  722  *     - LE_OK        The function succeed.
  723  *     - LE_FAULT     The function failed.
  724  *
  725  */
  726 //--------------------------------------------------------------------------------------------------
  727 le_result_t le_mcc_ActivateCall
  728 (
  729     le_mcc_CallRef_t callRef
  730         ///< [IN] The call reference.
  731 );
  732 
  733 //--------------------------------------------------------------------------------------------------
  734 /**
  735  * This function enables/disables the audio AMR Wideband capability.
  736  *
  737  * @return
  738  *     -  LE_OK             The function succeeded.
  739  *     -  LE_UNAVAILABLE    The service is not available.
  740  *     -  LE_FAULT          On any other failure.
  741  *
  742  * @note The capability setting takes effect immediately and is not persistent to reset.
  743  */
  744 //--------------------------------------------------------------------------------------------------
  745 le_result_t le_mcc_SetAmrWbCapability
  746 (
  747     bool enable
  748         ///< [IN] True enables the AMR Wideband capability, false disables it.
  749 );
  750 
  751 //--------------------------------------------------------------------------------------------------
  752 /**
  753  * This function gets the audio AMR Wideband capability.
  754  *
  755  * @return
  756  *     - LE_OK            The function succeeded.
  757  *     - LE_UNAVAILABLE   The service is not available.
  758  *     - LE_FAULT         On any other failure.
  759  */
  760 //--------------------------------------------------------------------------------------------------
  761 le_result_t le_mcc_GetAmrWbCapability
  762 (
  763     bool* enabledPtr
  764         ///< [OUT] True if AMR Wideband capability is enabled, false otherwise.
  765 );
  766 
  767 #endif // LE_MCC_INTERFACE_H_INCLUDE_GUARD
LE_MCC_EVENT_ORIGINATING
Outgoing call attempt. 
Definition: le_mcc_interface.h:239
le_mdmDefs_interface.h
le_mcc_ConnectService
void le_mcc_ConnectService(void)
le_mcc_GetCallerIdRestrict
le_result_t le_mcc_GetCallerIdRestrict(le_mcc_CallRef_t callRef, le_onoff_t *clirStatusPtrPtr)
LE_MCC_TERM_PROTOCOL_ERROR_UNSPECIFIED
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:360
le_mcc_ActivateCall
le_result_t le_mcc_ActivateCall(le_mcc_CallRef_t callRef)
LE_MCC_TERM_DESTINATION_OUT_OF_ORDER
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:290
LE_MCC_TERM_USER_NOT_MEMBER_OF_CUG
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:338
LE_MCC_EVENT_ON_HOLD
Remote party has put the call on hold. 
Definition: le_mcc_interface.h:249
LE_MCC_TERM_NO_ROUTE_TO_DESTINATION
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:272
LE_MCC_TERM_UNDEFINED
Undefined reason. 
Definition: le_mcc_interface.h:376
LE_MCC_TERM_USER_BUSY
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:278
LE_MCC_TERM_CALL_REJECTED
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:284
LE_MCC_TERM_REQUESTED_FACILITY_NOT_SUBSCRIBED
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:316
le_result_t
le_result_t
Definition: le_basics.h:35
LE_MCC_TERM_UNASSIGNED_NUMBER
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:270
LE_MCC_TERM_INVALID_TRANSIT_NW_SELECTION
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:342
LE_MCC_EVENT_TERMINATED
Call has terminated. 
Definition: le_mcc_interface.h:245
le_mcc_AddCallEventHandler
le_mcc_CallEventHandlerRef_t le_mcc_AddCallEventHandler(le_mcc_CallEventHandlerFunc_t handlerPtr, void *contextPtr)
LE_MCC_TERM_RECOVERY_ON_TIMER_EXPIRY
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:358
le_mcc_TerminationReason_t
le_mcc_TerminationReason_t
Definition: le_mcc_interface.h:262
LE_MCC_TERM_BEARER_CAPABILITY_UNAVAILABLE
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:322
le_mcc_CallRef_t
struct le_mcc_Call * le_mcc_CallRef_t
Definition: le_mcc_interface.h:387
LE_MCC_TERM_REMOTE_ENDED
Remote party ended the call (Normal Call Clearing). 
Definition: le_mcc_interface.h:266
LE_MCC_TERM_NORMAL_UNSPECIFIED
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:298
LE_MCC_TERM_PLATFORM_SPECIFIC
Platform specific code. 
Definition: le_mcc_interface.h:374
le_mcc_GetCallWaitingService
le_result_t le_mcc_GetCallWaitingService(bool *activePtr)
LE_MCC_TERM_NUMBER_CHANGED
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:286
LE_MCC_EVENT_ALERTING
Far end is now alerting its user (outgoing call). 
Definition: le_mcc_interface.h:241
LE_MCC_TERM_INVALID_TRANSACTION_IDENTIFIER
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:336
LE_MCC_EVENT_MAX
Enumerate max value. 
Definition: le_mcc_interface.h:251
le_mcc_TryConnectService
le_result_t le_mcc_TryConnectService(void)
le_mcc_Create
le_mcc_CallRef_t le_mcc_Create(const char *LE_NONNULL phoneNumPtr)
LE_MCC_TERM_NETWORK_OUT_OF_ORDER
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:302
LE_MCC_TERM_INCOMPATIBLE_DESTINATION
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:340
le_mcc_Delete
le_result_t le_mcc_Delete(le_mcc_CallRef_t callRef)
LE_MCC_TERM_ONLY_DIGITAL_INFORMATION_BEARER_AVAILABLE
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:332
LE_MCC_TERM_INVALID_MANDATORY_INFORMATION
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:346
LE_MCC_EVENT_INCOMING
Incoming call attempt (new call). 
Definition: le_mcc_interface.h:237
le_mcc_SetCallWaitingService
le_result_t le_mcc_SetCallWaitingService(bool active)
LE_MCC_TERM_OPERATOR_DETERMINED_BARRING
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:276
le_mcc_DisconnectService
void le_mcc_DisconnectService(void)
LE_MCC_TERM_LOCAL_ENDED
Local party ended the call (Normal Call Clearing). 
Definition: le_mcc_interface.h:264
le_mcc_HangUpAll
le_result_t le_mcc_HangUpAll(void)
le_mcc_GetPlatformSpecificTerminationCode
int32_t le_mcc_GetPlatformSpecificTerminationCode(le_mcc_CallRef_t callRef)
LE_MCC_TERM_ACM_LIMIT_EXCEEDED
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:326
LE_MCC_TERM_PREEMPTION
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:288
LE_MCC_TERM_INFORMATION_ELEMENT_NON_EXISTENT
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:352
le_mcc_CallEventHandlerFunc_t
void(* le_mcc_CallEventHandlerFunc_t)(le_mcc_CallRef_t callRef, le_mcc_Event_t event, void *contextPtr)
Definition: le_mcc_interface.h:409
le_mcc_Start
le_result_t le_mcc_Start(le_mcc_CallRef_t callRef)
LE_MCC_TERM_MESSAGE_TYPE_NOT_COMPATIBLE_WITH_PROTOCOL_STATE
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:350
LE_MCC_TERM_NETWORK_FAIL
Network could not complete the call. 
Definition: le_mcc_interface.h:268
LE_MCC_TERM_NO_SERVICE
No service or bad signal quality. 
Definition: le_mcc_interface.h:372
LE_MCC_TERM_INVALID_NUMBER_FORMAT
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:292
LE_MCC_TERM_FDN_ACTIVE
Definition: le_mcc_interface.h:369
LE_MCC_TERM_NO_USER_RESPONDING
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:280
LE_MCC_TERM_CONDITONAL_IE_ERROR
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:354
le_mcc_GetAmrWbCapability
le_result_t le_mcc_GetAmrWbCapability(bool *enabledPtr)
LE_MCC_TERM_MESSAGE_TYPE_NON_IMPLEMENTED
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:348
le_mcc_IsConnected
bool le_mcc_IsConnected(le_mcc_CallRef_t callRef)
le_mcc_SetAmrWbCapability
le_result_t le_mcc_SetAmrWbCapability(bool enable)
le_mcc_CallEventHandlerRef_t
struct le_mcc_CallEventHandler * le_mcc_CallEventHandlerRef_t
Definition: le_mcc_interface.h:395
LE_MCC_TERM_FACILITY_REJECTED
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:294
LE_MCC_TERM_INTERWORKING_UNSPECIFIED
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:362
LE_MCC_TERM_RESP_TO_STATUS_ENQUIRY
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:296
LE_MCC_TERM_MESSAGE_NOT_COMPATIBLE_WITH_PROTOCOL_STATE
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:356
LE_MCC_TERM_ACCESS_INFORMATION_DISCARDED
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:308
LE_MCC_TERM_REQUESTED_CIRCUIT_OR_CHANNEL_NOT_AVAILABLE
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:310
LE_MCC_EVENT_WAITING
Call is waiting. 
Definition: le_mcc_interface.h:247
LE_MCC_TERM_SEMANTICALLY_INCORRECT_MESSAGE
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:344
le_mcc_RemoveCallEventHandler
void le_mcc_RemoveCallEventHandler(le_mcc_CallEventHandlerRef_t handlerRef)
le_mcc_Event_t
le_mcc_Event_t
Definition: le_mcc_interface.h:233
legato.h
LE_MCC_EVENT_CONNECTED
Call has been established, and is media is active. 
Definition: le_mcc_interface.h:243
le_mcc_HangUp
le_result_t le_mcc_HangUp(le_mcc_CallRef_t callRef)
LE_MCC_TERM_SERVICE_OR_OPTION_NOT_IMPLEMENTED
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:334
LE_MCC_TERM_BEARER_SERVICE_NOT_IMPLEMENTED
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:328
LE_MCC_TERM_SWITCHING_EQUIPMENT_CONGESTION
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:306
LE_MCC_TERM_USER_ALERTING_NO_ANSWER
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:282
le_mcc_GetTerminationReason
le_mcc_TerminationReason_t le_mcc_GetTerminationReason(le_mcc_CallRef_t callRef)
LE_MCC_TERM_REQUESTED_FACILITY_NOT_IMPLEMENTED
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:330
LE_MCC_EVENT_SETUP
Call is being set up. 
Definition: le_mcc_interface.h:235
LE_MCC_TERM_TEMPORARY_FAILURE
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:304
le_mcc_Answer
le_result_t le_mcc_Answer(le_mcc_CallRef_t callRef)
LE_MCC_TERM_NOT_ALLOWED
Definition: le_mcc_interface.h:366
LE_MCC_TERM_QOS_UNAVAILABLE
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:314
le_mcc_GetRemoteTel
le_result_t le_mcc_GetRemoteTel(le_mcc_CallRef_t callRef, char *telPtr, size_t telPtrSize)
LE_MCC_TERM_SERVICE_TEMPORARILY_OUT_OF_ORDER
cf. 3GPP 24.008 10.5.3.6 
Definition: le_mcc_interface.h:364
LE_MCC_TERM_INCOMING_CALLS_BARRED_WITHIN_CUG
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:318
LE_MCC_TERM_BEARER_CAPABILITY_NOT_AUTH
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:320
le_mcc_SetServerDisconnectHandler
void le_mcc_SetServerDisconnectHandler(le_mcc_DisconnectHandler_t disconnectHandler, void *contextPtr)
LE_MCC_TERM_SERVICE_OPTION_NOT_AVAILABLE
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:324
LE_MCC_TERM_RESOURCES_UNAVAILABLE_OR_UNSPECIFIED
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:312
le_mcc_SetCallerIdRestrict
le_result_t le_mcc_SetCallerIdRestrict(le_mcc_CallRef_t callRef, le_onoff_t clirStatus)
LE_MCC_TERM_CHANNEL_UNACCEPTABLE
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:274
LE_MCC_TERM_NO_CIRCUIT_OR_CHANNEL_AVAILABLE
cf. 3GPP 24.008 Annex H 
Definition: le_mcc_interface.h:300
le_mcc_DisconnectHandler_t
void(* le_mcc_DisconnectHandler_t)(void *)
Definition: le_mcc_interface.h:151
le_onoff_t
le_onoff_t
Definition: le_basics.h:70