Edit

Share via

IMbnConnection::Connect method (mbnapi.h)

  • Article

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.

Establishes a data connection.

Syntax

HRESULT Connect(
  [in]  MBN_CONNECTION_MODE connectionMode,
  [in]  LPCWSTR             strProfile,
  [out] ULONG               *requestID
);

Parameters

[in] connectionMode

An MBN_CONNECTION_MODE value that specifies the mode of the connection.

[in] strProfile

Contains the profile designator.

[out] requestID

A pointer to a unique request ID returned by the Mobile Broadband service to identify this asynchronous request.

Return value

This method can return one of these values.

Return code Description
S_OK
 The operation was successful.
HRESULT_FROM_WIN32(ERROR_SERVICE_NOT_ACTIVE)
 The Mobile Broadband service is not running on this system.
E_HANDLE
 Invalid interface. Most likely the Mobile Broadband device has been removed from the system.
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)
 Invalid interface. Most likely the Mobile Broadband device has been removed from the system.
E_INVALIDARG
 An invalid profile name was specified or the strProfile argument is not compliant to XML profile schema
E_MBN_MAX_ACTIVATED_CONTEXTS
 There is already an active Mobile Broadband context. Multiple active contexts are not supported.

Remarks

The Connect method is used to activate a connection context for the device. The Mobile Broadband service currently supports at most one active context. Activation of the context will also result in L2 connection also being established. Similarly, deactivation of a context will result in disconnection of the physical data connection to the mobile network.

If the device is not in the packet-attached state at the time of calling this operation then the Mobile Broadband service will implicitly packet attach the device before issuing the connect request to the device. If there is any packet service state change then application will be notified by a call to the OnPacketServiceStateChange method of the IMbnRegistrationEvents interface.

If connectionMode is set to MBN_CONNECTION_MODE_PROFILE, then strProfile represents the name of the profile for the device. If set to MBN_CONNECTION_MODE_TMP_PROFILE, then strProfile represents the XML representation of the profile. A calling application can use IMbnConnectionProfileManager to get a list of connection profiles stored in the device.

This is an asynchronous operation that will return immediately. If this method returns successfully, then the Mobile Broadband service will call the OnConnectComplete method of IMbnConnectionEvents when the operation is complete.

Windows 8 and later versions of Windows: A Windows Store app may use Connect with only the MBN_CONNECTION_MODE_TMP_PROFILEconnectionMode and the strProfile parameter set to an XML representation of the profile. This implies that the connection is of a temporary nature and not saved for future use by the system.

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

IMbnConnection