MMSim: libmm-glib Reference Manual

## MMSim MMSim — The SIM interface |

## Functions

const gchar * | mm_sim_get_path ()
gchar * | mm_sim_dup_path ()
gboolean | mm_sim_get_active ()
const gchar * | mm_sim_get_identifier ()
gchar * | mm_sim_dup_identifier ()
const gchar * | mm_sim_get_imsi ()
gchar * | mm_sim_dup_imsi ()
const gchar * | mm_sim_get_eid ()
gchar * | mm_sim_dup_eid ()
const gchar * | mm_sim_get_operator_identifier ()
gchar * | mm_sim_dup_operator_identifier ()
const gchar * | mm_sim_get_operator_name ()
gchar * | mm_sim_dup_operator_name ()
const gchar * const * | mm_sim_get_emergency_numbers ()
gchar ** | mm_sim_dup_emergency_numbers ()
GList * | mm_sim_get_preferred_networks ()
const guint8 * | mm_sim_get_gid1 ()
guint8 * | mm_sim_dup_gid1 ()
const guint8 * | mm_sim_get_gid2 ()
guint8 * | mm_sim_dup_gid2 ()
MMSimType | mm_sim_get_sim_type ()
MMSimEsimStatus | mm_sim_get_esim_status ()
MMSimRemovability | mm_sim_get_removability ()
void | mm_sim_send_pin ()
gboolean | mm_sim_send_pin_finish ()
gboolean | mm_sim_send_pin_sync ()
void | mm_sim_send_puk ()
gboolean | mm_sim_send_puk_finish ()
gboolean | mm_sim_send_puk_sync ()
void | mm_sim_enable_pin ()
gboolean | mm_sim_enable_pin_finish ()
gboolean | mm_sim_enable_pin_sync ()
void | mm_sim_disable_pin ()
gboolean | mm_sim_disable_pin_finish ()
gboolean | mm_sim_disable_pin_sync ()
void | mm_sim_change_pin ()
gboolean | mm_sim_change_pin_finish ()
gboolean | mm_sim_change_pin_sync ()
void | mm_sim_set_preferred_networks ()
gboolean | mm_sim_set_preferred_networks_finish ()
gboolean | mm_sim_set_preferred_networks_sync ()

## Types and Values

struct | MMSim

## Object Hierarchy

        GObject
        ╰── GDBusProxy
            ╰── MmGdbusSimProxy
                ╰── MMSim

## Implemented Interfaces

MMSim implements GDBusInterface, GInitable, GAsyncInitable and MmGdbusSim.

## Description

The MMSim is an object providing access to the methods, signals and properties of the SIM interface.

When the SIM is exposed and available in the bus, it is ensured that at least this interface is also available.

## Functions

### mm_sim_get_path ()

    const gchar *
    mm_sim_get_path (MMSim *self);

Gets the DBus path of the MMSim object.

#### Parameters

self | A MMSim. |

#### Returns

The DBus path of the MMSim object.

[transfer none]

Since: 1.0

### mm_sim_dup_path ()

    gchar *
    mm_sim_dup_path (MMSim *self);

Gets a copy of the DBus path of the MMSim object.

#### Parameters

self | A MMSim. |

#### Returns

The DBus path of the MMSim object. The returned value should be freed with `g_free()`.

[transfer full]

Since: 1.0

### mm_sim_get_active ()

    gboolean
    mm_sim_get_active (MMSim *self);

Checks whether the MMSim is currently active.

#### Parameters

self | A MMSim. |

#### Returns

`TRUE` if the SIM is active, `FALSE` otherwise.

Since: 1.16

### mm_sim_get_identifier ()

    const gchar *
    mm_sim_get_identifier (MMSim *self);

Gets the unique SIM identifier of the MMSim object.

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_sim_dup_identifier()` if on another thread.

#### Parameters

self | A MMSim. |

#### Returns

The unique identifier of the MMSim object, or `NULL` if it couldn't be retrieved.

[transfer none]

Since: 1.0

### mm_sim_dup_identifier ()

    gchar *
    mm_sim_dup_identifier (MMSim *self);

Gets a copy of the unique SIM identifier of the MMSim object.

#### Parameters

self | A MMSim. |

#### Returns

The unique identifier of the MMSim object, or `NULL` if it couldn't be retrieved. The returned value should be freed with `g_free()`.

[transfer full]

Since: 1.0

### mm_sim_get_imsi ()

    const gchar *
    mm_sim_get_imsi (MMSim *self);

Gets the International Mobile Subscriber Identity (IMSI) of the MMSim object.

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_sim_dup_imsi()` if on another thread.

#### Parameters

self | A MMSim. |

#### Returns

The IMSI of the MMSim object, or `NULL` if it couldn't be retrieved.

[transfer none]

Since: 1.0

### mm_sim_dup_imsi ()

    gchar *
    mm_sim_dup_imsi (MMSim *self);

Gets a copy of the International Mobile Subscriber Identity (IMSI) of the MMSim object.

#### Parameters

self | A MMSim. |

#### Returns

The IMSI of the MMSim object, or `NULL` if it couldn't be retrieved. The returned value should be freed with `g_free()`.

[transfer full]

Since: 1.0

### mm_sim_get_eid ()

    const gchar *
    mm_sim_get_eid (MMSim *self);

Gets the Embedded UICC ID (or EID) of the MMSim object.

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_sim_dup_eid()` if on another thread.

#### Parameters

self | A MMSim. |

#### Returns

The EID of the MMSim object, or `NULL` if it couldn't be retrieved.

[transfer none]

Since: 1.16

### mm_sim_dup_eid ()

    gchar *
    mm_sim_dup_eid (MMSim *self);

Gets a copy of the Embedded UICC ID (EID) of the MMSim object.

#### Parameters

self | A MMSim. |

#### Returns

The EID of the MMSim object, or `NULL` if it couldn't be retrieved. The returned value should be freed with `g_free()`.

[transfer full]

Since: 1.16

### mm_sim_get_operator_identifier ()

    const gchar *
    mm_sim_get_operator_identifier (MMSim *self);

Gets the Operator Identifier of the MMSim object.

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_sim_dup_operator_identifier()` if on another thread.

#### Parameters

self | A MMSim. |

#### Returns

The Operator Identifier of the MMSim object, or `NULL` if it couldn't be retrieved.

[transfer none]

Since: 1.0

### mm_sim_dup_operator_identifier ()

    gchar *
    mm_sim_dup_operator_identifier (MMSim *self);

Gets a copy of the Operator Identifier of the MMSim object.

#### Parameters

self | A MMSim. |

#### Returns

The Operator Identifier of the MMSim object, or `NULL` if it couldn't be retrieved. The returned value should be freed with `g_free()`.

[transfer full]

Since: 1.0

### mm_sim_get_operator_name ()

    const gchar *
    mm_sim_get_operator_name (MMSim *self);

Gets the Operator Name of the MMSim object.

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_sim_dup_operator_name()` if on another thread.

#### Parameters

self | A MMSim. |

#### Returns

The Operator Name of the MMSim object, or `NULL` if it couldn't be retrieved.

[transfer none]

Since: 1.0

### mm_sim_dup_operator_name ()

    gchar *
    mm_sim_dup_operator_name (MMSim *self);

Gets a copy of the Operator Name of the MMSim object.

#### Parameters

self | A MMSim. |

#### Returns

The Operator Name of the MMSim object, or `NULL` if it couldn't be retrieved. The returned value should be freed with `g_free()`.

[transfer full]

Since: 1.0

### mm_sim_get_emergency_numbers ()

    const gchar * const  *
    mm_sim_get_emergency_numbers (MMSim *self);

Gets the list of emergency call numbers programmed in the SIM card.

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_sim_dup_emergency_numbers()` if on another thread.

#### Parameters

self | A MMSim. |

#### Returns

The emergency numbers, or `NULL` if none available. Do not free the returned value, it belongs to `self` .

[transfer none]

Since: 1.12

### mm_sim_dup_emergency_numbers ()

    gchar **
    mm_sim_dup_emergency_numbers (MMSim *self);

Gets a copy of the list of emergency call numbers programmed in the SIM card.

#### Parameters

self | A MMSim. |

#### Returns

The emergency numbers, or `NULL` if none available. The returned value should be freed with `g_strfreev()`.

[transfer full]

Since: 1.12

### mm_sim_get_preferred_networks ()

    GList *
    mm_sim_get_preferred_networks (MMSim *self);

Gets the list of MMSimPreferredNetwork objects exposed by this MMSim.

#### Parameters

self | A MMSim. |

#### Returns

a list of MMSimPreferredNetwork objects, or NULL. The returned value should be freed with `g_list_free_full()` using `mm_sim_preferred_network_free()` as GDestroyNotify function.

[transfer full][element-type ModemManager.SimPreferredNetwork]

Since: 1.18

### mm_sim_get_gid1 ()

    const guint8 *
    mm_sim_get_gid1 (MMSim *self,
                     gsize *data_len);

Gets the Group Identifier Level 1 of the MMSim object.

#### Parameters

self | A MMSim. |
data_len | Size of the output data, if any given. | [out]

#### Returns

The GID1 data, or `NULL` if unknown.

[transfer none][array length=data_len][element-type guint8]

Since: 1.20

### mm_sim_dup_gid1 ()

    guint8 *
    mm_sim_dup_gid1 (MMSim *self,
                     gsize *data_len);

Gets the Group Identifier Level 1 of the MMSim object.

#### Parameters

self | A MMSim. |
data_len | Size of the output data, if any given. | [out]

#### Returns

The GID1 data, or `NULL` if unknown.

[transfer full][array length=data_len][element-type guint8]

Since: 1.20

### mm_sim_get_gid2 ()

    const guint8 *
    mm_sim_get_gid2 (MMSim *self,
                     gsize *data_len);

Gets the Group Identifier Level 2 of the MMSim object.

#### Parameters

self | A MMSim. |
data_len | Size of the output data, if any given. | [out]

#### Returns

The GID2 data, or `NULL` if unknown.

[transfer none][array length=data_len][element-type guint8]

Since: 1.20

### mm_sim_dup_gid2 ()

    guint8 *
    mm_sim_dup_gid2 (MMSim *self,
                     gsize *data_len);

Gets the Group Identifier Level 2 of the MMSim object.

#### Parameters

self | A MMSim. |
data_len | Size of the output data, if any given. | [out]

#### Returns

The GID2 data, or `NULL` if unknown.

[transfer full][array length=data_len][element-type guint8]

Since: 1.20

### mm_sim_get_sim_type ()

    MMSimType
    mm_sim_get_sim_type (MMSim *self);

Gets the SIM type.

#### Parameters

self | A MMSim. |

#### Returns

a MMSimType.

Since: 1.20

### mm_sim_get_esim_status ()

    MMSimEsimStatus
    mm_sim_get_esim_status (MMSim *self);

Gets the eSIM status.

Only applicable if the SIM type is `MM_SIM_TYPE_ESIM`.

#### Parameters

self | A MMSim. |

#### Returns

a MMSimEsimStatus.

Since: 1.20

### mm_sim_get_removability ()

    MMSimRemovability
    mm_sim_get_removability (MMSim *self);

Gets whether the SIM is removable or not.

#### Parameters

self | A MMSim. |

#### Returns

a MMSimRemovability.

Since: 1.20

### mm_sim_send_pin ()

    void
    mm_sim_send_pin (MMSim *self,
                     const gchar *pin,
                     GCancellable *cancellable,
                     GAsyncReadyCallback callback,
                     gpointer user_data);

Asynchronously sends the PIN code to the SIM card.

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_sim_send_pin_finish()` to get the result of the operation.

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

#### Parameters

self | A MMSim. |
pin | The PIN code. |
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` . |

Since: 1.0

### mm_sim_send_pin_finish ()

    gboolean
    mm_sim_send_pin_finish (MMSim *self,
                            GAsyncResult *res,
                            GError **error);

Finishes an operation started with `mm_sim_send_pin()`.

#### Parameters

self | A MMSim. |
res | The GAsyncResult obtained from the GAsyncReadyCallback passed to `mm_sim_send_pin()`. |
error | Return location for error or `NULL`. |

#### Returns

`TRUE` if the operation succeeded, `FALSE` if `error` is set.

Since: 1.0

### mm_sim_send_pin_sync ()

    gboolean
    mm_sim_send_pin_sync (MMSim *self,
                          const gchar *pin,
                          GCancellable *cancellable,
                          GError **error);

Synchronously sends the PIN to the SIM card.

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

#### Parameters

self | A MMSim. |
pin | The PIN code. |
cancellable | A GCancellable or `NULL`. | [allow-none]
error | Return location for error or `NULL`. |

#### Returns

`TRUE` if the operation succeeded, `FALSE` if `error` is set.

Since: 1.0

### mm_sim_send_puk ()

    void
    mm_sim_send_puk (MMSim *self,
                     const gchar *puk,
                     const gchar *pin,
                     GCancellable *cancellable,
                     GAsyncReadyCallback callback,
                     gpointer user_data);

Asynchronously sends the PUK code to the SIM card.

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_sim_send_puk_finish()` to get the result of the operation.

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

#### Parameters

self | A MMSim. |
puk | The PUK code. |
pin | The PIN code. |
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` . |

Since: 1.0

### mm_sim_send_puk_finish ()

    gboolean
    mm_sim_send_puk_finish (MMSim *self,
                            GAsyncResult *res,
                            GError **error);

Finishes an operation started with `mm_sim_send_puk()`.

#### Parameters

self | A MMSim. |
res | The GAsyncResult obtained from the GAsyncReadyCallback passed to `mm_sim_send_puk()`. |
error | Return location for error or `NULL`. |

#### Returns

`TRUE` if the operation succeeded, `FALSE` if `error` is set.

Since: 1.0

### mm_sim_send_puk_sync ()

    gboolean
    mm_sim_send_puk_sync (MMSim *self,
                          const gchar *puk,
                          const gchar *pin,
                          GCancellable *cancellable,
                          GError **error);

Synchronously sends the PUK to the SIM card.

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

#### Parameters

self | A MMSim. |
puk | The PUK code. |
pin | The PIN code. |
cancellable | A GCancellable or `NULL`. | [allow-none]
error | Return location for error or `NULL`. |

#### Returns

`TRUE` if the operation succeeded, `FALSE` if `error` is set.

Since: 1.0

### mm_sim_enable_pin ()

    void
    mm_sim_enable_pin (MMSim *self,
                       const gchar *pin,
                       GCancellable *cancellable,
                       GAsyncReadyCallback callback,
                       gpointer user_data);

Asynchronously enables requesting the PIN code in the SIM card.

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_sim_enable_pin_finish()` to get the result of the operation.

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

#### Parameters

self | A MMSim. |
pin | The PIN code. |
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` . |

Since: 1.0

### mm_sim_enable_pin_finish ()

    gboolean
    mm_sim_enable_pin_finish (MMSim *self,
                              GAsyncResult *res,
                              GError **error);

Finishes an operation started with `mm_sim_enable_pin()`.

#### Parameters

self | A MMSim. |
res | The GAsyncResult obtained from the GAsyncReadyCallback passed to `mm_sim_enable_pin()`. |
error | Return location for error or `NULL`. |

#### Returns

`TRUE` if the operation succeeded, `FALSE` if `error` is set.

Since: 1.0

### mm_sim_enable_pin_sync ()

    gboolean
    mm_sim_enable_pin_sync (MMSim *self,
                            const gchar *pin,
                            GCancellable *cancellable,
                            GError **error);

Synchronously enables requesting the PIN code in the SIM card.

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

#### Parameters

self | A MMSim. |
pin | The PIN code. |
cancellable | A GCancellable or `NULL`. | [allow-none]
error | Return location for error or `NULL`. |

#### Returns

`TRUE` if the operation succeeded, `FALSE` if `error` is set.

Since: 1.0

### mm_sim_disable_pin ()

    void
    mm_sim_disable_pin (MMSim *self,
                        const gchar *pin,
                        GCancellable *cancellable,
                        GAsyncReadyCallback callback,
                        gpointer user_data);

Asynchronously disables requesting the PIN code in the SIM card.

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_sim_disable_pin_finish()` to get the result of the operation.

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

#### Parameters

self | A MMSim. |
pin | The PIN code. |
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` . |

Since: 1.0

### mm_sim_disable_pin_finish ()

    gboolean
    mm_sim_disable_pin_finish (MMSim *self,
                               GAsyncResult *res,
                               GError **error);

Finishes an operation started with `mm_sim_disable_pin()`.

#### Parameters

self | A MMSim. |
res | The GAsyncResult obtained from the GAsyncReadyCallback passed to `mm_sim_disable_pin()`. |
error | Return location for error or `NULL`. |

#### Returns

`TRUE` if the operation succeeded, `FALSE` if `error` is set.

Since: 1.0

### mm_sim_disable_pin_sync ()

    gboolean
    mm_sim_disable_pin_sync (MMSim *self,
                             const gchar *pin,
                             GCancellable *cancellable,
                             GError **error);

Synchronously disables requesting the PIN code in the SIM card.

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

#### Parameters

self | A MMSim. |
pin | The PIN code. |
cancellable | A GCancellable or `NULL`. | [allow-none]
error | Return location for error or `NULL`. |

#### Returns

`TRUE` if the operation succeeded, `FALSE` if `error` is set.

Since: 1.0

### mm_sim_change_pin ()

    void
    mm_sim_change_pin (MMSim *self,
                       const gchar *old_pin,
                       const gchar *new_pin,
                       GCancellable *cancellable,
                       GAsyncReadyCallback callback,
                       gpointer user_data);

Asynchronously changes the PIN code in the SIM card.

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_sim_change_pin_finish()` to get the result of the operation.

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

#### Parameters

self | A MMSim. |
old_pin | The current PIN code. |
new_pin | The new PIN code to be set. |
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` . |

Since: 1.0

### mm_sim_change_pin_finish ()

    gboolean
    mm_sim_change_pin_finish (MMSim *self,
                              GAsyncResult *res,
                              GError **error);

Finishes an operation started with `mm_sim_change_pin()`.

#### Parameters

self | A MMSim. |
res | The GAsyncResult obtained from the GAsyncReadyCallback passed to `mm_sim_change_pin()`. |
error | Return location for error or `NULL`. |

#### Returns

`TRUE` if the operation succeeded, `FALSE` if `error` is set.

Since: 1.0

### mm_sim_change_pin_sync ()

    gboolean
    mm_sim_change_pin_sync (MMSim *self,
                            const gchar *old_pin,
                            const gchar *new_pin,
                            GCancellable *cancellable,
                            GError **error);

Synchronously changes the PIN code in the SIM card.

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

#### Parameters

self | A MMSim. |
old_pin | The current PIN code. |
new_pin | The new PIN code to be set. |
cancellable | A GCancellable or `NULL`. | [allow-none]
error | Return location for error or `NULL`. |

#### Returns

`TRUE` if the operation succeeded, `FALSE` if `error` is set.

Since: 1.0

### mm_sim_set_preferred_networks ()

    void
    mm_sim_set_preferred_networks (MMSim *self,
                                   const GList *preferred_networks,
                                   GCancellable *cancellable,
                                   GAsyncReadyCallback callback,
                                   gpointer user_data);

Asynchronously sets the preferred network list of this MMSim.

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_sim_set_preferred_networks_finish()` to get the result of the operation.

#### Parameters

self | A MMSim. |
preferred_networks | A list of MMSimPreferredNetwork objects. | [element-type ModemManager.SimPreferredNetwork]
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` . |

Since: 1.18

### mm_sim_set_preferred_networks_finish ()

    gboolean
    mm_sim_set_preferred_networks_finish (MMSim *self,
                                          GAsyncResult *res,
                                          GError **error);

Finishes an operation started with `mm_sim_set_preferred_networks()`.

#### Parameters

self | A MMSim. |
res | The GAsyncResult obtained from the GAsyncReadyCallback passed to `mm_sim_set_preferred_networks()`. |
error | Return location for error or `NULL`. |

#### Returns

`TRUE` if the operation was successful, `FALSE` if `error` is set.

Since: 1.18

### mm_sim_set_preferred_networks_sync ()

    gboolean
    mm_sim_set_preferred_networks_sync (MMSim *self,
                                        const GList *preferred_networks,
                                        GCancellable *cancellable,
                                        GError **error);

Synchronously sets the preferred network list of this MMSim.

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

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_sim_set_preferred_networks_finish()` to get the result of the operation.

#### Parameters

self | A MMSim. |
preferred_networks | A list of MMSimPreferredNetwork objects. | [element-type ModemManager.SimPreferredNetwork]
cancellable | A GCancellable or `NULL`. | [allow-none]
error | Return location for error or `NULL`. |

Since: 1.18

## Types and Values

### struct MMSim

    struct MMSim;

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