api,modem: new 'GetCellInfo()' method

This new method allows querying the modem for information about the
current serving cell(s) as well as any other neighboring cell that may
be found.

The information for the cells is given in an array of dictionaries,
where each element of the dictionary is a new dictionary itself.

Each cell type has a different set of properties that may be given in
the dictionary, and some of those properties in each type are also
applicable under certain conditions (e.g. only applicable to the cell
if it's a 'serving' cell instead of 'neighboring').

The API documentation explains in detail what is expected in each
case.

4 files changed, 450 insertions, 0 deletions

diff --git a/docs/reference/api/ModemManager-sections.txt b/docs/reference/api/ModemManager-sections.txt
index 5b155dad..9635f35e 100644
--- a/docs/reference/api/ModemManager-sections.txt
+++ b/docs/reference/api/ModemManager-sections.txt
@@ -63,6 +63,7 @@ MMSmsCdmaServiceCategory
 MMSimType
 MMSimEsimStatus
 MMSimRemovability
+MMCellType
 </SECTION>
 
 <SECTION>
diff --git a/docs/reference/libmm-glib/libmm-glib-sections.txt b/docs/reference/libmm-glib/libmm-glib-sections.txt
index 4957c3ff..ac14962f 100644
--- a/docs/reference/libmm-glib/libmm-glib-sections.txt
+++ b/docs/reference/libmm-glib/libmm-glib-sections.txt
@@ -1791,6 +1791,7 @@ mm_oma_session_state_failed_reason_get_string
 mm_call_direction_get_string
 mm_call_state_get_string
 mm_call_state_reason_get_string
+mm_cell_type_get_string
 <SUBSECTION Private>
 mm_modem_capability_get_string
 mm_modem_lock_build_string_from_mask
@@ -1845,6 +1846,7 @@ mm_call_direction_build_string_from_mask
 mm_call_state_build_string_from_mask
 mm_call_state_reason_build_string_from_mask
 mm_modem_firmware_update_method_get_string
+mm_cell_type_build_string_from_mask
 <SUBSECTION Standard>
 MM_TYPE_BEARER_TYPE
 MM_TYPE_BEARER_IP_FAMILY
@@ -1899,6 +1901,7 @@ MM_TYPE_CALL_DIRECTION
 MM_TYPE_CALL_STATE
 MM_TYPE_CALL_STATE_REASON
 MM_TYPE_MODEM_FIRMWARE_UPDATE_METHOD
+MM_TYPE_CELL_TYPE
 mm_bearer_type_get_type
 mm_bearer_ip_family_get_type
 mm_bearer_ip_method_get_type
@@ -1952,6 +1955,7 @@ mm_call_direction_get_type
 mm_call_state_get_type
 mm_call_state_reason_get_type
 mm_modem_firmware_update_method_get_type
+mm_cell_type_get_type
 </SECTION>
 
 <SECTION>
@@ -2563,6 +2567,9 @@ mm_gdbus_modem_call_set_primary_sim_slot_sync
 mm_gdbus_modem_call_command
 mm_gdbus_modem_call_command_finish
 mm_gdbus_modem_call_command_sync
+mm_gdbus_modem_call_get_cell_info
+mm_gdbus_modem_call_get_cell_info_finish
+mm_gdbus_modem_call_get_cell_info_sync
 <SUBSECTION Private>
 mm_gdbus_modem_set_access_technologies
 mm_gdbus_modem_set_bearers
@@ -2612,6 +2619,7 @@ mm_gdbus_modem_complete_set_current_modes
 mm_gdbus_modem_complete_set_current_bands
 mm_gdbus_modem_complete_set_current_capabilities
 mm_gdbus_modem_complete_set_primary_sim_slot
+mm_gdbus_modem_complete_get_cell_info
 mm_gdbus_modem_interface_info
 mm_gdbus_modem_override_properties
 <SUBSECTION Standard>
diff --git a/include/ModemManager-enums.h b/include/ModemManager-enums.h
index bb3c5c0e..d909b6e3 100644
--- a/include/ModemManager-enums.h
+++ b/include/ModemManager-enums.h
@@ -659,6 +659,30 @@ typedef enum { /*< underscore_name=mm_modem_port_type >*/
 } MMModemPortType;
 
 /**
+ * MMCellType:
+ * @MM_CELL_TYPE_UNKNOWN: Unknown.
+ * @MM_CELL_TYPE_CDMA: CDMA cell.
+ * @MM_CELL_TYPE_GSM: GSM cell.
+ * @MM_CELL_TYPE_UMTS: UMTS cell.
+ * @MM_CELL_TYPE_TDSCDMA: TD-SCDMA cell.
+ * @MM_CELL_TYPE_LTE: LTE cell.
+ * @MM_CELL_TYPE_5GNR: 5GNR cell.
+ *
+ * Type of cell information reported.
+ *
+ * Since: 1.20
+ */
+typedef enum { /*< underscore_name=mm_cell_type >*/
+    MM_CELL_TYPE_UNKNOWN = 0,
+    MM_CELL_TYPE_CDMA    = 1,
+    MM_CELL_TYPE_GSM     = 2,
+    MM_CELL_TYPE_UMTS    = 3,
+    MM_CELL_TYPE_TDSCDMA = 4,
+    MM_CELL_TYPE_LTE     = 5,
+    MM_CELL_TYPE_5GNR    = 6,
+} MMCellType;
+
+/**
  * MMSmsPduType:
  * @MM_SMS_PDU_TYPE_UNKNOWN: Unknown type.
  * @MM_SMS_PDU_TYPE_DELIVER: 3GPP Mobile-Terminated (MT) message.
diff --git a/introspection/org.freedesktop.ModemManager1.Modem.xml b/introspection/org.freedesktop.ModemManager1.Modem.xml
index 4867841b..1e346b95 100644
--- a/introspection/org.freedesktop.ModemManager1.Modem.xml
+++ b/introspection/org.freedesktop.ModemManager1.Modem.xml
@@ -201,6 +201,423 @@
       <arg name="sim_slot" type="u" direction="in" />
     </method>
 
+
+    <!--
+        GetCellInfo:
+
+        Get information for available cells in different access technologies,
+        either serving or neighboring.
+
+        An array of dictionaries is returned, where each dictionary reports information for
+        one single cell.
+
+        The dictionaries have mandatory keys that are always given, including:
+
+        <variablelist>
+          <varlistentry><term><literal>"cell-type"</literal></term>
+            <listitem>
+              The <link linkend="MMCellType">MMCellType</link>, given as an unsigned integer
+              value (signature <literal>"u"</literal>).
+            </listitem>
+          </varlistentry>
+          <varlistentry><term><literal>"serving"</literal></term>
+            <listitem>
+              Flag specifying whether the cell is a serving cell or otherwise a neighboring cell,
+              given as a boolean value (signature <literal>"b"</literal>).
+            </listitem>
+          </varlistentry>
+        </variablelist>
+
+        For each different cell type, other optional keys may be given.
+
+        <variablelist>
+          <varlistentry><term><link linkend="MM-CELL-TYPE-CDMA:CAPS">MM_CELL_TYPE_CDMA</link></term>
+            <listitem>
+              <para>
+                The CDMA cell information may include the following additional keys:
+              </para>
+              <variablelist>
+                <varlistentry><term><literal>"nid"</literal></term>
+                  <listitem>
+                    Network id, given as a string value (signature <literal>"s"</literal>)
+                    in upper-case hexadecimal format without leading zeros. E.g. <literal>"12345"</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"sid"</literal></term>
+                  <listitem>
+                    System id, given as a string value (signature <literal>"s"</literal>)
+                    in upper-case hexadecimal format without leading zeros. E.g. <literal>"ABCD"</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"base-station-id"</literal></term>
+                  <listitem>
+                    Base station id, given as a string value (signature <literal>"s"</literal>)
+                    in upper-case hexadecimal format without leading zeros. E.g. <literal>"3F"</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"ref-pn"</literal></term>
+                  <listitem>
+                    Base station PN number, given as a string value (signature <literal>"s"</literal>)
+                    in upper-case hexadecimal format without leading zeros. E.g. <literal>"3F"</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"pilot-strength"</literal></term>
+                  <listitem>
+                    The signal strength of the pilot, given in the same format and scale as the GSM
+                    SINR level, given as an unsigned integer value (signature <literal>"u"</literal>).
+                  </listitem>
+                </varlistentry>
+              </variablelist>
+            </listitem>
+          </varlistentry>
+          <varlistentry><term><link linkend="MM-CELL-TYPE-GSM:CAPS">MM_CELL_TYPE_GSM</link></term>
+            <listitem>
+              <para>
+                The GSM cell information may include the following additional keys:
+              </para>
+              <variablelist>
+                <varlistentry><term><literal>"operator-id"</literal></term>
+                  <listitem>
+                    PLMN MCC/MNC, given as a string value (signature <literal>"s"</literal>).
+                    E.g. <literal>21034</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"lac"</literal></term>
+                  <listitem>
+                    This is the two-byte Location Area Code of the base station, given
+                    as a string value (signature <literal>"s"</literal>) in upper-case
+                    hexadecimal format without leading zeros, as specified in 3GPP TS
+                    27.007. E.g. <literal>"84CD"</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"ci"</literal></term>
+                  <listitem>
+                    This is the two- or four-byte Cell Identifier, given as a string value
+                    (signature <literal>"s"</literal>) in upper-case hexadecimal format
+                    without leading zeros, as specified in 3GPP TS 27.007.
+                    E.g. <literal>"2BAF"</literal> or <literal>"D30156"</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"timing-advance"</literal></term>
+                  <listitem>
+                    Measured delay (in bit periods; 1 bit period = 48/13 microsecond)
+                    of an access burst transmission on the RACH or PRACH to the expected
+                    signal from a mobile station at zero distance under static channel
+                    conditions, given as an unsigned integer value (signature
+                    <literal>"u"</literal>). Only applicable for the serving cell (i.e.
+                    "serving" must be TRUE).
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"arfcn"</literal></term>
+                  <listitem>
+                    Absolute RF channel number, given as an unsigned integer value (signature
+                    <literal>"u"</literal>).
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"base-station-id"</literal></term>
+                  <listitem>
+                    Base station id, given as a string value (signature <literal>"s"</literal>)
+                    in upper-case hexadecimal format without leading zeros, as specified in
+                    3GPP TS 27.007. E.g. <literal>"3F"</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"rx-level"</literal></term>
+                  <listitem>
+                    Serving cell Rx measurement, given as a unsigned integer value
+                    (signature <literal>"u"</literal>. Values range between 0 and 63.
+                  </listitem>
+                </varlistentry>
+              </variablelist>
+            </listitem>
+          </varlistentry>
+          <varlistentry><term><link linkend="MM-CELL-TYPE-UMTS:CAPS">MM_CELL_TYPE_UMTS</link></term>
+            <listitem>
+              <para>
+                The UMTS cell information may include the following additional keys:
+              </para>
+              <variablelist>
+                <varlistentry><term><literal>"operator-id"</literal></term>
+                  <listitem>
+                    PLMN MCC/MNC, given as a string value (signature <literal>"s"</literal>).
+                    E.g. <literal>21034</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"lac"</literal></term>
+                  <listitem>
+                    This is the two-byte Location Area Code of the base station, given
+                    as a string value (signature <literal>"s"</literal>) in upper-case
+                    hexadecimal format without leading zeros, as specified in 3GPP TS
+                    27.007. E.g. <literal>"84CD"</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"ci"</literal></term>
+                  <listitem>
+                    This is the two- or four-byte Cell Identifier, given as a string value
+                    (signature <literal>"s"</literal>) in upper-case hexadecimal format
+                    without leading zeros, as specified in 3GPP TS 27.007.
+                    e.g. <literal>"2BAF"</literal> or <literal>"D30156"</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"frequency-fdd-ul"</literal></term>
+                  <listitem>
+                    In FDD, the frequency of the uplink in kHz, given as an unsigned integer value
+                    (signature <literal>"u"</literal>). Values range between 0 and 16383.
+                    Only applicable for the serving cell (i.e. "serving" must be TRUE).
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"frequency-fdd-dl"</literal></term>
+                  <listitem>
+                    In FDD, the frequency of the downlink in kHz, given as an unsigned integer value
+                    (signature <literal>"u"</literal>). Values range between 0 and 16383.
+                    Only applicable for the serving cell (i.e. "serving" must be TRUE).
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"frequency-tdd"</literal></term>
+                  <listitem>
+                    In TDD, the frequency in kHz, given as an unsigned integer value
+                    (signature <literal>"u"</literal>). Values range between 0 and 16383.
+                    Only applicable for the serving cell (i.e. "serving" must be TRUE).
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"uarfcn"</literal></term>
+                  <listitem>
+                    UTRA absolute RF channel number, given as an unsigned integer value
+                    (signature <literal>"u"</literal>).
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"psc"</literal></term>
+                  <listitem>
+                    Primary scrambling code, given as an unsigned integer value
+                    (signature <literal>"u"</literal>).
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"rscp"</literal></term>
+                  <listitem>
+                    Received signal code power; the received power on one code measured
+                    in dBm on the primary CPICH channel of the cell, given as a
+                    signed integer value (signature <literal>"d"</literal>).
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"ecio"</literal></term>
+                  <listitem>
+                    ECIO; the received energy per chip divided by the power density in the
+                    band measured in dBm on the primary CPICH channel of the cell, given as a
+                    signed integer value (signature <literal>"d"</literal>).
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"path-loss"</literal></term>
+                  <listitem>
+                    The path loss of the cell, given as an unsigned integer value (signature
+                    <literal>"u"</literal>.
+                    Only applicable for the serving cell (i.e. "serving" must be TRUE).
+                  </listitem>
+                </varlistentry>
+              </variablelist>
+            </listitem>
+          </varlistentry>
+          <varlistentry><term><link linkend="MM-CELL-TYPE-TDSCDMA:CAPS">MM_CELL_TYPE_TDSCDMA</link></term>
+            <listitem>
+              <para>
+                The TD-SCDMA cell information may include the following additional keys:
+              </para>
+              <variablelist>
+                <varlistentry><term><literal>"operator-id"</literal></term>
+                  <listitem>
+                    PLMN MCC/MNC, given as a string value (signature <literal>"s"</literal>).
+                    E.g. <literal>21034</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"lac"</literal></term>
+                  <listitem>
+                    This is the two-byte Location Area Code of the base station, given
+                    as a string value (signature <literal>"s"</literal>) in upper-case
+                    hexadecimal format without leading zeros, as specified in 3GPP TS
+                    27.007. E.g. <literal>"84CD"</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"ci"</literal></term>
+                  <listitem>
+                    This is the two- or four-byte Cell Identifier, given as a string value
+                    (signature <literal>"s"</literal>) in upper-case hexadecimal format
+                    without leading zeros, as specified in 3GPP TS 27.007.
+                    e.g. <literal>"2BAF"</literal> or <literal>"D30156"</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"uarfcn"</literal></term>
+                  <listitem>
+                    UTRA absolute RF channel number, given as an unsigned integer value
+                    (signature <literal>"u"</literal>).
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"cell-parameter-id"</literal></term>
+                  <listitem>
+                    The cell parameter ID, given as an unsigned integer value
+                    (signature <literal>"u"</literal>).
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"timing-advance"</literal></term>
+                  <listitem>
+                    Measured delay (in bit periods; 1 bit period = 48/13 microsecond)
+                    of an access burst transmission on the RACH or PRACH to the expected
+                    signal from an MS at zero distance under static channel conditions,
+                    given as a unsigned integer value (signature <literal>"u"</literal>).
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"rscp"</literal></term>
+                  <listitem>
+                    Received signal code power; the received power on one code measured
+                    in dBm on the primary CPICH channel of the cell, given as a
+                    signed integer value (signature <literal>"d"</literal>).
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"path-loss"</literal></term>
+                  <listitem>
+                    The path loss of the cell, given as an unsigned integer value (signature
+                    <literal>"u"</literal>.
+                  </listitem>
+                </varlistentry>
+              </variablelist>
+            </listitem>
+          </varlistentry>
+          <varlistentry><term><link linkend="MM-CELL-TYPE-LTE:CAPS">MM_CELL_TYPE_LTE</link></term>
+            <listitem>
+              <para>
+                The LTE cell information may include the following additional keys:
+              </para>
+              <variablelist>
+                <varlistentry><term><literal>"operator-id"</literal></term>
+                  <listitem>
+                    PLMN MCC/MNC, given as a string value (signature <literal>"s"</literal>).
+                    E.g. <literal>21034</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"tac"</literal></term>
+                  <listitem>
+                    This is the two- or three-byte Tracking Area Code of the base station, given
+                    as a string value (signature <literal>"s"</literal>) in upper-case
+                    hexadecimal format without leading zeros, as specified in 3GPP TS
+                    27.007. E.g. <literal>"84CD"</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"ci"</literal></term>
+                  <listitem>
+                    This is the two- or four-byte Cell Identifier, given as a string value
+                    (signature <literal>"s"</literal>) in upper-case hexadecimal format
+                    without leading zeros, as specified in 3GPP TS 27.007.
+                    e.g. <literal>"2BAF"</literal> or <literal>"D30156"</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"physical-ci"</literal></term>
+                  <listitem>
+                    The physical cell id, given as a string value
+                    (signature <literal>"s"</literal>) in upper-case hexadecimal format
+                    without leading zeros. E.g. <literal>"1A0"</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"earfcn"</literal></term>
+                  <listitem>
+                    E-UTRA absolute RF channel number, given as an unsigned integer value
+                    (signature <literal>"u"</literal>).
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"rsrp"</literal></term>
+                  <listitem>
+                    The average reference signal received power in dBm, given as a signed
+                    integer value (signature <literal>"d"</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"rsrq"</literal></term>
+                  <listitem>
+                    The average reference signal received quality in dB, given as a signed
+                    integer value (signature <literal>"d"</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"timing-advance"</literal></term>
+                  <listitem>
+                    The timing advance, given as an unsigned integer value (signature <literal>"u"</literal>).
+                    Only applicable for the serving cell (i.e. "serving" must be TRUE).
+                  </listitem>
+                </varlistentry>
+              </variablelist>
+            </listitem>
+          </varlistentry>
+          <varlistentry><term><link linkend="MM-CELL-TYPE-5GNR:CAPS">MM_CELL_TYPE_5GNR</link></term>
+            <listitem>
+              <para>
+                The 5GNR cell information may include the following additional keys:
+              </para>
+              <variablelist>
+                <varlistentry><term><literal>"operator-id"</literal></term>
+                  <listitem>
+                    PLMN MCC/MNC, given as a string value (signature <literal>"s"</literal>).
+                    E.g. <literal>21034</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"tac"</literal></term>
+                  <listitem>
+                    This is the two- or three-byte Tracking Area Code of the base station, given
+                    as a string value (signature <literal>"s"</literal>) in upper-case
+                    hexadecimal format without leading zeros, as specified in 3GPP TS
+                    27.007. E.g. <literal>"84CD"</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"ci"</literal></term>
+                  <listitem>
+                    This is the two- or four-byte Cell Identifier, given as a string value
+                    (signature <literal>"s"</literal>) in upper-case hexadecimal format
+                    without leading zeros, as specified in 3GPP TS 27.007.
+                    e.g. <literal>"2BAF"</literal> or <literal>"D30156"</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"physical-ci"</literal></term>
+                  <listitem>
+                    The physical cell id, given as a string value
+                    (signature <literal>"s"</literal>) in upper-case hexadecimal format
+                    without leading zeros. E.g. <literal>"1A0"</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"nrarfcn"</literal></term>
+                  <listitem>
+                    NR absolute RF channel number, given as an unsigned integer value
+                    (signature <literal>"u"</literal>).
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"rsrp"</literal></term>
+                  <listitem>
+                    The average reference signal received power in dBm, given as a signed
+                    integer value (signature <literal>"d"</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"rsrq"</literal></term>
+                  <listitem>
+                    The average reference signal received quality in dB, given as a signed
+                    integer value (signature <literal>"d"</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"sinr"</literal></term>
+                  <listitem>
+                    The signal to interference and noise ratio, given as a signed integer value
+                    (signature <literal>"d"</literal>.
+                  </listitem>
+                </varlistentry>
+                <varlistentry><term><literal>"timing-advance"</literal></term>
+                  <listitem>
+                    The timing advance, given as an unsigned integer value (signature
+                    <literal>"u"</literal>).
+                    Only applicable for the serving cell (i.e. "serving" must be TRUE).
+                  </listitem>
+                </varlistentry>
+              </variablelist>
+            </listitem>
+          </varlistentry>
+        </variablelist>
+
+        Since: 1.20
+    -->
+    <method name="GetCellInfo">
+      <arg name="cell_info" type="aa{sv}" direction="out" />
+    </method>
+
     <!--
         Command:
         @cmd: The command string, e.g. "AT+GCAP" or "+GCAP" (leading AT is inserted if necessary).