MprAdminInterfaceConnect

[This is preliminary documentation and subject to change.]

The MprAdminInterfaceConnect function creates a connection to the specified WAN interface.

DWORD  MprAdminInterfaceConnect(
  MPR_SERVER_HANDLE hMprServer,    // handle to router
  HANDLE hInterface,               // handle to interface
  HANDLE hEvent,                   // event to signal when connection
                                   // attempt is complete
  BOOL fBlocking                   // flag to control
                                   // synchronous vs.
                                   // asychronous operation
);

Parameters

hMprServer
Handle to the Windows NT router on which to execute this call. Obtain this handle by calling MprAdminServerConnect.
hInterface
Handle to the interface. This handle is obtained from a previous call to MprAdminInterfaceCreate.
hEvent
Handle to an event that will be signaled after the attempt to connect the interface has completed. The function initiates the connection attempt and returns immediately. After the event is signaled, you can obtain the result of the connection attempt by calling MprAdminInterfaceGetInfo.

If this parameter is NULL, and fBlocking is TRUE, then this call is synchronous, that is, the function will not return until the connection attempt has completed.

The caller must specify NULL for this parameter, if hMprserver specifies a remote router.

fBlocking
If hEvent is NULL and this parameter is set to TRUE, the function will not return until the connection attempt has completed.

If hEvent is NULL, and this parameter is set to FALSE, the function will return immediately. A return value of PENDING indicates that the connection attempt was initiated successfully.

If hEvent is not NULL, this parameter is ignored.

Return Values

NO_ERROR
Success, the interface is connected.
ERROR_ACCESS_DENIED
The caller does not have sufficient privilege.
ERROR_ALREADY_CONNECTING
A connection is already in progress on this interface.
ERROR_DDM_NOT_RUNNING
The Demand Dial Manager (DDM) is not running.
ERROR_INTERFACE_DISABLED
The interface is currently disabled.
ERROR_INTERFACE_HAS_NO_DEVICES
No adapters are available for this interface.
ERROR_INVALID_HANDLE
The hInterface value is invalid.
ERROR_SERVICE_IS_PAUSED
The Demand Dial service is currently paused.
PENDING
The interface is in the process of connecting. The caller should wait on the hEvent handle, if one was specified. After the event is signaled, you can obtain the state of the connection and any associated error can by calling MprAdminInterfaceGetInfo.

Remarks

The following table summarizes the relationship between hEvent and fBlocking.

hEvent fBlocking Result
Event Handle Ignored The call returns immediately. A return value of PENDING indicates that the attempt was initiated successfully. Wait on hEvent. When hEvent is signalled, use MprAdminInterfaceGetInfo to determine the success or failure of the connection attempt.
NULL TRUE The call will not return until connection attempt has completed.
NULL FALSE The call returns immediately. A return value of PENDING indicates that the attempt was initiated successfully.

QuickInfo

  Windows NT: Use version 5.0 and later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in mprapi.h.
  Import Library: Link with mprapi.lib.

See Also

MprAdminInterfaceCreate, MprAdminInterfaceDisconnect, MprAdminInterfaceGetInfo, MprAdminServerConnect