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.