IMbnRegistration::GetRoamingText method (mbnapi.h)

Important

Starting in Windows 10, version 1803, the Win32 APIs described in this section are replaced by the Windows Runtime APIs in the Windows.Networking.Connectivity namespace.

Gets the roaming text describing the roaming provider.

Syntax

HRESULT GetRoamingText(
  [out] BSTR *roamingText
);

Parameters

[out] roamingText

Pointer to a string that contains additional information about a network with which the device is roaming. The maximum length is MBN_ROAMTEXT_LEN characters. The string is filled only when the method returns S_OK for success. Upon success, the calling application must free the allocated memory by calling SysFreeString.

Return value

This method can return one of these values.

Return code Description
S_OK
The operation was successful.
E_PENDING
The roaming text is not available. The Mobile Broadband service is currently probing the device for the information. When the roaming text is available, the Mobile Broadband service will call the OnRegisterModeAvailable method of IMbnRegistrationEvents.
E_MBN_PIN_REQUIRED
A PIN is required to get the roaming text.
E_MBN_SIM_NOT_INSERTED
A SIM is not inserted in the device.
E_MBN_BAD_SIM
A bad SIM is inserted in the device.

Remarks

The GetRoamingText method can get a text string containing additional information about the network when the registration state is either MBN_REGISTER_STATE_PARTNER or MBN_REGISTER_STATE_ROAMING.

This information may change when the Mobile Broadband device moves from one network to another. This includes whenever there is a change from MBN_REGISTER_STATE_HOME to MBN_REGISTER_STATE_SEARCHING in the network registration state. This also occurs when there is a change in the registered network, such as when a network moves its registration from one provider to another. After such changes, the Mobile Broadband service will call the OnRegisterStateChange method of IMbnRegistrationEvents.

For the recoverable error E_MBN_PIN_REQUIRED, the Mobile Broadband service will again try to fetch this information from the device when the error condition is over (when a PIN is entered). Then it will call the OnRegisterStateChange method of IMbnRegistrationEvents.

Requirements

Requirement Value
Minimum supported client Windows 7 [desktop apps | UWP apps]
Minimum supported server None supported
Target Platform Windows
Header mbnapi.h

See also

IMbnRegistration