lib: lte_lc: deprecate LTE_LC_ON_CFUN

Deprecate LTE_LC_ON_CFUN. The application should instead use the
NRF_MODEM_LIB_ON_CFUN macro.

Signed-off-by: Eivind Jølsgard <[email protected]>

doc/nrf/libraries/modem/lte_lc.rst

@@ -184,40 +184,6 @@ To enable modem sleep and TAU pre-warning notifications, enable the following op
 
 For additional configurations related to these features, see the API documentation.
 
-Functional mode changes callback
-================================
-
-The library allows the application to define compile-time callbacks to receive the modem's functional mode changes.
-These callbacks allow any part of the application to perform certain operations when the modem enters or re-enters a certain functional mode using the library :c:func:`lte_lc_func_mode_set` API.
-For example, one kind of operation that the application or a library may need to perform and repeat, whenever the modem enters a certain functional mode is the subscription to AT notifications.
-The application can set up a callback for modem`s functional mode changes using the :c:macro:`LTE_LC_ON_CFUN` macro.
-
-.. important::
-   When the :c:macro:`LTE_LC_ON_CFUN` macro is used, the application must not call :c:func:`nrf_modem_at_cfun_handler_set` as that will override the handler set by the modem library integration layer.
-
-.. note::
-   The CFUN callback is not supported with :c:func:`nrf_modem_at_cmd_async`.
-
-The following code snippet shows how to use the :c:macro:`LTE_LC_ON_CFUN` macro:
-
-.. code-block:: c
-
-   /* Define a callback */
-   LTE_LC_ON_CFUN(cfun_hook, on_cfun, NULL);
-
-   /* Callback implementation */
-   static void on_cfun(enum lte_lc_func_mode mode, void *context)
-   {
-           printk("Functional mode changed to %d\n", mode);
-   }
-
-   int main(void)
-   {
-           /* Change functional mode using the LTE link control API */
-           lte_lc_func_mode_set(LTE_LC_FUNC_MODE_NORMAL);
-           return 0;
-   }
-
 Dependencies
 ************
 

doc/nrf/libraries/modem/nrf_modem_lib/nrf_modem_lib_wrapper.rst

@@ -40,7 +40,7 @@ The result of the initialization and the callback context are provided to these
   The callback can be used to perform modem and library configurations that require the modem to be turned on in offline mode.
   The callback cannot be used to change the modem's functional mode.
   Calls to :c:func:`lte_lc_connect` and ``CFUN`` AT calls are not allowed, and must be done after :c:func:`nrf_modem_lib_init` has returned.
-  If a library needs to perform operations after the link is up, it can use the :ref:`lte_lc_readme` and subscribe to a :c:macro:`LTE_LC_ON_CFUN` callback.
+  If a library needs to perform operations after the link is up, it can use the :c:macro:`NRF_MODEM_LIB_ON_CFUN` callback.
 
 Callbacks for the macro :c:macro:`NRF_MODEM_LIB_ON_INIT` must have the signature ``void callback_name(int ret, void *ctx)``, where ``ret`` is the result of the initialization and ``ctx`` is the context passed to the macro.
 The callbacks registered using the :c:macro:`NRF_MODEM_LIB_ON_SHUTDOWN` macro are executed before the library is shut down.

doc/nrf/releases_and_maturity/migration/migration_guide_2.8.rst

@@ -109,6 +109,7 @@ LTE link control library
      * Replace the use of the :c:func:`lte_lc_deinit` function with the :c:func:`lte_lc_power_off` function.
      * Replace the use of the :c:func:`lte_lc_init_and_connect` function with the :c:func:`lte_lc_connect` function.
      * Replace the use of the :c:func:`lte_lc_init_and_connect_async` function with the :c:func:`lte_lc_connect_async` function.
+     * Replace the use of the :c:macro:`LTE_LC_ON_CFUN` macro with the :c:macro:`NRF_MODEM_LIB_ON_CFUN` macro.
      * Remove the use of the ``CONFIG_LTE_NETWORK_USE_FALLBACK`` Kconfig option.
        Use the :kconfig:option:`CONFIG_LTE_NETWORK_MODE_LTE_M_NBIOT` or :kconfig:option:`CONFIG_LTE_NETWORK_MODE_LTE_M_NBIOT_GPS` Kconfig option instead.
        In addition, you can control the priority between LTE-M and NB-IoT using the :kconfig:option:`CONFIG_LTE_MODE_PREFERENCE` Kconfig option.

doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst

@@ -718,6 +718,11 @@ Modem libraries
       Use the :kconfig:option:`CONFIG_LTE_NETWORK_MODE_LTE_M_NBIOT` or :kconfig:option:`CONFIG_LTE_NETWORK_MODE_LTE_M_NBIOT_GPS` Kconfig option instead.
       In addition, you can control the priority between LTE-M and NB-IoT using the :kconfig:option:`CONFIG_LTE_MODE_PREFERENCE` Kconfig option.
 
+  * Deprecated:
+
+    * The :c:macro:`LTE_LC_ON_CFUN` macro.
+      Use the :c:macro:`NRF_MODEM_LIB_ON_CFUN` macro instead.
+
   * Added:
 
     * A new :c:enum:`LTE_LC_EVT_RAI_UPDATE` event that is enabled with the :kconfig:option:`CONFIG_LTE_RAI_REQ` Kconfig option.

include/modem/lte_lc.h

@@ -1178,6 +1178,8 @@ struct lte_lc_cfun_cb {
  * @param name Callback name.
  * @param _callback Callback function.
  * @param _context User-defined context.
+ *
+ * @deprecated since v2.8.0, use @ref NRF_MODEM_LIB_ON_CFUN instead.
  */
 #define LTE_LC_ON_CFUN(name, _callback, _context)                                                  \
 	static void _callback(enum lte_lc_func_mode, void *ctx);                                   \

include/modem/nrf_modem_lib.h

@@ -166,8 +166,7 @@ struct nrf_modem_lib_at_cfun_cb {
  * configurations that require the modem to be turned on in offline mode. It cannot be used to
  * change the modem functional mode. Calls to @c lte_lc_connect and CFUN AT calls are not
  * allowed, and must be done after @c nrf_modem_lib_init has returned. If a library needs to
- * perform operations after the link is up, it can use the link controller and subscribe to a
- * @c LTE_LC_ON_CFUN callback.
+ * perform operations after the link is up, it can subscribe to a @c NRF_MODEM_LIB_ON_CFUN callback.
  *
  * @param name Callback name
  * @param _callback Callback function name

lib/sms/sms.c

@@ -403,8 +403,7 @@ int sms_send(const char *number, const uint8_t *data, uint16_t data_len, enum sm
 	return sms_submit_send(number, data, data_len, type);
 }
 
-#if defined(CONFIG_LTE_LINK_CONTROL)
-LTE_LC_ON_CFUN(sms_cfun_hook, sms_on_cfun, NULL);
+NRF_MODEM_LIB_ON_CFUN(sms_cfun_hook, sms_on_cfun, NULL);
 
 static void sms_on_cfun(enum lte_lc_func_mode mode, void *ctx)
 {
@@ -426,4 +425,3 @@ static void sms_on_cfun(enum lte_lc_func_mode mode, void *ctx)
 		}
 	}
 }
-#endif /* CONFIG_LTE_LINK_CONTROL */

samples/cellular/modem_callbacks/README.rst

@@ -23,7 +23,7 @@ Overview
 
 The sample performs the following operations:
 
-1. Registers callbacks during compile time for modem initialization, functional mode changes, and shutdown using the :c:macro:`NRF_MODEM_LIB_ON_INIT`, :c:macro:`LTE_LC_ON_CFUN` and :c:macro:`NRF_MODEM_LIB_ON_SHUTDOWN` macros respectively.
+1. Registers callbacks during compile time for modem initialization, functional mode changes, and shutdown using the :c:macro:`NRF_MODEM_LIB_ON_INIT`, :c:macro:`NRF_MODEM_LIB_ON_CFUN` and :c:macro:`NRF_MODEM_LIB_ON_SHUTDOWN` macros respectively.
 #. Initializes the :ref:`nrfxlib:nrf_modem`.
 #. Changes functional mode using the :c:func:`lte_lc_func_mode_set` function in the :ref:`lte_lc_readme` library
 #. Shuts down the :ref:`nrfxlib:nrf_modem`.

samples/cellular/modem_trace_backend/src/main.c

@@ -10,7 +10,7 @@
 #include <nrf_modem_at.h>
 
 /* define callback */
-LTE_LC_ON_CFUN(cfun_hook, on_cfun, NULL);
+NRF_MODEM_LIB_ON_CFUN(cfun_hook, on_cfun, NULL);
 
 /* callback implementation */
 static void on_cfun(enum lte_lc_func_mode mode, void *context)

samples/cellular/modem_trace_flash/src/main.c

@@ -25,7 +25,7 @@ LOG_MODULE_REGISTER(modem_trace_flash_sample, CONFIG_MODEM_TRACE_FLASH_SAMPLE_LO
 
 static const struct device *const uart_dev = DEVICE_DT_GET(UART1_DT_NODE);
 
-LTE_LC_ON_CFUN(cfun_hook, on_cfun, NULL);
+NRF_MODEM_LIB_ON_CFUN(cfun_hook, on_cfun, NULL);
 
 /* Callback for when modem functional mode is changed */
 static void on_cfun(enum lte_lc_func_mode mode, void *context)