2.2.1.2.85 MPRI_INTERFACE_3

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.

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 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.

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.

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.

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.

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.

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.