MMModem3gpp

## MMModem3gpp MMModem3gpp — The 3GPP interface |

## Synopsis

    struct              MMModem3gpp;
                        MMModem3gppNetwork;

    const gchar *       mm_modem_3gpp_network_get_operator_code
                                                            (const MMModem3gppNetwork *network);
    const gchar *       mm_modem_3gpp_network_get_operator_short
                                                            (const MMModem3gppNetwork *network);
    const gchar *       mm_modem_3gpp_network_get_operator_long
                                                            (const MMModem3gppNetwork *network);
    MMModemAccessTechnology mm_modem_3gpp_network_get_access_technology
                                                            (const MMModem3gppNetwork *network);
    MMModem3gppNetworkAvailability mm_modem_3gpp_network_get_availability
                                                            (const MMModem3gppNetwork *network);
    void                mm_modem_3gpp_network_free          (MMModem3gppNetwork *network);

    const gchar *       mm_modem_3gpp_get_path              (MMModem3gpp *self);
    gchar *             mm_modem_3gpp_dup_path              (MMModem3gpp *self);
    const gchar *       mm_modem_3gpp_get_imei              (MMModem3gpp *self);
    gchar *             mm_modem_3gpp_dup_imei              (MMModem3gpp *self);
    const gchar *       mm_modem_3gpp_get_operator_code     (MMModem3gpp *self);
    gchar *             mm_modem_3gpp_dup_operator_code     (MMModem3gpp *self);
    const gchar *       mm_modem_3gpp_get_operator_name     (MMModem3gpp *self);
    gchar *             mm_modem_3gpp_dup_operator_name     (MMModem3gpp *self);
    MMModem3gppFacility mm_modem_3gpp_get_enabled_facility_locks
                                                            (MMModem3gpp *self);
    MMModem3gppRegistrationState mm_modem_3gpp_get_registration_state
                                                            (MMModem3gpp *self);

    void                mm_modem_3gpp_register              (MMModem3gpp *self,
                                                             const gchar *network_id,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            mm_modem_3gpp_register_finish       (MMModem3gpp *self,
                                                             GAsyncResult *res,
                                                             GError **error);
    gboolean            mm_modem_3gpp_register_sync         (MMModem3gpp *self,
                                                             const gchar *network_id,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                mm_modem_3gpp_scan                  (MMModem3gpp *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GList *             mm_modem_3gpp_scan_finish           (MMModem3gpp *self,
                                                             GAsyncResult *res,
                                                             GError **error);
    GList *             mm_modem_3gpp_scan_sync             (MMModem3gpp *self,
                                                             GCancellable *cancellable,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----GDBusProxy
             +----MmGdbusModem3gppProxy
                   +----MMModem3gpp

## Implemented Interfaces

MMModem3gpp implements GDBusInterface, GInitable, GAsyncInitable and MmGdbusModem3gpp.

## Description

The MMModem3gpp is an object providing access to the methods, signals and properties of the 3GPP interface.

The 3GPP interface is exposed whenever a modem has any of the 3GPP capabilities (`MM_MODEM_CAPABILITY_GSM_UMTS`, `MM_MODEM_CAPABILITY_LTE` or `MM_MODEM_CAPABILITY_LTE_ADVANCED`).

## Details

### struct MMModem3gpp

    struct MMModem3gpp;

The MMModem3gpp structure contains private data and should only be accessed using the provided API.

### MMModem3gppNetwork

    typedef struct _MMModem3gppNetwork MMModem3gppNetwork;

The MMModem3gppNetwork structure contains private data and should only be accessed using the provided API.

### mm_modem_3gpp_network_get_operator_code ()

    const gchar *       mm_modem_3gpp_network_get_operator_code
                                                            (const MMModem3gppNetwork *network);

Get the operator code (MCCMNC) of the 3GPP network.

`network` : | A MMModem3gppNetwork.
Returns : | The operator code, or `NULL` if none available. [transfer none]

### mm_modem_3gpp_network_get_operator_short ()

    const gchar *       mm_modem_3gpp_network_get_operator_short
                                                            (const MMModem3gppNetwork *network);

Get the short operator name of the 3GPP network.

`network` : | A MMModem3gppNetwork.
Returns : | The long operator name, or `NULL` if none available. [transfer none]

### mm_modem_3gpp_network_get_operator_long ()

    const gchar *       mm_modem_3gpp_network_get_operator_long
                                                            (const MMModem3gppNetwork *network);

Get the long operator name of the 3GPP network.

`network` : | A MMModem3gppNetwork.
Returns : | The long operator name, or `NULL` if none available. [transfer none]

### mm_modem_3gpp_network_get_access_technology ()

    MMModemAccessTechnology mm_modem_3gpp_network_get_access_technology
                                                            (const MMModem3gppNetwork *network);

Get the technology used to access the 3GPP network.

`network` : | A MMModem3gppNetwork.
Returns : | A MMModemAccessTechnology.

### mm_modem_3gpp_network_get_availability ()

    MMModem3gppNetworkAvailability mm_modem_3gpp_network_get_availability
                                                            (const MMModem3gppNetwork *network);

Get availability of the 3GPP network.

`network` : | A MMModem3gppNetwork.
Returns : | A MMModem3gppNetworkAvailability.

### mm_modem_3gpp_network_free ()

    void                mm_modem_3gpp_network_free          (MMModem3gppNetwork *network);

Frees a MMModem3gppNetwork.

`network` : | A MMModem3gppNetwork.

### mm_modem_3gpp_get_path ()

    const gchar *       mm_modem_3gpp_get_path              (MMModem3gpp *self);

Gets the DBus path of the MMObject which implements this interface.

`self` : | A MMModem3gpp.
Returns : | The DBus path of the MMObject object. [transfer none]

### mm_modem_3gpp_dup_path ()

    gchar *             mm_modem_3gpp_dup_path              (MMModem3gpp *self);

Gets a copy of the DBus path of the MMObject object which implements this interface.

`self` : | A MMModem3gpp.
Returns : | The DBus path of the MMObject. The returned value should be freed with `g_free()`. [transfer full]

### mm_modem_3gpp_get_imei ()

    const gchar *       mm_modem_3gpp_get_imei              (MMModem3gpp *self);

Gets the IMEI, as reported by this MMModem3gpp.

### Warning

The returned value is only valid until the property changes so it is only safe to use this function on the thread where `self` was constructed. Use `mm_modem_3gpp_dup_imei()` if on another thread.

`self` : | A MMModem3gpp.
Returns : | The IMEI, or `NULL` if none available. [transfer none]

### mm_modem_3gpp_dup_imei ()

    gchar *             mm_modem_3gpp_dup_imei              (MMModem3gpp *self);

Gets a copy of the IMEI, as reported by this MMModem3gpp.

`self` : | A MMModem3gpp.
Returns : | The IMEI, or `NULL` if none available. The returned value should be freed with `g_free()`. [transfer full]

### mm_modem_3gpp_get_operator_code ()

    const gchar *       mm_modem_3gpp_get_operator_code     (MMModem3gpp *self);

Gets the code of the operator to which the mobile is currently registered.

Returned in the format `"MCCMNC"`, where `MCC` is the three-digit ITU E.212 Mobile Country Code and `MNC` is the two- or three-digit GSM Mobile Network Code. e.g. e`"31026"` or `"310260"`.

If the `MCC` and `MNC` are not known or the mobile is not registered to a mobile network, this property will be a zero-length (blank) string.

### Warning

The returned value is only valid until the property changes so it is only safe to use this function on the thread where `self` was constructed. Use `mm_modem_3gpp_dup_operator_code()` if on another thread.

`self` : | A MMModem3gpp.
Returns : | The operator code, or `NULL` if none available. [transfer none]

### mm_modem_3gpp_dup_operator_code ()

    gchar *             mm_modem_3gpp_dup_operator_code     (MMModem3gpp *self);

Gets a copy of the code of the operator to which the mobile is currently registered.

Returned in the format `"MCCMNC"`, where `MCC` is the three-digit ITU E.212 Mobile Country Code and `MNC` is the two- or three-digit GSM Mobile Network Code. e.g. e`"31026"` or `"310260"`.

`self` : | A MMModem3gpp.
Returns : | The operator code, or `NULL` if none available. The returned value should be freed with `g_free()`. [transfer full]

### mm_modem_3gpp_get_operator_name ()

    const gchar *       mm_modem_3gpp_get_operator_name     (MMModem3gpp *self);

Gets the name of the operator to which the mobile is currently registered.

### Warning

The returned value is only valid until the property changes so it is only safe to use this function on the thread where `self` was constructed. Use `mm_modem_3gpp_dup_operator_name()` if on another thread.

`self` : | A MMModem3gpp.
Returns : | The operator name, or `NULL` if none available. [transfer none]

### mm_modem_3gpp_dup_operator_name ()

    gchar *             mm_modem_3gpp_dup_operator_name     (MMModem3gpp *self);

Gets a copy of the name of the operator to which the mobile is currently registered.

`self` : | A MMModem3gpp.
Returns : | The operator name, or `NULL` if none available. The returned value should be freed with `g_free()`. [transfer full]

### mm_modem_3gpp_get_enabled_facility_locks ()

    MMModem3gppFacility mm_modem_3gpp_get_enabled_facility_locks
                                                            (MMModem3gpp *self);

Get the list of facilities for which PIN locking is enabled.

`self` : | A MMModem3gpp.
Returns : | A bitmask of MMModem3gppFacility flags, specifying which facilities have locks enabled.

### mm_modem_3gpp_get_registration_state ()

    MMModem3gppRegistrationState mm_modem_3gpp_get_registration_state
                                                            (MMModem3gpp *self);

Get the the mobile registration status as defined in 3GPP TS 27.007 section 10.1.19.

`self` : | A MMModem.
Returns : | A MMModem3gppRegistrationState value, specifying the current registration state.

### mm_modem_3gpp_register ()

    void                mm_modem_3gpp_register              (MMModem3gpp *self,
                                                             const gchar *network_id,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously requests registration with a given mobile network.

When the operation is finished, `callback` will be invoked in the thread-default main loop of the thread you are calling this method from. You can then call `mm_modem_3gpp_register_finish()` to get the result of the operation.

See `mm_modem_3gpp_register_sync()` for the synchronous, blocking version of this method.

`self` : | A MMModem3gpp.
`network_id` : | The operator ID to register. An empty string can be used to register to the home network.
`cancellable` : | A GCancellable or `NULL`. [allow-none]
`callback` : | A GAsyncReadyCallback to call when the request is satisfied or `NULL`.
`user_data` : | User data to pass to `callback`.

### mm_modem_3gpp_register_finish ()

    gboolean            mm_modem_3gpp_register_finish       (MMModem3gpp *self,
                                                             GAsyncResult *res,
                                                             GError **error);

Finishes an operation started with `mm_modem_3gpp_register()`.

`self` : | A MMModem3gpp.
`res` : | The GAsyncResult obtained from the GAsyncReadyCallback passed to `mm_modem_3gpp_register()`.
`error` : | Return location for error or `NULL`.
Returns : | `TRUE` if the modem was registered, `FALSE` if `error` is set.

### mm_modem_3gpp_register_sync ()

    gboolean            mm_modem_3gpp_register_sync         (MMModem3gpp *self,
                                                             const gchar *network_id,
                                                             GCancellable *cancellable,
                                                             GError **error);

Synchronously requests registration with a given mobile network.

The calling thread is blocked until a reply is received. See `mm_modem_3gpp_register()` for the asynchronous version of this method.

`self` : | A MMModem3gpp.
`network_id` : | The operator ID to register. An empty string can be used to register to the home network.
`cancellable` : | A GCancellable or `NULL`. [allow-none]
`error` : | Return location for error or `NULL`.
Returns : | `TRUE` if the modem was registered, `FALSE` if `error` is set.

### mm_modem_3gpp_scan ()

    void                mm_modem_3gpp_scan                  (MMModem3gpp *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously requests to scan available 3GPP networks.

When the operation is finished, `callback` will be invoked in the thread-default main loop of the thread you are calling this method from. You can then call `mm_modem_3gpp_scan_finish()` to get the result of the operation.

See `mm_modem_3gpp_scan_sync()` for the synchronous, blocking version of this method.

`self` : | A MMModem3gpp.
`cancellable` : | A GCancellable or `NULL`. [allow-none]
`callback` : | A GAsyncReadyCallback to call when the request is satisfied or `NULL`.
`user_data` : | User data to pass to `callback`.

### mm_modem_3gpp_scan_finish ()

    GList *             mm_modem_3gpp_scan_finish           (MMModem3gpp *self,
                                                             GAsyncResult *res,
                                                             GError **error);

Finishes an operation started with `mm_modem_3gpp_scan()`.

`self` : | A MMModem3gpp.
`res` : | The GAsyncResult obtained from the GAsyncReadyCallback passed to `mm_modem_3gpp_scan()`.
`error` : | Return location for error or `NULL`.
Returns : | a list of MMModem3gppNetwork structs, or NULL if `error` is set. The returned value should be freed with `g_list_free_full()` using `mm_modem_3gpp_network_free()` as GDestroyNotify function.

### mm_modem_3gpp_scan_sync ()

    GList *             mm_modem_3gpp_scan_sync             (MMModem3gpp *self,
                                                             GCancellable *cancellable,
                                                             GError **error);

Synchronously requests to scan available 3GPP networks.

The calling thread is blocked until a reply is received. See `mm_modem_3gpp_scan()` for the asynchronous version of this method.

`self` : | A MMModem3gpp.
`cancellable` : | A GCancellable or `NULL`. [allow-none]
`error` : | Return location for error or `NULL`.
Returns : | a list of MMModem3gppNetwork structs, or NULL if `error` is set. The returned value should be freed with `g_list_free_full()` using `mm_modem_3gpp_network_free()` as GDestroyNotify function.