base-bearer: improve comments of the load/reload_connection_status() methods

1 files changed, 19 insertions, 3 deletions

diff --git a/src/mm-base-bearer.h b/src/mm-base-bearer.h
index 499ec703..a02036ca 100644
--- a/src/mm-base-bearer.h
+++ b/src/mm-base-bearer.h
@@ -125,9 +125,15 @@ struct _MMBaseBearerClass {
                                     GError **error);
 
     /* Monitor connection status:
-     * NOTE: only CONNECTED or DISCONNECTED should be reported here; this method
+     *
+     * Only CONNECTED or DISCONNECTED should be reported here; this method
      * is used to poll for connection status once the connection has been
-     * established */
+     * established.
+     *
+     * This method will return MM_CORE_ERROR_UNSUPPORTED if the polling
+     * is not required (i.e. if we can safely rely on async indications
+     * sent by the modem).
+     */
     void (* load_connection_status) (MMBaseBearer *bearer,
                                      GAsyncReadyCallback callback,
                                      gpointer user_data);
@@ -137,7 +143,17 @@ struct _MMBaseBearerClass {
 
 #if defined WITH_SYSTEMD_SUSPEND_RESUME
 
-    /* Reload connection status */
+    /* Reload connection status:
+     *
+     * This method should return the exact connection status of the bearer, and
+     * the check must always be performed (if supported). This method should not
+     * return MM_CORE_ERROR_UNSUPPORTED as a way to skip the operation, as in
+     * this case the connection monitoring is required during the quick
+     * suspend/resume synchronization.
+     *
+     * It is up to each protocol/plugin whether providing the same method here
+     * and in load_connection_status() makes sense.
+     */
     void (* reload_connection_status) (MMBaseBearer *bearer,
                                        GAsyncReadyCallback callback,
                                        gpointer user_data);