2.2.1.2.84 MPRI_INTERFACE_3

Article
06/24/2021

The MPRI_INTERFACE_3 structure <72> is used to contain data for a router demand-dial interface. This structure is used in the following methods:

RRouterInterfaceCreate (section 3.1.4.13)
RRouterInterfaceGetInfo (section 3.1.4.14)

RRouterInterfaceSetInfo (section 3.1.4.15)

 typedef struct _MPR_INTERFACE_3 {
   WCHAR wszInterfaceName[257];
   DWORD dwInterface;
   BOOL fEnabled;
   ROUTER_INTERFACE_TYPE dwIfType;
   ROUTER_CONNECTION_STATE dwConnectionState;
   DWORD fUnReachabilityReasons;
   DWORD dwLastError;
   DWORD dwfOptions;
   WCHAR szLocalPhoneNumber[129];
   PWCHAR szAlternates;
   DWORD ipaddr;
   DWORD ipaddrDns;
   DWORD ipaddrDnsAlt;
   DWORD ipaddrWins;
   DWORD ipaddrWinsAlt;
   DWORD dwfNetProtocols;
   WCHAR szDeviceType[17];
   WCHAR szDeviceName[129];
   WCHAR szX25PadType[33];
   WCHAR szX25Address[201];
   WCHAR szX25Facilities[201];
   WCHAR szX25UserData[201];
   DWORD dwChannels;
   DWORD dwSubEntries;
   DWORD dwDialMode;
   DWORD dwDialExtraPercent;
   DWORD dwDialExtraSampleSeconds;
   DWORD dwHangUpExtraPercent;
   DWORD dwHangUpExtraSampleSeconds;
   DWORD dwIdleDisconnectSeconds;
   DWORD dwType;
   DWORD dwEncryptionType;
   DWORD dwCustomAuthKey;
   DWORD dwCustomAuthDataSize;
   LPBYTE lpbCustomAuthData;
   GUID guidId;
   DWORD dwVpnStrategy;
   ULONG AddressCount;
   IN6_ADDR ipv6addrDns;
   IN6_ADDR ipv6addrDnsAlt;
   IN6_ADDR* ipv6addr;
 } MPRI_INTERFACE_3,
  *PMPRI_INTERFACE_3;

wszInterfaceName: A pointer to a Unicode string that contains the name of the interface. This value MUST be specified during the call to the RRouterInterfaceCreate<73> method and cannot be modified after the interface is created.<74>

dwInterface: Specifies a unique identifier of the interface. This is a read-only field and cannot be set or modified.

fEnabled: Specifies whether the interface is enabled. The value TRUE is greater than zero (0) if the interface is enabled, or FALSE is zero (0) if the interface is disabled by an administrator.

Value	Meaning
TRUE >0	The interface is enabled.
FALSE 0	The interface is disabled.

Value

Meaning

TRUE

The interface is enabled.

FALSE

The interface is disabled.

dwIfType: A ROUTER_INTERFACE_TYPE (section 2.2.1.1.1) value specifying the type of interface.

dwConnectionState: A ROUTER_CONNECTION_STATE (section 2.2.1.1.2) value specifying the current state of the interface (for example: connected, disconnected, or unreachable). This is a read-only field and cannot be set or modified.

fUnReachabilityReasons: A value that describes the reason why the interface is unreachable. This is a read-only field and cannot be set or modified. The following table has the list of possible values.

Value	Meaning
MPR_INTERFACE_ADMIN_DISABLED 0x00000002	The administrator has disabled the interface.
MPR_INTERFACE_CONNECTION_FAILURE 0x00000004	The previous connection attempt failed.
MPR_INTERFACE_DIALOUT_HOURS_RESTRICTION 0x00000010	Dial-out is not allowed at the current time.
MPR_INTERFACE_OUT_OF_RESOURCES 0x00000001	No ports or devices are available for use.
MPR_INTERFACE_SERVICE_PAUSED 0x00000008	The service is paused.
MPR_INTERFACE_NO_MEDIA_SENSE 0x00000020	The network cable is disconnected from the network card.
MPR_INTERFACE_NO_DEVICE 0x00000040	The network card has been removed from the machine.

dwLastError: A value that contains a nonzero value if the interface fails to connect. This value is a Win32 error code as defined in [MS-ERREF]. This is a read-only field and cannot be set or modified.

dwfOptions: A value that specifies bit flags used to set connection options. It SHOULD <75> be a combination of the flags listed in the following table.

Value	Meaning
MPRIO_SpecificIpAddr 0x00000002	If this flag is set, the RRAS server attempts to use the IP address specified by the ipaddr field as the IP address for the dial-up connection. If this flag is not set, the value of the ipaddr member is ignored.
MPRIO_SpecificNameServers 0x00000004	If this flag is set, the RRAS server 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, the RRAS server ignores these members.
MPRIO_IpHeaderCompression 0x00000008	If this flag is set, the RRAS server negotiates to use the IP header compression on the PPP connections. The IP header compression can significantly improve performance. If this flag is not set, the IP header compression is not negotiated.
MPRIO_RemoteDefaultGateway 0x00000010	If this flag is set, the default route for the IP packets is through the dial-up adapter when the connection is active. If this flag is cleared, the default route is not modified.
MPRIO_DisableLcpExtensions 0x00000020	If this flag is set, the RRAS server disables the PPP LCP extensions defined in [RFC1570]. Disabling the PPP LCP extensions is sometimes necessary to connect to certain older PPP implementations, but it interferes with features such as server callback. This flag MUST NOT be set unless it is specifically required.
MPRIO_SwCompression 0x00000200	If this flag is set, software compression is negotiated on the link. Setting this flag causes the PPP to attempt to negotiate the 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 0x00000400	If this flag is set, only secure password schemes can be used to authenticate the client with the server. This prevents the PPP from using the PAP plaintext authentication protocol to authenticate the client. However, the [MS-CHAP], MD5-CHAP, and SPAP authentication protocols are supported. For increased security, set this flag. For increased interoperability, clear this flag.
MPRIO_RequireMsEncryptedPw 0x00000800	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 from using the PAP plaintext authentication protocol, MD5-CHAP, or SPAP. For increased security, set this flag. For increased interoperability, clear this flag. This flag takes precedence over MPRIO_RequireEncryptedPw.
MPRIO_RequireDataEncryption 0x00001000	If this flag is set, data encryption MUST be negotiated successfully or the connection is dropped. This flag is ignored unless MPRIO_RequireMsEncryptedPw is also set.
MPRIO_UseLogonCredentials 0x00004000	If this flag is set, the RRAS server uses the username, password, and domain of the currently logged-on user when dialing this entry. This flag is ignored unless MPRIO_RequireMsEncryptedPw is also set.
MPRIO_PromoteAlternates 0x00008000	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.
MPRIO_SecureLocalFiles 0x00010000	If this flag is set, the RRAS server checks for an existing remote file system and remote printer bindings before making a connection with this entry. Typically, this flag is set 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 0x00020000	If this flag is set, Extensible Authentication Protocol (EAP) MUST be supported for authentication.
MPRIO_RequirePAP 0x00040000	If this flag is set, Password Authentication Protocol (PAP) MUST be supported for authentication.
MPRIO_RequireSPAP 0x00080000	If this flag is set, Shiva's Password Authentication Protocol (SPAP) MUST be supported for authentication.
MPRIO_SharedPhoneNumbers 0x00800000	If this flag is set, phone numbers are shared.
MPRIO_RequireCHAP 0x08000000	If this flag is set, the Challenge Handshake Authentication Protocol (CHAP) MUST be supported for authentication.
MPRIO_RequireMsCHAP 0x10000000	If this flag is set, the Microsoft Challenge Handshake Authentication Protocol [MS-CHAP] MUST be supported for authentication.
MPRIO_RequireMsCHAP2 0x20000000	If this flag is set, version 2 of the [MS-CHAP] MUST be supported for authentication.
MPRIO_IpSecPreSharedKey 0x80000000	Configured the demand-dial interface to use preshared key.
MPRIO_RequireMachineCertificates 0x01000000	If this flag is set, a machine certificate is to be used for IKEv2 authentication.
MPRIO_UsePreSharedKeyForIkev2Initiator 0x02000000	If this flag is set, a preshared key is to be used by the initiator of the IKEv2 connection for authentication.
MPRIO_UsePreSharedKeyForIkev2Responder 0x04000000	If this flag is set, a preshared key is to be used by the responder of the IKEv2 connection for authentication.

szLocalPhoneNumber: A value that specifies a null-terminated Unicode string that contains a telephone number.

szAlternates: The offset from the beginning of this structure where the alternate phone numbers are stored. If no alternate phone number is available, this value MUST be set to 0. Alternate phone numbers are 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 fails to connect. For more information, see szLocalPhoneNumber. The alternate phone numbers MUST be stored after the custom data that is appended to this structure.

ipaddr: A value that specifies the IP address to be used while this connection is active. This member is ignored unless dwfOptions specifies the MPRIO_SpecificIpAddr flag.

ipaddrDns: A value that 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: A value that 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: A value that 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: A value that 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.

dwfNetProtocols: A value that specifies the network protocols to negotiate. This member can be a combination of the following flags.

Value	Meaning
MPRNP_Ipx 0x00000002	Negotiate the IPX protocol.
MPRNP_Ip 0x00000004	Negotiate the TCP/IPv4 protocol.
MPRNP_Ipv6 0x00000008	Negotiate the TCP/IPv6 protocol.

Value

Meaning

MPRNP_Ipx

0x00000002

Negotiate the IPX protocol.

MPRNP_Ip

0x00000004

Negotiate the TCP/IPv4 protocol.

MPRNP_Ipv6

0x00000008

Negotiate the TCP/IPv6 protocol.

szDeviceType: A value that specifies a null-terminated Unicode string that indicates the RRAS server device type that is referenced by szDeviceName. This is a read-only field that is computed based on the value of the szDeviceName member. The possible values for this member are the same as the wszDeviceName defined in RASI_PORT_0.

szDeviceName: Contains a null-terminated Unicode string that contains the name of a TAPI device to use with this phone book entry (for example, "Fabrikam Inc 28800 External"). To enumerate all available RAS-capable devices, use the RRouterDeviceEnum (section 3.1.4.37) method.

szX25PadType: Contains a null-terminated Unicode string that identifies the X.25 PAD type. This value SHOULD be set to an empty string ("") unless the entry dials using an X.25 PAD.<76>

szX25Address: Contains a null-terminated Unicode string that identifies the X.25 address to connect to. This value SHOULD be set to an empty string ("") unless the entry dials using an X.25 PAD or native X.25 device.<77>

szX25Facilities: Contains a null-terminated Unicode string that specifies the facilities to request from the X.25 host at connection time. This member is ignored if szX25Address is an empty string ("").

szX25UserData: Contains a null-terminated Unicode string that specifies the additional connection data supplied to the X.25 host at connection time. This member is ignored if szX25Address is an empty string ("").

dwChannels: Reserved for future use.

dwSubEntries: A value that specifies the number of multilink subentries associated with this entry. This is a read-only field and cannot be set or modified. Multilink entries SHOULD be specified by updating the Media section of the phonebook file as specified in 2.2.2.2.96.

dwDialMode: Indicates whether the RRAS server needs to 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
0x00000000	Dial the first available device only.
MPRDM_DialAll 0x00000001	Dial all subentries initially.
MPRDM_DialAsNeeded 0x00000002	Adjust the number of subentries as bandwidth is required. The RRAS server uses the dwDialExtraPercent, dwDialExtraSampleSeconds, dwDialHangUpExtraPercent, and dwHangUpExtraSampleSeconds members to determine when to dial or disconnect a subentry. This value SHOULD <78> be ignored and treated identically to MPRDM_DialAll.

Value

Meaning

0x00000000

Dial the first available device only.

MPRDM_DialAll

0x00000001

Dial all subentries initially.

MPRDM_DialAsNeeded

0x00000002

Adjust the number of subentries as bandwidth is required. The RRAS server uses the dwDialExtraPercent, dwDialExtraSampleSeconds, dwDialHangUpExtraPercent, and dwHangUpExtraSampleSeconds members to determine when to dial or disconnect a subentry. This value SHOULD <78> be ignored and treated identically to MPRDM_DialAll.

dwDialExtraPercent: A value that specifies the percentage of the total bandwidth that is available from the currently connected subentries. The RRAS server dials an additional subentry when the total bandwidth that is 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: A value that specifies the time, in seconds, for which current bandwidth usage MUST exceed the threshold that is specified by dwDialExtraPercent before the RRAS server dials an additional subentry.

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

dwHangUpExtraPercent: A value that specifies the percentage of the total bandwidth that is available from the currently connected subentries. The RRAS server terminates (hangs up) an existing subentry connection when the 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: A value that specifies the time, in seconds, for which current bandwidth usage MUST be less than the threshold that is specified by dwHangUpExtraPercent before the RRAS server terminates an existing subentry connection.

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

dwIdleDisconnectSeconds: A value that specifies the time, in seconds, after which an inactive connection is terminated. 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 either a time-out value or one of the following values.

Value	Meaning
MPRIDS_UseGlobalValue 0x00000000	Use the user preference value as the default.
MPRIDS_Disabled 0xFFFFFFFF	There is no idle time-out for this connection.

Value

Meaning

MPRIDS_UseGlobalValue

0x00000000

Use the user preference value as the default.

MPRIDS_Disabled

0xFFFFFFFF

There is no idle time-out for this connection.

dwType: A value that specifies the type of phone book entry. This is a read-only field that is calculated based on the value of the szDeviceType member. This member can be one of the following types.

Value	Meaning
MPRET_Phone 0x00000001	Phone line (for example: modem, ISDN, or X.25).
MPRET_Vpn 0x00000002	Virtual private network (VPN).
MPRET_Direct 0x00000003	Direct serial or parallel connection.

Value

Meaning

MPRET_Phone

0x00000001

Phone line (for example: modem, ISDN, or X.25).

MPRET_Vpn

0x00000002

Virtual private network (VPN).

MPRET_Direct

0x00000003

Direct serial or parallel connection.

dwEncryptionType: A value that 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 0x00000000	Do not use encryption.
MPR_ET_Require 0x00000001	Use encryption.
MPR_ET_RequireMax 0x00000002	Use maximum-strength encryption.
MPR_ET_Optional 0x00000003	If possible, use encryption.

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: A value that specifies the authentication key to be provided to an EAP ([MS-PEAP]) vendor.

dwCustomAuthDataSize: A value that specifies the size of the data pointed to by the lpbCustomAuthData member.

lpbCustomAuthData: The offset from the beginning of this structure where the CustomAuthData is stored. If CustomAuthData are not specified, this member MUST be set to 0. CustomAuthData is the authentication data to use with EAP [MS-PEAP]. CustomAuthData MUST be appended to the end of this structure.

guidId: The GUID that represents this phone book entry. This member is read-only.

dwVpnStrategy: The VPN strategy to use when dialing a VPN connection. This member SHOULD have one of the following values.<79>

Value	Meaning
MPR_VS_Default 0x00000000	The RRAS server dials the PPTP first. If the PPTP fails, the L2TP is attempted. If the L2TP fails, the IKEv2 is attempted. The protocol that succeeds is tried first in subsequent dialing for this entry.
MPR_VS_PptpOnly 0x00000001	The RRAS server dials only the PPTP.
MPR_VS_PptpFirst 0x00000002	The RRAS server always dials the PPTP first, the L2TP second, and the IKEv2 third.
MPR_VS_L2tpOnly 0x00000003	The RRAS server dials only the L2TP.
MPR_VS_L2tpFirst 0x00000004	The RRAS server dials the L2TP first, the PPTP second, and the IKEv2 third.
MPR_VS_Ikev2Only 0x00000007	The RRAS server dials only the IKEv2.
MPR_VS_Ikev2First 0x00000008	The RRAS server dials the IKEv2 first, the PPTP second, and the L2TP third.

AddressCount: Not used.

ipv6addrDns: A value that specifies the IP address of the DNS server to be used while this connection is active.

ipv6addrDnsAlt: A value that specifies the IP address of a secondary or backup DNS server to be used while this connection is active.

ipv6addr: Not used.

Share via

2.2.1.2.84 MPRI_INTERFACE_3

Additional resources