MPR_INTERFACE_2

[This is preliminary documentation and subject to change.]

The MPR_INTERFACE_2 structure contains information for a router demand-dial interface.

typedef struct _MPR_INTERFACE_2 {
  WCHAR                   wszInterfaceName[MAX_INTERFACE_NAME_LEN+1];
  HANDLE                  hInterface;
  BOOL                    fEnabled;
  ROUTER_INTERFACE_TYPE   dwIfType;
  ROUTER_CONNECTION_STATE dwConnectionState;
  DWORD                   fUnReachabilityReasons;
  DWORD                   dwLastError;
  // 
  // Demand dial-specific properties
  //
  DWORD       dwfOptions;
  //
  // Location/phone number
  //
  WCHAR       szLocalPhoneNumber[ RAS_MaxPhoneNumber + 1 ];
  PWCHAR      szAlternates;
  //
  // PPP/Ip
  //
  DWORD       ipaddr;
  DWORD       ipaddrDns;
  DWORD       ipaddrDnsAlt;
  DWORD       ipaddrWins;
  DWORD       ipaddrWinsAlt;
  //
  // Framing
  //
  DWORD       dwFrameSize;
  DWORD       dwfNetProtocols;
  //
  // Device
  //
  WCHAR       szDeviceType[ MPR_MaxDeviceType + 1 ];
  WCHAR       szDeviceName[ MPR_MaxDeviceName + 1 ];
  //
  // X.25
  //
  WCHAR       szX25PadType[ MPR_MaxPadType + 1 ];
  WCHAR       szX25Address[ MPR_MaxX25Address + 1 ];
  WCHAR       szX25Facilities[ MPR_MaxFacilities + 1 ];
  WCHAR       szX25UserData[ MPR_MaxUserData + 1 ];
  DWORD       dwChannels;
  //
  // Multilink
  //
  DWORD       dwSubEntries;
  DWORD       dwDialMode;
  DWORD       dwDialExtraPercent;
  DWORD       dwDialExtraSampleSeconds;
  DWORD       dwHangUpExtraPercent;
  DWORD       dwHangUpExtraSampleSeconds;
  //
  // Idle time-out
  //
  DWORD       dwIdleDisconnectSeconds;
  //
  // Entry Type
  //
  DWORD       dwType;
  //
  // EncryptionType
  //
  DWORD       dwEncryptionType;
  //
  // EAP information
  //
  DWORD       dwCustomAuthKey;
  DWORD       dwCustomAuthDataSize;
  LPBYTE      lpbCustomAuthData;
  //
  // GUID of the connection
  //
  GUID        guidId;
  //
  // Vpn Strategy
  //
  DWORD       dwVpnStrategy;
} MPR_INTERFACE_2, *PMPR_INTERFACE_2;

Members

wszInterfaceName
Pointer to a Unicode string that contains the name of the interface.
hInterface
Handle to the interface.
fEnabled
Specifies whether the interface is enabled. This value is TRUE if the interface is enabled, FALSE if the interface is administratively disabled.
dwIfType
Specifies the type of interface.
dwConnectionState
Specifies the current state of the interface, for example connected, disconnected, or unreachable. For a list of possible states, see ROUTER_CONNECTION_STATE.
fUnReachabilityReasons
Specifies a value that represents a reason why the interface is unreachable. See Unreachability Reasons for a list of possible values.
dwLastError
Specifies a nonzero value if the interface fails to connect.
dwfOptions
Specifies bit flags that are used to set connection options. You can set one or more of the following flags.
Flag Description
MPRIO_SpecificIpAddr If this flag is set, RRAS tries to use the IP address specified by ipaddr as the IP address for the dial-up connection. If this flag is not set, the value of the ipaddr member is ignored.

Setting the MPRIO_SpecificIpAddr flag corresponds to selecting the Specify an IP Address setting in the TCP/IP settings dialog box. Clearing the MPRIO_SpecificIpAddr flag corresponds to selecting the Server Assigned IP Address setting in the TCP/IP settings dialog box.

Currently, an IP address set in the phone-book entry properties or retrieved from a server overrides the IP address set in the network control panel.

MPRIO_SpecificNameServers If this flag is set, RRAS uses the ipaddrDns, ipaddrDnsAlt, ipaddrWins, and ipaddrWinsAlt members to specify the name server addresses for the dial-up connection. If this flag is not set, RRAS ignores these members.

Setting the MPRIO_SpecificNameServers flag corresponds to selecting the Specify Name Server Addresses setting in the TCP/IP Settings dialog box. Clearing the MPRIO_SpecificNameServers flag corresponds to selecting the Server Assigned Name Server Addresses setting in the TCP/IP Settings dialog box.

MPRIO_IpHeaderCompression If this flag is set, RRAS negotiates to use IP header compression on PPP connections.

If this flag is not set, IP header compression is not negotiated.

This flag corresponds to the Use IP Header Compression check box in the TCP/IP settings dialog box. It is generally advisable to set this flag because IP header compression significantly improves performance. The flag should be cleared only when connecting to a server that does not correctly negotiate IP header compression.

MPRIO_RemoteDefaultGateway If this flag is set, the default route for IP packets is through the dial-up adapter when the connection is active. If this flag is clear, the default route is not modified.

This flag corresponds to the Use Default Gateway on Remote Network check box in the TCP/IP settings dialog box.

MPRIO_DisableLcpExtensions If this flag is set, RRAS disables the PPP LCP extensions defined in RFC 1570. This may be necessary to connect to certain older PPP implementations, but interferes with features such as server callback. Do not set this flag unless specifically required.
MPRIO_SwCompression If this flag is set, software compression is negotiated on the link. Setting this flag causes the PPP driver to attempt to negotiate Compression Control Protocol (CCP) with the server. This flag should be set by default, but clearing it can reduce the negotiation period if the server does not support a compatible compression protocol.
MPRIO_RequireEncryptedPw If this flag is set, only secure password schemes can be used to authenticate the client with the server. This prevents the PPP driver from using the PAP plain-text authentication protocol to authenticate the client. However, the MS-CHAP, MD5-CHAP and SPAP authentication protocols are supported. Clear this flag for increased interoperability, and set it for increased security.

This flag corresponds to the Require Encrypted Password check box in the Security dialog box. See also MPRIO_RequireMsEncryptedPw.

MPRIO_RequireMsEncryptedPw If this flag is set, only the Microsoft secure password schemes can be used to authenticate the client with the server. This prevents the PPP driver from using the PAP plain-text authentication protocol, MD5-CHAP, or SPAP. The flag should be cleared for maximum interoperability and should be set for maximum security. This flag takes precedence over MPRIO_RequireEncryptedPw.

This flag corresponds to the Require Microsoft Encrypted Password check box in the Security dialog box. See also MPRIO_RequireDataEncryption.

MPRIO_RequireDataEncryption If this flag is set, data encryption must be negotiated successfully or the connection should be dropped. This flag is ignored unless MPRIO_RequireMsEncryptedPw is also set.

This flag corresponds to the Require Data Encryption checkbox in the Security dialog box.

MPRIO_NetworkLogon If this flag is set, RRAS logs on to the network after the point-to-point connection is established.

Windows NT/2000: This flag currently has no effect under Windows NT.

MPRIO_UseLogonCredentials If this flag is set, RRAS uses the user name, password, and domain of the currently logged-on user when dialing this entry. This flag is ignored unless MPRIO_RequireMsEncryptedPw is also set.

Note that this setting is ignored by the RasDial function where specifying empty strings for the szUserName and szPassword members of the RASDIALPARAMS structure gives the same result.

This flag corresponds to the Use Current Username and Password check box in the Security dialog box.

MPRIO_PromoteAlternates This flag has an effect when alternate phone numbers are defined by the szAlternates member. If this flag is set, an alternate phone number that connects successfully becomes the primary phone number, and the current primary phone number is moved to the alternate list.

This flag corresponds to the check box in the Alternate Numbers dialog box.

MPRIO_SecureLocalFiles If this flag is set, RRAS checks for existing remote file system and remote printer bindings before making a connection with this entry. Typically, you set this flag on phone-book entries for public networks to remind users to break connections to their private network before connecting to a public network.
MPRIO_RequireEAP If this flag is set, an Extensible Authentication Protocol (EAP) must be supported for authentication.
MPRIO_RequirePAP If this flag is set, Password Authentication Protocol must be supported for authentication.
MPRIO_RequireSPAP If this flag is set, Shiva's Password Authentication Protocol must be supported for authentication.
MPRIO_SharedPhoneNumbers If this flag is set, phone numbers are shared.
MPRIO_RequireCHAP If this flag is set, the Challenge Handshake Authentication Protocol must be supported for authentication.
MPRIO_RequireMsCHAP If this flag is set, the Microsoft Challenge Handshake Authentication Protocol must be supported for authentication.

szLocalPhoneNumber
Specifies a null-terminated string that contains a telephone number.
szAlternates
Pointer to a list of consecutive null-terminated Unicode strings. The last string is terminated by two consecutive null characters. The strings are alternate phone numbers that the router dials in the order listed if the primary number (see szLocalPhoneNumber) fails to connect.
ipaddr
Specifies the IP address to be used while this connection is active. This member is ignored unless dwfOptions specifies the MPRIO_SpecificIpAddr flag.
ipaddrDns
Specifies the IP address of the DNS server to be used while this connection is active. This member is ignored unless dwfOptions specifies the MPRIO_SpecificNameServers flag.
ipaddrDnsAlt
Specifies the IP address of a secondary or backup DNS server to be used while this connection is active. This member is ignored unless dwfOptions specifies the MPRIO_SpecificNameServers flag.
ipaddrWins
Specifies the IP address of the WINS server to be used while this connection is active. This member is ignored unless dwfOptions specifies the MPRIO_SpecificNameServers flag.
ipaddrWinsAlt
Specifies the IP address of a secondary WINS server to be used while this connection is active. This member is ignored unless dwfOptions specifies the MPRIO_SpecificNameServers flag.
dwFrameSize
Specifies the network protocol frame size. The value should be either 1006 or 1500.
dwfNetProtocols
Specifies the network protocols to negotiate. This member can be a combination of the following flags.
Flag Description
MPRNP_Ipx Negotiate the IPX protocol.
MPRNP_Ip Negotiate the TCP/IP protocol.

szDeviceType
Specifies a null-terminated string indicating the RRAS device type referenced by szDeviceName. This member can be one of the following string constants.
String Description
MPRDT_Modem A modem accessed through a COM port.
MPRDT_Isdn An ISDN card with the corresponding NDISWAN driver installed.
MPRDT_X25 An X.25 card with the corresponding NDISWAN driver installed.
MPRDT_Vpn A virtual private network connection.
MPRDT_Pad A Packet Assembler/Disassembler.
MPRDT_Generic Generic
MPRDT_Serial Direct serial connection through a serial port.
MPRDT_FrameRelay Frame Relay
MPRDT_Atm Asynchronous Transfer Mode
MPRDT_Sonet Sonet
MPRDT_SW56 Switched 56K Access
MPRDT_Irda Infrared Data Association (IrDA) compliant device.
MPRDT_Parallel Direct parallel connection through a parallel port.

szDeviceName
Contains a null-terminated string containing the name of a TAPI device to use with this phone-book entry, for example, "XYZ Corp 28800 External". To enumerate all available RAS-capable devices, use the RasEnumDevices function.
szX25PadType
Contains a null-terminated string that identifies the X.25 PAD type. Set this member to "" unless the entry should dial using an X.25 PAD.

Under Windows NT/Windows 2000, the szX25PadType string maps to a section name in PAD.INF.

szX25Address
Contains a null-terminated string that identifies the X.25 address to connect to. Set this member to "" unless the entry should dial using an X.25 PAD or native X.25 device.
szX25Facilities
Contains a null-terminated string that specifies the facilities to request from the X.25 host at connection. This member is ignored if szX25Address is an empty string ("").
szX25UserData
Contains a null-terminated string that specifies additional connection information supplied to the X.25 host at connection. This member is ignored if szX25Address is an empty string ("").
dwChannels
dwSubEntries
Specifies the number of multilink subentries associated with this entry. When calling RasSetEntryProperties, set this member to zero. To add subentries to a phone-book entry, use the RasSetSubEntryProperties function.
dwDialMode
Indicates whether RRAS should dial all of this entry's multilink subentries when the entry is first connected. This member can be one of the following values.
Value Meaning
MPRDM_DialAll Dial all subentries initially.
MPRDM_DialAsNeeded Adjust the number of subentries as bandwidth is needed. RRAS uses the dwDialExtraPercent, dwDialExtraSampleSeconds, dwDialHangUpExtraPercent, and dwHangUpExtraSampleSeconds members to determine when to dial or disconnect a subentry.

dwDialExtraPercent
Specifies a percent of the total bandwidth available from the currently connected subentries. RRAS dials an additional subentry when the total bandwidth used exceeds dwDialExtraPercent percent of the available bandwidth for at least dwDialExtraSampleSeconds seconds.

This member is ignored unless the dwDialMode member specifies the MPRDM_DialAsNeeded flag.

dwDialExtraSampleSeconds
Specifies the number of seconds for which current bandwidth usage must exceed the threshold specified by dwDialExtraPercent before RRAS dials an additional subentry.

This member is ignored unless the dwDialMode member specifies the MPRDM_DialAsNeeded flag.

dwHangUpExtraPercent
Specifies a percent of the total bandwidth available from the currently connected subentries. RRAS terminates (hangs up) an existing subentry connection when total bandwidth used is less than dwHangUpExtraPercent percent of the available bandwidth for at least dwHangUpExtraSampleSeconds seconds.

This member is ignored unless the dwDialMode member specifies the MPRDM_DialAsNeeded flag.

dwHangUpExtraSampleSeconds
Specifies the number of seconds for which current bandwidth usage must be less than the threshold specified by dwHangUpExtraPercent before RRAS terminates an existing subentry connection.

This member is ignored unless the dwDialMode member specifies the MPRDM_DialAsNeeded flag.

dwIdleDisconnectSeconds
Specifies the number of seconds after which the connection is terminated due to inactivity. Note that unless the idle time-out is disabled, the entire connection is terminated if the connection is idle for the specified interval. This member can specify a number of seconds, or one of the following values.
Value Meaning
MPRIDS_Disabled There is no idle time-out for this connection.
MPRIDS_UseGlobalValue Use the user preference value as the default.

dwType
Specifies the type of phone-book entry. This member can be one of the following types.
Type Description
MPRET_Phone Phone line, for example, modem, ISDN, X.25.
MPRET_Vpn Virtual Private Network
MPRET_Direct Direct serial or parallel connection

dwEncryptionType
Specifies the type of encryption to use for Microsoft Point-to-Point Encryption (MPPE) with the connection. This member can be one of the following values.
Value Meaning
MPR_ET_None No encryption
MPR_ET_Require Require encryption
MPR_ET_RequireMax Require maximum-strength encryption.
MPR_ET_Optional Do encryption if possible. No encryption is okay.

The value of dwEncryptionType does not affect how passwords are encrypted. Whether passwords are encrypted and how passwords are encrypted is determined by the authentication protocol, for example, PAP, MS-CHAP, or EAP.

dwCustomAuthKey
Specifies the authentication key provided to an Extensible Authentication Protocol (EAP) vendor.
dwCustomAuthDataSize
Specifies the size of the data pointed to by lpbCustomAuthData member.
lpbCustomAuthData
Pointer to authentication data to use with EAP.
guidId
The GUID (Globally Unique IDentifier) that represents this phone-book entry. This member cannot be set.
dwVpnStrategy
The VPN strategy to use when dialing a VPN connection. This member can have one of the following values.
Value Meaning
MPR_VS_Default RRAS dials PPTP first. If PPTP fails, L2TP is attempted. The protocol that succeeds is tried first in subsequent dialing for this entry.
MPR_VS_PptpOnly RAS dials only PPTP.
MPR_VS_PptpFirst RAS always dials PPTP first, L2TP second.
MPR_VS_L2tpOnly RAS dials only L2TP.
MPR_VS_L2tpFirst RAS dials L2TP first, PPTP second.

Remarks

The MPR_INTERFACE_2 structure has a number of members that are similar to members of the RASENTRY structure. The following members from the RASENTRY structure have no counterpart in MPR_INTERFACE_2:

dwCountryID
dwCountryCode
szAreaCode
dwFramingProtocol

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Mprapi.h.

See Also

MPR_INTERFACE_0, MPR_INTERFACE_1, MprAdminInterfaceGetInfo, MprAdminInterfaceSetInfo