About Routing and Remote Access Service

[This is preliminary documentation and subject to change.]

The following documentation describes the Application Programming Interface (API) for Microsoft® Windows NT® Routing and Remote Access Service (RAS). The Routing and RAS API has the following components.

  • RAS Administration
  • Router Administration
  • Router Configuration
  • Routing Protocol Interface
  • Routing Table Manager
  • Plugin Interface
  • Extensible Authentication Protocol
  • Tracing


Windows NT Routing and Remote Access Services Architecture

The following diagram presents a general architectural view of the Microsoft® Windows NT® router.


Registry Layout

The following syntax shows an example registry layout for the Router service.

HKEY_LOCAL_SYSTEM\System\CurrentControlSet
\Services
\Router
           \Parameters
                   LANOnlyMode = DWORD (0/1)
               \RouterManagers
               \IP
                   DLLPath = REG_SZ ....
                   ProtocolID = DWORD 0x0021
                   GlobalInfo = REG_BINARY ...

               \IPX
                   DLLPath = REG_SZ ...
                   ProtocolID = DWORD 0x002B
                   GlobalInfo = REG_BINARY ...
                   GlobalInFilter = REG_BSZ < filter set name > . . .

               ......
           \Interfaces
               \0
                   InterfaceName: REG_SZ Redmond
                   Type = DWORD (Internal/Dedicated/Dynamic)
                   \IP
                       ProtocolID = DWORD 0x0021
                       InterfaceInfo = BINARY . . .
                   \IPX
                       ProtocolID = DWORD 0x002B
                       InterfaceInfo = BINARY . . .
                   .....
               \N
                   InterfaceName: REG_SZ IntelEtherExpressPro2
                   .....
           \DemandDialManager
                   < RAS parameters and DDM parameters >

HKEY_LOCAL_SYSTEM\System\CurrentControlSet\Software\Microsoft
    \Router
        \CurrentVersion
            \RouterManagers
                \IP
                    \OSPF
                        ConfigDll: REG_SZ     ipadmin.dll
                        DllName: REG_SZ       ospf.dll
                        ProtocolID: REG_DWORD 0xD
                        Title: REG_SZ Open Shortest Path First
                \IPX
                    .......
            \UIConfigDlls

Every router manager installed in the system will have a registry key created under the Router key. The DLLPath variable specifies the location of the DLL corresponding to the router manager and the ProtocolID variable specifies the protocol family identifier for the router manager.

The Interfaces key is populated with the interfaces that have been added to the local system from the Router configuration. Each interface has an associated Type (Internal, Dedicated, or Dynamic) and subkeys for each router manager (IP and IPX in the previous example).


Remote Access Service (RAS) Administration Reference

The programmatic interface for the Remote Access Service (RAS) under Microsoft® Windows NT® Routing and RAS, which is available as a downloadable component for Windows NT 4.0 or within Windows NT 5.0, is similar to that in the version of RAS included in Windows NT 4.0. However, the naming convention is different between the two APIs.

Functions under Windows NT 4.0 RAS typically begin with RasAdmin. The analogous functions under Routing and RAS begin with MprAdmin. For example, Windows NT 4.0 RAS provides a function called RasAdminPortGetInfo. The analogous function in Routing and RAS is called MprAdminPortGetInfo. Another example: Windows NT 4.0 RAS provides the callback function RasAdminGetIpAddressForUser. Routing and RAS provides a similar callback function called MprAdminGetIpAddressForUser. An exception to this rule is RasAdminPortClearStatistics, which, under Routing and RAS is MprAdminPortClearStats.

The following table lists the Windows NT 4.0 RAS functions and the corresponding Routing and RAS functions.

Windows NT 4.0 RAS Routing and RAS
RasAdminAcceptNewConnection MprAdminAcceptNewConnection
RasAdminConnectionHangupNotification MprAdminConnectionHangupNotification
RasAdminGetIpAddressForUser MprAdminGetIpAddressForUser
RasAdminPortClearStatistics MprAdminPortClearStats
RasAdminPortDisconnect MprAdminPortDisconnect
RasAdminPortEnum MprAdminPortEnum
RasAdminPortGetInfo MprAdminPortGetInfo
RasAdminReleaseIpAddress MprAdminReleaseIpAddress
RasAdminUserGetInfo MprAdminUserGetInfo
RasAdminUserSetInfo MprAdminUserSetInfo

Although the Routing and RAS functions have similar functionality to their Windows NT 4.0 RAS counterparts, Routing and RAS functions often take a different set of parameters. See the reference page for a particular function for complete information on that function's parameter list.

Routing and RAS also adds the following functions which have no counterparts in Windows NT 4.0 RAS.

MprAdminAcceptNewLink

MprAdminConnectionClearStats

MprAdminConnectionEnum

MprAdminConnectionGetInfo

MprAdminGetPDCServer

MprAdminLinkHangupNotification

MprAdminPortReset


RAS Administration Functions

The following documentation explains the Routing and Remote Access Service functions for developing software to administer dial-up connections.


MprAdminConnectionClearStats

The MprAdminConnectionClearStats function resets the statistics counters for the specified connection.

DWORD MprAdminConnectionClearStats(
  RAS_SERVER_HANDLE hRasServer,       // handle to server
  HANDLE            hRasConnection    // handle to the connection
);

Parameters

hRasServer
Handle to the Remote Access Server on which to execute MprAdminConnectionClearStats. Obtain this handle by calling MprAdminServerConnect.
hRasConnection
Handle to the connection for which to reset the statistics. Obtain this handle by calling MprAdminConnectionEnum.

Return Values

If the function succeeds, the return value will be NO_ERROR.

If the function fails, the return value will be ERROR_INVALID_PARAMETER.

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

MprAdminConnectionEnum, MprAdminServerConnect


MprAdminConnectionEnum

The MprAdminConnectionEnum function enumerates all active connections.

DWORD MprAdminConnectionEnum(
  RAS_SERVER_HANDLE hRasServer,       // handle to the server
  DWORD             dwLevel,          // must be zero
  LPBYTE *          lplpbBuffer,      // pointer to array of connection structs
  DWORD             dwPrefMaxLen,     // maximum preferred length of returned data
  DWORD             lpdwEntriesRead,  // number of connections enumerated
  DWORD             lpdwTotalEntries, // number of connections that could've been enumerated
  LPDWORD           lpdwResumeHandle  // handle with which to resume enumeration
);

Parameters

hRasServer
Handle to the Remote Access Server on which connections will be enumerated. This handle is obtained from a previous call to MprAdminServerConnect.
dwLevel
This parameter must be zero.
lplpbBuffer
Upon successful execution, lplpbBuffer will point to an array of RAS_CONNECTION_0 structures. Free this memory by calling MprAdminBufferFree.
dwPrefMaxLen
Preferred maximum length of returned data (in 8-bit bytes). If dwPrefMaxLen is -1, the buffer returned will be large enough to hold all available information.
lpdwEntriesRead
Pointer to a DWORD variable. Upon successful return, this variable contains the total number of connections enumerated from the current resume position.
lpdwTotalEntries
Pointer to a DWORD variable. Upon successful return, this variable contains the total number of connections that could have been enumerated from the current resume position.
lpdwResumeHandle
Pointer to a DWORD variable. Upon successful return, this variable contains a resume handle that can be used to continue the enumeration. The lpdwResumeHandle parameter should be zero on the first call, and left unchanged on subsequent calls. If the return code is ERROR_MORE_DATA, the call may be re-issued with this handle to retrieve more data. If the handle is NULL upon return, the enumeration cannot be continued. This handle is invalid for other types of error returns.

Return Values

If the function succeeds, the return value will be NO_ERROR.

If the function fails, the return value will be ERROR_INVALID_PARAMETER.

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

MprAdminServerConnect, MprAdminBufferFree, RAS_CONNECTION_0


MprAdminConnectionGetInfo

The MprAdminConnectionGetInfo function provides information on a specific connection.

DWORD MprAdminConnectionGetInfo(
  RAS_SERVER_HANDLE hRasServer,    // handle to server
  DWORD             dwLevel,       // level of info returned
  HANDLE            hConnection,   // handle to connection
  LPBYTE *          lplpbBuffer    // pointer to returned info
);

Parameters

hRasServer
Handle to the Windows NT Routing and RAS machine on which connection information will be gathered. Obtain this handle by calling MprAdminServerConnect.
dwLevel
Specifies the format and content of the returned information. Acceptable values for dwLevel are zero or one. A value of zero will return a RAS_CONNECTION_0 structure; a value of one will return a RAS_CONNECTION_1 structure
hConnection
Handle to the connection for which to obtain information. Obtain this handle by calling MprAdminConnectionEnum.
lplpbBuffer
Pointer to a pointer variable that will point to a RAS_CONNECTION_0 or RAS_CONNECTION_1 structure upon successful execution. Free this memory by calling MprAdminBufferFree.

Return Values

If the function succeeds, the return value will be NO_ERROR.

If the function fails, the return value will be ERROR_INVALID_PARAMETER.

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

MprAdminServerConnect, MprAdminBufferFree, MprAdminConnectionEnum, RAS_CONNECTION_0, RAS_CONNECTION_1


MprAdminPortClearStats

The MprAdminPortClearStats function resets the statistics for the specified port.

DWORD MprAdminPortClearStats(
  RAS_SERVER_HANDLE hRasServer,   // handle to the server
  HANDLE            hPort         // handle to the port
);

Parameters

hRasServer
Handle to the Remote Access Server on which to clear the statistics for the specified port. Obtain this handle by calling MprAdminServerConnect.
hPort
Handle to the port for which statistics will be reset. Obtain this handle by calling MprAdminPortEnum.

Return Values

If the function succeeds, the return value will be NO_ERROR.

If the function fails, the return value will be ERROR_INVALID_PARAMETER.

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

MprAdminServerConnect, MprAdminPortEnum


MprAdminPortDisconnect

The MprAdminPortDisconnect function disconnects a connection on a specific port.

DWORD MprAdminPortDisconnect(
  RAS_SERVER_HANDLE hRasServer,    // handle to the server
  HANDLE            hPort          // handle to the port
);

Parameters

hRasServer
Handle to the Remote Access Server on which to disconnect the port. Obtain this handle by calling MprAdminServerConnect.
hPort
Handle to the port to disconnect. Obtain this handle by calling MprAdminPortEnum.

Return Values

If the function succeeds, the return value will be NO_ERROR.

If the function fails, the return value will be ERROR_INVALID_PARAMETER.

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

MprAdminServerConnect, MprAdminPortEnum


MprAdminPortEnum

The MprAdminPortEnum function enumerates all active ports in a specific connection, or all ports available for use or currently in use by RAS.

DWORD MprAdminPortEnum(
  RAS_SERVER_HANDLE hRasServer,        // handle to the server
  DWORD             dwLevel,           // must be zero
  HANDLE            hConnection,       // handle to connection
  LPBYTE *          lplpbBuffer,       // pointer to array of port structs
  DWORD             dwPrefMaxLen,      // maximum preferred length of returned data
  DWORD             lpdwEntriesRead,   // number of ports enumerated
  DWORD             lpdwTotalEntries,  // number of ports that could've been enumerated
  LPDWORD           lpdwResumeHandle   // handle with which to
                                       // resume enumeration
);

Parameters

hRasServer
Handle to the Remote Access Server on which to enumerate ports. Obtain this handle by calling MprAdminServerConnect.
dwLevel
This parameter must be zero.
hConnection
Handle to a connection within which the active ports will be enumerated. If hConnection is INVALID_HANDLE_VALUE, all the ports in use or available for use by Routing and RAS will be enumerated. Obtain the hConnection handle by calling MprAdminConnectionEnum.
lplpbBuffer
Pointer to a pointer variable that will point to an array of RAS_PORT_0 structures on successful return. Free this memory by calling MprAdminBufferFree.
dwPrefMaxLen
Preferred maximum length of returned data (in 8-bit bytes). If dwPrefMaxLen is -1, the buffer returned will be large enough to hold all available information.
lpdwEntriesRead
Pointer to a DWORD variable. Upon successful return, this variable contains the total number of ports enumerated from the current resume position.
lpdwTotalEntries
Pointer to a DWORD variable. Upon successful return, this variable contains the total number of ports that could have been enumerated from the current resume position.
lpdwResumeHandle
Pointer to a DWORD variable. Upon successful execution, lpdwResumeHandle contains a resume handle that can be used to continue the enumeration. LpdwResumeHandle should be zero on the first call, and left unchanged on subsequent calls. If the return code is ERROR_MORE_DATA, the call may be re-issued with the handle to retrieve more data. If the handle is NULL upon return, the enumeration cannot be continued. This handle is invalid for other types of error returns.

Return Values

If the function succeeds, the return value will be NO_ERROR.

If the function fails, the return value will be ERROR_INVALID_PARAMETER.

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

MprAdminBufferFree, MprAdminServerConnect, MprAdminConnectionEnum


MprAdminPortGetInfo

The MprAdminPortGetInfo function gets information for a specific port.

DWORD MprAdminPortGetInfo(
  RAS_SERVER_HANDLE hRasServer,    // handle to the server
  DWORD             dwLevel,       // level of info returned
  HANDLE            hPort,         // handle to port
  LPBYTE *          lplpbBuffer    // pointer returned data
);

Parameters

hRasServer
Handle to the Remote Access Server computer on which to collect port information. Obtain this handle by calling MprAdminServerConnect.
dwLevel
Specifies the format and content of the returned information. Acceptable values for dwLevel are zero or one. A value of zero will return a RAS_CONNECTION_0 structure; a value of one will return a RAS_CONNECTION_1 structure.
hPort
Handle to the port for which to collect information. Obtain this handle by calling MprAdminPortEnum.
lplpbBuffer
Pointer to a pointer variable that will point to a RAS_PORT_0 or RAS_PORT_1 structure on successful return. Free this memory by calling MprAdminBufferFree.

Return Values

If the function succeeds, the return value will be NO_ERROR.

If the function fails, the return value will be ERROR_INVALID_PARAMETER.

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

MprAdminServerConnect, MprAdminBufferFree, MprAdminPortEnum


MprAdminPortReset

The MprAdminPortReset function resets the communication device attached to the specified port.

DWORD MprAdminPortReset(
  RAS_SERVER_HANDLE hRasServer,    // handle to the server
  HANDLE            hPort          // handle to the port
);

Parameters

hRasServer
Handle to the Remote Access Server on which to reset the specified port. Obtain this handle by calling MprAdminServerConnect.
hPort
Handle to the port to be reset. Obtain this handle by calling MprAdminPortEnum.

Return Values

If the function succeeds, the return value will be NO_ERROR.

If the function fails, the return value will be ERROR_INVALID_PARAMETER.

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

MprAdminServerConnect, MprAdminPortEnum


RAS Administration Callout Functions

The following functions allow third parties to develop DLLs to customize the following aspects of RAS.

  • Control which remote access clients have access.
  • Event logging of remote access client connection and disconnection.
  • Logging and control of IP address allocation to remote access clients.


MprAdminAcceptNewConnection

The MprAdminAcceptNewConnection function is called each time a new user dials in and successfully completes RAS authentication.

BOOL MprAdminAcceptNewConnection(
  RAS_CONNECTION_0 * pRasConnection0,   // struct that describes connection
  RAS_CONNECTION_1 * pRasConnection1    // struct that describes connection
);

Parameters

pRasConnection0
Pointer to a RAS_CONNECTION_0 structure describing this connection.
pRasConnection1
Pointer to a RAS_CONNECTION_1 structure describing this connection.

Return Values

If RAS accepts the new connection, the return value is TRUE.

If RAS does not accept the new connection, the return value is FALSE.

Remarks

If RAS does not accept the new connection, RAS will not call the MprAdminConnectionHangupNotification function.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in mprapi.h.
Import Library: user-defined.

See Also

MprAdminConnectionHangupNotification, RAS_CONNECTION_0, RAS_CONNECTION_1


MprAdminAcceptNewLink

RAS calls the MprAdminAcceptNewLink function each time a link is created for particular connection. RAS will call this function once immediately after MprAdminAcceptNewConnection, and an additional time for every new link that is to be used with the connection.

BOOL MprAdminAcceptNewLink(
  RAS_PORT_0 * pRasPort0,    // struct that describes the port
  RAS_PORT_1 * pRasPort1     // struct that describes the port
);

Parameters

pRasPort0
Pointer to a RAS_PORT_0 structure that describes the port being used by the link.
pRasPort1
Pointer to a RAS_PORT_1 structure that describes the port being used by the link.

Return Values

If RAS should accept the new link, the return value should be TRUE.

If RAS should not accept the new link, the return value should be FALSE.

Remarks

If RAS does not accept the new link, RAS will not call the MprAdminLinkHangupNotification function.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in mprapi.h.
Import Library: user-defined.

See Also

MprAdminAcceptNewConnection, MprAdminConnectionHangupNotification, MprAdminLinkHangupNotification, RAS_PORT_0, RAS_PORT_1


MprAdminConnectionHangupNotification

The MprAdminConnectionHangupNotification function is called after the last link for the specified connection has been dismantled.

VOID MprAdminConnectionHangupNotification(
  RAS_CONNECTION_0 * pRasConnection0,   // struct that describes connection
  RAS_CONNECTION_1 * pRasConnection1    // struct that describes connection
);

Parameters

pRasConnection0
Pointer to a RAS_CONNECTION_0 structure describing this connection.
pRasConnection1
Pointer to a RAS_CONNECTION_1 structure describing this connection.

Return Values

This function does not have a return value.

See Also

MprAdminAcceptNewConnection, MprAdminAcceptNewLink, MprAdminConnectionHangupNotification, RAS_CONNECTION_0, RAS_CONNECTION_1


MprAdminGetIpAddressForUser

RAS calls MprAdminGetIpAddressForUser once for each user that requires an IP address. RAS calls the function with the IP address that RAS selects for the user. The third-party DLL that implements this function may change this address to one of its own choosing.

DWORD MprAdminGetIpAddressForUser(
  WCHAR * lpwszUserName,    // pointer to username
  WCHAR * lpwszPortName,    // pointer to port name
  DWORD * lpdwIpAddress,    // pointer to IP address
  BOOL *  bNotifyRelease    // notify DLL when user disconnects
);

Parameters

lpwszUserName
Pointer to a Unicode string containing the name of the user requiring an IP address.
lpwszPortName
Pointer to a Unicode string containing the name of the port on which the user is attempting to connect.
lpdwIpAddress
Pointer to a DWORD variable. When RAS calls the function this variable contains either the IP address RAS intends to allocate for the user or zero. If the variable contains an IP address, the DLL can either accept the address or substitute a different one. If the variable contains a zero, the DLL must allocate an IP address for the user. If this variable is zero, and the DLL does not allocate an IP address, the user will not be able to connect.
bNotifyRelease
Pointer to a BOOL variable. If the DLL sets this variable to TRUE, RAS will call MprAdminReleaseIpAddress when the user disconnects. Otherwise, RAS will not notifiy the DLL when this IP address is released.

Return Values

If function succeeds, the return value should be NO_ERROR.

If the function returns anything other than NO_ERROR, RAS will terminate the connection.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in mprapi.h.
Import Library: user-defined.

See Also

MprAdminReleaseIpAddress


MprAdminLinkHangupNotification

RAS calls the MprAdminLinkHangupNotification function whenever a link for a particular connection is dismantled.

VOID MprAdminLinkHangupNotification(
  RAS_PORT_0 * pRasPort0,    // struct that describes the port
  RAS_PORT_1 * pRasPort1     // struct that describes the port
);

Parameters

pRasPort0
Pointer to a RAS_PORT_0 structure that describes the port being used by the link.
pRasPort1
Pointer to a RAS_PORT_1 structure that describes the port being used by the link.

Return Values

This function does not have a return value.


MprAdminReleaseIpAddress

The MprAdminReleaseIpAddress function is called when a user disconnects and the user's IP address is about to be released.

VOID MprAdminReleaseIpAddress(
  WCHAR * lpwszUserName,    // pointer to username
  WCHAR * lpwszPortName,    // pointer to port name
  DWORD * lpdwIpAddress     // pointer to IP address
);

Parameters

lpwszUserName
Pointer to a Unicode string containing the name of the user requiring an IP address.
lpwszPortName
Pointer to a Unicode string containing the name of the port on which the user is attempting to connect.
lpdwIpAddress
Pointer to a DWORD variable. This variable contains the IP address to be released.

Return Values

This function does not have a return value.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in mprapi.h.
Import Library: user-defined.

See Also

MprAdminConnectionHangupNotification, MprAdminGetIpAddressForUser


RAS User Administration API list

RAS User Administration Functions

To obtain a list of current users on a particular domain, use the NetQueryDisplayInformation function. The prototype for this function is in the lmaccess.h header file.


MprAdminGetPDCServer

The MprAdminGetPDCServer function retrieves the name of the server with the master User Accounts Subsystem (UAS) from either a domain name or a server name. This server will be either the primary domain controller or a backup domain controller. Either the domain name parameter or the server name parameter may be NULL, but not both.

DWORD MprAdminGetPDCServer(
    const WCHAR *   lpwsDomainName,  // pointer to domain name
    const WCHAR *   lpwsServerName,  // pointer to server name
          LPWSTR    lpwsPDCServer    // pointer to buffer to receive
                                     // name of server with UAS
);

Parameters

lpwsDomainName
Pointer to a Unicode string containing the name of the domain for which to retrieve the server with the UAS.
lpwsServerName
Pointer to a Unicode string containing the name of a PDC or BDC in the domain for which to retrieve the server with the UAS.
lpwsPDCName
Pointer to a buffer at least UNCLEN+1 WCHARs in size. Upon successful return, this buffer will contain the name of the PDC or a BDC for the specified domain. See lmcons.h for more information.

Return Values

If the function succeeds, the return value will be NO_ERROR.

If the function fails the return value will be one of the following values.

Value | Meaning
NERR_DCNotFound | Could not find the domain controller for the domain.
ERROR_INVALID_NAME | The name could not be found.

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.


MprAdminUserGetInfo

The MprAdminUserGetInfo function retrieves all RAS information for a particular user.

DWORD MprAdminUserGetInfo(
    const WCHAR *  lpwsServerName,  // name of PDC or BDC with UAS
    const WCHAR *  lpwsUserName,    // name of user
          DWORD    dwLevel,         // must be zero
          LPBYTE   lpbBuffer        // RAS_USER_0 structure
);

Parameters

lpwsServerName
Pointer to a Unicode string containing the name of the server computer with the master User Accounts Subsystem. This computer will be either the primary domain controller or the backup domain controller. Use the MprAdminGetPDCServer function to obtain this name.
lpwsUserName
Pointer to a Unicode string containing the name of the user for which to get RAS information.
dwLevel
This parameter must be zero.
lpbBuffer
Pointer to a RAS_USER_0 structure. The caller must allocate (and free) the memory for this structure. Upon successful return, this structure contains the RAS data for the specified user.

Return Values

If the function succeeds, the return value will be NO_ERROR.

If the function fails the return value will be one of the following values.

Value | Meaning
ERROR_ACCESS_DENIED | The caller does not have sufficient privilege.
ERROR _INVALID_PARAMETER | The value of dwLevel is invalid.

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

MprAdminGetPDCServer, MprAdminUserSetInfo, RAS_USER_0


MprAdminUserSetInfo

The MprAdminUserSetInfo function sets RAS information for the specified user.

DWORD MprAdminUserSetInfo(
    const WCHAR *  lpwsServerName,  // name of PDC or BDC with UAS
    const WCHAR *  lpwsUserName,    // name of user
          DWORD    dwLevel,         // must be zero
    const LPBYTE   lpbBuffer        // RAS_USER_0 structure
);

Parameters

lpwsServerName
Pointer to a Unicode string containing the name of the server computer with the master User Accounts Subsystem. This computer will be either the primary domain controller or the backup domain controller. Use the MprAdminGetPDCServer function to obtain this name.
lpwsUserName
Pointer to a Unicode string containing the name of the user for which to set RAS information.
dwLevel
This parameter must be zero.
lpbBuffer
Pointer to a RAS_USER_0 structure that specifies the new RAS information for the user.

Return Values

If the function succeeds, the return value will be NO_ERROR.

If the function fails, the return value will be one of the following values.

Value | Meaning
ERROR_ACCESS_DENIED | The caller does not have sufficient privilege.
ERROR _INVALID_PARAMETER | The value of dwLevel is invalid.

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

MprAdminGetPDCServer, MprAdminUserGetInfo, RAS_USER_0


RAS Administration Structures

The RAS Administration Functions use the following structures.


PPP_ATCP_INFO

The PPP_ATCP_INFO structure contains the result of a PPP AppleTalk projection operation.

typedef struct _PPP_ATCP_INFO {
    DWORD    dwError;
    WCHAR    wszAddress[ ATADDRESSLEN + 1 ];
} PPP_ATCP_INFO;

Members

dwError
Contains the result of the PPP control protocol negotiation. A value of zero indicates success. A nonzero value indicates failure, and is the actual fatal error that occurred during the control protocol negotiation.
wszAddress
Contains a Unicode string that holds the client's AppleTalk address on the RAS connection.

See Also

PPP_INFO


PPP_INFO

The PPP_INFO structure is used to report the results of the various PPP projection operations for a connection.

typedef struct _PPP_INFO {
    PPP_NBFCP_INFO    nbf;
    PPP_IPCP_INFO     ip;
    PPP_IPXCP_INFO    ipx;
    PPP_ATCP_INFO     at;
} PPP_INFO;

Members

nbf
Holds a PPP_NBFCP_INFO structure.
ip
Holds a PPP_IPCP_INFO structure.
ipx
Holds a PPP_IPXCP_INFO structure.
at
Holds a PPP_ATCP_INFO structure.

See Also

PPP_ATCP_INFO, PPP_IPCP_INFO, PPP_IPXCP_INFO, PPP_NBFCP_INFO, RAS_CONNECTION_1


PPP_IPCP_INFO

The PPP_IPCP_INFO structure contains the result of a PPP Internet Protocol (IP) projection operation.

typedef struct _PPP_IPCP_INFO {
    DWORD    dwError;
    WCHAR    wszAddress[ IPADDRESSLEN + 1 ];
    WCHAR    wszRemoteAddress[ IPADDRESSLEN + 1 ];
} PPP_IPCP_INFO;

Members

dwError
Contains the result of the PPP control protocol negotiation. A value of zero indicates success. A nonzero value indicates failure, and is the actual fatal error that occurred during the control protocol negotiation.
wszAddress
Contains a Unicode string that holds the client's IP address on the RAS connection.
wszRemoteAddress
Contains a Unicode string that holds the IP address of the remote PPP peer (that is, the server's IP address). PPP does not require that servers provide this address, but Windows NT servers will consistently return the address anyway. Other PPP vendors may not provide the address. If the address is not available, this member returns an empty string, "".

See Also

PPP_INFO


PPP_IPXCP_INFO

The PPP_IPXCP_INFO structure contains the result of a PPP Internetwork Packet Exchange (IPX) projection operation.

typedef struct _PPP_IPXCP_INFO {
    DWORD    dwError;
    WCHAR    wszAddress[ IPXADDRESSLEN + 1 ];
} PPP_IPXCP_INFO;

Members

dwError
Contains the result of the PPP control protocol negotiation. A value of zero indicates success. A nonzero value indicates failure, and is the actual fatal error that occurred during the control protocol negotiation.
wszAddress
Contains a Unicode string that holds the client's IPX address on the RAS connection.

See Also

PPP_INFO


PPP_NBFCP_INFO

The PPP_NBFCP_INFO structure contains the result of a PPP NetBEUI Framer (NBF) projection operation.

typedef struct _PPP_NBFCP_INFO {
    DWORD    dwError;
    WCHAR    wszWksta[ NETBIOS_NAME_LEN + 1 ];
} PPP_NBFCP_INFO;

Members

dwError
Contains the result of the PPP control protocol negotiation. A value of zero indicates success. A nonzero value indicates failure, and is the actual fatal error that occurred during the control protocol negotiation.
wszWksta
Contains a Unicode string that is the local workstation's computer name. This unique computer name is the closest NetBIOS equivalent to a client's NetBEUI address on a remote access connection.

See Also

PPP_INFO


RAS_CONNECTION_0

The RAS_CONNECTION_0 structure contains general information regarding a specific connection, such as username or domain. For more detailed information about a specific connection, such as bytes sent or received, see RAS_CONNECTION_1.

typedef struct _RAS_CONNECTION_0 {
    HANDLE                   hConnection;
    HANDLE                   hInterface;
    DWORD                    dwConnectDuration;      // In seconds
    ROUTER_INTERFACE_TYPE    dwInterfaceType;
    DWORD                    dwConnectionFlags;
    WCHAR                    wszInterfaceName[ MAX_INTERFACE_NAME_LEN + 1 ];
    WCHAR                    wszUserName[ UNLEN + 1 ];
    WCHAR                    wszLogonDomain[ DNLEN + 1 ];
    WCHAR                    wszRemoteComputer[ NETBIOS_NAME_LEN + 1 ];

} RAS_CONNECTION_0, *PRAS_CONNECTION_0;

Members

hConnection
Handle to the connection.
hInterface
Handle to the interface.
dwConnectDuration
Duration of the current connection, in seconds.
dwInterfaceType
Interface type of the current conection.
dwConnectionFlags
Connection flags.
wszInterfaceName
Interface Name.
wszUserName
User name logged on to the current connection.
wszLogonDomain
Domain to which the current user is logged onto.
wszRemoteComputer
Name of the remote computer.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in mprapi.h.

See Also

RAS_CONNECTION_1


RAS_CONNECTION_1

The RAS_CONNECTION_1 structure contains specific information regarding a specific connection, such as error counts and bytes received. For more general information about a specific connection, such as username or domain, see RAS_CONNECTION_0.

typedef struct RAS_CONNECTION_1 {
    HANDLE      hConnection;
    HANDLE      hInterface;
    PPP_INFO    pppInfo;
    DWORD       dwBytesXmitted;
    DWORD       dwBytesRcved;
    DWORD       dwFramesXmited;
    DWORD       dwFramesRcved;
    DWORD       dwCrcErr;
    DWORD       dwTimeoutErr;
    DWORD       dwAlignmentErr;
    DWORD       dwHardwareOverrunErr;
    DWORD       dwFramingErr;
    DWORD       dwBufferOverrunErr;
    DWORD       dwBytesXmitedUncompressed;
    DWORD       dwbytesRcvedUncompressed;
    DWORD       dwBytesXmitedCompressed;
    DWORD       dwBytesRcvedCompressed;
} RAS_CONNECTION_1; *PRAS_CONNECTION_1;

Members

hConnection
Handle to the connection.
hInterface
Handle to the interface.
pppInfo
PPP_INFO structure.
dwBytesXmitted
Bytes transmitted on the current connection.
dwBytesRcved
Bytes received on the current connection.
dwFramesXmited
Frames transmitted on the current connection.
dwFramesRcved
Frames received on the current connection.
dwCrcErr
CRC (Cyclic Redundancy Check) errors on the current connection.
dwTimeoutErr
Time out errors on the current connection.
dwAlignmentErr
Alignment errors on the current connection.
dwHardwareOverrunErr
Number of hardware overrun errors on the current connection.
dwFramingErr
Number of framing errors for the current connection.
dwBufferOverrunErr
Number of buffer overrun errors.
dwBytesXmitedUncompressed
Uncompressed bytes of data transmitted on the current connection.
dwbytesRcvedUncompressed
Uncompressed bytes of data received on the current connection.
dwBytesXmitedCompressed
Compressed bytes transmitted on the current connection.
dwBytesRcvedCompressed
Compressed bytes received on the current connection.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in mprapi.h.

See Also

RAS_CONNECTION_0, PPP_INFO


RAS_PORT_0

The RAS_PORT_0 structure contains general information regarding a specific RAS port, such as port condition and port name. For more detailed information about a specific port, such as line speed or errors, see RAS_PORT_1.

typedef struct _RAS_PORT_0 {
    HANDLE                hPort;
    HANDLE                hConnection;
    RAS_PORT_CONDITION    dwPortCondition;
    DWORD                 dwTotalNumberOfCalls;
    DWORD                 dwConnectDuration;      // In seconds
    WCHAR                 wszPortName[ MAX_PORT_NAME + 1 ];
    WCHAR                 wszMediaName[ MAX_MEDIA_NAME + 1 ];
    WCHAR                 wszDeviceName[ MAX_DEVICE_NAME + 1 ];
    WCHAR                 wchDeviceType[ MAX_DEVICETYPE_NAME + 1 ];

} RAS_PORT_0, *PRAS_PORT_0;

Members

hPort
Handle to the port.
hConnection
Handle to the connection.
dwPortCondition
RAS_PORT_CONDITION structure.
dwTotalNumberOfCalls
Total number of calls for the given port.
dwConnectDuration
Duration of the current connection, in seconds.
wszPortName
Port name.
wszMediaName
Media name.
wszDeviceName
Device Name.
wchDeviceType
Device Type.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.

See Also

RAS_PORT_1, RAS_PORT_CONDITION


RAS_PORT_1

The RAS_PORT_1 structure contains detailed information regarding a specific RAS port, such as line speed or errors. For more general information about a port, such as port condition or port name, see RAS_PORT_0.

typedef struct _RAS_PORT_1{
    HANDLE                    hPort;
    HANDLE                    hConnection;
    RAS_HARDWARE_CONDITION    dwHardwareCondition;
    DWORD                     dwLineSpeed;            // in bits/second
    DWORD                     dwBytesXmited;
    DWORD                     dwBytesRcved;
    DWORD                     dwFramesXmited;
    DWORD                     dwFramesRcved;
    DWORD                     dwCrcErr;
    DWORD                     dwTimeoutErr;
    DWORD                     dwAlignmentErr;
    DWORD                     dwHardwareOverrunErr;
    DWORD                     dwFramingErr;
    DWORD                     dwBufferOverrunErr;
    DWORD                     dwBytesXmitedUncompressed;
    DWORD                     dwbytesRcvedUncompressed;
    DWORD                     dwBytesXmitedCompressed;
    DWORD                     dwBytesRcvedCompressed;
} RAS_PORT_1, *PRAS_PORT_1;

Members

hPort
Handle to the port.
hConnection
Handle to the connection.
dwHardwareCondition
RAS_HARDWARE_CONDITION structure.
dwLineSpeed
Line speed of the port, represented in bits per second.
dwBytesXmited
Bytes transmitted on the port.
dwBytesRcved
Bytes received on the port.
dwFramesXmited
Frames transmitted on the port.
dwFramesRcved
Frames received on the port.
dwCrcErr
CRC errors on the port.
dwTimeoutErr
Time out errors on the port.
dwAlignmentErr
Alignment errors on the port.
dwHardwareOverrunErr
Hardware overrun errors on the port.
dwFramingErr
Framing errors on the port.
dwBufferOverrunErr
Buffer overrun errors on the port.
dwBytesXmitedUncompressed
Uncompressed bytes transmitted on the port.
dwbytesRcvedUncompressed
Uncompressed bytes received on the port.
dwBytesXmitedCompressed
Compressed bytes transmitted on the port.
dwBytesRcvedCompressed
Compressed bytes received on the port.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.

See Also

RAS_PORT_0, RAS_HARDWARE_CONDITION


RAS_USER_0

The RAS_USER_0 structure contains information for particular Remote Access Service user.

typedef struct _RAS_USER_0 {
    BYTE     bfPrivilege;    // RASPRIV flags
    WCHAR    wszPhoneNumber[ MAX_PHONE_NUMBER_LEN + 1];
} RAS_USER_0, *PRAS_USER_0;

Members

bfPrivilege
Contains the types of privilege available to the RAS user.
wszPhoneNumber
Pointer to a Unicode string containing the phone number at which the RAS user should be called back.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rassapi.h.

See Also

MprAdminUserGetInfo, MprAdminUserSetInfo, Remote Access Privileges


RAS Administration Enumerated Types

The RAS Administration Functions use the following enumerated types.


RAS_HARDWARE_CONDITION

The RAS_HARDWARE_CONDITION enumeration type specifies hardware status information about a given RAS port.

typedef enum _RAS_HARDWARE_CONDITION {
    RAS_HARDWARE_OPERATIONAL,
    RAS_HARDWARE_FAILURE

} RAS_HARDWARE_CONDITION;

Values

RAS_HARDWARE_OPERATIONAL
The port is operational.
RAS_HARDWARE_FAILURE
The port is not operational, due to a hardware failure.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in mprapi.h.


RAS_PORT_CONDITION

The RAS_PORT_CONDITION enumerated type specifies information regarding the connection condition of a given RAS port.

typedef enum _RAS_PORT_CONDITION
{
    RAS_PORT_NON_OPERATIONAL,
    RAS_PORT_DISCONNECTED,
    RAS_PORT_CALLING_BACK,
    RAS_PORT_LISTENING,
    RAS_PORT_AUTHENTICATING,
    RAS_PORT_AUTHENTICATED,
    RAS_PORT_INITIALIZING

} RAS_PORT_CONDITION;

Values

RAS_PORT_NON_OPERATIONAL
The port is not operational.
RAS_PORT_DISCONNECTED
The port is disconnected.
RAS_PORT_CALLING_BACK
The port is in the process of a call-back.
RAS_PORT_LISTENING
The port is listening for incoming calls.
RAS_PORT_AUTHENTICATING
The port is authenticating a user.
RAS_PORT_AUTHENTICATED
The port has authenticated a user.
RAS_PORT_INITIALIZING
The port is initializing.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in mprapi.h.


Router Administration Reference

Use the following functions, structures, and enumerated types when developing software to administer Microsoft® Windows NT® routers.


Router Administration Functions

Use the following functions when developing software to administer Microsoft® Windows NT® routers.


MprAdminBufferFree

The MprAdminBufferFree function frees memory buffers returned by: MprAdminInterfaceGetInfo, MprAdminInterfaceEnum, MprAdminServerGetInfo, MprAdminInterfaceTransportGetInfo, and MprAdminTransportGetInfo.

DWORD  MprAdminBufferFree(
  PVOID pBuffer    // memory buffer to free
);

Parameters

pBuffer
Pointer to the memory buffer to free.

Return Values

NO_ERROR
The memory was freed successfully.
ERROR_INVALID_PARAMETER
The pBuffer parameter is NULL.

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

MprAdminInterfaceGetInfo, MprAdminInterfaceEnum, MprAdminServerGetInfo , MprAdminInterfaceTransportGetInfo, MprAdminTransportGetInfo


MprAdminGetErrorString

The MprAdminGetErrorString function returns the string associated with a router error from mprerror.h.

DWORD  MprAdminGetErrorString(
  DWORD dwError,                // router error code
  LPWSTR * lplpwsErrorString    // descriptive text for error
);

Parameters

dwError
The error code for a Windows NT router error.
lplpwsErrorString
Pointer to a LPWSTR variable that will point to the text associated with the dwError code on successful return. Free this memory by calling LocalFree.

Return Values

NO_ERROR
Success
ERROR_ACCESS_DENIED
The caller does not have sufficient privilege.
ERROR_INVALID_PARAMETER
The error code in dwError is unknown.

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

LocalFree


MprAdminInterfaceConnect

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


MprAdminInterfaceCreate

The MprAdminInterfaceCreate function creates an interface on a specified server.

DWORD  MprAdminInterfaceCreate(
  MPR_SERVER_HANDLE hMprServer,    // handle to router
  DWORD dwLevel,                   // level of information provided
  LPBYTE lpBuffer,                 // MPR_INTERFACE_0 structure
  HANDLE * phInterface             // handle to the interface
);

Parameters

hMprServer
Handle to the Windows NT router on which to execute this call. Obtain this handle by calling MprAdminServerConnect.
dwLevel
Level of the information passed in lpBuffer. Must be zero.
lpBuffer
Pointer to an MPR_INTERFACE_0 structure that contains the information to create the interface. The hInterface member of this structure is ignored.
phInterface
Pointer to a HANDLE variable. On successful return, the variable contains a handle to use in all subsequent calls to manage this interface.

Return Values

NO_ERROR
The router interface was created successfully.
ERROR_ACCESS_DENIED
The caller does not have sufficient privilege.
ERROR_DDM_NOT_RUNNING
The router interface type specified in the MPR_INTERFACE_0 structure is not supported because the Dynamic Interface Manager is configured to run only on a LAN.
ERROR_INTERFACE_ALREADY_EXISTS
An interface with the same name already exists.
ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.
ERROR_NOT_SUPPORTED
The dwLevel value is invalid.

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

MPR_INTERFACE_0, MprAdminInterfaceDelete, MprAdminServerConnect


MprAdminInterfaceDelete

The MprAdminInterfaceDelete function deletes an interface on a specified server.

DWORD  MprAdminInterfaceDelete(
  MPR_SERVER_HANDLE hMprServer,    // handle to the router
  HANDLE hInterface                // handle to the interface
);

Parameters

hMprServer
A handle to the Windows NT router on which to execute this call. Obtain this handle by calling MprAdminServerConnect.
hInterface
Handle to the interface to delete. Obtain this handle by calling MprAdminInterfaceCreate.

Return Values

NO_ERROR
The router interface was deleted successfully.
ERROR_ACCESS_DENIED
The caller does not have sufficient privilege.
ERROR_INTERFACE_CONNECTED
The interface specified is a demand dial interface and is currently connected.
ERROR_INVALID_HANDLE
The hInterface value is invalid.

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, MprAdminServerConnect


MprAdminInterfaceDisconnect

The MprAdminInterfaceDisconnect function disconnects a connected WAN interface.

DWORD  MprAdminInterfaceDisconnect(
  MPR_SERVER_HANDLE hMprServer,    // handle to router
  HANDLE hInterface                // handle to interface
);

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.

Return Values

NO_ERROR
Success
ERROR_ACCESS_DENIED
The caller does not have sufficient privilege.
ERROR_DDM_NOT_RUNNING
The Demand Dial Manager (DDM) is not running.
ERROR_INVALID_HANDLE
The hInterface value is invalid.
ERROR_INTERFACE_NOT_CONNECTED
This interface is not connected. Therefore, it cannot be disconnected.

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, MprAdminInterfaceConnect, MprAdminServerConnect


MprAdminInterfaceEnum

The MprAdminInterfaceEnum function enumerates all the interfaces on a specified server.

DWORD  MprAdminInterfaceEnum (
  MPR_SERVER_HANDLE hMprServer,    // handle to the router
  DWORD dwLevel,                   // level of information provided
  LPBYTE * lplpbBuffer,            // array of MPR_INTERFACE_0 structures
  DWORD dwPrefMaxLen,              // maximum length of data to return
  HANDLE lpdwEntriesRead,          // number of entries enumerated
  HANDLE lpdwTotalEntries,         // number of entries that could
                                   // have been enumerated
  LPDWORD lpdwResumeHandle         // handle for continuing
                                   // the enumeration
);

Parameters

hMprServer
Handle to the Windows NT router on which to execute this call. Obtain this handle by calling MprAdminServerConnect.
dwLevel
Level of the information passed in lpBuffer. Must be zero.
lplpbBuffer
The address of a pointer variable that will point to an array of MPR_INTERFACE_0 structures on successful return. This memory should be freed by the MprAdminBufferFree call.
dwPrefMaxLen
Specifies the preferred maximum length of returned data (in 8-bit bytes). If this parameter is -1, the buffer returned will be large enough to hold all available information.
lpdwEntriesRead
Pointer to a DWORD variable. On successful return, this variable contains the total number of entries that were enumerated from the current resume position.
lpdwTotalEntries
Pointer to a DWORD variable. On successful return, this variable contains the total number of entries that could have been enumerated from the current resume position.
lpdwResumeHandle
Pointer to a DWORD variable. On successful return, this variable contains a resume handle that can be used to continue the enumeration. The handle should be zero on the first call, and left unchanged on subsequent calls. If the return code is ERROR_MORE_DATA then the call may be re-issued with the handle to retrieve more data. If on return, the handle is NULL, the enumeration cannot be continued. For other types of error returns, this handle is invalid.

This parameter is optional. If the caller specifies NULL for this parameter, the function will not return a resume handle.

Return Values

NO_ERROR
All interfaces were enumerated successfully.
ERROR_ACCESS_DENIED
The caller does not have sufficient privilege.
ERROR_MORE_DATA
More information is available; the enumeration can be continued.
ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.
ERROR_NOT_SUPPORTED
The value of dwLevel is non-zero.

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

MprAdminBufferFree, MprAdminServerConnect


MprAdminInterfaceGetCredentials

Use the MprAdminInterfaceGetCredentials function to retrieve the domain, username, and password for dialing out on the specified demand-dial interface.

DWORD  MprAdminInterfaceGetCredentials(
    LPWSTR    lpwsServer,           // string containing name
                                    // of router
    LPWSTR    lpwsInterfaceName,    // string containing name
                                    // of interface
    LPWSTR    lpwsUserName,         // string to receive username
    LPWSTR    lpwsPassword,         // string to receive password
    LPWSTR    lpwsDomainName        // string to receive domain name
);

Parameters

lpwsServer
Pointer to a Unicode string containing the name of the Windows NT router on which to execute this call.

This parameter is optional. If the caller specifies NULL for this parameter, the call is executed on the local machine.

lpwsInterfaceName
Pointer to a Unicode string containing the name of the demand-dial interface.
lpwsUserName
Pointer to a Unicode string to receive the name of the user. This string should be UNLEN+1 long.

This parameter is optional. If the caller specifies NULL for this parameter, the function will not return the user name.

lpwsPassword
Pointer to a Unicode string to receive the password. This string should be PWLEN+1 long.

This parameter is optional. If the caller specifies NULL for this parameter, the function will not return the password.

lpwsDomainName
Pointer to a Unicode string to receive the domain name. This string should be DNLEN+1 long.

This parameter is optional. If the caller specifies NULL for this parameter, the function will not return the domain name.

Return Values

NO_ERROR
The credentials were retrieved successfully.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY
The specified interface doesn't have any demand dial parameters associated with it.
ERROR_INVALID_PARAMETER
At least, one of the following is true:

The lpwsInterfaceName parameter is NULL.

All three of the lpwsUserName, lpwsPassword, and lpwsDomainName parameters are NULL.

Other
Use FormatMessage to retrieve the system error message corresponding to the error code returned.

Remarks

The lpwsUserName, lpwsPassword, and lpwsDomainName parameters are optional. However, if the caller specifies NULL for all three parameters, MprAdminInterfaceGetCredentials will return ERROR_INVALID_PARAMETER.

The constants UNLEN, PWLEN, and DNLEN are the maximum lengths for the username, password, and domain name. These constants are defined in lmcons.h.

Note that the order of the parameters in MprAdminInterfaceGetCredentials is different from MprAdminInterfaceSetCredentials.

See Also

FormatMessage , MprAdminInterfaceSetCredentials


MprAdminInterfaceGetHandle

The MprAdminInterfaceGetHandle function retrieves a handle to a specified interface.

DWORD  MprAdminInterfaceGetHandle(
  MPR_SERVER_HANDLE hMprServer,    // handle to router
  LPWSTR lpwsInterfaceName,        // name of interface
  HANDLE * phInterface,            // handle to interface
  BOOL fIncludeClientInterfaces    // toggles inclusion of
                                   // client interfaces
);

Parameters

hMprServer
Handle to the Windows NT router on which this call will be executed. Obtain this handle by calling MprAdminServerConnect.
lpwsInterfaceName
Pointer to a Unicode string that contains the name of the interface to be retrieved.
phInterface
Pointer to a HANDLE variable that, on successful return, will contain a handle to the interface specified by lpwsInterfaceName.
fIncludeClientInterfaces
If this parameter is FALSE, interfaces of type ROUTER_IF_TYPE_CLIENT will be ignored in the search for the interface with the name specified by lpwsInterfaceName. If this parameter is TRUE, a handle to an interface of type ROUTER_IF_TYPE_CLIENT may be returned. Since it is possible that there are several interfaces of type ROUTER_IF_TYPE_CLIENT, the handle returned will be for the first interface found with the name specified by lpwsInterfaceName.

Return Values

NO_ERROR
Success
ERROR_ACCESS_DENIED
The caller does not have sufficient privilege.
ERROR_INVALID_PARAMETER
lpwsInterfaceName is NULL.
ERROR_NO_SUCH_INTERFACE
No interface exists with the name specified by lpwsInterfaceName.

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

ROUTER_INTERFACE_TYPE, MprAdminServerConnect


MprAdminInterfaceGetInfo

The MprAdminInterfaceGetInfo function retrieves information for a specified interface on a specified server.

DWORD  MprAdminInterfaceGetInfo(
  MPR_SERVER_HANDLE hMprServer,    // handle to router
  HANDLE hInterface,               // handle to interface
  DWORD dwLevel,                   // level of information
  LPBYTE * lplpbBuffer             // buffer for information
);

Parameters

hMprServer
A handle to the Windows NT router to query. This handle is obtained from a previous call to MprAdminServerConnect.
hInterface
A handle to the interface obtained by a previous call to MprAdminInterfaceCreate.
dwLevel
The level of the information returned in lplpbBuffer. Must be zero.
lplpbBuffer
The address of a pointer. On successful return, this pointer will point to an MPR_INTERFACE_0 structure. Free this memory by calling MprAdminBufferFree.

Return Values

NO_ERROR
Router interface created successfully.
ERROR_ACCESS_DENIED
The caller does not have sufficient privilege.
ERROR_INVALID_HANDLE
The hInterface value is invalid.
ERROR_INVALID_PARAMETER
lplpbBuffer is NULL.
ERROR_NOT_ENOUGH_MEMORY
Not enough resources to complete the operation.
ERROR_NOT_SUPPORTED
The dwLevel value is invalid.

See Also

MPR_INTERFACE_0, MprAdminBufferFree, MprAdminInterfaceCreate, MprAdminServerConnect


MprAdminInterfaceQueryUpdateResult

The MprAdminInterfaceQueryUpdateResult function returns the result of the last request to a specified router manager to update its routes for a specified interface. For more information see MprAdminInterfaceUpdateRoutes.

DWORD  MprAdminInterfaceQueryUpdateResult(
  MPR_SERVER_HANDLE hMprServer,    // handle to router
  HANDLE hInterface,               // handle to interface
  DWORD dwTransportId,             // transport/router manager ID
  LPDWORD lpdwUpdateResult         // result of last route update
);

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.
dwTransportId
A DWORD variable containing the transport identifier. This parameter identifies the router manager that updated its routing information.
lpdwUpdateResult
A pointer to a DWORD variable. On successful return, this variable will contain the result of the last call to MprAdminInterfaceUpdateRoutes.

Return Values

NO_ERROR
Success
ERROR_ACCESS_DENIED
The caller does not have sufficient privilege.
ERROR_INTERFACE_NOT_CONNECTED
The specified interface is not connected; the result of the last update is no longer available.
ERROR_INVALID_HANDLE
The hInterface value is invalid.
ERROR_INVALID_PARAMETER
The lpdwUpdateResult parameter is NULL.
ERROR_NO_SUCH_INTERFACE
The specified transport is not running on the specified interface.
ERROR_UNKNOWN_PROTOCOL_ID
The dwTransportId value does not match any installed router manager.

Remarks

The dwTransportId parameter specifies both a transport and a router manager, since Windows NT router maintains a unique router manager for each transport.

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, MprAdminInterfaceUpdateRoutes, MprAdminServerConnect


MprAdminInterfaceSetCredentials

Use MprAdminInterfaceSetCredentials function to set the domain, username, and password that will be used for dialing out on the specified demand-dial interface.

MprAdminInterfaceSetCredentials (
    LPWSTR    lpwsServer,           // string containing name
                                    // of router
    LPWSTR    lpwsInterfaceName,    // string containing name
                                    // of interface
    LPWSTR    lpwsUserName,         // string containing username
    LPWSTR    lpwsDomainName,       // string containing domain name
    LPWSTR    lpwsPassword          // string containing password
);

Parameters

lpwsServer
Pointer to a Unicode string containing the name of the Windows NT router on which to execute this call.

This parameter is optional. If the caller specifies NULL for this parameter, the call is executed on the local machine.

lpwsInterfaceName
Pointer to a Unicode string containing the name of the demand-dial interface.
LpwsUserName
Pointer to a Unicode string containing the username.

This parameter is optional. If the caller specifies NULL for this parameter, the function will not change the username associated with this interface.

LpwsPassword
Pointer to a Unicode string containing the password.

This parameter is optional. If the caller specifies NULL for this parameter, the function will not change the password associated with this interface.

LpwsDomainName
Pointer to a Unicode string containing the domain name.

This parameter is optional. If the caller specifies NULL for this parameter, the function will not change the domain name associated with this interface.

Return Values

NO_ERROR
The credentials were set successfully.
ERROR_INVALID_PARAMETER
At least, one of the following is true:

The lpwsInterfaceName parameter is NULL, or it is longer than MAX_INTERFACE_NAME_LEN.

At least one of the lpwsUserName, lpwsPassword, and lpwsDomainName parameters too long, and therefore invalid. See Remarks section for more information.

ERROR_NOT_ENOUGH_MEMORY
Insufficient memory to create a new data structure to contain the credentials.
Other
Use FormatMessage to retrieve the system error message corresponding to the error code returned.

Remarks

The lpwsUserName, lpwsPassword, and lpwsDomainName parameters are optional. If the caller specifies NULL for all three parameters, MprAdminInterfaceSetCredentials will remove all credential information for this interface.

The constants UNLEN, PWLEN, and DNLEN are the maximum lengths for the username, password, and domain name. These constants are defined in lmcons.h.

Note that the order of the parameters in MprAdminInterfaceSetCredentials is different from MprAdminInterfaceGetCredentials.

See Also

FormatMessage , MprAdminInterfaceGetCredentials, MprAdminInterfaceGetInfo


MprAdminInterfaceTransportAdd

The MprAdminInterfaceTransportAdd function adds a transport (for example, IP or IPX) to an specified interface.

DWORD  MprAdminInterfaceTransportAdd(
  MPR_SERVER_HANDLE hMprServer,    // handle to the router
  HANDLE hInterface,               // handle to the interface
  DWORD dwTransportlId,            // transport/router manager ID
  LPBYTE pInterfaceInfo,           // interface information
  DWORD dwInterfaceInfoSize        // size of interface information
);

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 to which to add the transport. This handle is obtained by a previous call to MprAdminInterfaceCreate.
dwTransportId
Identifies the transport to add to the interface.
pInterfaceInfo
Pointer to a buffer containing interface information for this transport.
dwInterfaceInfoSize
The size, in bytes, of the information pointed to by pInterfaceInfo.

Remarks

Note that the dwTransportId parameter also specifies a unique router manager, since Windows NT router uses a different router manager for each transport.

Return Values

NO_ERROR
The interface was added successfully.
ERROR_ACCESS_DENIED
The caller does not have sufficient privilege.
ERROR_INVALID_HANDLE
The hInterface value is invalid.
ERROR_INVALID_PARAMETER
The pInterfaceInfo parameter is NULL.
ERROR_UNKNOWN_PROTOCOL_ID
The dwTransportId value does not match any installed transport/router manager.

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, MprAdminInterfaceTransportRemove, MprAdminServerConnect


MprAdminInterfaceTransportGetInfo

The MprAdminInterfaceTransportGetInfo function retrieves information about a transport running on an specified interface.

DWORD  MprAdminInterfaceTransportGetInfo(
  MPR_SERVER_HANDLE hMprServer,    // handle to router
  HANDLE hInterface,               // handle to interface
  DWORD dwTransportId,             // transport/router manager ID
  LPBYTE * ppInterfaceInfo,        // buffer to receive
                                   // interface information
  LPDWORD lpdwInterfaceInfoSize    // size of interface
                                   // information returned
);

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.
dwTransportId
Identifies the transport/router manager for which information is requested.
ppInterfaceInfo
Pointer to a pointer variable. On successful return, the pointer variable will point to interface information for the specified transport.
lpdwInterfaceInfoSize
Pointer to a DWORD variable. On successful return, this variable contains the size in bytes of the interface information returned through the ppInterfaceInfo parameter.

This parameter is optional. If the caller specifies NULL for this parameter, the function will not return the size of the interface information.

Return Values

NO_ERROR
Success
ERROR_ACCESS_DENIED
The caller does not have sufficient privilege.
ERROR_INVALID_HANDLE
The hInterface value is invalid.
ERROR_NO_SUCH_INTERFACE
The specified transport is not running on the specified interface.
ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.
ERROR_UNKNOWN_PROTOCOL_ID
The dwTransportId value does not match any installed transport/router manager.

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, MprAdminInterfaceTransportSetInfo, MprAdminServerConnect


MprAdminInterfaceTransportRemove

The MprAdminInterfaceTransportRemove function removes a transport (for example, IP or IPX) from an specified interface.

DWORD  MprAdminInterfaceTransportRemove(
  MPR_SERVER_HANDLE hMprServer,    // handle to router
  HANDLE hInterface,               // handle to interface
  DWORD dwTransportlId             // transport/router manager ID
);

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 from which to remove the transport. Obtain this handle by calling MprAdminInterfaceCreate.
dwTransportId
Identifies the transport to remove from the interface.

Return Values

NO_ERROR
The interface was removed successfully.
ERROR_ACCESS_DENIED
The caller does not have sufficient privilege.
ERROR_INTERFACE_CONNECTED
The interface specified is a demand dial interface and is currently connected.
ERROR_INVALID_HANDLE
The hInterface value is invalid.
ERROR_NO_SUCH_INTERFACE
The specified transport is not running on the specified interface.
ERROR_UNKNOWN_PROTOCOL_ID
The dwTransportId value does not match any installed transport.

Remarks

Note that the dwTransportId parameter also specifies a unique router manager, since Windows NT router uses a different router manager for each transport.

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, MprAdminInterfaceTransportAdd, MprAdminServerConnect


MprAdminInterfaceTransportSetInfo

The MprAdminInterfaceTransportSetInfo function sets information for a transport running on an specified interface.

DWORD  MprAdminInterfaceTransportSetInfo(
  MPR_SERVER_HANDLE hMprServer,    // handle to router
  HANDLE hInterface,               // handle to interface
  DWORD dwTransportId,             // identifier for the transport
  LPBYTE pInterfaceInfo,           // interface information
  DWORD dwInterfaceInfoSize        // size of interface information
);

Parameters

hMprServer
Handle to the Windows NT router on which to execute this call. Obtain the handle by calling MprAdminServerConnect.
hInterface
Handle to the interface. Obtain this handle by calling MprAdminInterfaceCreate.
dwTransportId
Identifies the transport for which information will be set.
pInterfaceInfo
Pointer to the interface information for this transport.
dwInterfaceInfoSize
Specifies the size, in bytes, of the information pointed to by pInterfaceInfo.

Return Values

NO_ERROR
Information for the interface was set successfully.
ERROR_ACCESS_DENIED
The caller does not have sufficient privilege.
ERROR_INVALID_HANDLE
The hInterface value is invalid.
ERROR_INVALID_PARAMETER
The pInterfaceInfo parameter is NULL.
ERROR_NO_SUCH_INTERFACE
The specified transport is not running on the specified interface.
ERROR_UNKNOWN_PROTOCOL_ID
The dwTransportId value does not match any installed transport.

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, MprAdminServerConnect,

MprAdminInterfaceTransportGetInfo


MprAdminInterfaceUpdatePhonebookInfo

Call the MprAdminInterfaceUpdatePhonebookInfo function after making any changes to the phonebook entry for the specified demand dial interface. This function forces the router to pick up the changes for that interface.

DWORD  MprAdminInterfaceUpdatePhonebookInfo (
    MPR_SERVER_HANDLE       hMprServer,   // handle to the router
    HANDLE                  hInterface    // handle to the interface
);

Parameters

hMprServer
Handle to the Windows NT router on which to execute this call. Obtain the handle by calling MprAdminServerConnect.
hInterface
Handle to a demand-dial interface. Obtain this handle by calling MprAdminInterfaceCreate.

Return Values

NO_ERROR
The phonebook information was updated successfully.
ERROR_ACCESS_DENIED
The caller does not have sufficient privilege.
ERROR_CANNOT_LOAD_PHONEBOOK
The function could not load the phonebook into memory.
ERROR_CANNOT_OPEN_PHONEBOOK
The function could not find the phonebook file.
ERROR_DDM_NOT_RUNNING
The Demand Dial Manager (DDM) is not running.
ERROR_INTERFACE_HAS_NO_DEVICES
No device is currently associated with this interface.
ERROR_INVALID_HANDLE
The hInterface value is invalid.
ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to carry out the operation.
Other
Use FormatMessage to retrieve the system error message corresponding to the error code returned.

See Also

FormatMessage, MprAdminInterfaceCreate, MprAdminServerConnect


MprAdminInterfaceUpdateRoutes

The MprAdminInterfaceUpdateRoutes function requests that a specified router manager update its routing information for a specified interface.

DWORD  MprAdminInterfaceUpdateRoutes(
  MPR_SERVER_HANDLE hMprServer,    // handle to router
  HANDLE hInterface,               // handle to interface
  DWORD dwTransportId,             // identifies the router manager
  HANDLE hEvent                    // event to signal when
                                   // update complete
);

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. Obtain this handle by calling MprAdminInterfaceCreate.
dwTransportId
Identifies the router manager that should update its routing information. (Windows NT router uses a different router manager for each transport.)
hEvent
Handle to an event that will be signaled when the attempt to update routing information for this interface has completed. If this value is NULL, then the function is synchronous. If hMprServer specifies a remote router, the caller must specify NULL for this parameter, .

Return Values

NO_ERROR
Success
ERROR_ACCESS_DENIED
The caller does not have sufficient privilege.
ERROR_INTERFACE_NOT_CONNECTED
The specified interface is not connected. Therefore, routes cannot be updated.
ERROR_INVALID_HANDLE
The hInterface value is invalid.
ERROR_NO_SUCH_INTERFACE
The specified transport is not running on the specified interface.
ERROR_UNKNOWN_PROTOCOL_ID
The dwTransportId value does not match any of the router managers.
ERROR_UPDATE_IN_PROGRESS
A routing information update operation is already in progress on this interface.
PENDING
The interface is in the process of updating routing information. The caller should wait on the event object specified by hEvent. After the event is signaled, the status of the update operation can be obtained by calling MprAdminInterfaceQueryUpdateResult.

Remarks

The dwTransportId parameter specifies both a transport (for example, IP or IPX) and a unique router manager, since a Windows NT router uses a different router manager for each transport.

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, MprAdminInterfaceQueryUpdateResult, MprAdminServerConnect


MprAdminIsServiceRunning

The MprAdminIsServiceRunning function checks if the Routing and Remote Access Service is running on a specified machine. If not, none of the MprAdminXXX calls will succeed.

BOOL MprAdminIsServiceRunning(
  LPWSTR lpwsServerName    // name of machine to query
)

Parameters

lpwsServerName
Pointer to a Unicode string containing the name of the server to query.

Return Values

TRUE
The service is running on the specified server.
FALSE
The service is not running on the specified server.

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.


MprAdminServerConnect

Call the MprAdminServerConnect function to connect to the Windows NT router to administer. Call this function before making any other calls to the server. Use the handle returned in subsequent calls to administer interfaces on the server.

DWORD  MprAdminServerConnect(
  LPWSTR lpwsServerName,             // name of router
  MPR_SERVER_HANDLE * phMprServer    // handle to router
)

Parameters

lpwsServerName
Pointer to a Unicode string that contains the name of the remote server.
phMprServer
Pointer to a HANDLE variable that, on successful return, contains a handle to the server. Use this handle in subsequent calls to administer the server.

Return Values

NO_ERROR
Success

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

MprAdminServerDisconnect


MprAdminServerDisconnect

The MprAdminServerDisconnect function disconnects the connection made by a previous call to MprAdminServerConnect.

VOID MprAdminServerDisconnect(
  MPR_SERVER_HANDLE hMprServer    // handle to router
)

Parameters

hMprServer
Handle to the Windows NT router from which to disconnect. Obtain this handle by calling MprAdminServerConnect.

Return Values

None

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

MprAdminServerConnect


MprAdminServerGetInfo

The MprAdminServerGetInfo function retrieves routing and RAS information from a specified server.

DWORD  MprAdminServerGetInfo (
  MPR_SERVER_HANDLE hMprServer,    // handle to router
  DWORD     dwLevel,               // level of information requested
  LPBYTE  * lplpbBuffer            // MPR_SERVER_0 structure
)

Parameters

hMprServer
Handle to the Windows NT router to query. Obtain this handle by calling MprAdminMIBServerConnect.
dwLevel
Level of the information returned in lplpbBuffer. Must be zero.
lplpbBuffer
Pointer to a pointer variable. On successful return, this pointer variable will point to an MPR_SERVER_0 structure. Free this memory by calling MprAdminBufferFree.

Return Values

ERROR_ACCESS_DENIED
The caller does not have sufficient privilege.
ERROR_INVALID_PARAMETER
The lplpbBuffer parameter is NULL.

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

MprAdminBufferFree, MPR_SERVER_0, MprAdminServerConnect


MprAdminTransportGetInfo

The MprAdminTransportGetInfo function retrieves global information, default client interface information, or both, for a specified transport.

DWORD  APIENTRY
MprAdminTransportGetInfo(
  MPR_SERVER_HANDLE hMprServer,          // handle to router
  DWORD dwTransportId,                   // identifies the transport
  LPBYTE * ppGlobalInfo,                 // buffer to receive global
                                         // information for transport
  LPDWORD lpdwGlobalInfoSize,            // size of global information
                                         // returned
  LPBYTE * ppClientInterfaceInfo,        // buffer to receive client
                                         // interface information
  LPDWORD lpdwClientInterfaceInfoSize        // size of client interface
                                         // information returned
)

Parameters

hMprServer
Handle to the Windows NT router to query. This handle is obtained from a previous call to MprAdminServerConnect.
dwTransportId
Identifies the transport about which to retrieve information.
ppGlobalInfo
Pointer to a pointer variable. On successful return, this variable will point to a global information for this transport. Free this memory by calling MprAdminBufferFree.

This parameter is optional. If the caller specifies NULL for this parameter, the function will not retrieve the global information.

lpdwGlobalInfoSize
Pointer to a DWORD variable. On successful return, this variable will contain the size in bytes of the global information for the transport.
ppClientInterfaceInfo
Pointer to a pointer variable. On successful return, this variable will point to default client interface information for this transport. Free this memory by calling MprAdminBufferFree.

This parameter is optional. If the caller specifies NULL for this parameter, the function will not retrieve the client interface information.

lpdwClientInterfaceInfoSize
Pointer to a DWORD variable. On successful return, this variable will contain the size in bytes of the client interface information.

Return Values

NO_ERROR
The information was retrieved successfully.
ERROR_ACCESS_DENIED
The caller does not have sufficient privilege.
ERROR_INVALID_PARAMETER
One of the following is true:

The ppGlobalInfo parameter and the ppClientInterfaceInfo parameter are both NULL.

The ppGlobalInfo parameter doesn't point to valid memory.

The ppClientInterfaceInfo parameter doesn't point to valid memory.

ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to carry out the operation.
ERROR_UNKNOWN_PROTOCOL_ID
The dwTransportId value does not match any installed transport.

Remarks

The ppGlobalInfo and ppClientInterfaceInfo parameters cannot both be NULL.

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

MprAdminBufferFree, MprAdminServerConnect, MprAdminTransportSetInfo


MprAdminTransportSetInfo

The MprAdminTransportSetInfo function sets global information, or default client interface information, or both, for a specified transport.

DWORD  APIENTRY
MprAdminTransportSetInfo(
  MPR_SERVER_HANDLE hMprServer,      // handle to router
  DWORD dwTransportId,               // identifies the transport
  LPBYTE pGlobalInfo,                // global information for transport
  DWORD dwGlobalInfoSize,            // size of global information
  LPBYTE pClientInterfaceInfo,       // information for client interfaces
  DWORD dwClientInterfaceInfoSize    // size of information for client
                                     // interfaces
)
hMprServer
Handle to the Windows NT router on which to set the information. Obtain this handle by calling MprAdminServerConnect.
dwTransportId
Identifies the transport for which to set information.
pGlobalInfo
Pointer to a buffer containing global information for the transport.

This parameter is optional. If the caller specifies NULL for this parameter, the function will not set the global information.

dwGlobalInfoSize
Specifies the size in bytes of the buffer pointed to by the pGlobalInfo parameter.
pClientInterfaceInfo
Pointer to a buffer containing default client interface information for the transport.

This parameter is optional. If the caller specifies NULL for this parameter, the function will not set the default client interface information.

dwClientInterfaceInfoSize
Specifies the size in bytes of the buffer pointed to by the pClientInterfaceInfo parameter.

Return Values

NO_ERROR
The information was set successfully.
ERROR_ACCESS_DENIED
The caller does not have sufficient privilege.
ERROR_INVALID_PARAMETER
The pGlobalInfo parameter and the pClientInterfaceInfo parameter are both NULL.
ERROR_NOT_ENOUGH_MEMORY
Not enough resources to complete the operation.
ERROR_UNKNOWN_PROTOCOL_ID
The dwTransportId value does not match any installed transport.

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

MprAdminServerConnect, MprAdminTransportGetInfo


Router Administration Structures

The Router Administration Functions and the Router Configuration Functions use the following structures.


IPX_ADAPTER_BINDING_INFO

The IPX_ADAPTER_BINDING_INFO structure contains IPX-specific information for a particular network adapter.

typedef struct IPX_ADAPTER_BINDING_INFO {
    ULONG    AdapterIndex;
    UCHAR    Network[4];
    UCHAR    LocalNode[6];
    UCHAR    RemoteNode[6];
    ULONG    MaxPacketSize;
    ULONG    LinkSpeed;
}IPX_ADAPTER_BINDING_INFO, * PIPX_ADAPTER_BINDING_INFO;

Members

AdapterIndex
Identifies the adapter that has been allocated for the interface.
Network[4]
The network number to which the adapter is bound
LocalNode[6]
The node number to which the adapter is bound
RemoteNode[6]
The node number of a peer router or client for demand dial point-to-point connections (for LAN connections this field will be set to the broadcast node address: i.e. 0xFFFFFFFFFFFF)
MaxPacketSize
The maximum packet size that can be transmitted over a connection established on the adapter.
LinkSpeed
The speed of the connection in 100 baud, for example, for 9600 baud connection this value is 96.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in routprot.h.
Import Library: N/A.

See Also

BindInterface, IP_ADAPTER_BINDING_INFO


IP_ADAPTER_BINDING_INFO

The IP_ADAPTER_BINDING_INFO structure contains IP-specific information for a particular network adapter.

typedef struct IP_ADAPTER_BINDING_INFO {
    DWORD               NumAddresses;
    DWORD               RemoteAddress;
    IP_LOCAL_BINDING    Address[1];
}IP_ADAPTER_BINDING_INFO, *PIP_ADAPTER_BINDING_INFO;

Members

NumAddresses
The number of IP addresses associated with this adapter.
RemoteAddress
This member is for WAN interfaces. It contains the address of the machine at the other end of a dial-up link.
Address
Pointer to an array of IP_LOCAL_BINDING structures. The array will contain a structure for each of the IP addresses associated with this adapter.

Remarks

Since an adapter may have more than one IP address, the IP_ADAPTER_BINDING_INFO structure maintains an array of IP_LOCAL_BINDING structures.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in routprot.h.
Import Library: N/A.

See Also

BindInterface, IP_LOCAL_BINDING , IPX_ADAPTER_BINDING_INFO


IP_LOCAL_BINDING

The IP_LOCAL_BINDING structure contains IP address information for an adapter.

typedef struct IP_LOCAL_BINDING {
    DWORD    IPAddress;
    DWORD    Mask;
}IP_LOCAL_BINDING, * PIP_LOCAL_BINDING;

Members

IPAddress
An IP address for the adapter.
Mask
The network mask for the IP address.

Remarks

Since an adapter may have more than one IP address, the IP_ADAPTER_BINDING_INFO structure maintains an array of IP_LOCAL_BINDING structures.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in routprot.h.
Import Library: N/A.

See Also

IP_ADAPTER_BINDING_INFO


MPR_INTERFACE_0

The MPR_INTERFACE_0 structure contains information for a particular router interface.

typedef struct _MPR_INTERFACE_0 {
    WCHAR                  wszInterfaceName[MAX_INTERFACE_NAME_LEN+1];
    HANDLE                     hInterface;
    BOOL                       fEnabled;
    ROUTER_INTERFACE_TYPE      IfType;
    ROUTER_CONNECTION_STATE    dwConnectionState;
    DWORD                      fUnReachabilityReasons;
    DWORD                      dwLastError;
} MPR_INTERFACE_0, * PMPR_INTERFACE_0;

Members

wszInterfaceName
Pointer to a unicode string containing the name of the interface.
hInterface
Handle to the interface
fEnabled
TRUE if the interface is enabled. FALSE if the interface is administratively disabled.
IfType
Type of the interface
dwConnectionState
The current state of the interface, for example connected, disconnected, unreachable. See ROUTER_CONNECTION_STATE for a list of possible states.
fUnReachabilityReasons;
If the interface is unreachable, this member stores the reason.
MPR_INTERFACE_OUT_OF_RESOURCES
No ports or devices are available for use.
MPR_INTERFACE_ADMIN_DISABLED
The administrator has disabled the interface.
MPR_INTERFACE_CONNECTION_FAILURE
The previous connection attempt failed. Look at the dwLastError field for the error code.
MPR_INTERFACE_SERVICE_PAUSED
The service is paused.
dwLastError
Set to non-zero value if the interface fails to connect.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in mprapi.h.
Import Library: N/A.

See Also

MprAdminInterfaceEnum, MprAdminInterfaceGetInfo, ROUTER_CONNECTION_STATE, ROUTER_INTERFACE_TYPE


MPR_IFTRANSPORT_0

The MPR_IFTRANSPORT_0 structure contains information for a particular interface transport.

typedef struct _MPR_IFTRANSPORT_0 {
    DWORD     dwTransportId;
    HANDLE    hIfTransport;
    WCHAR     wszIfTransportName[MAX_TRANSPORT_NAME_LEN+1];
} MPR_IFTRANSPORT_0, *PMPR_IFTRANSPORT_0;

Members

dwTransportId
The transport identifier.
hIfTransport
Handle to the interface transport.
wszIfTransportName
Unicode string containing the name of the interface transport.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in mprapi.h.

See Also

MPR_TRANSPORT_0 , MprConfigInterfaceTransportEnum


MPR_TRANSPORT_0

The MPR_TRANSPORT_0 structure contains information for a particular transport.

typedef struct _MPR_TRANSPORT_0 {
    DWORD     dwTransportId;
    HANDLE    hTransport;
    WCHAR     wszTransportName[MAX_TRANSPORT_NAME_LEN+1];
} MPR_TRANSPORT_0, *PMPR_TRANSPORT_0;

Members

dwTransportId
The transport identifier.
hTransport
Handle to the transport.
wszTransportName
Unicode string containing the name of the transport.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in mprapi.h.

See Also

MPR_IFTRANSPORT_0


MPR_SERVER_0

The MPR_SERVER_0 structure contains information for a particular Windows NT router.

typedef struct MPR_SERVER_0 {
    BOOL     fLanOnlyMode;
    DWORD    dwUptime;
    DWORD    dwTotalPorts;
    DWORD    dwPortsInUse;
} MPR_SERVER_0; *PMPR_SERVER_0;

Members

fLanOnlyMode
If TRUE, the Demand Dial Manager (DDM) is not running on the Windows NT router. If FALSE, the DDM is running on the Windows NT router.
dwUptime
The elapsed time (in seconds) since the router was started.
dwTotalPorts
The number of ports on the system.
dwPortsInUse
The number of ports currently in use.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in mprapi.h.
Import Library: N/A.

See Also

MprAdminServerGetInfo, MprConfigServerGetInfo


Router Administration Enumerated Types

The Router Administration Functions and the Router Configuration Functions use the following enumerated types.


ROUTER_CONNECTION_STATE

The ROUTER_CONNECTION_STATE type enumerates the possible states in which an interface on a Windows NT router may be.

typdef enum _ROUTER_CONNECTION_STATE {
    ROUTER_IF_STATE_UNREACHABLE,
    ROUTER_IF_STATE_DISCONNECTED,
    ROUTER_IF_STATE_CONNECTING,
    ROUTER_IF_STATE_CONNECTED
}ROUTER_CONNECTION_STATE

Values

ROUTER_IF_STATE_UNREACHABLE
The interface is unreachable. Check the fUnreachabilityReasons member in the MPR_INTERFACE_0 structure for more information.
ROUTER_IF_STATE_DISCONNECTED
The interface is reachable but disconnected.
ROUTER_IF_STATE_CONNECTING
The interface is in the process of connecting
ROUTER_IF_STATE_CONNECTED
The interface is connected.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in mprapi.h.

See Also

MPR_INTERFACE_0


ROUTER_INTERFACE_TYPE

The ROUTER_INTERFACE_TYPE type enumerates the different kinds of interfaces on a Windows NT router.

typedef enum _ROUTER_INTERFACE_TYPE {
    ROUTER_IF_TYPE_CLIENT,
    ROUTER_IF_TYPE_HOME_ROUTER,
    ROUTER_IF_TYPE_FULL_ROUTER,
    ROUTER_IF_TYPE_DEDICATED,
    ROUTER_IF_TYPE_INTERNAL,
    ROUTER_IF_TYPE_LOOPBACK
} ROUTER_INTERFACE_TYPE;

Values

ROUTER_IF_TYPE_CLIENT
The interface is for a remote client.
ROUTER_IF_TYPE_HOME_ROUTER
The interface is for a home router.
ROUTER_IF_TYPE_FULL_ROUTER
The interface is for a full router.
ROUTER_IF_TYPE_DEDICATED
The interface is always connected. It is a LAN interface, or the interface is connected over a leased line.
ROUTER_IF_TYPE_INTERNAL
The interface is an internal-only interface.
ROUTER_IF_TYPE_LOOPBACK
The interface is a loopback interface.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in mprapi.h.

See Also

MPR_INTERFACE_0


Information Header Functions

Use the following functions to manipulate router information blocks.


MprInfoBlockAdd

The MprInfoBlockAdd function creates a new header that is identical to an existing header with the addition of the single block.

DWORD MprInfoBlockAdd(
  LPVOID   lpInfoBlock,      // pointer to existing header
  DWORD    dwInfoType,       // info type of new block
  DWORD    dwItemSize,       // size of items in new block
  DWORD    dwItemCount,      // number of items in new block
  LPBYTE   lpItemData,       // data for new block
  LPVOID * lplpNewInfoBlock  // new header (incl. new block)
);

Parameters

lpInfoBlock
Pointer to the header to which to add the new block.
dwInfoType
Specifies the type of block to add. The types available depend on the transport: IP or IPX.
dwItemSize
Specifies the size of each item in the block to be added.
dwItemCount
Specifies the number of items of size dwItemSize to be copied as data for the new block.
lpItemData
Pointer to the data for the new block. The size in bytes of this buffer should be equal to the product of dwItemSize and dwItemCount.
lplpNewInfoBlock
Pointer to a pointer variable that, on successful return, points to the new header.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value will be one of the following values.

Value | Description
ERROR_INVALID_PARAMETER | The lpInfoBlock, lplpNewInfoBlock or lpItemData parameters are NULL, or a block of type dwInfoType already exists in the header.
Other | The call failed. Use FormatMessage to retrieve the error message corresponding to the returned error code.

See Also

FormatMessage, MprInfoBlockRemove, MprInfoDuplicate


MprInfoBlockFind

The MprInfoBlockFind function locates a specified block in an information header, and retrieves information about the block.

DWORD MprInfoBlockFind(
  LPVOID   lpInfoBlock,     // info header to search
  DWORD    dwInfoType,      // block type to search for
  LPDWORD  lpdwItemSize,    // size of data items in found block
  LPDWORD  lpdwItemCount,   // number of data items in found block
  LPBYTE * lplpItemData     // data in found block
);

Parameters

lpInfoBlock
Header in which to locate the block.
dwInfoType
Specifies the type of block to locate. The types available depend on the transport: IP or IPX.
lpdwItemSize
Pointer to a DWORD variable that, on successful return, specifies the size of each item in the located block's data. This parameter is optional. If this parameter is NULL, the item size will not be returned.
lpdwItemCount
Pointer to a DWORD variable that, on successful return, specifies the number of items of size dwItemSize contained in the block's data. This parameter is optional. If this parameter is NULL, the item count will not be returned.
lplpItemData
Pointer to a pointer that, on successful return, points to the data for the located block. This parameter is optional. If this parameter is NULL, the data will not be returned.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value will be one of the following values.

Value | Description
ERROR_INVALID_PARAMETER | The lpInfoBlock is NULL.
ERROR_NOT_FOUND | No block of type dwInfoType exists in the header.
Other | The call failed. Use FormatMessage to retrieve the error message corresponding to the returned error code.

See Also

FormatMessage


MprInfoBlockRemove

The MprInfoBlockRemove function creates a new header that is identical to an existing header with a specified block removed.

DWORD MprInfoBlockRemove(
  LPVOID   lpInfoBlock,        // pointer to existing header
  DWORD    dwInfoType,         // info type of block to remove
  LPVOID * lplpNewInfoBlock    // new header with block removed
);

Parameters

lpInfoBlock
Pointer to the header from which the block should be removed.
dwInfoType
Specifies the type of block to be removed. The types available depend on the transport: IP or IPX.
lplpNewInfoBlock
Pointer to a pointer variable that, on successful, return, points to the new header.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value will be one of the following values.

Value | Description
ERROR_INVALID_PARAMETER | The lpInfoBlock is NULL, or no block of type dwInfoType exists in the header.
ERROR_NOT_ENOUGH_MEMORY | The memory allocation required for successful execution of MprInfoBlockRemove could not be completed.
Other | The call failed. Use FormatMessage to retrieve the error message corresponding to the returned error code.

See Also

FormatMessage, MprInfoBlockAdd


MprInfoBlockSet

The MprInfoBlockSet creates a new header that is identical to an existing header with a specified block modified.

DWORD MprInfoBlockSet(
  LPVOID   lpInfoBlock,      // pointer to existing header
  DWORD    dwInfoType,       // info type of block to modify
  DWORD    dwItemSize,       // new size of items in the modified block
  DWORD    dwItemCount,      // new number of items in the modified block
  LPBYTE   lpItemData,       // new data for the modified block
  LPVOID * lplpNewInfoBlock  // new header (incl. modified block)
);

Parameters

lpInfoBlock
Pointer to header in which to modify the specified block.
dwInfoType
Specifies the type of block to change. The types available depend on the transport: IP or IPX.
dwItemSize
Specifies the size of each item in the block's new data.
dwItemCount
Specifies the number of items of size dwItemSize to be copied as the new data for the block.
lpItemData
Pointer to the new data for the block. This should point to a buffer with a size (in bytes) equal to the product of dwItemSize and dwItemCount.
lplpNewInfoBlock
Pointer to a pointer variable that, on successful return, points to the new header.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value will be one of the following values.

Value | Description
ERROR_INVALID_PARAMETER | One (or more) required parameters is NULL, or no block of type dwInfoType exists in the header.
Other | The call failed. Use FormatMessage to retrieve the error message corresponding to the returned error code.

See Also

FormatMessage, MprInfoBlockAdd, MprInfoBlockRemove, MprInfoBlockSet


MprInfoCreate

The MprInfoCreate function creates a new information header.

DWORD MprInfoCreate(
  DWORD    dwVersion,          // version of info header
  LPVOID * lplpNewInfoBlock    // pointer to new info header
);

Parameters

dwVersion
Specifies the version of the RTR_INFO_BLOCK_HEADER structure to be created. The only value currently supported is RTR_INFO_BLOCK_VERSION, as declared in Rtinfo.h.
lplpNewInfoBlock
Pointer to the allocated and initialized header.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value will be one of the following values.

Value | Description
ERROR_INVALID_PARAMETER | The lplpNewInfoBlock is NULL.
ERROR_NOT_ENOUGH_MEMORY | The requested memory allocation could not be completed.
Other | The call failed. Use FormatMessage to retrieve the error message corresponding to the returned error code.

See Also

FormatMessage, RTR_INFO_BLOCK_HEADER.


MprInfoDelete

The MprInfoDelete function deletes an information header created using MprInfoCreate, or retrieved by MprInfoBlockAdd, MprInfoBlockRemove, or MprInfoBlockSet.

DWORD MprInfoDelete(
  LPVOID lpInfoBlock    // pointer to header to delete
);

Parameters

lpInfoBlock
Pointer to the header to be deallocated.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails the return value will be one of the following values.

Value | Description
ERROR_INVALID_PARAMETER | The lpInfoBlock is NULL.
Other | The call failed. Use FormatMessage to retrieve the error message corresponding to the returned error code.

See Also

MprInfoBlockAdd, MprInfoBlockRemove, MprInfoBlockSet, FormatMessage


MprInfoDuplicate

The MprInfoDuplicate function duplicates an existing information header.

DWORD MprInfoDuplicate(
  LPVOID   lpInfoBlock,       // pointer to existing info header
  LPVOID * lplpNewInfoBlock   // pointer to pointer to duplicate
);

Parameters

lpInfoBlock
Pointer to the information header to duplicate.
lplpNewInfoBlock
Pointer to a pointer variable. On successful return, this variable will pointer to the new (duplicate) information header.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value will be one of the following values.

Value | Description
ERROR_INVALID_PARAMETER | The lplpNewInfoBlock is NULL.
ERROR_NOT_ENOUGH_MEMORY | The requested memory allocation could not be completed.
Other | The call failed. Use FormatMessage to retrieve the error message corresponding to the returned error code.

See Also

FormatMessage, MprInfoCreate


Functions That Use Information Blocks

The following table lists functions that use information blocks. Each of these functions has a parameter that points to either a global information block or an interface information block.

Function | Info Block Parameter
MprAdminInterfaceTransportAdd | pInterfaceInfo
MprAdminInterfaceTransportGetInfo | ppInterfaceInfo
MprAdminInterfaceTransportSetInfo | pInterfaceInfo
MprAdminTransportGetInfo | ppGlobalInfo
MprAdminTransportGetInfo | pGlobalInfo
MprConfigInterfaceTransportAdd | pInterfaceInfo
MprConfigInterfaceTransportGetInfo | ppInterfaceInfo
MprConfigInterfaceTransportSetInfo | pInterfaceInfo
MprConfigTransportCreate | pGlobalInfo
MprConfigTransportGetInfo | ppGlobalInfo
MprConfigTransportSetInfo | pGlobalInfo


Information Header Structures

Use the following structures when calling information header functions.


RTR_INFO_BLOCK_HEADER

The RTR_INFO_BLOCK_HEADER structure describes a router information block.

typedef struct _RTR_INFO_BLOCK_HEADER {
    ULONG           Version;
    ULONG           Size;
    ULONG           TocEntriesCount;
    RTR_TOC_ENTRY   TocEntry[1];
} RTR_INFO_BLOCK_HEADER, *PRTR_INFO_BLOCK_HEADER;

Members

Version
Contains the version of the structure. The only value currently supported is RTR_INFO_BLOCK_VERSION, as declared in Rtinfo.h.
Size
Size of the entire information block including the Version member.
TocEntriesCount
The number of entries.
TocEntry
Table of contents followed by the actual information blocks.

See Also

RTR_TOC_ENTRY


RTR_TOC_ENTRY

The RTR_TOC_ENTRY structure describes an entry in the table of contents (TOC) of an RTR_INFO_BLOCK_HEADER.

typedef struct _RTR_TOC_ENTRY {
    ULONG    InfoType;
    ULONG    InfoSize;
    ULONG    Count;
    ULONG    Offset;
} RTR_TOC_ENTRY, *PRTR_TOC_ENTRY;

Members

InfoType
Contains the information structure type.
InfoSize
Contains the size of the information structure.
Count
Contains the number of information structures of this type
Offset
Contains the offset of the first structure, from the start of the RTR_INFO_BLOCK_HEADER.

See Also

RTR_INFO_BLOCK_HEADER


Information Header Enumeration Types

Use the following info types when calling information header functions.

IP Info Types for Router Information Blocks
IPX Info Types for Router Information Blocks


IP Info Types for Router Information Blocks

The following information types are list in ipinfoid.h. Use these info types with the Information Header functions when running the IP transport.

IP_IN_FILTER_INFO

IP_OUT_FILTER_INFO

IP_GLOBAL_INFO

IP_INTERFACE_STATUS_INFO

IP_ROUTE_INFO

IP_PROT_PRIORITY_INFO

IP_ROUTER_DISC_INFO


IPX Info Types for Router Information Blocks

The following information types are list in ipxrtdef.h. Use these info types with the Router Information Block functions when running the IPX transport.

IPX_ADAPTER_INFO_TYPE

IPX_GLOBAL_INFO_TYPE

IPX_INTERFACE_INFO_TYPE

IPX_IN_TRAFFIC_FILTER_GLOBAL_INFO_TYPE

IPX_IN_TRAFFIC_FILTER_INFO_TYPE

IPX_OUT_TRAFFIC_FILTER_GLOBAL_INFO_TYPE

IPX_OUT_TRAFFIC_FILTER_INFO_TYPE

IPX_ROUTE_FILTER_INFO_TYPE

IPX_SERVICE_FILTER_INFO_TYPE

IPX_STATIC_NETBIOS_NAME_INFO_TYPE

IPX_STATIC_ROUTE_INFO_TYPE

IPX_STATIC_SERVICE_INFO_TYPE

IPXWAN_INTERFACE_INFO_TYPE


About the MIB API

About the Management Information Base (MIB)

[This is preliminary documentation and subject to change.]

The Management Information Base (MIB) API is used to query and set the values of MIB variable exported by one of the router managers or any of the routing protocols that the router manager services. These variables do not have to correspond to the variables defined in the SNMP MIB definition. Instead, it is the SNMP Agent's job to convert the variables into a format suitable for interaction with an SNMP Manager. The variables provided by the SNMP Agent must at least cover all the variables defined in the SNMP MIB definition.

The module servicing the MIB call will be a router manager or one of the routing protocols. The call must specify a router manager even if the call will be handled by one of the routing protocols. In such a case, the caller should specify the router manager that corresponds to the protocol family for that routing protocol. For example, if the Open Shortest Path First (OSPF) routing protocol were handling the MIB call, the caller would need to specify the IP Router Manager, since OSPF belongs to the IP protocol family. In each of the MIB functions, the dwTransportId parameter specifies a router manager, and the RoutingPid parameter specifies the routing protocol. The router manager also has a unique RoutingPid, since some of the MIB variables may be handled by the router manager itself.

To query and set variables, the module that services the calls must define a set of data structures. These data structures include structures to use as Object Identifiers and structures that hold the value of the MIB variables being accessed. These data structures are opaque to all but the caller of the MIB function and the module servicing the call.


Using the MIB API

  • Obtaining the MIB II Interfaces Table


Obtaining the MIB II Interfaces Table

The following code uses MprAdminMIBEntryGet to obtain the MIB II interfaces table.

HANDLE            _hMibSrv;
   MIB_OPAQUE_QUERY  MibOpaqueQuery;
   PMIB_OPAQUE_INFO  pMibOpaqueInfo = NULL;
   DWORD  dwInSize, dwOutSize, dwResult;
   PMIB_IFTABLE  pIntfTable;

   MibOpaqueQuery.dwVarId = IF_TABLE;
   dwInSize = sizeof( MIB_OPAQUE_QUERY );
   dwOutSize = 0;

   dwResult = MprAdminMIBEntryGet ( _hMibSrv,
                                    PID_IP,
                                    IPRTRMGR_PID,
                                    (PVOID)&MibOpaqueQuery,
                                    dwInSize,
                                    (PVOID *)&pMibOpaqueInfo,
                                    &dwOutSize );

   if ( dwResult != NO_ERROR )
      return;

   if ( pMibOpaqueInfo == NULL )
      return;

   pIntfTable = ( PMIB_IFTABLE ) pMibOpaqueInfo -> rgbyData;


MIB Reference

Use the following functions to query and set the values of MIB variables exported by one of the router managers or any of the routing protocols that the router manager services.


MprAdminMIBBufferFree

The MprAdminMIBBufferFree function frees buffers returned by the following functions:

MprAdminMIBEntryGet

MprAdminMIBEntryGetFirst

MprAdminMIBEntryGetNext

VOID MprAdminMIBBufferFree(
  LPVOID pBuffer    // address of memory to free
);

Parameters

pBuffer
Pointer to a memory buffer to free.

Return Values

NO_ERROR
Success
ERROR_INVALID_PARAMETER
The pBuffer parameter is NULL.

See Also

MprAdminMIBEntryGet, MprAdminMIBEntryGetFirst, MprAdminMIBEntryGetNext


MprAdminMIBEntryCreate

The MprAdminMIBEntryCreate function creates an entry for one of the variables exported by a routing protocol or router manager.

DWORD  MprAdminMIBEntryCreate(
  MIB_SERVER_HANDLE hMibServer,    // handle to router
  DWORD dwTransportId,             // transport/router manager ID
  DWORD dwRoutingPid,              // routing protocol ID
  LPVOID lpEntry,                  // opaque data structure
  DWORD dwEntrySize                // size of opaque data structure
);

Parameters

hMibServer
A handle to the Windows NT router on which to execute this call. Obtain this handle by calling MprAdminMIBServerConnect.
dwTransportId
Identifies the router manager that exported the variable.
dwRoutingPid
Identifies the routing protocol that exported the variable.
lpEntry
Pointer to an opaque data structure. The data structure's format is determined by the module servicing the call. The data structure should contain information to identify the variable being created and the value to assign to the variable.
dwEntrySize
Specifies the size, in bytes, of the data pointed to by the lpEntry parameter.

Return Values

NO_ERROR
Success
ERROR_ACCESS_DENIED
The caller does not have sufficient privilege.
ERROR_CANNOT_COMPLETE
The dwRoutingPid variable doesn't match any installed routing protocol.
ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.
ERROR_UNKNOWN_PROTOCOL_ID
The dwTransportId value does not match any installed router manager.

Remarks

Do not pass in NULL for the lpEntry parameter, as the resulting behavior is undefined.

See Also

MprAdminMIBServerConnect, MprAdminMIBEntryDelete, Protocol Identifiers, Transport Identifiers


MprAdminMIBEntryDelete

The MprAdminMIBEntryDelete function deletes an entry for one of the variables exported by a routing protocol or router manager.

DWORD  MprAdminMIBEntryDelete(
  MIB_SERVER_HANDLE hMibServer,    // handle to router
  DWORD dwTransportId,             // transport/router manager ID
  DWORD dwRoutingPid,              // routing protocol ID
  LPVOID lpEntry,                  // opaque data structure
  DWORD dwEntrySize                // size of opaque data structure
);

Parameters

hMibServer
A handle to the Windows NT router on which to execute this call. Obtain this handle by calling MprAdminMIBServerConnect.
dwTransportId
Identifies the router manager that exported the variable.
dwRoutingPid
Identifier the routing protocol that exported the variable.
lpEntry
Pointer to an opaque data structure. The data structure's format is determined by the module servicing the call. The data structure should contain information to identify the variable to be deleted.
dwEntrySize
Specifies the size, in bytes, of the data pointed to by lpEntry parameter.

Return Values

NO_ERROR
Success
ERROR_ACCESS_DENIED
The caller does not have sufficient privilege.
ERROR_CANNOT_COMPLETE
The dwRoutingPid variable doesn't match any installed routing protocol.
ERROR_UNKNOWN_PROTOCOL_ID
The dwTransportId value does not match any installed router manager.

Remarks

Do not pass in NULL for the lpEntry parameter, as the resulting behavior is undefined.

See Also

MprAdminMIBServerConnect, MprAdminMIBEntryCreate, Protocol Identifiers, Transport Identifiers


MprAdminMIBEntryGet

The MprAdminMIBEntryGet function retrieves the value of one of the variables exported by a routing protocol or router manager.

DWORD  MprAdminMIBEntryGet(
  MIB_SERVER_HANDLE hMibServer,    // handle to router
  DWORD dwTransportId,             // transport/router manager ID
  DWORD dwRoutingPid,              // routing protocol ID
  LPVOID lpInEntry,                // address of data to identify
                                   // variable
  DWORD dwInEntrySize,             // size of data to identify variable
  LPVOID * lplpOutEntry,           // address of output data
  LPDWORD lpdwOutEntrySize         // size of output data
);

Parameters

hMibServer
Handle to the Windows NT router on which to execute this call. Obtain this handle by calling MprAdminMIBServerConnect.
dwTransportId
Identifies the router manager that exported the variable.
dwRoutingPid
Identifies the routing protocol that exported the variable.
lpInEntry
Pointer to an opaque data structure. The data structure's format is determined by the module servicing the call. The data structure should contain information to identify the variable being queried.
dwInEntrySize
Specifies the size, in bytes, of the data structure pointed to by lpInEntry.
lplpOutEntry
Pointer to a pointer variable. On successful return, this pointer variable points to an opaque data structure. The data structure's format is determined by the module servicing the call. The data structure will contain the value of the variable that was queried. Free this memory by calling MprAdminMIBBufferFree.
lpdwoutEntrySize
Pointer to a DWORD variable that, on successful return, contains the size in bytes of the data structure returned through the lplpOutEntry parameter.

Return Values

NO_ERROR
The entry was retrieved successfully.
ERROR_ACCESS_DENIED
The caller does not have sufficient privilege.
ERROR_CANNOT_COMPLETE
The dwRoutingPid variable doesn't match any installed routing protocol.
ERROR_UNKNOWN_PROTOCOL_ID
The dwTransportId value does not match any installed router manager.
ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.

Remarks

Do not pass in NULL for the lpInEntry parameter, as the resulting behavior is undefined.

See Also

MprAdminMIBBufferFree, MprAdminMIBServerConnect, MprAdminMIBEntrySet, MprAdminMIBEntryGetFirst, MprAdminMIBEntryGetNext, Obtaining the MIB II Interfaces Table, Protocol Identifiers, Transport Identifiers


MprAdminMIBEntryGetFirst

The MprAdminMIBEntryGetFirst function retrieves the first variable of some set of variables exported by a protocol or router manager. The module servicing the call defines the semantics of first.

DWORD  MprAdminMIBEntryGetFirst(
  MIB_SERVER_HANDLE hMibServer,    // handle to router
  DWORD dwTransportId,             // transport/router manager ID
  DWORD dwRoutingPid,              // routing protocol ID
  LPVOID lpInEntry,                // address of data to
                                   // identify variable.
  DWORD dwInEntrySize,             // size of data to identify
                                   // variable
  LPVOID * lplpOutEntry,           // address of output data
  LPDWORD lpdwOutEntrySize         // size of output data
);

Parameters

hMibServer
Handle to the Windows NT router on which to execute this call. Obtain this handle by calling MprAdminMIBServerConnect.
dwTransportId
Identifies the router manager that exported the variable.
dwRoutingPid
Identifies the routing protocol that exported the variable.
lpInEntry
Pointer to an opaque data structure. The data structure's format is determined by the module servicing the call. The data structure should contain information to identify the variable being queried.
dwInEntrySize
Size in bytes of the date pointed to by lpInEntry.
lplpOutEntry
Pointer to a pointer variable. On successful return, this pointer variable will point to an opaque data structure. The data structure's format is determined by the module servicing the call. The data structure will contain the value of the first variable from the set of variables exported. Free this memory by calling MprAdminMIBBufferFree.
lpdwoutEntrySize
Pointer to a DWORD variable. On successful return, this variable contains the size in bytes of the data structure returned through the lplpOutEntry parameter.

Return Values

NO_ERROR
The entry was retrieved successfully.
ERROR_ACCESS_DENIED
The caller does not have sufficient privilege.
ERROR_CANNOT_COMPLETE
The dwRoutingPid variable doesn't match any installed routing protocol.
ERROR_UNKNOWN_PROTOCOL_ID
The dwTransportId value does not match any installed transport/router manager.
ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.

Remarks

Do not pass in NULL for the lpInEntry parameter, as the resulting behavior is undefined.

See Also

MprAdminMIBBufferFree, MprAdminMIBServerConnect, MprAdminMIBEntryGet, MprAdminMIBEntryGetNext, Protocol Identifiers, Transport Identifiers


MprAdminMIBEntryGetNext

The MprAdminMIBEntryGetNext function retrieves the next variable of some set of variables exported by a protocol or router manager. It is up to the module servicing the call to define the semantics of next.

DWORD  MprAdminMIBEntryGetNext(
  MIB_SERVER_HANDLE hMibServer,    // handle to router
  DWORD dwTransportId,             // transport/router manager ID
  DWORD dwRoutingPid,              // routing protocol ID
  LPVOID lpInEntry,                // address of data to identify
                                   // variable.
  DWORD dwInEntrySize,             // size of data to identify
                                   // variable
  LPVOID * lplpOutEntry,           // address of output data
  LPDWORD lpdwOutEntrySize         // size of output data
);

Parameters

hMibServer
Handle to the Windows NT router on which to execute this call. This handle is obtained from a previous call to MprAdminMIBServerConnect.
dwTransportId
Identifies the router manager that exported the variable.
dwRoutingPid
Identifies the routing protocol that exported the variable.
lpInEntry
Pointer to an opaque data structure. The data structure's format is determined by the module servicing the call. The data structure should contain information to identify the variable being queried.
dwInEntrySize
Specifies the size, in bytes, of the data structure pointed to by lpInEntry.
lplpOutEntry
Pointer to a pointer variable. On successful return, this pointer variable will pointer to an opaque data structure. The data structure's format is determined by the module servicing the call. The data structure will contain the value of the next variable from the set of variables exported. Free this memory by calling MprAdminMIBBufferFree.
lpdwoutEntrySize
Pointer to a DWORD variable. On a successful return, this variable contains the size in bytes of the data structure returned through the lplpOutEntry parameter.

Return Values

NO_ERROR
The entry was retrieved successfully.
ERROR_ACCESS_DENIED
The caller does not have sufficient privilege.
ERROR_CANNOT_COMPLETE
The dwRoutingPid variable doesn't match any installed routing protocol.
ERROR_UNKNOWN_PROTOCOL_ID
The dwTransportId value does not match any installed router manager.
ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.

Remarks

Do not pass in NULL for the lpInEntry parameter, as the resulting behavior is undefined.

See Also

MprAdminMIBBufferFree, MprAdminMIBServerConnect, MprAdminMIBEntryGet, MprAdminMIBEntryGetFirst, Protocol Identifiers, Transport Identifiers


MprAdminMIBEntrySet

The MprAdminMIBEntrySet function sets the value of one of the variables exported by a routing protocol or router manager.

DWORD  MprAdminMIBEntrySet(
  MIB_SERVER_HANDLE hMibServer,    // handle to router
  DWORD dwTransportId,             // transport/router manager ID
  DWORD dwRoutingPid,              // routing protocol ID
  LPVOID lpEntry,                  // opaque data structure
  DWORD dwEntrySize                // size of opaque data structure
);

Parameters

hMibServer
Handle to the Windows NT router on which to execute this call. Obtain this handle by calling MprAdminMIBServerConnect.
dwTransportId
Identifies the router manager that exported the variable.
dwRoutingPid
Identifies the routing protocol that exported the variable.
lpEntry
Pointer to an opaque data structure. The data structure's format is determined by the module servicing the call. The data structure should contain information to identify the variable being set and the value to be assigned to the variable.
dwEntrySize
Specifies the size, in bytes, of the data pointed to by the lpEntry parameter.

Return Values

NO_ERROR
The entry was set successfully.
ERROR_ACCESS_DENIED
The caller does not have sufficient privilege.
ERROR_CANNOT_COMPLETE
The dwRoutingPid variable doesn't match any installed routing protocol.
ERROR_UNKNOWN_PROTOCOL_ID
The dwTransportId value does not match any installed router manager.

Remarks

Do not pass in NULL for the lpEntry parameter, as the resulting behavior is undefined.

See Also

MprAdminMIBServerConnect, MprAdminMIBEntryGet, Protocol Identifiers, Transport Identifiers


MprAdminMIBServerConnect

Call the MprAdminMIBServerConnect function to connect to the Windows NT router being administered. This call should be made before any other calls to the server. The handle returned by this function is used in subsequent MIB calls.

DWORD  MprAdminMIBServerConnect(
  LPWSTR lpwsServerName,             // name of router
  MIB_SERVER_HANDLE * phMibServer    // handle to router
);

Parameters

lpwsServerNamer
Pointer to a Unicode string that contains the name of the remote server. If the caller specifies NULL for this parameter, the function will return a handle to the local server.
phMibServer
Pointer to a handle variable. On successful return, this variable will contain a handle to the server.

Return Values

NO_ERROR
Success

See Also

MprAdminMIBServerDisconnect


MprAdminMIBServerDisconnect

The MprAdminMIBServerDisconnect function disconnects the connection made by a previous call to MprAdminMIBServerConnect.

DWORD  MprAdminMIBServerDisconnect(
  MIB_SERVER_HANDLE hMibServer    // handle to router
);

Parameters

hMibServer
Handle to the Windows NT router from which to disconnect. Obtain this handle by calling MprAdminMIBServerConnect.

Return Values

NO_ERROR
Success

See Also

MprAdminMIBServerConnect


Router Configuration Reference

Use the following functions, structures, and enumerated types when developing software to configure Microsoft® Windows NT® routers.


Router Configuration Functions

Use the following functions when developing software to configure Microsoft® Windows NT® routers


MprConfigBufferFree

The MprConfigBufferFree function frees buffers allocated by calls to the following functions:

MprConfigXEnum

MprConfigXGetInfo

where X stands for Server, Interface, Transport, or InterfaceTransport.

DWORD  MprConfigBufferFree(
  LPVOID pBuffer    // address of memory buffer to free
);

Parameters

pBuffer
Pointer to a memory buffer allocated by a previous call to:

MprConfigXEnum

MprConfigXGetInfo

where X stands for Server, Interface, Transport, or InterfaceTransport.

Return Values

NO_ERROR
The memory was freed 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

MprConfigInterfaceEnum, MprConfigInterfaceTransportEnum, MprConfigTransportEnum, MprConfigInterfaceGetInfo, MprConfigInterfaceTransportGetInfo, MprConfigServerGetInfo, MprConfigTransportGetInfo.


MprConfigInterfaceCreate

The MprConfigInterfaceCreate function creates a router interface in the specified router configuration.

DWORD
MprConfigInterfaceCreate(
  HANDLE hMprConfig,            // handle to the router configuration
  DWORD dwLevel,                // level of information requested
  LPBYTE lpbBuffer,             // MPR_INTERFACE_0 structure
  HANDLE * phRouterInterface    // handle to the interface configuration
);

Parameters

hMprConfig
Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
dwLevel
Level of information requested. This parameter must be zero.
lpbBuffer
Pointer to an MPR_INTERFACE_0 structure.
phRouterInterface
Pointer to a handle variable. On successful return, this variable will contain a handle to the interface configuration.

Return Values

NO_ERROR
The router interface was created successfully.
ERROR_INVALID_PARAMETER
At least one of the following is true:

hMprConfig is NULL

dwLevel is not zero.

lpbBuffer is NULL

phRouterInterface is NULL

ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.
Other
Use FormatMessage to retrieve the system error message corresponding to the error code returned.

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

FormatMessage, MprConfigInterfaceDelete, MprConfigServerConnect


MprConfigInterfaceDelete

The MprConfigInterfaceDelete function removes a router interface from the router configuration. All transport information associated with this interface is also removed.

DWORD  MprConfigInterfaceDelete(
  HANDLE hMprConfig,         // handle to the router configuration
  HANDLE hRouterInterface    // handle to the interface configuration
);

Parameters

hMprConfig
Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
hRouterInterface
Handle to the interface configuration. Obtain this handle by calling MprConfigInterfaceCreate, MprConfigInterfaceGetHandle, or MprConfigInterfaceEnum.

Return Values

NO_ERROR
The router interface was deleted successfully.
ERROR_INVALID_PARAMETER
The hMprConfig parameter is NULL, or the hRouterInterface parameter is NULL, or both parameters are NULL.
ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.
Other
Use FormatMessage to retrieve the system error message corresponding to the error code returned.

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

FormatMessage, MprConfigInterfaceCreate, MprConfigInterfaceEnum, MprConfigInterfaceGetHandle, MprConfigServerConnect


MprConfigInterfaceEnum

The MprConfigInterfaceEnum function enumerates the interfaces configured for the router.

DWORD  MprConfigInterfaceEnum(
  HANDLE hMprConfig,           // handle to the router configuration
  DWORD dwLevel,               // level of information requested
  LPBYTE * lplpBuffer,         // array of MPR_INTERFACE_0 structures
  DWORD dwPrefMaxLen,          // maximum length of data to return
  LPDWORD lpdwEntriesRead,     // number of entries enumerated
  LPDWORD lpdwTotalEntries,    // number of entries that could've
                               // been enumerated
  LPDWORD lpdwResumeHandle     // handle for continuing the enumeration
);

Parameters

hMprConfig
Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
dwLevel
Level of the information returned through the lplpBuffer parameter. This parameter must be zero.
lplpBuffer
Pointer to a pointer variable. On successful return, this pointer variable will point to an array of MPR_INTERFACE_0 structures. Free this memory by calling MprConfigBufferFree.
dwPrefMaxLen
Specifies the preferred maximum length of returned data (in 8-bit bytes). If this parameter is -1, the buffer returned will be large enough to hold all available information.
lpdwEntriesRead
Pointer to a DWORD variable. On successful return, this variable contains the total number of entries that were enumerated from the current resume position.
lpdwTotalEntries
Pointer to a DWORD variable. On successful return, this variable contains the total number of entries that could have been enumerated from the current resume position.
lpdwResumeHandle
Pointer to a DWORD variable. On successful return, this variable contains a resume handle that can be used to continue the enumeration. The handle should be zero on the first call, and left unchanged on subsequent calls. If on return, the handle is NULL, the enumeration cannot be continued. For other types of error returns, this handle is invalid.

This parameter is optional. If the caller specifies NULL for this parameter, the function will not return a resume handle.

Return Values

NO_ERROR
The interfaces were enumerated successfully.
ERROR_INVALID_PARAMETER
One of the following is true:

hMprConfig is NULL.

dwLevel is not zero.

lplpBuffer is NULL.

dwPrefMaxLen is smaller than the size of a single MPR_INTERFACE_0 structure.

lpdwEntriesRead is NULL.

lpdwTotalEntries is NULL.

ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.
ERROR_NO_MORE_ITEMS
No more entries available from the current resume position.
Other
Use FormatMessage to retrieve the system error message corresponding to the error code returned.

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

FormatMessage, MprConfigBufferFree, MprConfigServerConnect


MprConfigInterfaceGetHandle

The MprConfigInterfaceGetHandle function retrieves a handle to the specified interface's configuration in the specified router configuration.

DWORD  MprConfigInterfaceGetHandle(
  HANDLE hMprConfig,            // handle to the router configuration
  LPWSTR lpwsInterfaceName,     // Unicode string containing name
                                // of interface
  HANDLE * phRouterInterface    // handle to the specified interface
);

Parameters

hMprConfig
Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
lpwsInterfaceName
Pointer to a Unicode string containing the name of the interface for which the configuration handle is requested.
phRouterInterface
Pointer to a handle variable. On successful return, this variable contains a handle to the interface configuration.

Return Values

NO_ERROR
The configuration handle for the interface was retrieved successfully.
ERROR_INVALID_PARAMETER
The hMprConfig parameter is NULL, or the lpwsInterfaceName parameter is NULL, or both parameters are NULL.
ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.
ERROR_NO_SUCH_INTERFACE
The specified interface was not found in the router configuration.
Other
Use FormatMessage to retrieve the system error message corresponding to the error code returned.

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

FormatMessage, MprConfigServerConnect


MprConfigInterfaceGetInfo

The MprConfigInterfaceGetInfo function retrieves the configuration for the specified interface from the router.

DWORD  MprConfigInterfaceGetInfo(
  HANDLE hMprConfig,          // handle to the router configuration
  HANDLE hRouterInterface,    // handle to the interface configuration
  DWORD dwLevel,              // level of information requested
  LPBYTE * lplpBuffer,        // MPR_INTERFACE_0 structure
  LPDWORD lpdwBufferSize      // size of returned data
);

Parameters

hMprConfig
Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
hRouterInterface
Handle to the interface configuration for which to retrieve information. Obtain this handle by calling MprConfigInterfaceCreate, MprConfigInterfaceGetHandle, or MprConfigInterfaceEnum.
dwLevel
Level of the information returned in the lplpBuffer parameter. This parameter must be zero.
lplpBuffer
Pointer to a pointer variable. On successful return, this pointer variable points to an MPR_INTERFACE_0 structure. Free this buffer by calling MprConfigBufferFree.
lpdwBufferSize
Pointer to a DWORD variable. On successful return, this variable will contain the size, in bytes, of the data returned through lplpBuffer.

Return Values

NO_ERROR
The interface information was retrieved successfully.
ERROR_INVALID_PARAMETER
At least one of the following is true:

hMprConfig is NULL

hRouterInterface is NULL

dwLevel is not zero.

lplpBuffer is NULL

lpdwBufferSize is NULL

ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.
ERROR_NO_SUCH_INTERFACE
The interface corresponding to hRouterInterface is not present in the router configuration.

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

MprConfigBufferFree, MprConfigInterfaceCreate, MprConfigInterfaceEnum, MprConfigInterfaceGetHandle, MprConfigServerConnect


MprConfigInterfaceSetInfo

The MprConfigInterfaceSetInfo function sets the configuration for the specified interface.

DWORD  MprConfigInterfaceSetInfo(
  HANDLE hMprConfig,          // handle to the router configuration
  HANDLE hRouterInterface,    // handle to the interface configuration
  DWORD dwLevel,              // level of the information requested
  LPBYTE lpBuffer             // MPR_INTERFACE_0 structure
);

Parameters

hMprConfig
Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
hRouterInterface
Handle to the interface configuration being updated. Obtain this handle by calling MprConfigInterfaceCreate, MprConfigInterfaceGetHandle, or MprConfigInterfaceEnum.
dwLevel
Level of the information in the lpBuffer parameter. This parameter must be zero.
lpBuffer
Pointer to a buffer containing an MPR_INTERFACE_0 structure. The information in this buffer is used to update the interface configuration.

Return Values

NO_ERROR
The interface information was set successfully.
ERROR_INVALID_PARAMETER
At least one of the following is true:

hMprConfig is NULL.

HRouterInterface is NULL.

dwLevel is not zero.

lpBuffer is NULL.

ERROR_NO_SUCH_INTERFACE
The interface corresponding to hRouterInterface is not present in the router configuration.
Other
Use FormatMessage to retrieve the system error message corresponding to the error code returned.

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

FormatMessage, MprConfigInterfaceCreate, MprConfigInterfaceEnum, MprConfigInterfaceGetHandle, MprConfigServerConnect


MprConfigServerBackup

The MprConfigServerBackup function creates a backup of the router-manager, interface, and phonebook configuration for the router.

DWORD  MprConfigServerBackup (
    HANDLE    hMprConfig,    // handle to the router configuration
    LPWSTR    lpwsPath       // path to backup directory
)

Parameters

hMprConfig
Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
lpwsPath
Pointer to a Unicode string that contains the path to the directory where MprConfigServerBackup to write the backup files. This path should end with a trailing backslash.

Return Values

NO_ERROR
The configuration was backed up successfully.
ERROR_INVALID_PARAMETER
The hMprConfig parameter is NULL.
ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.
Other
Use FormatMessage to retrieve the system error message corresponding to the error code returned.

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

FormatMessage , MprConfigServerConnect, MprConfigServerRestore


MprConfigServerConnect

The MprConfigServerConnect function connects to the Windows NT router machine to be configured. Call this function before making any other calls to the server. The handle returned by this function is used in subsequent calls to configure interfaces and transports on the server.

DWORD  MprConfigServerConnect(
  LPWSTR lpwsServerName,    // address of server name
  HANDLE * phMprConfig      // address of router configuration handle
);

Parameters

lpwsServername
Pointer to a Unicode string containing the name of the remote server to configure. If this parameter is NULL, the function returns a handle to the router configuration on the local machine .
phMprConfig
Pointer to a handle variable. On successful return, this variable contains a handle to the router configuration.

Return Values

NO_ERROR
Success.
ERROR_INVALID_PARAMETER
The phMprConfig parameter is NULL.
ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.
Other
Use FormatMessage to retrieve the system error message corresponding to the error code returned.

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

FormatMessage, MprConfigServerDisconnect


MprConfigServerDisconnect

The MprConfigServerDisconnect function disconnects a connection made by a previous call to MprConfigServerConnect.

VOID  MprConfigServerDisconnect(
  HANDLE hMprConfig    // handle to router configuration
);

Parameters

hMprConfig
Handle to a router configuration obtained from a previous call to MprConfigServerConnect.

Return Values

None.

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

FormatMessage, MprConfigServerConnect


MprConfigServerGetInfo

The MprConfigServerGetInfo function retrieves server-level configuration information for the specified router.

DWORD  MprConfigServerGetInfo (
    HANDLE      hMprConfig,    // handle to the router configuration
    DWORD       dwLevel,       // level of information
    LPBYTE  *   lplpBuffer     // buffer to receive information
)

Parameters

hMprConfig
Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
dwLevel
Specifies the level of the information requested. This parameter must be zero.
lplpBuffer
Pointer to a pointer variable. On successful return, this variable will point to a buffer containing the retrieved information. Free the memory for this buffer using MprConfigBufferFree.

Return Values

NO_ERROR
The information was retrieved successfully.
ERROR_INVALID_PARAMETER
At least one of the following is true:

The hMprConfig parameter is NULL.

The dwLevel parameter is not zero.

The lplpBuffer parameter is NULL.

ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.
Other
Use FormatMessage to retrieve the system error message corresponding to the error code returned.

Remarks

Currently, the only information returned by MprConfigServerGetInfo is the fLanOnlyMode flag.

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

FormatMessage , MPR_SERVER_0, MprConfigBufferFree , MprConfigServerConnect


MprConfigServerRestore

The MprConfigServerRestore function restores the router-manager, interface, and phonebook configuration from a backup created by a previous call to MprConfigServerBackup.

DWORD  MprConfigServerRestore(
    HANDLE    hMprConfig,    // handle to the router configuration
    LPWSTR    lpwsPath       // path to backup directory
)

Parameters

hMprConfig,
Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
lpwsPath
Pointer to a Unicode string that contains the path to the directory where MprConfigServerBackup to write the backup files. This path should end with a trailing backslash.

Return Values

NO_ERROR
The configuration was restored successfully.
ERROR_INVALID_PARAMETER
The hMprConfig parameter is NULL.
ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.
Other
Use FormatMessage to retrieve the system error message corresponding to the error code returned.

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

FormatMessage , MprConfigServerBackup, MprConfigServerConnect


MprConfigInterfaceTransportAdd

The MprConfigInterfaceTransportAdd function adds the specified transport to the specified interface configuration on the router.

DWORD  MprConfigInterfaceTransportAdd(
  HANDLE hMprConfig,              // handle to the router configuration
  HANDLE hRouterInterface,        // handle to the interface configuration
  DWORD dwTransportId,            // identifier of the transport/router
                                  // manager
  LPWSTR lpwsTransportName,       // transport name
  LPBYTE pInterfaceInfo,          // interface information
  DWORD dwInterfaceInfoSize,      // size of interface information
  HANDLE * phRouterIfTransport    // handle to transport configuration
);

Parameters

hMprConfig
Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
hRouterInterface
Handle to the interface configuration to add the specified transport. Obtain this handle by calling MprConfigInterfaceCreate, MprConfigInterfaceGetHandle, or MprConfigInterfaceEnum.
dwTransportId
Identifies the transport. This parameter also identifies the router manager for the transport.
lpwsTransportName
Pointer to a Unicode string containing the name for the transport being added. If this parameter is not specified, and the transport is IP or IPX, MprConfigInterfaceTransportAdd will use "IP" or "IPX". If this parameter is not specified, and the transport is other than IP or IPX, MprConfigInterfaceTransportAdd will convert the dwTransportId parameter into a string, and use that as the transport name.
pInterfaceInfo
Pointer to the interface information to be added to the interface configuration. The router manager for the specified transport interprets this information.
dwInterfaceInfoSize
Specifies the size, in bytes, of the data pointed to by pInterfaceInfo.
phRouterIfTransport
Pointer to a handle variable. On successful return, this variable will contain a handle to the transport configuration for this interface.

Return Values

NO_ERROR
The transport configuration was added successfully.
ERROR_INVALID_PARAMETER
One of the following is true:

hMprConfig is NULL.

hRouterInterface is NULL.

phRouterIfTransport is NULL.

ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.
Other
Use FormatMessage to retrieve the system error message corresponding to the error code returned.

Remarks

In addition to specifying a transport, the dwTransportId parameter also specifies a router manager, since Windows NT router maintains a unique router manager for each transport.

If the specified transport already exists, MprConfigInterfaceTransportAdd does the equivalent of an MprConfigInterfaceTransportSetInfo call using the given parameter values.

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

FormatMessage, MPR_IFTRANSPORT_0, MprConfigInterfaceCreate, MprConfigInterfaceEnum, MprConfigInterfaceGetHandle, MprConfigServerConnect


MprConfigInterfaceTransportEnum

The MprConfigInterfaceTransportEnum function enumerates the transports configured on the specified interface.

DWORD  MprConfigInterfaceTransportEnum(
  HANDLE hMprConfig,           // handle to the router configuration
  HANDLE hRouterInterface,     // handle to the interface configuration
  DWORD dwLevel,               // level of information requested
  LPBYTE * lplpBuffer,         // array of MPR_IFTRANSPORT_0 structures
  DWORD dwPrefMaxLen,          // maximum length of data to return
  LPDWORD lpdwEntriesRead,     // number of entries enumerated
  LPDWORD lpdwTotalEntries,    // number of entries that could've
                               // been enumerated
  LPDWORD lpdwResumeHandle     // handle for continuing the enumeration
);

Parameters

hMprConfig
Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
hRouterInterface
Handle to the interface configuration from which to enumerate the transports. Obtain this handle by calling MprConfigInterfaceCreate, or MprConfigInterfaceEnum.
dwLevel
Level of the information returned in the lplpBuffer parameter. This parameter must be zero.
lplpBuffer
Pointer to pointer variable. On successful return, this pointer variable will point to an array of MPR_IFTRANSPORT_0 structures This memory should be freed by calling MprConfigBufferFree.
dwPrefMaxLen
Specifies the preferred maximum length of returned data (in 8-bit bytes). If this parameter is -1, the buffer returned will be large enough to hold all available information.
lpdwEntriesRead
Pointer to a DWORD variable. On successful return, this variable contains the total number of entries that were enumerated from the current resume position.
lpdwTotalEntries
Pointer to a DWORD variable. On successful return, this variable contains the total number of entries that could have been enumerated from the current resume position.
lpdwResumeHandle
Pointer to a DWORD variable. On successful return, this variable contains a resume handle that can be used to continue the enumeration. The handle should be zero on the first call, and left unchanged on subsequent calls. If on return, the handle is NULL, the enumeration cannot be continued. For other types of error returns, this handle is invalid.

This parameter is optional. If the caller specifies NULL for this parameter, the function will not return a resume handle.

Return Values

NO_ERROR
The interface transports were enumerated successfully.
ERROR_INVALID_PARAMETER
One of the following is true:

hMprConfig is NULL.

HRouterInterface is NULL.

dwLevel is not zero.

lplpBuffer is NULL.

dwPrefMaxLen is smaller than the size of a single MPR_TRANSPORT_0 structure.

lpdwEntriesRead is NULL.

lpdwTotalEntries is NULL.

ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.
ERROR_NO_MORE_ITEMS
No more entries available from the current resume position.
Other
Use FormatMessage to retrieve the system error message corresponding to the error code returned.

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

FormatMessage, MPR_IFTRANSPORT_0, MprConfigBufferFree, MprConfigInterfaceCreate, MprConfigInterfaceEnum, MprConfigInterfaceGetHandle


MprConfigInterfaceTransportGetHandle

The MprConfigInterfaceTransportGetHandle function retrieves a handle to the specified transport configuration on the specified interface in the specified router configuration.

DWORD  MprConfigInterfaceTransportGetHandle(
  HANDLE hMprConfig,              // handle to the router configuration
  HANDLE hRouterInterface,        // handle to the interface configuration
  DWORD dwTransportId,            // identifier of the transport configuration
  HANDLE * phRouterIfTransport    // handle to the transport configuration
);

Parameters

hMprConfig
Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
hRouterInterface
Handle to the interface configuration. Obtain this handle by calling MprConfigInterfaceCreate, MprConfigInterfaceGetHandle, or MprConfigInterfaceEnum.
dwTransportId
Identifies the transport configuration.
phRouterIfTranport
Pointer to a handle variable. On successful return, this variable contains a handle to the transport configuration for this interface.

Return Values

NO_ERROR
A handle to the interface transport configuration was returned successfully.
ERROR_INVALID_PARAMETER
At least one of the following is true:

hMprConfig is NULL.

hRouterInterface is NULL.

phRouterIfTransport is NULL.

ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.
ERROR_NO_SUCH_INTERFACE
The interface specified by hRouterInterface was not found in the router configuration, or the transport specified by dwTransportId was not enabled on the specified interface.
Other
Use FormatMessage to retrieve the system error message corresponding to the error code returned.

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

FormatMessage, MprConfigInterfaceCreate, MprConfigInterfaceEnum, MprConfigInterfaceGetHandle, MprConfigServerConnect


MprConfigInterfaceTransportGetInfo

The MprConfigInterfaceTransportGetInfo function retrieves the configuration information for the specified transport and interface.

DWORD  MprConfigInterfaceTransportGetInfo(
  HANDLE hMprConfig,                // handle to the router configuration
  HANDLE hRouterInterface,          // handle to the interface configuration
  HANDLE hRouterIfTransport,        // handle to the transport configuration
  LPBYTE * ppInterfaceInfo,         // interface transport information
  LPDWORD lpdwInterfaceInfoSize    // size of interface transport information
);

Parameters

hMprConfig
Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
hRouterInterface
Handle to the interface configuration from which to retrieve the specified transport information. Obtain this handle by calling MprConfigInterfaceCreate, MprConfigInterfaceGetHandle, or MprConfigInterfaceEnum.
hRouterIfTransport
Handle to the interface transport configuration from which to retrieve the information. Obtain this handle by calling MprConfigInterfaceTransportGetHandle, or MprConfigInterfaceTransportEnum.
ppInterfaceInfo
Pointer to a pointer variable. On successful return, this pointer variable points to the interface transport information. Free this memory by calling MprConfigBufferFree.

This parameter is optional. If the caller specifies NULL for this parameter, the function will not return the interface transport information.

lpdwInterfaceInfoSize
Pointer to a DWORD variable. On successful return, this variable contains the size, in bytes, of the data pointed to by *ppInterfaceInfo.

This parameter is optional; the caller may specify NULL for this parameter. However, if ppInterfaceInfo is not NULL, this parameter cannot be NULL (see Remarks section).

Return Values

NO_ERROR
The interface transport information was retrieved successfully. (Also, see Remarks section below.)
ERROR_INVALID_PARAMETER
One of the following is true:

hMprConfig is NULL.

hRouterInterface is NULL.

hRouterIfTransport is NULL.

ppInterfaceInfo is not NULL, but lpdwInterfaceInfoSize is NULL.

ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.
ERROR_NO_SUCH_INTERFACE
The interface specified by hRouterInterface was not found in the router configuration, or the transport specified by hRouterIfTransport was not enabled on the specified interface.
Other
Use FormatMessage to retrieve the system error message corresponding to the error code returned.

Remarks

If the ppInterfaceInfo parameter is NULL, MprConfigInterfaceTransportGetInfo does nothing, and returns immediately with a value of NO_ERROR.

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

FormatMessage, MprConfigBufferFree, MprConfigInterfaceCreate, MprConfigInterfaceEnum, MprConfigInterfaceGetHandle, MprConfigServerConnect, MprConfigInterfaceTransportEnum, MprConfigInterfaceTransportGetHandle , MPR_IFTRANSPORT_0


MprConfigInterfaceTransportRemove

The MprConfigInterfaceTransportRemove function removes the specified transport from the specified interface configuration on the router.

DWORD  MprConfigInterfaceTransportRemove(
  HANDLE hMprConfig,           // handle to the router configuration
  HANDLE hRouterInterface,     // handle to the interface configuration
  HANDLE hRouterIfTransport    // handle to the transport configuration
);

Parameters

hMprConfig
Handle to the router configuration. The handle is obtained from a previous call to MprConfigServerConnect.
hRouterInterface
Handle to the interface configuration from which to delete the specified transport. Obtain this handle by calling MprConfigInterfaceCreate, MprConfigInterfaceGetHandle, or MprConfigInterfaceEnum.
hRouterIfTransport
Handle to the interface transport configuration to be deleted. Obtain this handle by calling MprConfigInterfaceTransportAdd, MprConfigInterfaceTransportGetHandle, or MprConfigInterfaceTransportEnum.

Return Values

NO_ERROR
The transport configuration was removed successfully.
ERROR_INVALID_PARAMETER
One of the following is true:

hMprConfig is NULL.

hRouterInterface is NULL.

phRouterIfTransport is NULL.

Other
Use FormatMessage to retrieve the system error message corresponding to the error code returned.

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

FormatMessage, MprConfigInterfaceCreate, MprConfigInterfaceEnum, MprConfigInterfaceGetHandle, MprConfigInterfaceTransportAdd, MprConfigInterfaceTransportEnum, MprConfigInterfaceTransportGetHandle, MprConfigServerConnect


MprConfigInterfaceTransportSetInfo

The MprConfigInterfaceTransportSetInfo function updates the configuration information for the specified transport and interface.

DWORD  MprConfigInterfaceTransportSetInfo(
  HANDLE hMprConfig,            // handle to the router configuration
  HANDLE hRouterInterface,      // handle to the interface configuration
  HANDLE hRouterIfTransport,    // handle to the transport configuration
  LPBYTE pInterfaceInfo,        // interface transport information
  DWORD dwInterfaceInfoSize     // size of interface transport information
);

Parameters

hMprConfig
Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
hRouterInterface
Handle to the interface configuration in which to update the information. Obtain this handle by calling MprConfigInterfaceCreate, or MprConfigInterfaceEnum.
hRouterIfTransport
Handle to the interface transport configuration in which to update the information. Obtain this handle by calling MprConfigInterfaceTransportGetHandle, or MprConfigInterfaceTransportEnum.
pInterfaceInfo
Pointer to the interface transport information.

This parameter is optional. If the caller specifies NULL for this parameter, the function will not update the interface transport information.

dwInterfaceInfoSize
Specifies the size, in bytes, of the data pointed to by pInterfaceInfo.

This parameter is optional; the caller may specify zero for this parameter. However, if pInterfaceInfo is not NULL, this parameter cannot be zero (see Remarks section).

Return Values

NO_ERROR
The interface transport information was updated successfully. (Also, see Remarks section below.)
ERROR_INVALID_PARAMETER
At least one of the following is true:

hMprConfig is NULL.

hRouterInterface is NULL.

hRouterIfTransport is NULL.

ERROR_NO_SUCH_INTERFACE
The interface specified by hRouterInterface is no longer present in the router configuration, or the transport specified by hRouterIfTransport is no longer present on the interface.
Other
Use FormatMessage to retrieve the system error message corresponding to the error code returned.

Remarks

If the pInterfaceInfo parameter is NULL, MprConfigInterfaceTransportSetInfo does nothing, and returns immediately with a value of NO_ERROR.

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

FormatMessage, MprConfigInterfaceCreate, MprConfigInterfaceEnum, MprConfigInterfaceGetHandle, MprConfigServerConnect, MprConfigInterfaceTransportEnum, MprConfigInterfaceTransportGetHandle


MprConfigTransportCreate

The MprConfigTransportCreate function adds the specified transport to the list of transports present in the specified router configuration.

DWORD  MprConfigTransportCreate(
  HANDLE hMprConfig,                  // handle to the router configuration
  DWORD dwTransportId,                // identifier of the transport/router
                                      // manager
  LPWSTR lpwsTransportName            // address of the transport name
  LPBYTE pGlobalInfo                  // address of the global info.,
  DWORD dwGlobalInfoSize,             // size of the global info buffer
  LPBYTE pClientInterfaceInfo         // address of info for client routers
  DWORD dwClientInterfaceInfoSize,    // size of the client info buffer
  LPWSTR lpwsDLLPath                  // address of the router manager
                                      // DLL name
  HANDLE phRouterTransport            // handle to the transport configuration
);

Parameters

hMprConfig
Handle to the router configuration to which to add the transport. Obtain this handle by calling MprConfigServerConnect.
dwTransportId
Identifies the transport to add to the configuration. This parameter also identifies the router manager for the transport.
lpwsTransportName
Pointer to a Unicode string containing the name of the transport being added. If this parameter is not specified, the dwTransportId parameter is converted into string and used as the transport name.
pGlobalInfo
Pointer to the global information for the transport. The router manager for the transport interprets this information.
dwGlobalInfoSize
Specifies the size, in bytes, of the data pointed to by pGlobalInfo.
pClientInterfaceInfo
Pointer to the default interface information for client routers. This information is used to configure dynamic interfaces for client routers for this transport. This parameter is optional; the caller may specify NULL for this parameter.
dwClientInterfaceInfoSize
The size in bytes of the data pointed to by the pClientInterfaceInfo parameter. If the caller specifies NULL for pClientInterfaceInfo, the caller should specify zero for this parameter.
lpwsDLLPath
Pointer to a Unicode string containing the name of the router manager DLL for the specified transport. If specified, the function will set the DLLPath for this transport to this name.

This parameter is optional; the caller may specify NULL for this parameter.

phRouterTransport
Pointer to a handle variable. On successful return, this variable contains a handle to the transport configuration.

Return Values

NO_ERROR
Success.
ERROR_INVALID_PARAMETER
The hMprConfig parameter is NULL, or the phRouterTransport parameter is NULL, or both are NULL.
ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.
Other
Use FormatMessage to retrieve the system error message corresponding to the error code returned.

Remarks

If the specified transport already exists, MprConfigTransportCreate does the equivalent of an MprConfigTransportSetInfo call using the supplied parameter values.

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

FormatMessage, MprConfigServerConnect


MprConfigTransportDelete

The MprConfigTransportDelete function removes the specified transport from the list of transports present in the specified router configuration.

DWORD  MprConfigTransportDelete(
  HANDLE hMprConfig,         // handle to the router configuration
  HANDLE hRouterTransport    // handle to the transport configuration
);

Parameters

hMprConfig
Handle to the router configuration from which to remove the transport. Obtain this handle by calling MprConfigServerConnect.
hRouterTransport
Handle to the configuration for the transport being deleted. Obtain this handle by calling MprConfigTransportCreate or MprConfigTransportGetHandle.

Return Values

NO_ERROR
Success
ERROR_INVALID_PARAMETER
The hMprConfig parameter is NULL, or the hRouterTransport parameter is NULL, or both are NULL.
ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.
Other
Use FormatMessage to retrieve the system error message corresponding to the error code returned.

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

FormatMessage, MprConfigServerConnect, MprConfigTransportCreate, MprConfigTransportGetHandle


MprConfigTransportEnum

The MprConfigTransportEnum function enumerates the transports configured on the router.

DWORD  MprConfigTransportEnum(
  HANDLE hMprConfig,           // handle to the router configuration
  DWORD dwLevel,               // level of information requested
  LPBYTE * lplpBuffer,         // array of MPR_TRANSPORT_0 structures
  DWORD dwPrefMaxLen,          // maximum length of data to return
  LPDWORD lpdwEntriesRead,     // number of entries enumerated
  LPDWORD lpdwTotalEntries,    // number of entries that could've
                               // been enumerated
  LPDWORD lpdwResumeHandle     // handle for continuing the enumeration
);

Parameters

hMprConfig
Handle to the router configuration for the transports. Obtain this handle by calling MprConfigServerConnect.
dwLevel
Level of the information returned through the lplpBuffer parameter. This parameter must be zero.
lplpBuffer
Pointer to a pointer variable. On successful return, this pointer will point to an array of MPR_TRANSPORT_0 structures. Free this memory buffer by calling MprConfigBufferFree.
dwPrefMaxLen
Specifies the preferred maximum length of returned data (in 8-bit bytes). If this parameter is -1, the buffer returned will be large enough to hold all available information.
lpdwEntriesRead
Pointer to a DWORD variable. On successful return, this variable contains the total number of entries that were enumerated from the current resume position.
lpdwTotalEntries
Pointer to a DWORD variable. On successful return, this variable contains the total number of entries that could have been enumerated from the current resume position.
lpdwResumeHandle
Pointer to a DWORD variable. On successful return, this variable contains a resume handle that can be used to continue the enumeration. The handle should be zero on the first call, and left unchanged on subsequent calls. If on return, the handle is NULL, the enumeration cannot be continued. For other types of error returns, this handle is invalid.

This parameter is optional. If the caller specifies NULL for this parameter, the function will not return a resume handle.

Return Values

NO_ERROR
The transports were enumerated successfully.
ERROR_INVALID_PARAMETER
At least one of the following is true:

hMprConfig is NULL.

dwLevel is not zero.

lplpBuffer is NULL.

dwPrefMaxLen is smaller than the size of a single MPR_TRANSPORT_0 structure.

lpdwEntriesRead is NULL.

lpdwTotalEntries is NULL.

ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.
ERROR_NO_MORE_ITEMS
No more entries available from the current resume position.
Other
Use FormatMessage to retrieve the system error message corresponding to the error code returned.

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

FormatMessage, MprConfigBufferFree, MprConfigServerConnect


MprConfigTransportGetHandle

The MprConfigTransportGetHandle function retrieves a handle to the specified transport's configuration in the specified router configuration.

DWORD  MprConfigTransportGetHandle(
  HANDLE hMprConfig,            // handle to the router configuration
  DWORD dwTransportId,          // transport identifier
  HANDLE * phRouterTransport    // handle to the transport's configuration
);

Parameters

hMprConfig
Handle to the router configuration. The handle is obtained from a previous call to MprConfigServerConnect.
dwTransportId
Identifies the transport for which to retrieve the configuration.
phRouterTransport
Pointer to a handle variable. On successful return, this variable will contain a handle to the specified transport's configuration.

Return Values

NO_ERROR
Success.
ERROR_INVALID_PARAMETER
The hMprConfig parameter and/or the phRouterTransport parameter is NULL.
ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.
ERROR_UNKNOWN_PROTOCOL_ID
The transport specified by dwTransportId was not found in the router configuration.
Other
Use FormatMessage to retrieve the system error message corresponding to the error code returned.

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

FormatMessage, MprConfigServerConnect


MprConfigTransportGetInfo

The MprConfigTransportGetInfo function retrieves the configuration for the specified transport from the router.

DWORD  MprConfigTransportGetInfo(
  HANDLE hMprConfig,                      // handle to the router configuration
  HANDLE hRouterTransport,                // handle to the transport configuration
  LPBYTE * ppGlobalInfo,                  // global information for the transport
  LPDWORD lpdwGlobalInfoSize,             // size of global information
  LPBYTE * ppClientInterfaceInfo,         // interface information for client
                                          // routers
  LPDWORD lpdwClientInterfaceInfoSize,    // size of interface information
  LPWSTR * lplpwsDLLPath                  // name of router manager DLL
);

Parameters

hMprConfig
Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
hRouterTransport
Handle to the transport configuration being retrieved. Obtain this handle by calling MprConfigTransportCreate, MprConfigTransportGetHandle or MprConfigTransportEnum.
ppGlobalInfo
Pointer to a pointer variable. On successful return, this pointer variable will point to the global information for the transport. Free the buffer containing the global information by calling MprConfigBufferFree.

This parameter is optional. If the caller specifies NULL for this parameter, the function will not retrieve the global information.

lpdwGlobalInfoSize
Pointer to a DWORD variable. On successful return, this variable will contain the size, in bytes, of the buffer returned through the ppGlobalInfo parameter.

This parameter is optional; the caller may specify NULL for this parameter. However, if ppGlobalInfo is not NULL, this parameter cannot be NULL.

ppClientInterfaceInfo
Pointer to a pointer variable. On successful return, this pointer will point to the default interface information for client routers for this transport. Free the buffer containing the interface information by calling MprConfigBufferFree.

This parameter is optional. If the caller specifies NULL for this parameter, the function will not retrieve the interface information.

lpdwClientInterfaceInfoSize
Pointer to a DWORD variable. On successful return, this variable will contain the size in bytes of the buffer returned through the ppClientInterfaceInfo parameter.

This parameter is optional; the caller may specify NULL for this parameter. However, if ppClientInterfaceInfo, is not NULL, this parameter cannot NULL.

lplpwsDLLPath
Pointer to a pointer to a Unicode string. On successful return, the Unicode string will contain the name of the router manager DLL for the specified transport.

This parameter is optional. If the caller specifies NULL for this parameter, the function will not retrieve the name of the router manager DLL.

Return Values

NO_ERROR
The information for the transport configuration was set successfully.
ERROR_INVALID_PARAMETER
At least one of the following is true:

hMprConfig is NULL

hRouterTransport is NULL

ppGlobalInfo is not NULL, but lpdwGlobalInfoSize is NULL.

ppClientInterfaceInfo is not NULL, but lpdwClientInterfaceInfo is NULL.

ERROR_UNKNOWN_PROTOCOL_ID
The transport configuration corresponding to hRouterTransport was not found in the router configuration.
ERROR_NOT_ENOUGH_MEMORY
Insufficient resources to complete the operation.
Other
Use FormatMessage to retrieve the system error message corresponding to the error code returned.

Remarks

If the pGlobalInfo, pClientInterfaceInfo, and lpwsDLLPath parameters are all NULL, the function will do nothing, and return a value of NO_ERROR.

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

MprConfigBufferFree, MprConfigServerConnect, MprConfigTransportCreate, MprConfigTransportGetHandle, MprConfigTransportEnum


MprConfigTransportSetInfo

The MprConfigTransportSetInfo function changes the configuration for the specified transport in the specified router configuration.

DWORD  MprConfigTransportSetInfo(
  HANDLE hMprConfig,                  // handle to the router configuration
  HANDLE hRouterTransport,            // handle to the transport configuration
  LPBYTE pGlobalInfo,                 // global information for the transport
  DWORD dwGlobalInfoSize,             // size of global information
  LPBYTE pClientInterfaceInfo,        // interface information for
                                      // client routers
  DWORD dwClientInterfaceInfoSize,    // size of interface information
  LPWSTR lpwsDLLPath                  // name of router manager DLL
);

Parameters

hMprConfig
Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
hRouterTransport
Handle to the transport configuration being updated. Obtain this handle by calling MprConfigTransportCreate, MprConfigTransportGetHandle or MprConfigTransportEnum.
pGlobalInfo
Pointer to the global information for the transport. The router manager for the transport interprets this information.
dwGlobalInfoSize
Specifies the size, in bytes, of the data pointed to by pGlobalInfo. If the caller specifies NULL for pGlobalInfo, the caller should specify zero for this parameter.
pClientInterfaceInfo
Pointer to the default interface information for client routers. The information is used to configure dynamic interfaces for client routers for this transport.

This parameter is optional; the caller may specify NULL for this parameter.

dwClientInterfaceInfoSize
Specifies the size, in bytes, of the data pointed to by pClientInterfaceInfo. If the caller specifies NULL for pClientInterfaceInfo, the caller should specify zero for this parameter.
lpwsDLLPath
The name of the router manager DLL for the specified transport.

This parameter is optional; the caller may specify NULL for this parameter.

Return Values

NO_ERROR
The transport information was set successfully (however, see the remarks section below).
ERROR_INVALID_PARAMETER
The hMprConfig parameter is NULL, or the hRouterTransport parameter is NULL, or both are NULL.
ERROR_UNKNOWN_PROTOCOL_ID
The transport configuration corresponding to hRouterTransport was not found in the router configuration.
Other
Use FormatMessage to retrieve the system error message corresponding to the error code returned.

Remarks

Use this function to set the transport's global information, default interface information, or the name of the router manager DLL for the transport.

The function attempts to set the items in the order in which they appear in the parameter list:

  1. Global Information
  2. Default Interface Information for Client Routers
  3. Router manager DLL Name

If the function is unable to set any one of the items, it will return immediately without attempting to set the remaining items.

If the pGlobalInfo, pClientInterfaceInfo, and lpwsDLLPath parameters are all NULL, the function will do nothing returning a value of NO_ERROR.

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

FormatMessage, MprConfigServerConnect, MprConfigTransportCreate, MprConfigTransportGetHandle, MprConfigTransportEnum


About the Routing Protocol Interface

The following documentation describes the integration of third-party routing protocols into the Microsoft® Windows NT® Routing and Remote Access Service, a multiprotocol router. It defines the interface between the router manager and the routing protocol dynamic link library (DLL).

Using this interface, vendors can implement routing protocols; for example, IGRP, NLSP, BGP, as user-mode DLLs that work with Windows NT Routing and RAS (RRAS).


Adapters

An adapter represents the physical point of attachment to a network segment. A bound LAN card isone adapter. Similarly, a machine with two modems, each capable of connecting to a remote network, will have two adapters, one to represent each modem.


Interfaces

An interface represents a network that can be reached over a LAN or WAN adapter. Each interface has a unique identifier on the router. Interfaces that are active have an adapter that is providing connectivity to the network they represent. Interfaces that are inactive do not have an adapter providing connectivity.

Routing a packet to a network represented by an interface will cause the router to allocate an adapter for that interface, and establish a WAN connection to the remote network. Allocating an adapter to an interface is referred to as "binding."

Interfaces are manageable objects. Each interface appears as a row in the Interface Table of the appropriate SNMP MIB.


Static and Autostatic Routes

Typically, routes to remote networks are obtained dynamically through routing protocols. However, the administrator can also "seed" the routing table by providing routes manually. These routes are referred to as static. A static route is associated with an interface that represents the remote network. Unlike dynamic routes, static routes are retained even if the router is restarted or the interface is disabled.

An autostatic route is obtained through a routing protocol, but once obtained behaves like a static route. The process for obtaining autostatic routes is as follows: The IP or IPX router manager issues a request that a routing protocol update the routing information for a specific interface. The results of the update are then converted into static routes. Note that only certain routing protocols support requests for autostatic route updates.


Using Routing Protocol Interface

The following code implements a sample IP routing protocol.

AddInterface Sample
DeleteInterface Sample
GetInterfaceConfigInfo Sample
SetInterfaceConfigInfo Sample
BindInterface Sample
UnBindInterface Sample
EnableInterface Sample
DisableInterface Sample
RegisterProtocol Sample
StartProtocol Sample
StopProtocol Sample
GetGlobalInfo Sample
SetGlobalInfo Sample
DoUpdateRoutes Sample
GetEventMessage Sample
MibCreate Sample
MibDelete Sample
MibGet Sample
MibSet Sample
MibGetFirst Sample
MibGetNext Sample


Routing Protocol Interface Code Samples

The following code samples demonstrate how an IP routing protocol might implement the functions in the routing protocol interface. The function DoUpdateServices is not implemented, since IP routing protocols do not provide services.


AddInterface Sample

DWORD
APIENTRY
AddInterface(
    IN PWCHAR               pwszInterfaceName,
    IN DWORD                dwIndex,
    IN NET_INTERFACE_TYPE   dwIfType,
    IN PVOID                pvConfig
    )
/*++
  Routine Description
      Called by the IP Router Manager to add an interface when
      it finds our information block (header) within the interface's
      configuration.
      We verify the information and create the structure for the
      interface.  Then we see all the configured addresses for
      the interface and create a binding structure for each address.
      The interface comes up as UNBOUND-DISABLED

  Arguments
      pwszInterfaceName The name of the interface. We store it
                        for logging
      dwIndex           The positive integer this interface will
                        be referred to by
      dwIfType          The type of the interface (WAN/LAN etc)
      pvConfig          Our config for this interface

  Return Value
      ERROR_INVALID_PARAMETER
      ERROR_INVALID_DATA
      NO_ERROR

--*/
{
    ULONG       ulNameLen,i;
    DWORD       dwResult;
    PWCHAR      pwszName;
    PINTRNL_IF  pBind;
    PNT_IF      pIf,pPrev;
    PLIST_ENTRY pleNode;

    PSAMPLE_PROTOCOL_INTERFACE_INFO pIfInfo;

    EnterProtocolApi();

    TraceEnter("AddInterface");

    Trace3(INTF, "AddInterface called for: %S %d %d ",
           pwszInterfaceName,
           dwIndex,
           dwIfType);

    ulNameLen = wcslen(pwszInterfaceName);

    if((pwszInterfaceName == NULL) ||
       (pvConfig == NULL) ||
       (ulNameLen == 0))
    {
        Trace0(ERR,
               "AddInterface: Router Manager called us with NULL info");

        TraceLeave("AddInterface");

        ExitProtocolApi();

        return ERROR_INVALID_PARAMETER;
    }

    pIfInfo = (PSAMPLE_PROTOCOL_INTERFACE_INFO)pvConfig;

    if(!ValidateInterfaceInfo(pIfInfo))
    {
        TraceLeave("AddInterface");

        ExitProtocolApi();

        return ERROR_INVALID_DATA;
    }

    EnterCriticalSection(&g_csIfListLock);

    //
    // Create the interface block and the blocks for the binding
    //

    dwResult = NO_ERROR;

    __try
    {
        pIf = HeapAlloc(g_hPrivateHeap,
                        HEAP_ZERO_MEMORY,
                        sizeof(NT_IF));

        if(pIf == NULL)
        {
            dwResult = GetLastError();

            Trace1(ERR,
                   "AddInterface: Error %d allocating memory for i/f",
                   dwResult);

            __leave;
        }

        InitializeListHead(&pIf->leInternalIfHead);

        pwszName = HeapAlloc(g_hPrivateHeap,
                             HEAP_ZERO_MEMORY,
                             (ulNameLen + 1)*sizeof(WCHAR));

        if(pwszName == NULL)
        {
            dwResult = GetLastError();

            Trace1(ERR,
                   "AddInterface: Error %d allocating memory for name",
                   dwResult);

            __leave;
        }

        wcscpy(pwszName,
               pwszInterfaceName);

        pIf->pwszIfName = pwszName;

        ClearNtState(pIf);

        pIf->dwType = dwIfType;

        pIf->ulNumBindings = pIfInfo->ulNumBindings;

        for(i = 0; i < pIfInfo->ulNumBindings; i++)
        {
            pBind = HeapAlloc(g_hPrivateHeap,
                                HEAP_ZERO_MEMORY,
                                sizeof(INTRNL_IF));

            if(pBind == NULL)
            {
                dwResult = GetLastError();

                Trace1(ERR,
                       "AddInterface: Error %d allocating memory for internal i/f",
                       dwResult);

                __leave;
            }

            InsertHeadList(&(pIf->leInternalIfHead),
                           &(pBind->leInternalIfLink));

            //
            // Copy out binding info
            //

            pBind->dwAddress    = pIfInfo->rgbiInfo[i].dwAddress;
            pBind->dwMask       = pIfInfo->rgbiInfo[i].dwMask;
            pBind->bEnabled     = pIfInfo->rgbiInfo[i].bEnabled;
            pBind->dwState      = BINDING_DOWN;
            pBind->sSocket      = INVALID_SOCKET;

            if(pIfInfo->ulNumBindings == 1)
            {
                //
                // If we have only one address, we set that to 0.0.0.0
                // for now even if our config has screwed up
                //

                pBind->dwAddress    = 0x00000000;
                pBind->dwMask       = 0x00000000;
            }
        }
    }
    __finally
    {
        if(dwResult != NO_ERROR)
        {
            //
            // Clean up all resources
            //

            if(pIf)
            {
                if(pIf->pwszIfName)
                {
                    HeapFree(g_hPrivateHeap,
                             0,
                             pIf->pwszIfName);
                }

                pleNode  = pIf->leInternalIfHead.Flink;

                while(pleNode != &pIf->leInternalIfHead)
                {
                    pBind = CONTAINING_RECORD(pleNode,
                                              INTRNL_IF,
                                              leInternalIfLink);

                    pleNode = pleNode->Flink;

                    HeapFree(g_hPrivateHeap,
                             0,
                             pBind);
                }
            }
        }
        else
        {
            //
            // Insert the interface into our link
            //

            for(pleNode  = g_leIfListHead.Flink;
                pleNode != &g_leIfListHead;
                pleNode  = pleNode->Flink)
            {
                pPrev = CONTAINING_RECORD(pleNode,
                                          NT_IF,
                                          leNtIfLink);

                if(pPrev->dwNtIndex > dwIndex)
                {
                    break;
                }
            }

            //
            // pPrev now points to the interface with a higher index
            // pPrev->Blink < dwIndex so put our interface after
            // pPrev->Blink. This way we get an ordered list
            //

            InsertHeadList(pPrev->leNtIfLink.Blink,
                           &(pIf->leNtIfLink));

        }
    }

    LeaveCriticalSection(&g_csIfListLock);

    TraceLeave("AddInterface");

    ExitProtocolApi();

    return dwResult;
}


DeleteInterface Sample

DWORD
APIENTRY
DeleteInterface(
    IN DWORD dwIndex
    )
/*++
  Routine Description
      Called by the IP Router Manager to delete an interface.
      If the interface is running we shut it down and free all the
      resources used by it.

  Arguments
      dwIndex   The index of the interface to be deleted

  Return Value
      ERROR_INVALID_PARAMETER   Interface with the given index not found
      NO_ERROR

--*/
{
    PNT_IF      pIf;
    PLIST_ENTRY pleNode;
    PINTRNL_IF  pBind;

    EnterProtocolApi();

    TraceEnter("DeleteInterface");

    Trace1(ERR,
           "DeleteInterface: Called for interface %d",
           dwIndex);

    EnterCriticalSection(&g_csIfListLock);

    pIf = GetIfBlockGivenIndex(dwIndex);

    if(pIf == NULL)
    {
        //
        // Did not have an interface corresponding to
        // this index
        //

        LeaveCriticalSection(&g_csIfListLock);

        Trace1(ERR,
               "DeleteInterface: Interface %d does not exist",
               dwIndex);

        TraceLeave("DeleteInterface");

        ExitProtocolApi();

        return ERROR_INVALID_PARAMETER;
    }

    //
    // Remove it from the list of NT Interfaces
    //

    RemoveEntryList(&(pIf->leNtIfLink));

    ASSERT(pIf->dwNtIndex == dwIndex);
    ASSERT(pIf->pwszIfName);

    //
    // Shut down each binding on the interface. We may have already
    // gotten Unbind() calls so they may have already been shut down
    //

    pleNode = pIf->leInternalIfHead.Flink;

    while(pleNode != &(pIf->leInternalIfHead))
    {
        pBind = CONTAINING_RECORD(pleNode, INTRNL_IF, leInternalIfLink);

        pleNode = pleNode->Flink;

        if(pBind->dwState == BINDING_UP)
        {
            //
            // So we did not get an unbind or disable for this
            //

            ASSERT(pBind->sSocket != INVALID_SOCKET);

            if(closesocket(pBind->sSocket) != NO_ERROR)
            {
                Trace3(ERR,
                       "DeleteInterface: Error %d closing socket %d on interface %S",
                       WSAGetLastError(),
                       pBind->sSocket,
                       pIf->pwszIfName);
            }
        }

        HeapFree(g_hPrivateHeap,
                 0,
                 pBind);
    }

    //
    // Free other resources
    //

    HeapFree(g_hPrivateHeap,
             0,
             pIf->pwszIfName);

    //
    // Lastly free the interface itself
    //

    HeapFree(g_hPrivateHeap,
             0,
             pIf);

    LeaveCriticalSection(&g_csIfListLock);

    TraceLeave("AddInterface");

    ExitProtocolApi();

    return NO_ERROR;
}


GetInterfaceConfigInfo Sample

DWORD
APIENTRY
GetInterfaceConfigInfo(
    IN     DWORD  dwIndex,
    IN OUT PVOID  pvConfig,
    IN OUT PDWORD pdwSize
    )
/*++
  Routine Description
      Called by the IP Router Manager to retrieve an
      interface's configuration. Usually this is because an admin
      utility is displaying this information. The Router Manager calls
      us with a NULL config and ZERO size. We return the required size
      to it. It then allocates the needed memory and calls us a second
      time with a valid buffer.  We validate parameters each time and
      copy out our config if we can

  Arguments
      dwIndex   Index of the interface being queried
      pvConfig  Pointer to buffer to store the config
      pdwSize   Size of the buffer

  Return Value
      ERROR_INSUFFICIENT_BUFFER If the size of the buffer is too small
      ERROR_INVALID_PARAMETER
      ERROR_INVALID_DATA
      NO_ERROR

--*/
{
    PNT_IF      pIf;
    PLIST_ENTRY pleNode;
    PINTRNL_IF  pBind;
    ULONG       i;

    PSAMPLE_PROTOCOL_INTERFACE_INFO pIfInfo;

    EnterProtocolApi();

    TraceEnter("GetInterfaceConfigInfo");

    if(pdwSize == NULL)
    {
        Trace0(ERR,
               "GetInterfaceConfigInfo: Router Manager called us with NULL size");

        TraceLeave("GetInterfaceConfigInfo");

        ExitProtocolApi();

        return ERROR_INVALID_PARAMETER;
    }

    EnterCriticalSection(&g_csIfListLock);

    pIf = GetIfBlockGivenIndex(dwIndex);

    if(pIf == NULL)
    {
        LeaveCriticalSection(&g_csIfListLock);

        Trace1(ERR,
               "GetInterfaceConfigInfo: Interface %d does not exist",
               dwIndex);

        TraceLeave("GetInterfaceConfigInfo");

        ExitProtocolApi();

        return ERROR_INVALID_PARAMETER;
    }

    if(*pdwSize < SIZEOF_PROTO_IF_INFO(pIf->ulNumBindings))
    {
        *pdwSize = SIZEOF_PROTO_IF_INFO(pIf->ulNumBindings);

        LeaveCriticalSection(&g_csIfListLock);

        TraceLeave("GetInterfaceConfigInfo");

        ExitProtocolApi();

        return ERROR_INSUFFICIENT_BUFFER;
    }

    *pdwSize = SIZEOF_PROTO_IF_INFO(pIf->ulNumBindings);

    if(pvConfig == NULL)
    {
        LeaveCriticalSection(&g_csIfListLock);

        Trace0(ERR,
               "GetInterfaceConfigInfo: Router Manager called us with NULL config buffer");

        TraceLeave("GetInterfaceConfigInfo");

        ExitProtocolApi();

        return ERROR_INVALID_PARAMETER;
    }

    //
    // So we have a good buffer of the right size
    // Copy out the info
    //

    pIfInfo = (PSAMPLE_PROTOCOL_INTERFACE_INFO)pvConfig;

    pIfInfo->ulNumBindings = pIf->ulNumBindings;

    for(pleNode  = pIf->leInternalIfHead.Flink, i = 0;
        pleNode != &pIf->leInternalIfHead;
        pleNode  = pleNode->Flink, i++)
    {
        pBind = CONTAINING_RECORD(pleNode, INTRNL_IF, leInternalIfLink);

        pIfInfo->rgbiInfo[i].dwAddress  = pBind->dwAddress;
        pIfInfo->rgbiInfo[i].dwMask     = pBind->dwMask;
        pIfInfo->rgbiInfo[i].bEnabled   = pBind->bEnabled;
    }

    ASSERT(i == pIf->ulNumBindings);

    //
    // If we had only one address we will return 0.0.0.0 as the address
    // even if we know what the current address is
    //

    if(pIf->ulNumBindings == 1)
    {
        pIfInfo->rgbiInfo[0].dwAddress  = 0x00000000;
        pIfInfo->rgbiInfo[0].dwMask     = 0x00000000;
    }

    LeaveCriticalSection(&g_csIfListLock);

    TraceLeave("GetInterfaceConfigInfo");

    ExitProtocolApi();

    return NO_ERROR;
}


SetInterfaceConfigInfo Sample

DWORD
APIENTRY
SetInterfaceConfigInfo(
    IN DWORD dwIndex,
    IN PVOID pConfig
    )
/*++
  Routine Description

  Arguments

  Return Value
      NO_ERROR

--*/
{
    PNT_IF      pIf;
    PLIST_ENTRY pleNode;
    PINTRNL_IF  pBind;
    ULONG       i;

    PSAMPLE_PROTOCOL_INTERFACE_INFO pIfInfo;

    EnterProtocolApi();

    TraceEnter("SetInterfaceConfigInfo");

    if(pConfig == NULL)
    {
        //
        // A NULL config means no change
        //

        TraceLeave("SetInterfaceConfigInfo");

        ExitProtocolApi();

        return NO_ERROR;
    }

    EnterCriticalSection(&g_csIfListLock);

    pIf = GetIfBlockGivenIndex(dwIndex);

    if(pIf == NULL)
    {
        Trace1(ERR,
               "SetInterfaceConfigInfo: Interface %d does not exist",
               dwIndex);

        TraceLeave("SetInterfaceConfigInfo");

        ExitProtocolApi();

        return ERROR_INVALID_PARAMETER;
    }

    return NO_ERROR;
}


BindInterface Sample

DWORD
APIENTRY
BindInterface(
    IN DWORD dwIndex,
    IN PVOID pBinding
    )
/*++
  Routine Description
      Called by the IP Router Manager once it learns the address(es)
      on an interface.  This may happen as soon as the router starts
      (after the interface is added, of course) when the interface has
      a static address or may happen when an interface acquires a DHCP
      address or may happen when IPCP acquire the address for a dial up
      link. The binding may consist of one or more addresses.  We walk
      the addresses given and find the corresponding block in our
      config.  We then update any information and if the interface has
      been enabled, we activate the binding, i.e. begin running on it.

  Arguments
      dwIndex   Index of the interface in question
      pBinding  Pointer to IP_ADAPTER_BINDING_INFO containing info about
                the addresses on the interface

  Return Value
      ERROR_INVALID_PARAMETER
      NO_ERROR

--*/
{
    PNT_IF      pIf;
    PLIST_ENTRY pleNode;
    PINTRNL_IF  pBind;
    ULONG       i;
    BOOL        bFound;
    DWORD       dwResult;

    PIP_ADAPTER_BINDING_INFO pBindingInfo;

    EnterProtocolApi();

    TraceEnter("BindInterface");

    if(pBinding == NULL)
    {
        Trace0(ERR,
               "BindInterface: Router Manager called us with NULL binding");

        TraceLeave("BindInterface");

        ExitProtocolApi();

        return ERROR_INVALID_PARAMETER;
    }

    pBindingInfo = (PIP_ADAPTER_BINDING_INFO)pBinding;

    if(pBindingInfo->NumAddresses < 1)
    {
        Trace0(ERR,
               "BindInterface: Router Manager called us with NO binding");

        TraceLeave("BindInterface");

        ExitProtocolApi();

        return ERROR_INVALID_PARAMETER;
    }

    EnterCriticalSection(&g_csIfListLock);

    pIf = GetIfBlockGivenIndex(dwIndex);

    if(pIf == NULL)
    {
        LeaveCriticalSection(&g_csIfListLock);

        Trace1(ERR,
               "BindInterface: Interface %d does not exist",
               dwIndex);

        TraceLeave("BindInterface");

        ExitProtocolApi();

        return ERROR_INVALID_PARAMETER;
    }

    if(IsNtBound(pIf))
    {
        //
        // Can not receive two bind notifications without an
        // Unbind in the middle
        //

        Trace1(ERR,
               "BindInterface: Interface %S is already bound",
               pIf->pwszIfName);

        LeaveCriticalSection(&g_csIfListLock);

        TraceLeave("BindInterface");

        ExitProtocolApi();

        return ERROR_INVALID_PARAMETER;
    }

    SetNtBound(pIf);

    for(i = 0; i < pBindingInfo->NumAddresses; i++)
    {
        pBind = GetBindingGivenAddress(pIf,
                                       pBindingInfo->Address[i].IPAddress);

        if(pBind == NULL)
        {
            //
            // Our config is bad, we will try and go through all
            // the blocks and see if we can at least bind on the others.
            //

            Trace3(ERR,
                   "BindInterface: Couldnt find config block for %d.%d.%d.%d/%d.%d.%d.%d over %S",
                   PRINT_ADDRESS(pBindingInfo->Address[i].IPAddress),
                   PRINT_ADDRESS(pBindingInfo->Address[i].Mask),
                   pIf->pwszIfName);

            continue;
        }

        if(pBindingInfo->NumAddresses == 1)
        {
            //
            // If we have only one address, then the addresses
            // may not match, so update them
            //

            pBind->dwAddress = pBindingInfo->Address[i].IPAddress;
            pBind->dwMask    = pBindingInfo->Address[i].Mask;
        }
    }

#if DBG

    //
    // Check to make sure we got bindings for all the
    // configured addresses
    //

    if(pIf->ulNumBindings > 1)
    {
        for(pleNode  = pIf->leInternalIfHead.Flink;
            pleNode != &pIf->leInternalIfHead;
            pleNode  = pleNode->Flink)
        {
            bFound = FALSE;

            pBind = CONTAINING_RECORD(pleNode, INTRNL_IF, leInternalIfLink);

            for(i = 0; i < pBindingInfo->NumAddresses; i++)
            {
                if(pBind->dwAddress == pBindingInfo->Address[i].IPAddress)
                {
                    ASSERT(pBind->dwMask == pBindingInfo->Address[i].Mask);

                    bFound = TRUE;
                    break;
                }
            }

            if(!bFound)
            {
                Trace3(ERR,
                       "BindInterface: Binding not indicated for %d.%d.%d.%d/%d.%d.%d.%d over %S",
                       PRINT_ADDRESS(pBind->dwAddress),
                       PRINT_ADDRESS(pBind->dwMask),
                       pIf->pwszIfName);
            }
        }
    }

#endif // DBG

    //
    // OK now we have the bindings all set up
    //

    if(IsNtEnabled(pIf))
    {
        //
        // So the interface is bound and enabled => we are all set
        // to go
        //

        for(pleNode  = pIf->leInternalIfHead.Flink;
            pleNode != &pIf->leInternalIfHead;
            pleNode  = pleNode->Flink)
        {
            pBind = CONTAINING_RECORD(pleNode, INTRNL_IF, leInternalIfLink);

            if(pBind->bEnabled)
            {
                //
                // Our config tells us that we are enabled
                // for this address
                //

                ASSERT(pBind->dwState != BINDING_UP);

                //
                // This will set the state to BINDING_UP
                //

                dwResult = ActivateBinding(pBind);

                if(dwResult != NO_ERROR)
                {
                    Trace2(ERR,
                           "BindInterface: Unable to activate %d.%d.%d.%d over %S",
                           PRINT_ADDRESS(pBind->dwAddress),
                           pIf->pwszIfName);
                }
            }
        }
    }

    LeaveCriticalSection(&g_csIfListLock);

    TraceLeave("BindInterface");

    ExitProtocolApi();

    return NO_ERROR;
}


UnBindInterface Sample

DWORD
APIENTRY
UnBindInterface(
    IN DWORD dwIndex
    )
/*++
  Routine Description
      Called when the interface loses its IP Address(es). This may
      happen when the interface is shutting down. It may be because an
      admin Disabled the interface with IP (as opposed to just disabling
      or protocol on the interface). It can happen when the admin
      releases a DHCP acquired interface or when a dial up link
      disconnects. We see if we were running on the binding and if so,
      we shut it down. We dont release any memory associated with the
      binding because we can get bound again.

  Arguments
      dwIndex   The index of the interface being unbound

  Return Value
      ERROR_INVALID_PARAMETER
      NO_ERROR

--*/
{
    PNT_IF      pIf;
    PLIST_ENTRY pleNode;
    PINTRNL_IF  pBind;
    DWORD       dwResult;

    EnterProtocolApi();

    TraceEnter("UnbindInterface");

    EnterCriticalSection(&g_csIfListLock);

    pIf = GetIfBlockGivenIndex(dwIndex);

    if(pIf == NULL)
    {
        LeaveCriticalSection(&g_csIfListLock);

        Trace1(ERR,
               "UnbindInterface: Interface %d does not exist",
               dwIndex);

        TraceLeave("UnbindInterface");

        ExitProtocolApi();

        return ERROR_INVALID_PARAMETER;
    }

    if(!IsNtBound(pIf))
    {
        //
        // Nothing new happening
        //

        Trace1(INTF,
               "UnbindInterface: Unbind received for %S which was never bound",
               pIf->pwszIfName);

        LeaveCriticalSection(&g_csIfListLock);

        TraceLeave("UnbindInterface");

        ExitProtocolApi();

        return NO_ERROR;
    }

    ClearNtBound(pIf);

    if(IsNtEnabled(pIf))
    {
        //
        // Since it is enabled and was bound, deactivate the
        // bindings
        //

        for(pleNode  = pIf->leInternalIfHead.Flink;
            pleNode != &pIf->leInternalIfHead;
            pleNode  = pleNode->Flink)
        {
            pBind = CONTAINING_RECORD(pleNode, INTRNL_IF, leInternalIfLink);

            if(pBind->dwState == BINDING_UP)
            {
                //
                // This binding had been successfully activated
                //

                dwResult = DeactivateBinding(pBind);

                if(dwResult != NO_ERROR)
                {
                    Trace2(ERR,
                           "UnbindInterface: Unable to deactivate %d.%d.%d.%d over %S",
                           PRINT_ADDRESS(pBind->dwAddress),
                           pIf->pwszIfName);
                }
            }
        }

        if(pIf->ulNumBindings == 1)
        {
            //
            // Clear out the old address
            //

            pBind = CONTAINING_RECORD(pIf->leInternalIfHead.Flink,
                                      INTRNL_IF,
                                      leInternalIfLink);

            pBind->dwAddress = 0x00000000;
            pBind->dwMask    = 0x00000000;
        }
    }

    LeaveCriticalSection(&g_csIfListLock);

    TraceLeave("UnbindInterface");

    ExitProtocolApi();

    return NO_ERROR;

}


EnableInterface Sample

DWORD
APIENTRY
EnableInterface(
    IN DWORD dwIndex
    )
/*++
  Routine Description
      An interface comes up in a DISABLED state. This function is
      called by the router manager to enable the interface.  It can also
      be called when the interface is being reenabled after being
      disabled by the admin. The bindings on an interface are kept
      across and Enable-Disable, so we heck to see if we were already
      bound, and if so we activate the protocol over the bindings.

  Arguments
      dwIndex   Interface to be enabled

  Return Value
      NO_ERROR

--*/
{
    PNT_IF      pIf;
    PLIST_ENTRY pleNode;
    PINTRNL_IF  pBind;
    DWORD       dwResult;

    EnterProtocolApi();

    TraceEnter("EnableInterface");

    EnterCriticalSection(&g_csIfListLock);

    pIf = GetIfBlockGivenIndex(dwIndex);

    if(pIf == NULL)
    {
        LeaveCriticalSection(&g_csIfListLock);

        Trace1(ERR,
               "EnableInterface: Interface %d does not exist",
               dwIndex);

        TraceLeave("EnableInterface");

        ExitProtocolApi();

        return ERROR_INVALID_PARAMETER;
    }

    if(IsNtEnabled(pIf))
    {
        //
        // Nothing new happening
        //

        Trace1(INTF,
               "EnableInterface: Enable received for %S which is already enabled",
               pIf->pwszIfName);

        LeaveCriticalSection(&g_csIfListLock);

        TraceLeave("EnableInterface");

        ExitProtocolApi();

        return NO_ERROR;
    }

    SetNtEnabled(pIf);

    if(IsNtBound(pIf))
    {
        //
        // Since it is enabled and bound, activate the bindings
        //

        for(pleNode  = pIf->leInternalIfHead.Flink;
            pleNode != &pIf->leInternalIfHead;
            pleNode  = pleNode->Flink)
        {
            pBind = CONTAINING_RECORD(pleNode, INTRNL_IF, leInternalIfLink);

            ASSERT(pBind->dwState == BINDING_DOWN);

            if(pBind->bEnabled)
            {
                dwResult = ActivateBinding(pBind);

                if(dwResult != NO_ERROR)
                {
                    Trace2(ERR,
                           "EnableInterface: Unable to activate %d.%d.%d.%d over %S",
                           PRINT_ADDRESS(pBind->dwAddress),
                           pIf->pwszIfName);
                }
            }
        }
    }

    LeaveCriticalSection(&g_csIfListLock);

    TraceLeave("EnableInterface");

    ExitProtocolApi();

    return NO_ERROR;
}


DisableInterface Sample

DWORD
APIENTRY
DisableInterface(
    IN DWORD dwIndex
    )
/*++
  Routine Description
      Called by the IP Router Manger to disable an interface.  This is
      usually in response to an admin setting the AdminStatus in IP to
      DOWN. This is different from an admin just disabling the bEnabled
      flag in our config because that is opaque to IP. That is a routing
      protocol specific disable and is conveyed to us via
      SetInterfaceConfig() calls.  THIS IS AN IMPORTANT DISTINCTION. A
      ROUTING PROTOCOL NEEDS TO MANTAIN TWO STATES - AN NT STATE AND A
      PROTOCOL SPECIFIC STATE.

  Arguments
      dwIndex   The index of the interface to disable

  Return Value
      ERROR_INVALID_PARAMETER
      NO_ERROR

--*/
{
    PNT_IF      pIf;
    PLIST_ENTRY pleNode;
    PINTRNL_IF  pBind;
    DWORD       dwResult;

    EnterProtocolApi();

    TraceEnter("DisableInterface");

    EnterCriticalSection(&g_csIfListLock);

    pIf = GetIfBlockGivenIndex(dwIndex);

    if(pIf == NULL)
    {
        LeaveCriticalSection(&g_csIfListLock);

        Trace1(ERR,
               "DisableInterface: Interface %d does not exist",
               dwIndex);

        TraceLeave("DisableInterface");

        ExitProtocolApi();

        return ERROR_INVALID_PARAMETER;
    }

    if(!IsNtEnabled(pIf))
    {
        //
        // Nothing new happening
        //

        Trace1(INTF,
               "DisableInterface: Disable received for %S which was never enabled",
               pIf->pwszIfName);

        LeaveCriticalSection(&g_csIfListLock);

        TraceLeave("DisableInterface");

        ExitProtocolApi();

        return NO_ERROR;
    }

    ClearNtEnabled(pIf);

    if(IsNtBound(pIf))
    {
        //
        // Since it was enabled and is bound, it must have been
        // activated, so deactivate the bindings now
        //

        for(pleNode  = pIf->leInternalIfHead.Flink;
            pleNode != &pIf->leInternalIfHead;
            pleNode  = pleNode->Flink)
        {
            pBind = CONTAINING_RECORD(pleNode, INTRNL_IF, leInternalIfLink);

            if(pBind->dwState == BINDING_UP)
            {
                //
                // This binding had been successfully activated
                //

                dwResult = DeactivateBinding(pBind);

                if(dwResult != NO_ERROR)
                {
                    Trace2(ERR,
                           "DisableInterface: Unable to deactivate %d.%d.%d.%d over %S",
                           PRINT_ADDRESS(pBind->dwAddress),
                           pIf->pwszIfName);
                }
            }
        }
    }

    LeaveCriticalSection(&g_csIfListLock);

    TraceLeave("DisableInterface");

    ExitProtocolApi();

    return NO_ERROR;

}


RegisterProtocol Sample

DWORD
APIENTRY
RegisterProtocol(
    IN OUT PMPR_ROUTING_CHARACTERISTICS pRoutingChar,
    IN OUT PMPR_SERVICE_CHARACTERISTICS pServiceChar
    )
/*++
Routine Description
    This is the first function called by the IP Router Manager.
    The Router Manager tells the routing protocol it version and
    capabilities. It also tells the our DLL, the ID of the protocol
    it expects us to register.  This allows one DLL to support
    multiple routing protocols.
    We return the functionality we support and a pointer to
    our functions.

Arguments

Return Value
    NO_ERROR

--*/
{
    //
    // The Router Manager should be calling us to register
    // our protocol.
    // The Router Manager must be atleast the version we are
    // compiled with.
    // The Router Manager must support routing and demand update.
    //

    if(pRoutingChar->dwProtocolId != SAMPLE_PROTOCOL_ROUTE_ID)
    {
        return ERROR_NOT_SUPPORTED;
    }

    if(pRoutingChar->dwVersion < MS_ROUTER_VERSION)
    {
        return ERROR_NOT_SUPPORTED;
    }

    if(pRoutingChar->fSupportedFunctionality != (ROUTING |
                                             DEMAND_UPDATE_ROUTES))
    {
        return ERROR_NOT_SUPPORTED;
    }

    //
    // Since we are not a service advertiser (an IPX thing)
    //

    //
    // We setup our characteristics and function pointers
    //

    pServiceChar->fSupportedFunctionality = 0;

    pRoutingChar->fSupportedFunctionality = (ROUTING |
                                             DEMAND_UPDATE_ROUTES);

    pRoutingChar->pfnStartProtocol    = StartProtocol;
    pRoutingChar->pfnStopProtocol     = StopProtocol;
    pRoutingChar->pfnAddInterface     = AddInterface;
    pRoutingChar->pfnDeleteInterface  = DeleteInterface;
    pRoutingChar->pfnGetEventMessage  = GetEventMessage;
    pRoutingChar->pfnGetInterfaceInfo = GetInterfaceConfigInfo;
    pRoutingChar->pfnSetInterfaceInfo = SetInterfaceConfigInfo;
    pRoutingChar->pfnBindInterface    = BindInterface;
    pRoutingChar->pfnUnbindInterface  = UnBindInterface;
    pRoutingChar->pfnEnableInterface  = EnableInterface;
    pRoutingChar->pfnDisableInterface = DisableInterface;
    pRoutingChar->pfnGetGlobalInfo    = GetGlobalInfo;
    pRoutingChar->pfnSetGlobalInfo    = SetGlobalInfo;
    pRoutingChar->pfnMibCreateEntry   = MibCreate;
    pRoutingChar->pfnMibDeleteEntry   = MibDelete;
    pRoutingChar->pfnMibGetEntry      = MibGet;
    pRoutingChar->pfnMibSetEntry      = MibSet;
    pRoutingChar->pfnMibGetFirstEntry = MibGetFirst;
    pRoutingChar->pfnMibGetNextEntry  = MibGetNext;
    pRoutingChar->pfnUpdateRoutes     = DoUpdateRoutes;

    return NO_ERROR;
}


StartProtocol Sample

DWORD
APIENTRY
StartProtocol(
    IN HANDLE               hMgrNotifyEvent,
    IN PSUPPORT_FUNCTIONS   pSupportFunctions,
    IN PVOID                pvConfig
    )
/*++
  Routine Description
      After the protocol has been registered, the IP Router Manager
      calls this function to tell the protocol to start. Most of the
      startup code is executed here.

  Arguments
      hMgrNotifyEvent   Event to Set if the IP Router Manager needs to
                        be notified to take any action on our behalf
      pSupportFunctions Some functions exported by IP Router Manager
      pvConfig          Our global configuration which was setup by our
                        setup/admin DLL

  Return Value
      NO_ERROR

--*/
{
    WSADATA wsaData;
    DWORD   dwResult, dwThread;
    HANDLE  hThread;
    BOOL    bWinsockLoaded;

    PSAMPLE_PROTOCOL_GLOBAL_INFO    pGlobalInfo;

    EnterProtocolApi();

    TraceEnter("StartProtocol");

    if(pvConfig == NULL)
    {
        Trace0(ERR,
               "StartProtocol: Called with NULL config");

        TraceLeave("StartProtocol");

        ExitProtocolApi();

        return ERROR_INVALID_PARAMETER;
    }

    pGlobalInfo = (PSAMPLE_PROTOCOL_GLOBAL_INFO)pvConfig;

    if(!ValidateGlobalInfo(pGlobalInfo))
    {
        TraceLeave("StartProtocol");

        ExitProtocolApi();

        return ERROR_INVALID_DATA;
    }

    g_hPrivateHeap       = NULL;
    g_hRtmEvent          = NULL;
    g_hMgrNotifyEvent    = NULL;
    g_hRtmHandle         = NULL;
    g_hStopProtocolEvent = NULL;
    g_hSocketEvent       = NULL;
    g_pmmStopMsg         = NULL;
    bWinsockLoaded       = FALSE;

    g_psfnSupportFunctions = pSupportFunctions;

    do
    {
        InitializeCriticalSections();

        //
        // We need Winsock2.0 or better
        //

        dwResult = (DWORD)WSAStartup(MAKEWORD(2,0), &wsaData);

        if(dwResult != 0)
        {

            Trace1(ERR,
                   "StartProtocol: Error %d starting WinSock.", dwResult);

            LogErr0(WINSOCK_FAIL,
                    dwResult);
            break;
        }

        bWinsockLoaded = TRUE;

        dwResult = CreateHeaps();

        if(dwResult != NO_ERROR)
        {
            break;
        }

        dwResult = CreateEvents();

        if(dwResult != NO_ERROR)
        {
            break;
        }

        //
        // The message that will be used to notify the stopping
        // of this protocol. If we cant create this, we wont be
        // able to stop
        //

        g_pmmStopMsg = HeapAlloc(g_hPrivateHeap,
                                 0,
                                 sizeof(MGR_MSG));

        if(g_pmmStopMsg == NULL)
        {
            dwResult = GetLastError();

            Trace1(ERR,
                   "StartProtocol: Couldnt allocate stop message. Error %d",
                   dwResult);

            break;
        }

        //
        // Register as an RTM client. We will not keep multiple routes
        // to one destination so we set the flags to denote this
        //

        g_hRtmHandle = RtmRegisterClient(RTM_PROTOCOL_FAMILY_IP,
                                         SAMPLE_PROTOCOL_ROUTE_ID,
                                         g_hRtmEvent,
                                         RTM_PROTOCOL_SINGLE_ROUTE);

        if(g_hRtmHandle == NULL)
        {
            dwResult = GetLastError();

            Trace1(ERR,
                   "StartProtocol: Error %d registering with RTM",
                   dwResult);

            LogErr0(RTM_REGISTER_FAILED,
                    dwResult);

            break;
        }

        //
        // Create the main thread. This executes the MainThread()
        // function
        //

        hThread = CreateThread(NULL, 0,
                               MainThread,
                               NULL,
                               0,
                               &dwThread);

        if (hThread == NULL)
        {
            dwResult = GetLastError();

            Trace1(ERR,
                   "StartProtocol: Error %d starting main thread",
                   dwResult);

            LogErr0(CREATE_THREAD_FAILED,
                    dwResult);

            break;
        }

        //
        // We will never refer to the thread using the handle
        // so close it and avoid a leak
        //

        CloseHandle(hThread);

    }while(FALSE);

    if(dwResult != NO_ERROR)
    {
        //
        // Something bad happened
        //

        if(g_pmmStopMsg)
        {
            HeapFree(g_hPrivateHeap,
                     0,
                     g_pmmStopMsg);
        }

        CleanupProtocol(bWinsockLoaded);

    }
    else
    {
        g_hMgrNotifyEvent = hMgrNotifyEvent;

        g_dwProtocolState = PROTOCOL_STATE_RUNNING;
    }

    TraceLeave("StartProtocol");

    ExitProtocolApi();

    return NO_ERROR;
}


StopProtocol Sample

DWORD
APIENTRY
StopProtocol()
/*++
  Routine Description
     This function is called by the IP Router Manager to tell the
     protocol to stop.  We set the protocol state to prevent us from
     servicing any more requests. Then we notify the MainThread to stop
     and return PENDING to the IP Router Manager. If we had no thread
     and no work functions in our implementation, we could have stopped
     synchronously.

  Arguments

  Return Value
     PENDING

--*/
{
    EnterCriticalSection(&g_csProtocolStateLock);

    TraceEnter("StopProtocol");

    //
    // Cannot stop if already stopped
    //

    if(g_dwProtocolState != PROTOCOL_STATE_RUNNING)
    {
        Trace1(GLOBAL,
               "StopProtocol: Protocol state is %s",
               g_ppszStateStrings[g_dwProtocolState]);

        TraceLeave("StopProtocol");

        LeaveCriticalSection(&g_csProtocolStateLock);

        ExitProtocolApi();

        return ERROR_CAN_NOT_COMPLETE;
    }

    //
    // Dont release the state lock, so that the other threads
    // won't cleanup under us
    //

    //
    // Tell the main thread to stop. That will clean out everything
    //

    Trace0(GLOBAL,
           "StopProtocol: Signalling main thread to stop");

    SetEvent(g_hStopProtocolEvent);

    //
    // Set state to STOPPING;
    //

    g_dwProtocolState = PROTOCOL_STATE_STOPPING;

    Trace1(GLOBAL,
           "StopProtocol: %d threads are still active",
           g_dwProtocolRefCount);

    TraceLeave("StopProtocol");

    LeaveCriticalSection(&g_csProtocolStateLock);

    return ERROR_PROTOCOL_STOP_PENDING;
}


GetGlobalInfo Sample

DWORD
APIENTRY
GetGlobalInfo(
    IN OUT PVOID    pvConfig,
    IN OUT PDWORD   pdwSize
    )
/*++
  Routine Description
      The function is called by the IP Router Manager, usually in
      because of a query by the admin utility.  We see if we have space
      enough to return our global config. If we do we return it,
      otherwise we return the size needed.

  Arguments
      pvConfig  Pointer to allocated buffer to store our config
      pdwSize   Size of config.

  Return Value
      ERROR_INSUFFICIENT_BUFFER If the size of the buffer is too small
      ERROR_INVALID_PARAMETER
      ERROR_INVALID_DATA
      NO_ERROR

--*/
{
    PSAMPLE_PROTOCOL_GLOBAL_INFO    pGlobalInfo;

    EnterProtocolApi();

    TraceEnter("GetGlobalInfo");

    if(pdwSize == NULL)
    {
        Trace0(ERR,
               "GetGlobalInfo: Router Manager called us with NULL size");

        TraceLeave("GetGlobalInfo");

        ExitProtocolApi();

        return ERROR_INVALID_PARAMETER;
    }

    if((*pdwSize < sizeof(SAMPLE_PROTOCOL_GLOBAL_INFO))||
       (pvConfig == NULL))
    {
        //
        // Either the size was too small or there was no
        // storage
        //

        *pdwSize = sizeof(SAMPLE_PROTOCOL_GLOBAL_INFO);

        Trace3(GLOBAL,
               "GetGlobalInfo: Router Manager called us with size %d and info %x. Info size should be %d",
               *pdwSize,
               pvConfig,
               sizeof(SAMPLE_PROTOCOL_GLOBAL_INFO));

        TraceLeave("GetGlobalInfo");

        ExitProtocolApi();

        return ERROR_INSUFFICIENT_BUFFER;
    }

    *pdwSize = sizeof(SAMPLE_PROTOCOL_GLOBAL_INFO);

    //
    // Ok, so we have a good buffer to write our info into
    //

    pGlobalInfo = (PSAMPLE_PROTOCOL_GLOBAL_INFO)pvConfig;

    //
    // Currently that is all the info we have
    //

    EnterCriticalSection(&g_csGlobalInfoLock);

    pGlobalInfo->dwLogLevel = g_dwLogLevel;

    LeaveCriticalSection(&g_csGlobalInfoLock);

    TraceLeave("GetGlobalInfo");

    ExitProtocolApi();

    return NO_ERROR;
}


SetGlobalInfo Sample

DWORD
APIENTRY
SetGlobalInfo(
    IN PVOID pvConfig
    )
/*++
  Routine Description
      Called by the IP Router Manager usually in response to an admin
      utility changing the config.  We verify the parameters and the
      info and set it

  Arguments

  Return Value
      ERROR_INVALID_PARAMETER
      ERROR_INVALID_DATA
      NO_ERROR

--*/
{
    PSAMPLE_PROTOCOL_GLOBAL_INFO    pGlobalInfo;

    EnterProtocolApi();

    TraceEnter("SetGlobalInfo");

    if(pvConfig == NULL)
    {
        Trace0(ERR,
               "SetGlobalInfo: Router Manager called us with NULL info");

        TraceLeave("SetGlobalInfo");

        ExitProtocolApi();

        return ERROR_INVALID_PARAMETER;
    }

    pGlobalInfo = (PSAMPLE_PROTOCOL_GLOBAL_INFO)pvConfig;

    if(!ValidateGlobalInfo(pGlobalInfo))
    {
        //
        // Bad global info
        //

        TraceLeave("SetGlobalInfo");

        ExitProtocolApi();

        return ERROR_INVALID_DATA;
    }

    //
    // Good info
    //

    EnterCriticalSection(&g_csGlobalInfoLock);

    g_dwLogLevel = pGlobalInfo->dwLogLevel;

    LeaveCriticalSection(&g_csGlobalInfoLock);

    TraceLeave("SetGlobalInfo");

    ExitProtocolApi();

    return ERROR_INVALID_DATA;

}


DoUpdateRoutes Sample

DWORD
APIENTRY
DoUpdateRoutes(
    IN DWORD dwIndex
    )
/*++
  Routine Description
      This function is called by the IP Router Manger to ask us to
      update routes over a Demand Dial link.  The link has already been
      brought up so should be in ENABLED-BOUND state.  After we are done
      we need to set the g_hMgrNotifyEvent to inform the Router Manager
      that we have a message in our queue to be delivered to it. The
      Router Manager will call our GetEventMessage() function in which
      we will inform it that we are done with update routes (and the
      routes have been stored in RTM). The Router Manager will "freeze"
      these routes by converting them to AUTOSTATIC.

  Arguments

  Return Value
      NO_ERROR/PENDING  For Success

--*/
{
    DWORD   dwResult;

    //
    // We will fire off a worker function to do the "real work"
    // That will set the event
    //

    dwResult = QueueAsyncFunction(UpdateRoutes,
                                  (PVOID)dwIndex,
                                  TRUE);

    return dwResult;
}


GetEventMessage Sample

DWORD
APIENTRY
GetEventMessage(
    OUT ROUTING_PROTOCOL_EVENTS *pEvent,
    OUT PMESSAGE                pResult
    )
/*++
  Routine Description
      This is called by the IP Router Manager if we indicate that we
      have a message in our queue to be delivered to it (by setting the
      g_hMgrNotifyEvent)

  Arguments

  Return Value
      NO_ERROR

--*/
{
    PLIST_ENTRY pleNode;
    PMGR_MSG    pmmMsg;

    //
    // IMPORTANT: This can be called after the protocol is stopped
    // so we dont do ref counting for this API.
    //

    EnterCriticalSection(&g_csQueueLock);

    if(IsListEmpty(&g_leMsgQueue))
    {
        LeaveCriticalSection(&g_csQueueLock);

        return ERROR_NO_MORE_ITEMS;
    }

    pleNode = RemoveHeadList(&g_leMsgQueue);

    LeaveCriticalSection(&g_csQueueLock);

    pmmMsg = CONTAINING_RECORD(pleNode,
                               MGR_MSG,
                               leMsgLink);

    *pEvent  = pmmMsg->rreEvent;
    *pResult = pmmMsg->mResult;

    HeapFree(g_hPrivateHeap,
             0,
             pmmMsg);

    return NO_ERROR;
}


MibCreate Sample

DWORD
APIENTRY
MibCreate(
    IN DWORD dwInputSize,
    IN PVOID pInputData
    )
/*++
  Routine Description

  Arguments

  Return Value
      NO_ERROR

--*/
{
    //
    // Not supported
    //

    return NO_ERROR;
}


MibDelete Sample

DWORD
APIENTRY
MibDelete(
    IN DWORD dwInputSize,
    IN PVOID pInputData
    )
/*++
  Routine Description

  Arguments

  Return Value
      NO_ERROR

--*/
{
    //
    // Not supported
    //

    return NO_ERROR;
}


MibGet Sample

DWORD
APIENTRY
MibGet(
    IN     DWORD  dwInputSize,
    IN     PVOID  pInputData,
    IN OUT PDWORD pdwOutputSize,
       OUT PVOID  pOutputData
    )
/*++
  Routine Description
      Called by an admin (SNMP) utility.  It actually passes through the
      IP Router Manager, but all that does is demux the call to the
      desired routing protocol. We verify the parameters and return the
      information if we can

  Arguments

  Return Value
      ERROR_INSUFFICIENT_BUFFER
      ERROR_INVALID_PARAMETER
      ERROR_NO_DATA
      ERROR_NO_MORE_ITEMS
      ERROR_INVALID_INDEX
      NO_ERROR

--*/
{
    PPROTO_MIB_QUERY    pQuery;
    PPROTO_MIB_RESPONSE pResponse;
    PPROTO_MIB_INTF     pMibIf;
    PPROTO_MIB_GLOBAL   pMibGlobal;
    ULONG               ulNumIndices;
    DWORD               dwResult;

    EnterProtocolApi();

    TraceEnter("MibGet");

    if(dwInputSize < sizeof(DWORD))
    {
        //
        // Need atleas the OID to do the get
        //

        TraceLeave("MibGet");

        ExitProtocolApi();

        return ERROR_INVALID_PARAMETER;
    }

    //
    // The input to the function is the query
    //

    pQuery      = (PPROTO_MIB_QUERY)pInputData;
    pResponse   = (PPROTO_MIB_RESPONSE)pOutputData;

    //
    // It would be really bad if someone messed the sizes up
    //

    ASSERT(dwInputSize%sizeof(DWORD) == 0);

    ulNumIndices = NUM_INDICES(dwInputSize);

    dwResult = NO_ERROR;

    switch(pQuery->dwOid)
    {
        case PROTO_MIB_GLOBAL_ID:
        {
            //
            // The output size needed is the PROTO_MIB_RESPONSE + just
            // enough for the structure we need. We dont need space for
            // the whole union
            //

            if(*pdwOutputSize < FIELD_OFFSET(PROTO_MIB_RESPONSE, mgGlobal) + sizeof(PROTO_MIB_GLOBAL))
            {
                *pdwOutputSize = FIELD_OFFSET(PROTO_MIB_RESPONSE, mgGlobal) + sizeof(PROTO_MIB_GLOBAL);

                dwResult = ERROR_INSUFFICIENT_BUFFER;

                break;
            }

            *pdwOutputSize = FIELD_OFFSET(PROTO_MIB_RESPONSE, mgGlobal) + sizeof(PROTO_MIB_GLOBAL);

            pResponse->dwOid = PROTO_MIB_GLOBAL_ID;

            EnterCriticalSection(&g_csGlobalInfoLock);

            pResponse->mgGlobal.dwLogLevel = g_dwLogLevel;

            LeaveCriticalSection(&g_csGlobalInfoLock);

            break;
        }
        case PROTO_MIB_INTF_ID:
        {
            EnterCriticalSection(&g_csIfListLock);

            dwResult = LocateInterface(QUERY_TYPE_GET,
                                       pQuery,
                                       ulNumIndices,
                                       pResponse,
                                       pdwOutputSize);

            LeaveCriticalSection(&g_csIfListLock);

            break;
        }
        default:
        {
            dwResult = ERROR_INVALID_PARAMETER;

            break;
        }
    }

    TraceLeave("MibGet");

    ExitProtocolApi();

    return dwResult;
}


MibSet Sample

DWORD
APIENTRY
MibSet(
    IN DWORD dwInputSize,
    IN PVOID pInputData
    )
/*++
  Routine Description

  Arguments

  Return Value
      NO_ERROR

--*/
{
    //
    // Not supported
    //

    return NO_ERROR;
}


MibGetFirst Sample

DWORD
APIENTRY
MibGetFirst(
    IN     DWORD  dwInputSize,
    IN     PVOID  pInputData,
    IN OUT PDWORD pdwOutputSize,
       OUT PVOID  pOutputData
    )
/*++
  Routine Description

  Locks

  Arguments

  Return Value
      NO_ERROR

--*/
{
    PPROTO_MIB_QUERY    pQuery;
    PPROTO_MIB_RESPONSE pResponse;
    PPROTO_MIB_INTF     pMibIf;
    PPROTO_MIB_GLOBAL   pMibGlobal;
    ULONG               ulNumIndices;
    DWORD               dwResult;

    EnterProtocolApi();

    TraceEnter("MibGet");

    if(dwInputSize < sizeof(DWORD))
    {
        //
        // Need at least the OID to do the get
        //

        TraceLeave("MibGet");

        ExitProtocolApi();

        return ERROR_INVALID_PARAMETER;
    }

    //
    // The input to the function is the query
    //

    pQuery      = (PPROTO_MIB_QUERY)pInputData;
    pResponse   = (PPROTO_MIB_RESPONSE)pOutputData;

    //
    // It would be really bad if someone messed the sizes up
    //

    ASSERT(dwInputSize%sizeof(DWORD) == 0);

    ulNumIndices = NUM_INDICES(dwInputSize);

    dwResult = NO_ERROR;

    switch(pQuery->dwOid)
    {
        case PROTO_MIB_GLOBAL_ID:
        {
            //
            // Only support GET_FIRST for tables
            //

            dwResult = ERROR_INVALID_PARAMETER;

            break;
        }
        case PROTO_MIB_INTF_ID:
        {
            EnterCriticalSection(&g_csIfListLock);

            dwResult = LocateInterface(QUERY_TYPE_GET_FIRST,
                                       pQuery,
                                       ulNumIndices,
                                       pResponse,
                                       pdwOutputSize);

            LeaveCriticalSection(&g_csIfListLock);

            break;
        }
    }

    TraceLeave("MibGet");

    ExitProtocolApi();

    return dwResult;
}


MibGetNext Sample

DWORD
APIENTRY
MibGetNext(
    IN     DWORD  dwInputSize,
    IN     PVOID  pInputData,
    IN OUT PDWORD pdwOutputSize,
       OUT PVOID  pOutputData
    )
/*++
  Routine Description

  Locks

  Arguments

  Return Value
      NO_ERROR

--*/
{
    PPROTO_MIB_QUERY    pQuery;
    PPROTO_MIB_RESPONSE pResponse;
    PPROTO_MIB_INTF     pMibIf;
    PPROTO_MIB_GLOBAL   pMibGlobal;
    ULONG               ulNumIndices;
    DWORD               dwResult;

    EnterProtocolApi();

    TraceEnter("MibGet");

    if(dwInputSize < sizeof(DWORD))
    {
        //
        // Need at least the OID to do the get
        //

        TraceLeave("MibGet");

        ExitProtocolApi();

        return ERROR_INVALID_PARAMETER;
    }

    //
    // The input to the function is the query
    //

    pQuery      = (PPROTO_MIB_QUERY)pInputData;
    pResponse   = (PPROTO_MIB_RESPONSE)pOutputData;

    //
    // It would be really bad if someone messed the sizes up
    //

    ASSERT(dwInputSize%sizeof(DWORD) == 0);

    ulNumIndices = NUM_INDICES(dwInputSize);

    dwResult = NO_ERROR;

    switch(pQuery->dwOid)
    {
        case PROTO_MIB_GLOBAL_ID:
        {
            //
            // Only support GET_NEXT for tables
            //

            dwResult = ERROR_INVALID_PARAMETER;

            break;
        }
        case PROTO_MIB_INTF_ID:
        {
            EnterCriticalSection(&g_csIfListLock);

            dwResult = LocateInterface(QUERY_TYPE_GET_FIRST,
                                       pQuery,
                                       ulNumIndices,
                                       pResponse,
                                       pdwOutputSize);

            LeaveCriticalSection(&g_csIfListLock);

            break;
        }
    }

    TraceLeave("MibGet");

    ExitProtocolApi();

    return dwResult;
}


Routing Protocol Interface Reference

The following documentation covers the functions and structures to use when implementing a routing protocol as a user-mode DLL.


Routing Protocol Interface Functions

A routing protocol DLL should implement the following functions. A possible exception is the DoUpdateServices function. Only routing protocol that support services need to implement DoUpdateServices.


RegisterProtocol

The RegisterProtocol function registers the routing protocol with the router manager. It also informs the router manager what functionality the routing protocol supports.

DWORD RegisterProtocol (
    PMPR_ROUTING_CHARACTERISTICS   pRoutingChar,
    PMPR_SERVICE_CHARACTERISTICS   pServiceChar
);

Parameters

pRoutingChar,
Pointer to an MPR_ROUTING_CHARACTERISTICS structure. See the reference page for this structure for more information on how to use it with the RegisterProtocol function.
pServiceChar
Pointer to an MPR_SERVICE_CHARACTERISTICS structure. See the reference page for this structure for more information on how to use it with the RegisterProtocol function.

Return Values

NO_ERROR
The routing protocol agreed to register with the router manager.
ERROR_NOT_SUPPORTED
The routing protocol refused to register with the router manager.

Remarks

All routing protocol DLLs must fill in values for the MPR_ROUTING_CHARACTERISTICS structure.

Routing protocol DLLs that provide services must fill in values for the MPR_SERVICE_CHARACTERISTICS structure. If a routing protocol DLL does not provide services, it should fill in zero for the fSupportedFunctionality member of this structure, but need not fill in values for the other members.

Routing protocols are implemented in user-mode DLLs. A single DLL may implement multiple routing protocols. Therefore, router manager may call RegisterProtocol multiple times, once for each routing protocol implemented in the DLL.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in routprot.h.
Import Library: user-defined.

See Also

MPR_ROUTING_CHARACTERISTICS, MPR_SERVICE_CHARACTERISTICS, RegisterProtocol Sample


StartProtocol

The StartProtocol function initializes the routing protocol's functionality. The router manager uses this function to pass the routing protocol global configuration parameters and a set of API entry points. The protocol uses these entry points to call into the router manager.

DWORD StartProtocol(
  HANDLE NotificationEvent,
                    // handle to an event object
  PSUPPORT_FUNCTIONS SupportFunctions,
                    // address of SUPPORT_FUNCTIONS structure
  PVOID GlobalInfo  // address of configuration information
);

Parameters

NotificationEvent
Handle to an event object. The routing protocol will signal this event when it wants the router manager to retrieve an asynchronous message from the queue maintained by the protocol.
SupportFunctions
Pointer to a SUPPORT_FUNCTIONS structure. The fields of this structure are pointers to functions in the router manager. These functions allow the protocol to access information that spans routing protocols.
GlobalInfo
Pointer to protocol-defined global (as opposed to interface specific) configuration information. This information is private to the routing protocol.

Return Values

NO_ERROR
The routing protocol initialized successfully and is ready to receive interface information.
ERROR_CAN_NOT_COMPLETE
The attempt to initialize the routing protocol failed.
ERROR_INVALID_PARAMETER
One of the parameters pointed to by the GlobalInfo parameter is invalid.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in routprot.h.
Import Library: user-defined.

See Also

GetEventMessage, StartProtocol Sample, StopProtocol, SUPPORT_FUNCTIONS


StopProtocol

The StopProtocol function causes the routing protocol to perform an orderly shutdown.

DWORD StopProtocol(void);

Return Values

NO_ERROR
The routing protocol shutdown successfully (synchronous completion).
ERROR_PROTOCOL_STOP_PENDING
The routing protocol has initiated the shutdown process. The protocol will report the results through the event-message queue.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in routprot.h.
Import Library: user-defined.

See Also

GetEventMessage, StartProtocol, StopProtocol Sample


GetEventMessage

The GetEventMessage function gets an entry from the routing protocol's message queue. The routing protocol uses the queue to inform the router manager of asynchronous events.

DWORD GetEventMessage(
  ROUTING_PROTOCOL_EVENTS  * Event,
                       // address of message queue entry
  MESSAGE  * Result    // event dependent message
);

Parameters

Event
Pointer to an event. Information about this event is reported in the associated message. Note that this is not a Win32 event object. (The ROUTING_PROTOCOL_EVENTS type is declared in routprot.h.)

Event values
Value | Description
ROUTER_STOPPED | The router protocol shutdown successfully. The message is empty for this event. (See StopProtocol)
SAVE_GLOBAL_CONFIG_INFO | The routing protocol reports that its global configuration information has been changed by an external agent, that is,, through means other than SetGlobalInfo. The routing protocol requests that the router manager retrieve and permanently store this information. The message is empty for this event.
SAVE_INTERFACE_CONFIG_INFO | The routing protocol reports that the configuration information associated with one of its interfaces has been changed by an external agent, that is, through means other than SetInterfaceConfigInfo. The routing protocol requests that the router manager retrieve and permanently store this information. The message contains the ID of the interface.
UPDATE_COMPLETE | The routing protocol has completed an autostatic update request from the router manager. The router manager can proceed with converting received routing information to static. The message contains the index of the interface on which the update was performed, the type of the information received (routes or services), and the result field which indicates whether the update succeeded. See DoUpdateRoutes and DoUpdateServices.

Result
Pointer to a MESSAGE union. The contents of the message are specific to the reported event.

This parameter is optional; the caller may specify NULL for this parameter.

Return Values

NO_ERROR
The entry was retrieved successfully.
ERROR_NO_MORE_ITEMS
The routing protocol's message queue does not contain any entries.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in routprot.h.
Import Library: user-defined.

See Also

DoUpdateRoutes, DoUpdateServices, GetEventMessage Sample, MESSAGE, SetGlobalInfo, SetInterfaceConfigInfo, StopProtocol


GetGlobalInfo

The GetGlobalInfo function retrieves global (as opposed to interface-specific) configuration information kept by the routing protocol.

DWORD GetGlobalInfo(
  PVOID GlobalInfo       // address of configuration information
  PULONG GlobalInfoSize  // size of configuration information
);

Parameters

GlobalInfo
Pointer to a buffer to receive the protocol-defined global configuration information. The format of this information is specific to the routing protocol.
GlobalInfoSize
Pointer to a DWORD variable.

On input: This variable contains the size, in bytes, of the buffer pointed to by the GlobalInfo parameter.

On output: This variable contains the size, in bytes, of the data placed in the output buffer. If the initial size was not large enough, the variable contains the size required to hold all of the output data.

Return Values

NO_ERROR
The routing protocol retrieved the global configuration information successfully. The information is in the buffer pointed to by GlobalInfo.
ERROR_CAN_NOT_COMPLETE
The routing protocol could not retrieve the global information.
ERROR_INSUFFICIENT_BUFFER
The size of the output buffer provided is not large enough to hold the requested information. The required size is returned in the DWORD variable pointed to by OutputDataSize.
ERROR_INVALID_PARAMETER
The GlobalInfoSize parameter is NULL.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in routprot.h.
Import Library: user-defined.

See Also

GetGlobalInfo Sample, SetInterfaceConfigInfo, SetGlobalInfo


SetGlobalInfo

The SetGlobalInfo function sets the global (as opposed to interface-specific) configuration information kept by the routing protocol. The format of this information is specific to the routing protocol.

DWORD SetGlobalInfo(
  PVOID GlobalInfo  // address of GlobalInfo block
);

Parameters

GlobalInfo
Pointer to a buffer containing the protocol-defined global configuration information.

Return Values

NO_ERROR
The routing protocol set the configuration information successfully.
ERROR_CAN_NOT_COMPLETE
The routing protocol could not set the configuration information.
ERROR_INVALID_PARAMETER
The GlobalInfo parameter is NULL, or one of the parameters in the configuration information is invalid.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in routprot.h.
Import Library: user-defined.

See Also

GetInterfaceConfigInfo, GetGlobalInfo, SetGlobalInfo Sample


AddInterface

The AddInterface function adds an interface to be managed by the routing protocol. The protocol should consider the interface to be in a disabled state. The interface can be enabled by calling EnableInterface.

DWORD AddInterface(
  LPWSTR InterfaceName,  // name of the interface
  ULONG InterfaceIndex,  // index for the interface
  NET_INTERFACE_TYPE InterfaceType,
                         // type of the interface
  PVOID InterfaceInfo    // interface information block
);

Parameters

InterfaceName
Pointer to a Unicode string. The string contains a name that uniquely identifies the interface in the set of interfaces configured on the router.
InterfaceIndex
Identifies the interface in the set of interfaces configured on the router.
InterfaceType
The type of the interface.
Value | Description
PERMANENT | Permanent connectivity (e.g., LAN, Frame Relay).
DEMAND_DIAL | Demand dial connectivity (analog, ISDN, PPTP, switched FR).
LOCAL_WORKSTATION_DIAL | Local workstation connectivity only.
REMOTE_WORKSTATION_DIAL | Remote workstation connectivity only.

InterfaceInfo
Pointer to a buffer that contains protocol-defined configuration information associated with the interface. This information is private to the routing protocol.

Return Values

NO_ERROR
The interface was added successfully.
ERROR_CAN_NOT_COMPLETE
The attempt to add the interface failed.
ERROR_INVALID_PARAMETER
The InterfaceIndex parameter is invalid (for example, an interface with that index already exists), or one of the parameters pointed to by InterfaceInfo is invalid.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in routprot.h.
Import Library: user-defined.

See Also

AddInterface Sample, DeleteInterface, EnableInterface


DeleteInterface

The DeleteInterface function removes an interface from the set managed by the routing protocol.

DWORD DeleteInterface(
  ULONG InterfaceIndex  // index of the interface
);

Parameters

InterfaceIndex
Identifies the interface in the set of interfaces configured on the router.

Return Values

NO_ERROR
The interface was deleted successfully.
ERROR_CAN_NOT_COMPLETE
The attempt to delete the interface failed.
ERROR_INVALID_PARAMETER
The InterfaceIndex parameter is invalid (for example, no interface exists with that index).

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in routprot.h.
Import Library: user-defined.

See Also

AddInterface, DeleteInterface Sample


GetInterfaceConfigInfo

The GetInterfaceConfigInfo function gets the configuration information kept by the routing protocol for a specific interface.

DWORD GetInterfaceConfigInfo(
  ULONG InterfaceIndex,     // the index of the interface
  PVOID InterfaceInfo,      // buffer for interface information
  PULONG InterfaceInfoSize  // size of the buffer for interface
                            // information
);

Parameters

InterfaceIndex
Identifies the interface in the set of interfaces configured on the router.
InterfaceInfo
Pointer to a buffer that receives the protocol-defined configuration information associated with the interface. This information is private to the routing protocol.
InterfaceInfoSize
Pointer to a DWORD variable.

On input: This variable contains the size, in bytes, of the buffer provided to receive the configuration information.

On output: This variable contains the size, in bytes, of the data placed in the buffer. If the initial size was not large enough, this variable contains the size required to hold all of the data.

Return Values

NO_ERROR
The information was retrieved successfully. The buffer pointed to by the InterfaceInfo parameter contains the configuration information.
ERROR_CAN_NOT_COMPLETE
The attempt to retrieve the information failed.
ERROR_INVALID_PARAMETER
The InterfaceIndex parameter is invalid (for example, no interface exists with that index), or the InterfaceInfoSize parameter is NULL.
ERROR_INSUFFICIENT_BUFFER
The size of the output buffer provided is not large enough to hold the requested information. The required size is returned in the DWORD variable pointed to by InterfaceInfoSize.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in routprot.h.
Import Library: user-defined.

See Also

GetInterfaceConfigInfo Sample, SetInterfaceConfigInfo


SetInterfaceConfigInfo

The SetInterfaceConfigInfo function sets the configuration of a specific interface kept by the routing protocol.

DWORD SetInterfaceConfigInfo(
  ULONG InterfaceIndex,  // index of interface
  PVOID InterfaceInfo    // interface information block
);

Parameters

InterfaceIndex
Identifies the interface in the set of interfaces configured on the router.
InterfaceInfo
Pointer to a buffer that holds the protocol-defined configuration information associated with the interface. This information is private to the routing protocol.

Return Values

NO_ERROR
The interface configuration was set successfully.
ERROR_CAN_NOT_COMPLETE
The attempt to set the interface configuration failed.
ERROR_INVALID_PARAMETER
The InterfaceIndex parameter is invalid (for example, no interface exists with that index), the InterfaceInfo parameter is NULL, or one of the parameters in the configuration information is invalid.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in routprot.h.
Import Library: user-defined.

See Also

GetInterfaceConfigInfo, SetInterfaceConfigInfo Sample


BindInterface

The BindInterface function tells the routing protocol that an adapter has been allocated for an interface. The function directs the routing protocol to start protocol-defined activities over this adapter for the interface (unless the interface is administratively disabled).

DWORD BindInterface(
  ULONG InterfaceIndex,  // index of the interface
  PVOID BindingInfo      // adapter information block
);

Parameters

InterfaceIndex
Identifies the interface in the set of interfaces configured on the router.
BindingInfo
Pointer to a buffer that contains transport-specific information. This information allows the routing protocol to communicate with other routing agents over the interface.

Return Values

NO_ERROR
The interface is now bound to the specified adapter.
ERROR_CAN_NOT_COMPLETE
The attempt to bind the interface to the adapter failed.
ERROR_INVALID_PARAMETER
At least one of the following is true:

The InterfaceIndex parameter is invalid, for example, no interface exists with that index, or the interface exists, but is already bound.

One of the parameters in the adapter information pointed to by the BindingInfo parameter is invalid.

Remarks

If this function is called on an interface that is administratively enabled, the routing protocol should activate the interface.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in routprot.h.
Import Library: user-defined.

See Also

BindInterface Sample, IP_ADAPTER_BINDING_INFO, IPX_ADAPTER_BINDING_INFO, UnbindInterface


UnbindInterface

The UnbindInterface function tells the routing protocol that an adapter has been deallocated from the specified interface. The function directs the routing protocol to stop protocol-defined activities over the adapter.

DWORD UnbindInterface(
  ULONG InterfaceIndex  // index of the interface
);

Parameters

InterfaceIndex
Identifies the interface in the set of interfaces configured on the router.

Return Values

NO_ERROR
The interface was unbound successfully; the routing protocol has stopped activity over the adapter for this interface.
ERROR_CAN_NOT_COMPLETE
The attempt to unbind the interface failed.
ERROR_INVALID_PARAMETER
The InterfaceIndex parameter is invalid (for example, no interface exists with that index, or the interface exists, but is already unbound).

Remarks

The routing protocol should no longer consider routes dynamically obtained through the interface to be valid. It should remove these routes from the routing table.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in routprot.h.
Import Library: user-defined.

See Also

BindInterface, UnbindInterface Sample


EnableInterface

The EnableInterface function tells the routing protocol that an interface is enabled. The protocol can use the interface.

DWORD EnableInterface(
  ULONG InterfaceIndex  // index of the interface
);

Parameters

InterfaceIndex
Identifies the interface in the set of interfaces configured on the router.

Return Values

NO_ERROR
The interface was enabled successfully.
ERROR_CAN_NOT_COMPLETE
The attempt to enable the interface failed.
ERROR_INVALID_PARAMETER
The InterfaceIndex parameter is invalid (for example, no interface exists with that index).

Remarks

If this function is called on an interface that is bound to an adapter, the routing protocol should activate the interface.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in routprot.h.
Import Library: user-defined.

See Also

BindInterface, DisableInterface, EnableInterface Sample


DisableInterface

The DisableInterface function tells the routing protocol that an interface was administratively disabled.

DWORD DisableInterface(
  ULONG  InterfaceIndex  // index of the interface
);

Parameters

InterfaceIndex
Identifies the interface in the set of interfaces configured on the router.

Return Values

NO_ERROR
The interface was disabled successfully.
ERROR_CAN_NOT_COMPLETE
The attempt to disable the interface failed.
ERROR_INVALID_PARAMETER
The InterfaceIndex parameter is invalid (for example, no interface exists with that index, or the interface with that index is already disabled).

Remarks

If the interface is bound to a physical adapter, the protocol should deactivate the interface. That is, the protocol should refrain from any activity over this interface if the interface is bound to a physical adapter. Also, the protocol should not initiate demand dial connections for this interface.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in routprot.h.
Import Library: user-defined.

See Also

EnableInterface, DisableInterface Sample, UnbindInterface


DoUpdateRoutes

The DoUpdateRoutes function requests the routing protocol to perform a routing information update over the specified interface to obtain static route information. (This process is called an autostatic route update.)

DWORD DoUpdateRoutes(
  ULONG  InterfaceIndex  // index of the interface
);

Parameters

InterfaceIndex
Identifies the interface in the set of interfaces configured on the router.

Return Values

NO_ERROR
The update operation was successfully started on the interface. Check the routing protocol event queue for a completion event (see GetEventMessage).
ERROR_CAN_NOT_COMPLETE
The update operation could not be performed.
ERROR_INVALID_PARAMETER
The InterfaceIndex parameter is invalid (for example, no interface exists with that index).

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in routprot.h.
Import Library: user-defined.

See Also

DoUpdateRoutes Sample, DoUpdateServices, GetEventMessage


DoUpdateServices

The DoUpdateServices function requests the routing protocol to perform a service information update over the interface to obtain static service information. This process is called an autostatic service update.

DWORD DoUpdateServices(
  ULONG  InterfaceIndex  // index of the interface
);

Parameters

InterfaceIndex
Identifies the interface in the set of interfaces configured on the router.

Return Values

NO_ERROR
The update operation was successfully started on the interface. Check the routing protocol event queue for a completion event (see GetEventMessage).
ERROR_CAN_NOT_COMPLETE
The update operation could not be performed.
ERROR_INVALID_PARAMETER
The InterfaceIndex parameter is invalid (for example, no interface exists with that index).

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in routprot.h.
Import Library: user-defined.

See Also

DoUpdateRoutes, GetEventMessage


MibCreate

The MibCreate function passes an SNMP MIB-style Create Request to the routing protocol.

DWORD MibCreate(
  ULONG InputDataSize,  // size of the data for the request
  PVOID InputData       // address of the data for the request
);

Parameters

InputDataSize
Specifies the size of the data for the Create Request.
InputData
Pointer to a buffer that contains the data for the Create Request.

Return Values

NO_ERROR
The routing protocol completed the request.
ERROR_CAN_NOT_COMPLETE
The routing protocol could not complete the request.
ERROR_INVALID_PARAMETER
Specifies the size or content of the data is inappropriate for the request.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in routprot.h.
Import Library: user-defined.

See Also

MibCreate Sample, MibDelete


MibDelete

The MibDelete function passes an SNMP MIB-style Delete Request to the routing protocol.

DWORD MibDelete(
  ULONG InputDataSize,  // size of the data for the request
  PVOID InputData       // address of the data for the request
);

Parameters

InputDataSize
Specifies the size of the data for the Delete Request.
InputData
Pointer to a buffer that contains the data for the Delete Request.

Return Values

NO_ERROR
The routing protocol completed the request.
ERROR_CAN_NOT_COMPLETE
The routing protocol could not complete the request.
ERROR_INVALID_PARAMETER
The size or content of the data is inappropriate for the request.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in routprot.h.
Import Library: user-defined.

See Also

MibCreate, MibDelete Sample


MibGet

The MibGet function passes an SNMP MIB-style Get Request to the routing protocol DLL.

DWORD MibGet(
  ULONG InputDataSize,    // size of the data for the request
  PVOID InputData,        // address of the data for the request
  ULONG *OutputDataSize,  // size of the data returned
  PVOID  OutputData       // address of data returned
);

Parameters

InputDataSize
Specifies the size of the data for the Get Request.
InputData
Pointer to a buffer that contains the data for the Get Request.
OutputDataSize
Pointer to a ULONG variable:

On input: This variable contains the size of the output buffer.

On output: This variable contains the size of the data placed in the output buffer. If the initial size was not large enough, the variable contains the buffer size required to hold all of the output data.

OutputData
Pointer to a buffer to receive the data from the MIB entry.

Return Values

NO_ERROR
The routing protocol completed the request.
ERROR_CAN_NOT_COMPLETE
The routing protocol could not complete the request.
ERROR_INVALID_PARAMETER
The size or content of the data is inappropriate for the request.
ERROR_INSUFFICIENT_BUFFER
The size of the output buffer provided is not large enough to hold the requested information. The required size is returned in the ULONG variable pointed to by the OutputDataSize parameter.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in routprot.h.
Import Library: user-defined.

See Also

MibGet Sample, MibGetFirst, MibGetNext, MibSet


MibSet

The MibSet function passes a SNMP MIB-style Set Request to the routing protocol.

DWORD MibSet(
  ULONG InputDataSize,  // size of the data for the request
  PVOID InputData       // address of the data for the request
);

Parameters

InputDataSize
Specifies the size of the data for the Set Request.
InputData
Pointer to a buffer that contains the data for the Set Request.

Return Values

NO_ERROR
The routing protocol completed the request.
ERROR_CAN_NOT_COMPLETE
The routing protocol could not complete the request.
ERROR_INVALID_PARAMETER
The size or content of the data is inappropriate for the request.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in routprot.h.
Import Library: user-defined.

See Also

MibGet, MibGetFirst, MibGetNext, MibSet Sample


MibGetFirst

The MibGetFirst function passes a SNMP MIB-style Get First Request to the routing protocol.

DWORD MibGetFirst(
  ULONG InputDataSize,    // size of the data for the request
  PVOID InputData,        // address of the data for the request
  ULONG *OutputDataSize,  // size of the data returned
  PVOID OutputData        // address of the data returned
);

Parameters

InputDataSize
Specifies the size of the data for the Get First Request.
InputData
Pointer to the data to be passed with the Get First Request.
OutputDataSize
Pointer to a ULONG variable:

On input: This variable contains the size of the output buffer.

On output: This variable contains the size of the data placed in the output buffer. If the initial size was not large enough, the variable contains the buffer size required to hold all of the output data.

OutputData
Pointer to a buffer to receive the data from the MIB entry.

Return Values

NO_ERROR
The routing protocol completed the request.
ERROR_CAN_NOT_COMPLETE
The routing protocol could not complete the request.
ERROR_INVALID_PARAMETER
The size or content of the data is inappropriate for the request.
ERROR_INSUFFICIENT_BUFFER
The size of the output buffer provided is not large enough to hold the requested information. The required size is returned in the ULONG variable pointed to by the OutputDataSize parameter.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in routprot.h.
Import Library: user-defined.

See Also

MibGet, MibGetFirst Sample, MibGetNext, MibSet


MibGetNext

The MibGetNext function passes a SNMP MIB-style Get Next Request to the routing protocol.

DWORD MibGetNext(
  ULONG InputDataSize,    // size of the data for the request
  PVOID InputData,        // address of the data for the request
  ULONG *OutputDataSize,  // size of the returned data
  PVOID OutputData        // address of the returned data
);

Parameters

InputDataSize
Specifies the size of the data for the Get Next Request.
InputData
Pointer to the data for the Get Next Request.
OutputDataSize
Pointer to a ULONG variable:

On input: This variable that contains the size of the output buffer.

On output: This variable contains the size of data placed in the output buffer. If the initial size was not large enough, the variable contains the buffer size required to hold all of the output data.

OutputData
Pointer to a buffer to receive the data from the MIB entry.

Return Values

NO_ERROR
The routing protocol completed the request.
ERROR_CAN_NOT_COMPLETE
The routing protocol could not complete the request.
ERROR_INVALID_PARAMETER
The size or content of the data is inappropriate for the request.
ERROR_INSUFFICIENT_BUFFER
The size of the output buffer provided is not large enough to hold the requested information. The required size is returned in the ULONG variable pointed to by the OutputDataSize parameter.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in routprot.h.
Import Library: user-defined.

See Also

MibGet, MibGetFirst, MibGetNext Sample, MibSet


Routing Protocol Interface Structures

The Routing Protocol Interface Functions use the following structures.


MESSAGE

The MESSAGE union contains information about an event reported to the router manager through the routing protocol's message queue.

typedef union _MESSAGE {
    UPDATE_COMPLETE_MESSAGE UpdateCompleteMessage;
    DWORD                   InterfaceIndex;
}   MESSAGE, *PMESSAGE;

Members

UpdateCompleteMessage
Provides information associated with an UPDATE_COMPLETE event.
InterfaceIndex
Identifies the interface associated with a SAVE_INTERFACE_CONFIG_INFO event.

See Also

DoUpdateRoutes, DoUpdateServices, GetEventMessage, UPDATE_COMPLETE_MESSAGE


MPR_ROUTING_CHARACTERISTICS

The MPR_ROUTING_CHARACTERISTICS structure contains information used to register routing protocols with the router manager.

typedef struct _MPR_ROUTING_CHARACTERISTICS {
    DWORD               dwVersion;
    DWORD               dwProtocolId;
    DWORD               fSupportedFunctionality;
    PSTART_PROTOCOL     pfnStartProtocol;
    PSTOP_PROTOCOL      pfnStopProtocol;
    PADD_INTERFACE      pfnAddInterface;
    PDELETE_INTERFACE   pfnDeleteInterface;
    PGET_EVENT_MESSAGE  pfnGetEventMessage;
    PGET_INTERFACE_INFO pfnGetInterfaceInfo;
    PSET_INTERFACE_INFO pfnSetInterfaceInfo;
    PBIND_INTERFACE     pfnBindInterface;
    PUNBIND_INTERFACE   pfnUnbindInterface;
    PENABLE_INTERFACE   pfnEnableInterface;
    PDISABLE_INTERFACE  pfnDisableInterface;
    PGET_GLOBAL_INFO    pfnGetGlobalInfo;
    PSET_GLOBAL_INFO    pfnSetGlobalInfo;
    PDO_UPDATE_ROUTES   pfnUpdateRoutes;
    PDO_UPDATE_SERVICES pfnUpdateServices;
    PMIB_CREATE         pfnMibCreateEntry;
    PMIB_DELETE         pfnMibDeleteEntry;
    PMIB_GET            pfnMibGetEntry;
    PMIB_SET            pfnMibSetEntry;
    PMIB_GET_FIRST      pfnMibGetFirstEntry;
    PMIB_GET_NEXT       pfnMibGetNextEntry;
    PMIB_SET_TRAP_INFO  pfnMibSetTrapInfo;
    PMIB_GET_TRAP_INFO  pfnMibGetTrapInfo;
} MPR_ROUTING_CHARACTERISTICS, *PMPR_ROUTING_CHARACTERISTICS;

Members

dwVersion
On input: specifies the version of Routing and RAS currently running.

On output: the routing protocol should specify the version of Routing and RAS that it requires.

The symbol MS_ROUTER_VERSION in the header file routprot.h is defined to be the Routing and RAS version for a given implementation.

dwProtocolID
Specifies the routing protocol that the router manager requests the DLL to register. (A common name space is used for all protocol families.)
fSupportedFunctionality
On input: specifies the functionality that the router manager supports.

On output: the routing protocol should reset these flags to indicate the subset of functionality that it supports.

Supported Functionality Values
Value | Description
ROUTING | The protocol participates in Multiprotocol routing by importing Routing Table Manager APIs.
SERVICES | The protocol assumes responsibility for managing services (such as IPX SAP), and provides Service Table Management APIs.
DEMAND_UPDATE_ROUTES | The protocol is able to perform autostatic updates of routes when requested by the router manager.
DEMAND_UPDATE_SERVICES | The protocol is able to perform autostatic updates of services when requested by the router manager.

pfnStartProtocol
Pointer to an implementation of the StartProtocol function for this routing protocol.
pfnStopProtocol
Pointer to an implementation of the StopProtocol function for this routing protocol.
pfnAddInterface
Pointer to an implementation of the AddInterface function for this routing protocol.
pfnDeleteInterface
Pointer to an implementation of the DeleteInterface function for this routing protocol.
pfnGetInterfaceInfo
Pointer to an implementation of the GetInterfaceConfigInfo function for this routing protocol.
pfnSetInterfaceInfo
Pointer to an implementation of the SetInterfaceConfigInfo function for this routing protocol.
pfnBindInterface
Pointer to an implementation of the BindInterface function for this routing protocol.
pfnUnbindInterface
Pointer to an implementation of the UnbindInterface function for this routing protocol.
pfnEnableInterface
Pointer to an implementation of the EnableInterface function for this routing protocol.
pfnDisableInterface
Pointer to an implementation of the DisableInterface function for this routing protocol.
pfnGetGlobalInfo
Pointer to an implementation of the GetGlobalInfo function for this routing protocol.
pfnSetGlobalInfo
Pointer to an implementation of the SetGlobalInfo function for this routing protocol.
pfnUpdateRoutes
Pointer to an implementation of the DoUpdateRoutes function for this routing protocol.
pfnUpdateServices
Pointer to an implementation of the DoUpdateServices function for this routing protocol.
pfnMibCreateEntry
Pointer to an implementation of the MibCreate function for this routing protocol.
pfnMibDeleteEntry
Pointer to an implementation of the MibDelete function for this routing protocol.
pfnMibGetEntry
Pointer to an implementation of the MibGet function for this routing protocol.
pfnMibSetEntry
Pointer to an implementation of the MibSet function for this routing protocol.
pfnMibGetFirstEntry
Pointer to an implementation of the MibGetFirst function for this routing protocol.
pfnMibGetNextEntry
Pointer to an implementation of the MibGetNext function for this routing protocol.
pfnMibSetTrapInfo
Pointer to an implementation of the MibSetTrapInfo function for this routing protocol.
pfnMibGetTrapInfo
Pointer to an implementation of the MibGetTrapInfo function for this routing protocol.

Remarks

Most of the members of this structure are pointers to functions implemented in the routing protocol DLL. The routing protocol fills in the address values for these pointers during a call to the RegisterProtocol function.

For a complete description of a particular function pointed to by one of the structure members, see the reference page for that function.

To use this structure, the user should add -DMPR50=1 to the compiler flags.

See Also

MPR_SERVICE_CHARACTERISTICS, RegisterProtocol, Protocol Identifiers


MPR_SERVICE_CHARACTERISTICS

The MPR_SERVICE_CHARACTERISTICS structure contains information used to register a routing protocol with the router manager.

typedef struct _MPR_SERVICE_CHARACTERISTICS {
    DWORD                               dwVersion;
    DWORD                               dwProtocolId;
    DWORD                               fSupportedFunctionality;
    PIS_SERVICE                         pfnIsService;
    PCREATE_SERVICE_ENUMERATION_HANDLE  pfnCreateServiceEnumerationHandle;
    PENUMERATE_GET_NEXT_SERVICE         pfnEnumerateGetNextService;
    PCLOSE_SERVICE_ENUMERATION_HANDLE   pfnCloseServiceEnumerationHandle;
    PGET_SERVICE_COUNT                  pfnGetServiceCount;
    PCREATE_STATIC_SERVICE              pfnCreateStaticService;
    PDELETE_STATIC_SERVICE              pfnDeleteStaticService;
    PBLOCK_CONVERT_SERVICES_TO_STATIC   pfnBlockConvertServicesToStatic;
    PBLOCK_DELETE_STATIC_SERVICES       pfnBlockDeleteStaticServices;
    PGET_FIRST_ORDERED_SERVICE          pfnGetFirstOrderedService;
    PGET_NEXT_ORDERED_SERVICE           pfnGetNextOrderedService;
}MPR_SERVICE_CHARACTERISTICS, *PMPR_SERVICE_CHARACTERISTICS;

Members

dwVersion
On input: specifies the version of Routing and RAS currently running.

On output: the routing protocol should specify the version of Routing and RAS that it requires.

The symbol MS_ROUTER_VERSION in the header file routprot.h is defined to be the Routing and RAS version for a given implementation.

dwProtocolID
Specifies the routing protocol that the router manager requests the DLL to register. (A common name space is used for all protocol families.)
fSupportedFunctionality
On input: specifies the functionality that the router manager supports.

On output: the routing protocol should reset these flags to indicate the subset of functionality that it supports. If this routing protocol does not provide services, fSupportedFunctionality should be zero.

Supported Functionality Values
Value | Description
ROUTING | The protocol participates in Multiprotocol routing by importing Routing Table Manager APIs.
SERVICES | The protocol assumes responsibility for managing services (such as IPX SAP), and provides Service Table Management APIs.
DEMAND_UPDATE_ROUTES | The protocol is able to perform autostatic updates of routes when requested by the router manager.
DEMAND_UPDATE_SERVICES | The protocol is able to perform autostatic updates of services when requested by the router manager.

pfnIsService
Pointer to an implementation of the IsService function for this routing protocol.
pfnCreateServiceEnumerationHandle
Pointer to an implementation of the CreateServiceEnumerationHandle function for this routing protocol.
pfnEnumerateGetNextService
Pointer to an implementation of the EnumerateGetNextService function for this routing protocol.
pfnCloseServiceEnumerationHandle
Pointer to an implementation of the CloseServiceEnumerationHandle function for this routing protocol.
pfnGetServiceCount
Pointer to an implementation of the GetServiceCount function for this routing protocol.
pfnCreateStaticService
Pointer to an implementation of the CreateStaticService function for this routing protocol.
pfnDeleteStaticService
Pointer to an implementation of the DeleteStaticService function for this routing protocol.
pfnBlockConvertServicesToStatic
Pointer to an implementation of the BlockConvertServicesToStatic function for this routing protocol.
pfnBlockDeleteStaticServices
Pointer to an implementation of the BlockDeleteStaticServices function for this routing protocol.
pfnGetFirstOrderedService
Pointer to an implementation of the GetFirstOrderedService function for this routing protocol.
pfnGetNextOrderedService
Pointer to an implementation of the GetNextOrderedService function for this routing protocol.

Remarks

The members of this structure are pointers to Service Table Management functions implemented in the routing protocol DLL. The routing protocol fills in the address values for these pointers during a call to the RegisterProtocol function.

Only routing protocol DLLs that support services need to fill in the MPR_SERVICE_CHARACTERISTICS structure.

For a complete description of a particular function pointed to by one of the structure members, see the reference page for that function.

To use this structure, the user should add -DMPR50=1 to the compiler flags.

See Also

MPR_ROUTING_CHARACTERISTICS, RegisterProtocol, Protocol Identifiers


UPDATE_COMPLETE_MESSAGE

The UPDATE_COMPLETE_MESSAGE structure contains information describing the completion status of an update operation.

typedef struct _UPDATE_COMPLETE_MESSAGE {
    ULONG    InterfaceIndex;
    ULONG    UpdateType;
    ULONG    UpdateStatus;
}   UPDATE_COMPLETE_MESSAGE, *PUPDATE_COMPLETE_MESSAGE;

Members

InterfaceIndex
Identifies the interface over which the update was performed.
UpdateType
Indicates the type of information that was received in this update.
DEMAND_UPDATE_ROUTES
Routing information was reported to the Routing Table Manager.
DEMAND_UPDATE_SERVICES
Services information that is accessible through the Services Table Management functions provided by the routing protocol.
UpdateStatus
Indicates the result of the update operation.
NO_ERROR
The update was completed successfully
ERROR_CAN_NOT_COMPLETE
The update was unsuccessful.

See Also

MESSAGE


Support Functions Reference

The following functions are provided to routing protocols by the router manager. When the router manager calls the StartProtocol function (implemented by the routing protocol), the router manager passes the routing protocol a SUPPORT_FUNCTIONS structure containing pointers to these functions.

DemandDialRequest
MIBEntryCreate
MIBEntryDelete
MIBEntrySet
MIBEntryGet
MIBEntryGetFirst
MIBEntryGetNext


SUPPORT_FUNCTIONS

The router manager uses the SUPPORT_FUNCTIONS structure to pass the routing protocol a set of pointers to functions provided by the router manager.

typedef struct _SUPPORT_FUNCTIONS {
  DWORD (WINAPI *DemandDialRequest)( DWORD, DWORD );
  DWORD (WINAPI *MIBEntryCreate)( DWORD, DWORD, LPVOID );
  DWORD (WINAPI *MIBEntryDelete)( DWORD, DWORD, LPVOID );
  DWORD (WINAPI *MIBEntrySet)( DWORD, DWORD, LPVOID );
  DWORD (WINAPI *MIBEntryGet)( DWORD, DWORD, LPVOID, LPDWORD LPVOID );
  DWORD (WINAPI *MIBEntryGetFirst)( DWORD, DWORD, LPVOID, LPDWORD, LPVOID );
  DWORD (WINAPI *MIBEntryGetNext)( DWORD, DWORD, LPVOID, LPVOID, LPVOID);
} SUPPORT_FUNCTIONS, *PSUPPORT_FUNCTIONS;

Members

DemandDialRequest
Pointer to the DemandDialRequest function provided by the router manager for the routing protocol.
MIBEntryCreate
Pointer to the MIBEntryCreate function provided by the router manager for the routing protocol.
MIBEntryDelete
Pointer to the MIBEntryDelete function provided by the router manager for the routing protocol.
MIBEntrySet
Pointer to the MIBEntrySet function provided by the router manager for the routing protocol.
MIBEntryGet
Pointer to the MIBEntryGet function provided by the router manager for the routing protocol.
MIBEntryGetFirst
Pointer to the MIBEntryGetFirst function provided by the router manager for the routing protocol.
MIBEntryGetNext
Pointer to the MIBEntryGetNext function provided by the router manager for the routing protocol.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.

See Also

StartProtocol


DemandDialRequest

The routing protocol should call DemandDialRequest to initiate a demand dial connection.

DWORD ( * DemandDialRequest) (
  DWORD InitiatingProtocolId,      // ID of DLL to process request
  DWORD InterfaceIndex      // ID of the interface
);

Parameters

InitiatingProtocolId
Specifies the ID of the routing protocol on behalf of which the connection should be established. (Normally, this parameter will be the ID of the calling routing protocol.)
InterfaceIndex
Specifies the ID of the interface for which the connection should be established.

Return Value

NO_ERROR
The connection was established successfully.
ERROR_CAN_NOT_COMPLETE
The attempt to establish the connection failed.
ERROR_INVALID_PARAMETER
The InitiatingProtocolId parameter and/or the InterfaceIndex parameter were/was invalid.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.

See Also

Protocol Identifiers


MibEntryCreate

The routing protocol should call MibEntryCreate to execute an SNMP MIB-style Create request of the router manager or a peer protocol DLL.

DWORD ( * MibEntryCreate ) (
  DWORD TargetProtocolId,      // ID of DLL to process the request
  DWORD InputDataSize,      // size of the data for the request
  PVOID InputData      // address of the data for the request
);

Parameters

TargetProtocolId
Specifies the ID of the DLL that should process this request. This parameter may be the ID of the router manager or the ID of a routing protocol.
InputDataSize
Specifies the size, in bytes, of the data to pass with the Create request.
InputData
Pointer to the data to pass with the Create request.

Return Value

NO_ERROR
The MIB entry was created successfully.
ERROR_CAN_NOT_COMPLETE
The attempt to create the MIB entry failed.
ERROR_INVALID_PARAMETER
The size or content of the input data are incompatible with the request.

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

Protocol Identifiers, MibEntryDelete


MibEntryDelete

The routing protocol should call MibEntryDelete to execute an SNMP MIB-style Delete request of the router manager or a peer protocol DLL.

DWORD ( * MibEntryDelete ) (
  DWORD TargetProtocolId,      // ID of DLL to process request
  DWORD InputDataSize,      // size of the data for the request
  PVOID InputData      // address of the data for the request
);

Parameters

TargetProtocolId
Specifies the ID of the DLL that should process this request. This parameter may be the ID of the router manager or the ID of a routing protocol.
InputDataSize
Specifies the size, in bytes, of the data to pass with the Delete request.
InputData
Pointer to the data to pass with the Delete request.

Return Value

NO_ERROR
The MIB entry was deleted successfully.
ERROR_CAN_NOT_COMPLETE
The attempt to delete the MIB entry failed.
ERROR_INVALID_PARAMETER
The size or content of the input data are incompatible with the request.

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

Protocol Identifiers, MibEntryCreate


MibEntrySet

The routing protocol should call MibEntrySet to execute an SNMP MIB-style Set request of the router manager or a peer protocol DLL.

DWORD ( * MibEntrySet ) (
  DWORD TargetProtocolId,      // ID of DLL to process request
  DWORD InputDataSize,      // size of the data for the request
  PVOID InputData      // address of the data for the request
);

Parameters

TargetProtocolId
Specifies the ID of the DLL that should process this request. This parameter may be the ID of the router manager or the ID of a routing protocol.
InputDataSize
Specifies the size, in bytes, of the data to pass with the Set request
InputData
Pointer to the data to pass with the Set request.

Return Value

NO_ERROR
The operation completed successfully.
ERROR_CAN_NOT_COMPLETE
The operation failed.
ERROR_INVALID_PARAMETER
The size or content of the input data are incompatible with the request.

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

Protocol Identifiers, MibEntryGet


MibEntryGet

The routing protocol should call MibEntryGet to execute an SNMP MIB-style Get request of the router manager or a peer protocol DLL.

DWORD ( * MibEntryGet ) (
  DWORD TargetProtocolId,      // ID of DLL to process request
  DWORD InputDataSize,      // size of the data for the request
  PVOID InputData,      // address of the data for the request
  DWORD * OutputDataSize,      // size of the data returned
  PVOID OutputData      // address of the data returned
);

Parameters

TargetProtocolId
Specifies the ID of the DLL that should process this request. This parameter may be the ID of the router manager or the ID of a routing protocol.
InputDataSize
Specifies the size, in bytes, of the data to pass with the Get request.
InputData
Pointer to the data to pass with the Get request.
OutputDataSize
A pointer to a DWORD variable:

On input: This variable contains the size, in bytes, of the output buffer.

On output: This variable contains the size, in bytes, of data placed in the output buffer. If the initial size was not large enough, this variable contains the buffer size required to hold all of the output data.

OutputData
Pointer to a buffer to hold the data from the MIB entry.

Return Value

NO_ERROR
The Get request completed successfully. The OutputData parameter points to the data from the MIB entry.
ERROR_CAN_NOT_COMPLETE
The operation failed.
ERROR_INVALID_PARAMETER
The size or content of the input data are incompatible with the request.
ERROR_INSUFFICIENT_BUFFER
The size of the output buffer provided is not large enough to hold the requested information. The required size is returned in the DWORD variable pointed to by the OutputDataSize parameter.

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

Protocol Identifiers, MibEntrySet, MibEntryGetFirst, MibEntryGetNext


MibEntryGetFirst

The routing protocol should call MibEntryGetFirst to execute an SNMP MIB-style Get First request of the router manager or a peer protocol DLL.

DWORD ( * MibEntryGetFirst ) (
  DWORD TargetProtocolId,      // ID of DLL to process request
  DWORD InputDataSize,      // size of the data for the request
  PVOID InputData,      // address of the data for the request
  DWORD * OutputDataSize,      // size of the data returned
  PVOID OutputData      // address of the data returned
);

Parameters

TargetProtocolId
Specifies the ID of the DLL that should process this request. This parameter may be the ID of the router manager or the ID of a routing protocol.
InputDataSize
Specifies the size, in bytes, of the data to pass with the Get First request.
InputData
Pointer to the data to pass with the Get First request.
OutputDataSize
A pointer to a DWORD variable:

On input: This variable contains the size, in bytes, of the output buffer.

On output: This variable contains the size, in bytes, of data placed in the output buffer. If the initial size was not large enough, this variable contains the buffer size required to hold all of the output data.

OutputData
Pointer to a buffer to hold the data from the MIB entry.

Return Value

NO_ERROR
The Get First request completed successfully. The OutputData parameter points to the data from the MIB entry.
ERROR_CAN_NOT_COMPLETE
The operation failed.
ERROR_INVALID_PARAMETER
The size or content of the input data are incompatible with the request.
ERROR_INSUFFICIENT_BUFFER
The size of the output buffer provided is not large enough to hold the requested information. The required size is returned in the memory pointed to by the OutputDataSize parameter.

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

Protocol Identifiers, MibEntryGet, MibEntryGetNext


MibEntryGetNext

The routing protocol should call MibEntryGetNext to execute an SNMP MIB-style Get Next request of the router manager or a peer protocol DLL.

DWORD ( * MibEntryGetNext ) (
  DWORD TargetProtocolId,      // ID of DLL to process request
  DWORD InputDataSize,      // size of the data for the request
  PVOID InputData,      // address of the data for the request
  DWORD * OutputDataSize,      // size of the data returned
  PVOID OutputData      // address of the data returned
);

Parameters

TargetProtocolId
Specifies the ID of the DLL that should process this request. This parameter may be the ID of the router manager or the ID of a routing protocol.
InputDataSize
Specifies the size, in bytes, of the data to pass with the Get Next request.
InputData
Pointer to the data to pass with the Get Next request.
OutputDataSize
A pointer to a DWORD variable:

On input: This variable contains the size, in bytes, of the output buffer.

On output: This variable contains the size, in bytes, of data placed in the output buffer. If the initial size was not large enough, this variable contains the buffer size required to hold all of the output data.

OutputData
Pointer to a buffer to hold the data from the MIB entry.

Return Value

NO_ERROR
The Get Next request completed successfully. The OutputData parameter points to the data from the MIB entry.
ERROR_CAN_NOT_COMPLETE
The operation failed.
ERROR_INVALID_PARAMETER
The size or content of the input data are incompatible with the request.
ERROR_INSUFFICIENT_BUFFER
The size of the output buffer provided is not large enough to hold the requested information. The required size is returned in the DWORD pointed to by OutputDataSize.

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

Protocol Identifiers, MibEntryGet, MibEntryGetFirst


IPX Service Table Management

An IPX routing protocol that registers for service handling should maintain a service bindery table as defined by Novell's IPX Service Advertising Protocol (SAP) specifications. The routing protocol should also provide the router manager access to this table through the following functions. (See the RegisterProtocol function for more information on how a routing protocol registers for service handling.)


Service Table Management Functions

Implement the following functions for routing protocols that register for service handling.

IsService
CreateServiceEnumerationHandle
EnumerateGetNextService
CloseServiceEnumerationHandle
GetServiceCount
GetFirstOrderedService
GetNextOrderedService
CreateStaticService
DeleteStaticService
BlockConvertServicesToStatic
BlockDeleteStaticServices
GetServiceID
GetServiceFromID
GetNextServiceFromID


IsService

The IsService function checks whether a service of specified type and name exists in the service table, and optionally will return the service's parameters.

BOOL IsService (
  IN USHORT           Type,
  IN PUCHAR           Name,
  OUT PIPX_SERVICE    Service   //OPTIONAL
  );

Parameters

Type
Specifies the type of the service being checked.
Name
Specifies the name of the service being checked.
Service
Receives a pointer to a structure in which to place the information about the matching service (if any).

Return Values

TRUE
The service exists in the table.
FALSE
No such service exists or the operation failed. Call GetLastError for more information about the failure:
NO_ERROR
The operation succeeded but no such service exists.
ERROR_INVALID_PARAMETER
The service type or name is invalid.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in user-defined.
Import Library: user-defined.

See Also

GetLastError, IPX_SERVICE


CreateServiceEnumerationHandle

The CreateServiceEnumerationHandle function returns a handle that allows use of fast and change-tolerant enumeration APIs that can scan through all services or a specified subset.

HANDLE CreateServiceEnumerationHandle (
  IN DWORD           ExclusionFlags,
  IN PIPX_SERVICE    CriteriaService
  );

Parameters

ExclusionFlags
Limits the set of services CreateServiceEnumerationHandle returns to a subset defined by a combination of ExclusionFlags and values in the corresponding fields of CriteriaService. This parameter must be one of the following values.
Value | Defintion
STM_ONLY_THIS_INTERFACE | Enumerate only those services that were obtained through the interface specified in the InterfaceIndex field of CriteriaService.
STM_ONLY_THIS_PROTOCOL | Enumerate only those services that were obtained through the protocol specified in the Protocol field of CriteriaService (for example, IPX_PROTOCOL_SAP for services obtained by the DLL protocol or IPX_PROTOCOL_STATIC for services maintained by the Router Manager).
STM_ONLY_THIS_TYPE | Enumerate only those services that have the same type as those in the Service field of CriteriaService.

CriteriaService
Points to an IPX_SERVICE structure with field values that correspond to those specified in ExclusionFlags.

Return Values

Handle for use with the service enumeration function. A NULL handle indicates no services exists with the specified criteria, or that the operation failed. Call GetLastError to obtain more information:

ERROR_NO_SERVICES
No services exist with the specified criteria.
ERROR_INVALID_PARAMETER
One or more of the input parameters is invalid. For example, invalid enumeration flags or invalid fields in CriteriaService.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in user-defined.
Import Library: user-defined.

See Also

CloseServiceEnumerationHandle, EnumerateGetNextService, GetLastError, IPX_SERVICE


EnumerateGetNextService

The EnumerateGetNextService function returns the next service entry in an enumeration started by CreateServiceEnumerationHandle.

DWORD EnumerateGetNextService (
  IN HANDLE          EnumerationHandle,
  OUT PIPX_SERVICE    Service
  );

Parameters

EnumerationHandle
Handle that identifies the enumeration and specifies its scope. The handle is obtained from a call to CreateServiceEnumerationHandle.
Service
Points to an IPX_SERVICE structure that will contain the next service in the enumeration. Although services are returned in any particular order, each service in the subset is returned only once.

Return Values

NO_ERROR
The next service was placed in the buffer pointed to by Service.
ERROR_NO_MORE_ITEMS
No more services exist with the specified criteria.
ERROR_CAN_NOT_COMPLETE
Operation failed.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in user-defined.
Import Library: user-defined.

See Also

CreateServiceEnumerationHandle, IPX_SERVICE


CloseServiceEnumerationHandle

The CloseServiceEnumerationHandle function terminates the enumeration and frees associated resources.

DWORD CloseServiceEnumerationHandle (
  IN HANDLE    EnumerationHandle
  );

Parameters

EnumerationHandle
Handle that identifies the enumeration to terminate, obtained from a previous call to CreateServiceEnumerationHandle.

Return Values

NO_ERROR
The enumeration was terminated successfully.
ERROR_CAN_NOT_COMPLETE
Operation failed.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in user-defined.
Import Library: user-defined.

See Also

CreateServiceEnumerationHandle


GetServiceCount

The GetServiceCount function returns the number of services in the table.

ULONG GetServiceCount (
  void
  );

Return Values

Successful completion of GetServiceCount will return the number of services in the table.

0 (Zero)
No services are available in the table or the operation failed. Call GetLastError to obtain more information:
NO_ERROR
Operation succeeded but no services are available.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in user-defined.
Import Library: user-defined.

See Also

GetLastError


GetFirstOrderedService

The GetFirstOrderedService function returns the first service in the specified order from the designated subset of services in the table.

DWORD GetFirstOrderedService (
  IN DWORD               OrderingMethod,
  IN DWORD               ExclusionFlags,
  IN OUT PIPX_SERVICE    Service
  );

Parameters

OrderingMethod
Indicates the order in which the services will be searched. This parameter must be one of the following values.
STM_ORDER_BY_TYPE_AND_NAME
Services will be searched in type.name order
STM_ORDER_BY_INTERFACE_TYPE_NAME
Services will be searched in interface index.type.name order.
ExclusionFlags
Limits the set of examined services to a subset defined by ExclusionFlags and the values in the corresponding fields of Service. See CreateServiceEnumerationHandle for a description of the possible flags.
Service
Points to an IPX_SERVICE structure.
Value of Service at Input:
Values in the fields correspond to flags specified in ExclusionFlags.
Value of Service upon Output:
The first service that matches specified criteria.

Return Values

NO_ERROR
A matching service was found and placed in the structure pointed to by Service.
ERROR_NO_MORE_ITEMS
No services matching the specified criteria exist.
ERROR_INVALID_PARAMETER
One or more input parameters are invalid, that is,invalid ordering method, enumeration flags, or field values in Service.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in user-defined.
Import Library: user-defined.

See Also

CreateServiceEnumerationHandle, IPX_SERVICE


GetNextOrderedService

The GetNextOrderedService function returns the next service from a subset of services in the table. The service returned is the next service after a given input service using the ordering method specified.

DWORD GetNextOrderedService (
  IN DWORD               OrderingMethod,
  IN DWORD               ExclusionFlags,
  IN OUT PIPX_SERVICE    Service
  );

Parameters

OrderingMethod
Indicates the order in which the services will be searched. See GetFirstOrderedService for a description of the various ordering methods.
ExclusionFlags
Limits the set of examined services to a subset defined by ExclusionFlags and the values in the corresponding fields of Service. See CreateServiceEnumerationHandle for a description of the possible flags.
Service
Points to an IPX_SERVICE structure.
Value of Service at Input:
Contains the service from which to continue searching; also contains field values that correspond to the specified ExclusionFlags.
Value of Service upon Output:
The structure contains the first service that follows the input service and matches the specified criteria.

Return Values

NO_ERROR
The next matching service was found and placed in the structure pointed to by Service.
ERROR_NO_MORE_SERVICES
No more services matching the specified criteria exist.
ERROR_INVALID_PARAMETER
One or more of the input parameters is invalid; for example, invalid ordering method, enumeration flags, or field values in Service.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in user-defined.
Import Library: user-defined.

See Also

CreateServiceEnumerationHandle, IPX_SERVICE


CreateStaticService

The CreateStaticService function adds a static service to the table.

DWORD CreateStaticService (
  IN ULONG                       InterfaceIndex,
  IN PIPX_STATIC_SERVICE_INFO    ServiceEntry
  );

Parameters

InterfaceIndex
A unique number that identifies the interface associated with the new service.
ServiceEntry
Pointer to an IPX_STATIC_SERVICE_INFO structure containing parameters of the static service to be added.

Return Values

NO_ERROR
The static service was added successfully.
ERROR_CAN_NOT_COMPLETE
The SAP Agent is down.
ERROR_INVALID_PARAMETER
One or more of the input parameters is invalid, for example, invalid interface index, or invalid fields in ServiceEntry.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in user-defined.
Import Library: user-defined.

See Also

DeleteStaticService, IPX_STATIC_SERVICE_INFO


DeleteStaticService

The DeleteStaticService function deletes a static service from the table.

DWORD DeleteStaticService (
  IN ULONG                             InterfaceIndex,
  IN PIPX_STATIC_SERVICE_INFO    ServiceEntry
  );

Parameters

InterfaceIndex
A unique number that identifies the interface associated with the service intended for deletion.
ServiceEntry
Pointer to an IPX_STATIC_SERVICE_INFO structure containing the parameters of the static service intended for deletion.

Return Values

NO_ERROR
The service was deleted successfully.
ERROR_CAN_NOT_COMPLETE
The SAP Agent is down.
ERROR_INVALID_PARAMETER
One or more of the input parameters is invalid; for example,invalid interface index, or invalid fields in ServiceEntry.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in user-defined.
Import Library: user-defined.

See Also

CreateStaticService, IPX_STATIC_SERVICE_INFO


BlockConvertServicesToStatic

The BlockConvertServicesToStatic function converts all services received on a specified interface to static.

DWORD BlockConvertServicesToStatic (
  IN ULONG    InterfaceIndex
  );

Parameters

InterfaceIndex
A unique number that identifies the interface associated with the services intended for conversion.

Return Values

NO_ERROR
The services were converted successfully.
ERROR_CAN_NOT_COMPLETE
The SAP Agent is down.
ERROR_INVALID_PARAMETER
The InterfaceIndex parameter is invalid.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in user-defined.
Import Library: user-defined.

See Also

BlockDeleteStaticServices


BlockDeleteStaticServices

The BlockDeleteStaticServices function deletes all static services associated with a specified interface.

DWORD BlockDeleteStaticServices (
  IN ULONG    InterfaceIndex
  );

Parameters

InterfaceIndex
A unique number that identifies the interface associated with the services to be deleted.

Return Values

NO_ERROR
The services were deleted successfully.
ERROR_CAN_NOT_COMPLETE
The SAP Agent is down.
ERROR_INVALID_PARAMETER
The InterfaceIndex parameter is invalid.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in user-defined.
Import Library: user-defined.

See Also

BlockConvertServicesToStatic


GetServiceID

The GetServiceID returns the unique identifier of an IPX service (object identifier).

BOOL GetServiceID (
  IN USHORT    Type,
  IN PUCHAR    Name,
  OUT PULONG   ServiceID
  );

Parameters

Type
Supplies the type of the service for which the identifierwill be returned.
Name
Name of service for which the identifierwill be returned.
ServiceID
Address of memory to hold the unique identifier of the service. This identifier will be in the range: 0xC0000000 - 0xCFFFFFFF.

Return Values

TRUE
The service exists in the table. The identifier is returned in the memory pointed to by ServiceID.
FALSE
No such service exists, or the operation failed. Call GetLastError to obtain more information:
NO_ERROR
Operation succeeded but no such service exists.
ERROR_INVALID_PARAMETER
The service type, service name, or both are invalid.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in user-defined.
Import Library: user-defined.

See Also

GetLastError


GetServiceFromID

The GetServiceFromID function returns a service given its object identifier.

BOOL GetServiceFromID (
  IN ULONG            ServiceID,
  OUT PIPX_SERVICE    Service
  );

Parameters

ServiceID
The unique identifier of the service. The identifier will be in the range: 0xC0000000 - 0xCFFFFFFF.
Service
Address of an IPX_SERVICE structure to hold the returned service information upon successful execution.

Return Value

TRUE
The service exists in the table. The service information is returned in the structure pointed to by Service.
FALSE
No service exists, or the operation failed. Call GetLastError to obtain more information:
NO_ERROR
The operation succeeded but no such service exists.
ERROR_INVALID_PARAMETER
The service identifier is invalid.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in user-defined.
Import Library: user-defined.

See Also

GetLastError, IPX_SERVICE


GetNextServiceFromID

The GetNextServiceFromID function allows service enumeration based on object identifiers.

DWORD GetNextServiceFromID (
  IN ULONG            ServiceID,
  OUT PIPX_SERVICE    NextService,
  OUT PULONG          NextServiceID
  );

Parameters

ServiceID
A unique service identifier in the range 0xC0000000 - 0xCFFFFFFF, or 0xFFFFFFFF to start the enumeration from the beginning of the identifier table.
NextService
Address of an IPX_SERVICE structure. The function will fill this structure with service information from the next service in the identifier table.
NextServiceID
Address of the identifier of the next service in the identifier table. The function fills this identifier upon a successful call. The identifier is in the range 0xC0000000 - 0xCFFFFFFF.

Return Values

NO_ERROR
The operation succeeded. NextService and NextsServiceID point to the information and identifier for the next service in the table.
ERROR_NO_MORE_SERVICES
No more services exist in the table.
ERROR_INVALID_PARAMETER
The ServiceID parameter is invalid.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in user-defined.
Import Library: user-defined.

See Also

IPX_SERVICE


Service Table Management Structures

Use the following structures when implementing routing protocols that register for service handling.

IPX_SERVICE
IPX_SERVER_ENTRY
IPX_STATIC_SERVICE_INFO


IPX_SERVICE

The IPX_SERVICE structures contains information about an IPX service, and identifies the interface and protocol through which this information was obtained.

typedef struct _IPX_SERVICE {
    ULONG                InterfaceIndex;    // index of interface
    ULONG                Protocol;          //
    IPX_SERVER_ENTRY     Service;
} IPX_SERVICE, *PIPX_SERVICE;

Parameters

InterfaceIndex
Contains the index of the interface through which the service information was obtained.
Protocol
Contains the identifier of the protocol that obtained the service information. (Static services are viewed as services obtained through the protocol IPX_PROTOCOL_STATIC).
Service
Specifies an IPX_SERVER_ENTRY structure.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in stm.h.
Import Library: N/A.

See Also

IPX_SERVER_ENTRY


IPX_SERVER_ENTRY

The IPX_SERVER_ENTRY structure describes a particular IPX service.

typedef struct _IPX_SERVER_ENTRY {
    USHORT    Type;
    UCHAR     Name[48];
    UCHAR     Network[4];
    UCHAR     Node[6];
    UCHAR     Socket[2];
    USHORT    HopCount;
    } IPX_SERVER_ENTRY, * PIPX_SERVER_ENTRY;

Members

Type
Contains the service type as defined by the SAP specification.
Name[48]
Contains the service name as defined by SAP specifications.
Network[4]
Contains the network number portion of the service address.
Node[6]
Contains the node number portion of the service address.
Socket[2]
Contains the socket number portion of service address.
HopCount
Contains the service hop count.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in stm.h.
Import Library: N/A.

See Also

IPX_SERVICE


IPX_STATIC_SERVICE_INFO

The IPX_STATIC_SERVICE_INFO structure describes a particular static IPX service.

typedef struct _IPX_SERVER_ENTRY {
    USHORT    Type;
    UCHAR     Name[48];
    UCHAR     Network[4];
    UCHAR     Node[6];
    UCHAR     Socket[2];
    USHORT    HopCount;
    } IPX_SERVER_ENTRY, * PIPX_SERVER_ENTRY;

typedef IPX_SERVER_ENTRY IPX_STATIC_SERVICE_INFO;

Members

Type
Contains the service type as defined by the SAP specification.
Name[48]
Contains the service name as defined by SAP specifications.
Network[4]
Contains the network number portion of the service address.
Node[6]
Contains the node number portion of the service address.
Socket[2]
Contains the socket number portion of service address.
HopCount
Contains the service hop count.

Remarks

The IPX_STATIC_SERVICE_INFO structure is a typedef of the IPX_SERVER_ENTRY structure. The typedef is in ipxrtdef.h.

See Also

IPX_SERVER_ENTRY


About Routing Table Manager

The Routing Table Manager (RTM) is designed to be a central repository of routing information for all routing protocols that operate under Routing and Remote Access Service (RRAS). The RTM provides routing information to all interested components, such as routing protocols, management agents, and monitoring agents. The RTM also determines the best route to each destination network known to the routing protocols. It determines this route based on routing protocol priorities and on metrics associated with the routes. Note that the administrator is able to configure routing protocol priorities. The RTM then passes the best-route information on to the forwarders and back to the routing protocols.

Each routing protocol calls RtmRegisterClient to register with the RTM. RtmRegisterClient returns a handle that will let the routing protocol add or delete route entries. RtmRegisterClient also allows the routing protocol to register an Event object with the RTM. The RTM will signal this event to notify the routing protocol of changes in best-route information. All other components can obtain information stored in the RTM through route enumeration.


Route Tables and Route Table Entries

The RTM maintains distinct route tables for each protocol family. Currently explicit support is provided for the Internet protocol (IP) and Internet Packet Exchange (IPX) routing protocol families. Regardless of the protocol family, each route entry contains the following information.

  • Destination network.
  • Identifier of the protocol that added the route.
  • Index of interface through which the route was obtained.
  • Address of the next hop router. RRAS will use this router to forward packets to the destination network if the network is not directly connected.
  • The time the route was created or last updated.
  • The amount of time this route should be kept in the routing table. If this amount of time elapses, and the route has not been updated, the RTM will remove the route from the table (in this case, the route is said to have "aged out").
  • Data specific to the protocol family. This data is transparent to RTM. However, if this data changes for a route that is designated as a "best route," the RTM will send out route-change notification.
  • Data specific to the routing protocol. This data is completely transparent to the RTM in that changes to this data will not cause route change notification.

The following values taken together uniquely identify a route in the routing table.

  • Destination network.
  • Protocol identifier.
  • Interface Index.
  • Address of next-hop router.

In general, the RTM creates separate entries for routes that differ in any of these parameters values. However, an exception is made for routing protocols that do not keep more that one entry for each destination network. For these protocols, the RTM ignores differences in interface index or next-hop address. An example of such a protocol would be the RRAS implementation of Open Shortest Path First (OSPF).


Changes to the Best Route to a Network

A change in any of the following values for the best route to a given destination network, causes the RTM to generate a notification message that is sent to each registered client and to the forwarders.

  • Protocol identifier.
  • Interface Index.
  • Address of next-hop router.
  • Protocol-family specific data that includes route metrics.

A change in protocol identifier, interface index, or next-hop router address can occur when a new, better-route entry is added, or when the current best-route entry is deleted or aged out, leaving another route as the new best route.


Routing Table Manager Reference

The following functions and structures provide an interface that routing protocols can use to access the routing tables maintained by the routing table manager.


Routing Table Manager Functions

Use the following functions to access the routing tables maintained by the routing table manager.


RtmRegisterClient

The RtmRegisterClient function registers a client as a handler of the specified protocol. It establishes a route change notification mechanism for the client, and sets protocol options.

HANDLE RtmRegisterClient(
  DWORD ProtocolFamily,      // identifier of protocol family
  DWORD RoutingProtocol,     // identifier of routing protocol
  HANDLE ChangeEvent,        // event to signal when best routes change
  DWORD Flags                // flags to indicate special handling of
                             // routing protocol
);

Parameters

ProtocolFamily
The protocol family of the routing protocol to register.
RoutingProtocol
The routing protocol identifier, same as used when registering with the router manager (see RegisterProtocol).
ChangeEvent
The Routing Table Manager (RTM) will signal this event when the best route to any network in the table changes. See RtmDequeueRouteChangeMessage for more information about route change notification.

This parameter is optional. If the caller specifies NULL for this parameter, the RTM will not notify the client of changes in best route status.

Flags
Miscellaneous options for special handling of the routing protocol. The following value is currently supported.
Flags | Values
RTM_PROTOCOL_SINGLE_ROUTE | The RTM will only keep one route per destination network for the routing protocol, that is, the RTM will replace route entries that have the same destination network numbers instead of adding new ones.

Return Values

On successful return, a HANDLE value that identifies the client in subsequent calls to the RTM.

A NULL handle indicates that the RTM was unable to register the client. Call GetLastError to obtain the reason for the failure.

ERROR_CLIENT_ALREADY_EXISTS
Another client has already registered to handle the specified protocol.
ERROR_INVALID_PARAMETER
The specified protocol family is not supported or the Flags parameter is invalid.
ERROR_NO_SYSTEM_RESOURCES
Insufficient resources to carry out the operation.
ERROR_NOT_ENOUGH_MEMORY
Insufficient memory to allocate data structures for the client.

QuickInfo

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

See Also

GetLastError, RegisterProtocol, RTM Protocol Family Identifiers, RtmDequeueRouteChangeMessage, RtmDeregisterClient


RtmDeregisterClient

The RtmDeregisterClient function deregisters the client, and frees resources associated with the client.

DWORD RtmDeregisterClient(
  HANDLE ClientHandle      // handle that identifies the client
);

Parameters

ClientHandle
A handle that identifies the client to deregister. Obtain this handle by calling RtmRegisterClient.

Return Values

NO_ERROR
The client was deregistered successfully.
ERROR_INVALID_HANDLE
The ClientHandle parameter is not a valid RTM handle.
ERROR_NO_SYSTEM_RESOURCES
Insufficient resources to carry out the operation.

Remarks

This function removes all routes that were added by the client.

QuickInfo

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

See Also

RtmRegisterClient


RtmDequeueRouteChangeMessage

The RtmDequeueRouteChangeMessage function returns the next route-change message in the queue associated with the specified client.

DWORD RtmDequeueRouteChangeMessage(
  HANDLE ClientHandle,      // handle that identifies the client
  DWORD Flags,              // type of change message
  PVOID CurBestRoute,       // the new best route
  PVOID PrevBestRoute       // the previous best route
);

Parameters

ClientHandle
A handle that identifies the client for which the operation is performed. Obtain this handle by calling RtmRegisterClient.
Flags
The address of a DWORD variable. The value of this variable is set by the RTM. The value indicates the type of the change message, and what information was returned in the provided buffers. This parameter will be one of the following.
Flags | Values
RTM_ROUTE_ADDED | The first route was added for a particular destination network. The CurBestRoute parameter points to the information for the added route.
RTM_ROUTE_DELETED | The only route available for a particular destination network was deleted. The PrevBestRoute parameter points to the information for the deleted route.
RTM_ROUTE_CHANGED At least one of the significant parameters was changed for a best route to a particular destination network. The significant parameters are:

Protocol ID

Interface Index

Next Hop Address

Protocol Family Specific Data
(including route metrics)

The PrevBestRoute parameter points to the route information as it was before the change. The CurBestRoute parameter points to current (that is,after-change) route information.

CurBestRoute
The address of a structure to receive the current best route information (if any). The type of the structure is specific to the protocol family (for example, IP or IPX).

This parameter is optional. If the caller specifies NULL for this parameter, the current best route information is not returned.

PrevBestRoute
The address of a structure to receive the previous best route information (if any). The type of the structure is specific to the protocol family (for example, IP or IPX).

This parameter is optional. If the caller specifies NULL for this parameter, the previous best route information is not returned.

Return Values

NO_ERROR
This message was the last message in the client's queue. The event object is reset.
ERROR_INVALID_HANDLE
The ClientHandle parameter is not a valid RTM handle, or at registration the client did not provide an event object for change message notification (see RtmRegisterClient).
ERROR_MORE_MESSAGES
The client's queue contains additional messages. The client should call RtmDequeueRouteChangeMessage again as soon as possible to allow the RTM to free the resources associated with the pending messages.
ERROR_NO_MESSAGES
The client's queue contains no messages; the call was unsolicited. The event is reset.
ERROR_NO_SYSTEM_RESOURCES
Insufficient resources to carry out the operation.

QuickInfo

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

See Also

RtmRegisterClient


RtmAddRoute

The RtmAddRoute function adds a route entry, or updates an existing route entry.

DWORD RtmAddRoute(
  HANDLE ClientHandle,      // handle that identifies the client
  PVOID Route,              // pointer to new route structure
  DWORD TimeToLive,         // how long to keep the route
  DWORD Flags,              // best route change status
  PVOID CurBestRoute,       // pointer to new best route
  PVOID PrevBestRoute       // pointer to previous best route
);

Parameters

ClientHandle
A handle that identifies the client and therefore the routing protocol of the added or updated route. Obtain this handle by calling RtmRegisterClient.
Route
The address of a protocol-family-specific structure containing the new orupdated route. The following fields will be used by the RTM to update the routing table:
RR_Network
The destination network number.
RR_InterfaceID
The index of the interface through which the route was received.
RR_NextHopAddress
The address of the next hop router.
RR_FamilySpecificData
Data specific to the protocol family. Although the data is transparent to the RTM, it is considered when comparing routes to determine if route information has changed. The data is also used to set metric values that are independent of the routing protocol. Consequently, it's used to determine the best route for the destination network.
RR_ProtocolSpecificData
Data specific to the routing protocol that supplied the route.
RR_TimeStamp
The RTM sets this field with the current system time.
TimeToLive
The number of seconds the specified route should be kept in the routing table. If this parameter is set to INFINITE, the route is kept until explicitly deleted. The current limit for TimeToLive is 2147483 sec (24+ days).
Flags
The address of a DWORD variable. The value of this variable is set by the RTM. The value indicates the type of the change, and what information was returned in the provided buffers. This parameter will be one of the following.
Flags | Values
RTM_NO_CHANGE | The addition or update either did not change any of the significant route parameters, or the route entry affected is not the best route among the entries for the destination network.
RTM_ROUTE_ADDED | The route added for the first for the destination network. The CurBestRoute parameter points to the information for the added route.
RTM_ROUTE_CHANGED At least one of the significant parameters was changed for the best route to the destination network. The significant parameters are:

Protocol ID

Interface Index

Next Hop Address

Protocol Family Specific Data
(including route metrics)

The PrevBestRoute parameter points to the route information as it was before the change. The CurBestRoute parameter points to the current (that is, after-change) route information.

CurBestRoute
The address of a structure to receive the current best route information (if any). The type of the structure is specific to the protocol family (for example, IP or IPX).

This parameter is optional. If the caller specifies NULL for this parameter, the current best route information is not returned.

PrevBestRoute
The address of a structure to receive the previous best route information (if any). The type of the structure is specific to the protocol family (for example, IP or IPX).

This parameter is optional. If the caller specifies NULL for this parameter the previous best route information is not returned.

Return Value

NO_ERROR
The route was added/updated successfully.
ERROR_INVALID_HANDLE
The client handle parameter is not a valid RTM handle.
ERROR_INVALID_PARAMETER
The route structure contains an invalid parameter.
ERROR_NO_SYSTEM_RESOURCES
Insufficient resources to carry out the operation.
ERROR_NOT_ENOUGH_MEMORY
Insufficient memory to allocate the route entry.

Remarks

The function generates a route change message if the best route to a destination network has changed as the result of this operation. However, the route change message is not sent to the client that makes this call. Instead, relevant information is returned by this function directly to that client through the Flags, CurBestRoute, and PrevBestRoute parameters.

QuickInfo

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

See Also

RtmDeleteRoute, RtmDequeueRouteChangeMessage


RtmDeleteRoute

The RtmDeleteRoute function deletes a route entry.

DWORD RtmDeleteRoute(
  HANDLE ClientHandle,    // handle that identifies client
  PVOID Route,            // pointer to route structure
  DWORD Flags,            // best route change status
  PVOID CurBestRoute      // pointer to new best route
);

Parameters

ClientHandle
Handle that identifies the client and therefore the routing protocol of the added/updated route. Obtain this handle by calling RtmRegisterClient.
Route
Pointer to a protocol-family-specific structure containing the new/updated route. The following fields will be used by the RTM to update the routing table:
RR_Network
The destination network number
RR_InterfaceID
The index of the interface through which the route was received.
RR_NextHopAddress
The network address of the next hop router.
Flags
A pointer to a set of flags that indicate the type of the change message, and what information was placed in the provided buffers. This parameter will be one of the following values.
Flags | Values
RTM_NO_CHANGE | Deleting the route did not affect the best route to any destination network, that is, another entry represents a route to the same destination network, and has a lower metric.
RTM_ROUTE_DELETED | The route deleted was the only route available for a particular destination network.
RTM_ROUTE_CHANGED | After this route was deleted, another route became the best route to a particular destination network. CurBestRoute points to the information for the new best route.

CurBestRoute
Pointer to a structure to receive the current best route information (if any). The type of the structure is specific to the protocol family (for example, IP or IPX).

This parameter is optional. If the caller specifies NULL for this parameter the current best route information is not returned.

Return Values

NO_ERROR
The route was added or updated successfully.
ERROR_INVALID_HANDLE
The client handle parameter is not a valid RTM handle.
ERROR_INVALID_PARAMETER
The route structure pointed to by the Route parameter contains a member value.
ERROR_NO_SUCH_ROUTE
No entries in the routing table match the parameters of the specified route.
ERROR_NO_SYSTEM_RESOURCES
Insufficient resources to perform the operation.

Remarks

The function generates a route-change message if the best route to a destination network has changed as the result of the deletion. However, the route change message is not sent to the client that makes this call. Instead, relevant information is returned by this function directly to that client.

QuickInfo

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

See Also

RtmAddRoute, RtmDequeueRouteChangeMessage


RtmIsRoute

The RtmIsRoute function checks if a route (or routes) to a specified destination network exist. If so, the function returns information for the best route to that network.

BOOL RtmIsRoute(
  DWORD ProtocolFamily,    // specifies type of network
  PVOID Network,           // specifies the network
  PVOID BestRoute          // receives best route for the network
);

Parameters

ProtocolFamily
Identifies the type of data structure pointed to by the Network parameter (for example, IP_NETWORK, IPX_NETWORK).
Network
Points to a structure that contains protocol-family-specific network number data. This data identifies the network for which the caller seeks route information.
BestRoute
Points to a protocol-family-specific structure to receive the current best route information (if any).

Return Values

TRUE
At least one route to the specified network exists. The best route is returned in the structure pointed to by the BestRoute parameter.
FALSE
No route to the specified network exists, or the operation failed. Call GetLastError to obtain more information:
NO_ERROR
The operation succeeded, but no route exists to the specified network.
ERROR_INVALID_PARAMETER
The value of the ProtocolFamily parameter doesn't correspond to any installed protocol family.
ERROR_NO_SYSTEM_RESOURCES
Insufficient resources to carry out the operation.

QuickInfo

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

See Also

GetLastError, IP_NETWORK, IPX_NETWORK, RTM Protocol Family Identifiers


RtmGetNetworkCount

The RtmGetNetworkCount function retrieves the number of networks that the Router Table Manager (RTM) has routes to.

ULONG RtmGetNetworkCount(
  DWORD ProtocolFamily    // type of network (IP or IPX)
);

Parameters

ProtocolFamily
Specifies which type of network (for example IP or IPX) to obtain route information for.

Return Values

Network count
The number of networks known to the routing protocols of the specified protocol family.

If the return value is zero, either no routes are available, or the operation failed. Call GetLastError to obtain more information:

NO_ERROR
The operation succeeded, but no routes are available.
ERROR_INVALID_PARAMETER
The value of the ProtocolFamily parameter doesn't correspond to any installed protocol family.

QuickInfo

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

See Also

GetLastError, RTM Protocol Family Identifiers


RtmGetRouteAge

The RtmGetRouteAge function returns the age of a route. The age is the time, in seconds, since it was created or last updated.

ULONG RtmGetRouteAge(
  PVOID Route    // pointer to route structure
);

Parameters

Route
Pointer to a protocol-family-specific structure containing route data recently obtained from the Routing Table Manager (RTM).

Return Values

RouteAge
The time in seconds since route was created or last updated.
INFINITE
The content of the route structure is invalid. In this case, a call to GetLastError will return ERROR_INVALID_PARAMETER.

Remarks

The route age is computed from the RR_TimeStamp member of the structure pointed to by the Route parameter. The RTM sets the value of this member when a route is added or updated.

QuickInfo

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

See Also

GetLastError, RTM_IP_ROUTE, RTM_IPX_ROUTE


RtmCreateEnumerationHandle

The RtmCreateEnumerationHandle function returns a handle to use with RtmEnumerateGetNextRoute to scan through all routes or a subset of routes known to the Routing Table Manager (RTM).

HANDLE RtmCreateEnumerationHandle(
  DWORD  ProtocolFamily,     // type of network (IP or IPX)
  DWORD  EnumerationFlags,   // flags that specify type of criteria
  PVOID  CriteriaRoute       // structure that holds criteria values
);

Parameters

ProtocolFamily
Specifies the protocol family of the routes to enumerate.
EnumerationFlags
Limits the set of routes returned by the enumeration API to a subset defined by these flags and the values in the corresponding members of the structure pointed to by the CriteriaRoute parameter. This parameter can be one of the following values.
EnumerationFlags | Values
RTM_ONLY_THIS_NETWORK | Enumerate only those routes that have the same network number as the RR_Network member of the structure pointed to by CriteriaRoute.
RTM_ONLY_THIS_INTERFACE | Enumerate only those routes that were obtained through the interface specified by the RR_InterfaceID member of the structure pointed to by CriteriaRoute.
RTM_ONLY_THIS_PROTOCOL | Enumerate only those routes that were added by the protocol handler specified by the RR_RoutingProtocol field of the structure pointed to by CriteriaRoute.
RTM_ONLY_BEST_ROUTES | Enumerate only the best routes to each of the networks in the set.

CriteriaRoute
Pointer to a protocol-family-specific route structure (RTM_IP_ROUTE or RTM_IPX_ROUTE). The member values in this structure correspond to the flags specified by the EnumerationFlags parameter.

Return Values

If the function succeeds, the return value is a HANDLE to use with subsequent enumeration calls.

If the function fails, or no routes exist with the specified criteria, the return value is NULL. Call GetLastError to obtain more information:

ERROR_NO_ROUTES
No routes exist with specified criteria.
ERROR_INVALID_PARAMETER
One or more of the input parameters is invalid (for example, unknown protocol family, invalid enumeration flags).
ERROR_NO_SYSTEM_RESOURCES
Insufficient resources to carry out the operation.
ERROR_NOT_ENOUGH_MEMORY
Insufficient memory to allocate the handle.

QuickInfo

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

See Also

GetLastError, RTM_IP_ROUTE, RTM_IPX_ROUTE, RtmCloseEnumerationHandle, RtmEnumerateGetNextRoute


RtmEnumerateGetNextRoute

The RtmEnumerateGetNextRoute function returns the next route entry in the enumeration started by a call to RtmCreateEnumerationHandle.

DWORD RtmEnumerateGetNextRoute(
  HANDLE   EnumerationHandle,  // handle that identifies enumeration
  PVOID    Route               // structure to receive next route
);

Parameters

EnumerationHandle
Handle that identifies the enumeration and specifies its scope. Obtain this handle by calling RtmCreateEnumerationHandle.
Route
Pointer to a protocol-family-specific route structure (RTM_IP_ROUTE or RTM_IPX_ROUTE). This structure will receive the next route in the enumeration.

Return Values

NO_ERROR
The next route in the enumeration was copied to the structure pointed to by the Route parameter.
ERROR_INVALID_HANDLE
The EnumerationHandle parameter is not valid.
ERROR_NO_MORE_ROUTES
No more routes exist in the enumeration.
ERROR_NO_SYSTEM_RESOURCES
insufficient resources to carry out the operation.

Remarks

Although routes are not returned in any particular order, each route in the enumeration is returned only once.

QuickInfo

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

See Also

RTM_IP_ROUTE, RTM_IPX_ROUTE, RtmCloseEnumerationHandle, RtmCreateEnumerationHandle


RtmCloseEnumerationHandle

The RtmCloseEnumerationHandle terminates a specified enumeration and frees the associated resources.

DWORD RtmCloseEnumerationHandle(
  HANDLE   EnumerationHandle  // handle that identifies enumeration
);

Parameters

EnumerationHandle
Handle that identifies the enumeration to terminate. Obtain this handle by calling RtmCreateEnumerationHandle.

Return Values

NO_ERROR
The enumeration was terminated successfully.
ERROR_INVALID_HANDLE
The EnumerationHandle parameter is not a valid.
ERROR_NO_SYSTEM_RESOURCES
Insufficient resources to carry out the operation.

QuickInfo

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

See Also

RtmCreateEnumerationHandle, RtmEnumerateGetNextRoute


RtmBlockDeleteRoutes

The RtmBlockDeleteRoutes function deletes all routes in the specified subset of routes in the table.

HANDLE RtmBlockDeleteRoutes(
  HANDLE  ClientHandle,       // handle that identifies client
  DWORD   EnumerationFlags,   // flags that specify type of criteria
  PVOID   CriteriaRoute       // structure that hold criteria values
);

Parameters

ClientHandle
Handle that identifies the client and therefore the routing protocol of the routes to be deleted.
EnumerationFlags
Limits the set of deleted routes to a subset defined by these flags and the values in the corresponding members of the structure pointed to by the CriteriaRoute parameter. The flags are the same as those used in RtmCreateEnumerationHandle except that RTM_ONLY_BEST_ROUTES is redundant for RtmBlockDeleteRoutes. The best route designation is adjusted as routes are deleted, so the function eventually deletes all the routes in the subset.
CriteriaRoute
Pointer to a protocol-family-specific route structure (RTM_IP_ROUTE or RTM_IPX_ROUTE). The member values in this structure correspond to the flags specified by the EnumerationFlags parameter.

Return Values

NO_ERROR
The routes were deleted successfully.
ERROR_NO_ROUTES
No routes exist with the specified criteria.
ERROR_INVALID_HANDLE
The ClientHandle parameter is not valid.
ERROR_INVALID_PARAMETER
One or more of the input parameters is invalid (for example, invalid enumeration flags).
ERROR_NO_SYSTEM_RESOURCES
Insufficient resources to carry out the operation.
ERROR_NOT_ENOUGH_MEMORY
Insufficient memory to carry out the operation.

Remarks

The function generates appropriate notification messages to all registered clients including the caller.

QuickInfo

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

See Also

RtmCreateEnumerationHandle, RtmRegisterClient


RtmGetFirstRoute

The RtmGetFirstRoute function returns the first route from the specified subset of routes in the table.

DWORD RtmGetFirstRoute(
  DWORD   ProtocolFamily,     // type of network (IP or IPX)
  DWORD   EnumerationFlags,   // flags that specify type of criteria
  PVOID   Route               // structure for criteria values and
                              // returned route.
);

Parameters

ProtocolFamily
Identifies the protocol family (for example, IP or IPX) of routes to retrieve.
EnumerationFlags
Limits the set of deleted routes to a subset defined by these flags and the values in the corresponding members of the structure pointed to by the CriteriaRoute parameter. The flags are the same as those used in RtmCreateEnumerationHandle.
Route
Points to a protocol-family-specific structure (RTM_IP_ROUTE or RTM_IPX_ROUTE).

The calling function provides member values for this structure. These values in conjunction with the EnumerationFlags parameter, specify the set from which to return routes.

On successful return, this structure receives the first route that matched the specified criteria.

Return Values

NO_ERROR
The first matching route was placed in the structure pointed to by the Route parameter.
ERROR_INVALID_PARAMETER
One or more of the input parameters is invalid (for example, unknown protocol family, or invalid enumeration flags).
ERROR_NO_ROUTES
No routes exist that match the specified criteria.
ERROR_NO_SYSTEM_RESOURCES
Insufficient resources to carry out the operation.

Remarks

The routes are returned in the following order:

  1. Network Number
  2. Routing Protocol
  3. Interface Identifier
  4. Next Hop Address

This function is less efficient than the corresponding enumeration handle functions.

QuickInfo

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

See Also

RtmCloseEnumerationHandle, RtmCreateEnumerationHandle, RtmEnumerateGetNextRoute, RtmGetNextRoute


RtmGetNextRoute

The RtmGetNextRoute function returns the next route from the specified subset of routes in the table.

DWORD RtmGetNextRoute(
  DWORD   ProtocolFamily,     // type of network (IP or IPX)
  DWORD   EnumerationFlags,   // flags that specify type of criteria
  PVOID   Route               // structure for criteria values and
                              // returned route.
);

Parameters

ProtocolFamily
Identifies the protocol family (for example, IP or IPX) of routes to retrieve.
EnumerationFlags
Limits the set of deleted routes to a subset defined by these flags and the values in the corresponding members of the structure pointed to by the CriteriaRoute parameter. The flags are the same as those used in RtmCreateEnumerationHandle.
Route
Points to a protocol-family-specific structure (RTM_IP_ROUTE or RTM_IPX_ROUTE).

The calling function provides member values for this structure. These values in conjunction with the EnumerationFlags parameter, specify the set from which to return routes.

On successful return, this structure receives the first route that matched the specified criteria.

Return Values

NO_ERROR
The first matching route was placed in the structure pointed to by the Route parameter.
ERROR_INVALID_PARAMETER
One or more of the input parameters is invalid (for example, unknown protocol family, or invalid enumeration flags).
ERROR_NO_ROUTES
No routes exist that match the specified criteria.
ERROR_NO_SYSTEM_RESOURCES
Insufficient resources to carry out the operation.

Remarks

The routes are returned in the following order:

  1. Network Number
  2. Routing Protocol
  3. Interface Identifier
  4. Next Hop Address

This function is less efficient than the corresponding enumeration handle functions.

QuickInfo

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

See Also

RtmCloseEnumerationHandle, RtmCreateEnumerationHandle, RtmEnumerateGetNextRoute, RtmGetFirstRoute


Routing Table Manager Structures

The Routing Table Manager Functions use the following structures.


IP_NETWORK

The IP_NETWORK structure describes an IP network address.

typedef struct _IP_NETWORK {
    DWORD    N_NetNumber;
    DWORD    N_NetMask;
} IP_NETWORK, *PIP_NETWORK;

Members

N_NetNumber
Contains the IP network number expressed as an IP address in machine byte order.
N_NetMask
Contains the network mask. Apply this mask to the IP address in order to extract the network address. The network mask is in machine byte order.

See Also

RTM_IP_ROUTE


IP_NEXT_HOP_ADDRESS

The IP_NEXT_HOP_ADDRESS structure contains the address for the next-hop router for an IP route.

typedef struct _IP_NETWORK {
    DWORD    N_NetNumber;
    DWORD    N_NetMask;
} IP_NETWORK, *PIP_NETWORK;

typedef IP_NETWORK IP_NEXT_HOP_ADDRESS, *PIP_NEXT_HOP_ADDRESS;

Members

N_NetNumber
Contains the IP network address expressed as an IP address in machine byte order.
N_NetMask
Contains the network mask. Apply this mask to the IP address in order to extract the network address. The network mask is in machine byte order.

Remarks

The IP_NEXT_HOP_ADDRESS structure is a typedef of the IP_NETWORK structure. The typedef is in rtm.h.

See Also

IP_NETWORK, RTM_IP_ROUTE


IP_SPECIFIC_DATA

typedef struct _IP_SPECIFIC_DATA {
    DWORD    FSD_Type;
    DWORD    FSD_Policy;
    DWORD    FSD_NextHopAS;
    DWORD    FSD_Priority;
    DWORD    FSD_Metric;
    DWORD    FSD_Metric1;
    DWORD    FSD_Metric2;
    DWORD    FSD_Metric3;
    DWORD    FSD_Metric4;
    DWORD    FSD_Metric5;
    DWORD    FSD_Flags;
} IP_SPECIFIC_DATA, *PIP_SPECIFIC_DATA;

Members

FSD_Type
Specifies the route type as defined in RFC 1354. The following list shows the possible values for this member.
Member | Value
1 | The route type is not specified. The type is different from those listed here.
2 | The route is invalid. Normally, this value is used to invalidate a route. However, since invalidation is not supported by the Routing Table Manager (RTM), the route will still be considered in best-route computations. Therefore, routing protocols should not use this value.
3 | The route is a local route, that is, the next hop is the final destination.
4 | The route is a remote route, that is, the next hop is not the final destination.

FSD_Policy
Specifies the set of conditions that would cause the selection of a multi-path route. This member is typically in IP TOS format. For more information, see RFC 1354.
FSD_NextHopAS
Specifies the autonomous system number of the next hop.
FSD_Priority
Specifies a metric value. The RTM uses this value to compare this route entry to route entries obtained from other routing protocols. The value of this member is set by the RTM.
FSD_Metric
Specifies a metric value. The RTM uses this value to compare this route entry to other route entries obtained from the same routing protocol. The value of this member is set by the routing protocol.
FSD_Metric1
Specifies a routing-protocol-specific metric value. This metric value is documented in RFC 1354.
FSD_Metric2
Specifies a routing-protocol-specific metric value. This metric value is documented in RFC 1354.
FSD_Metric3
Specifies a routing-protocol-specific metric value. This metric value is documented in RFC 1354.
FSD_Metric4
Specifies a routing-protocol-specific metric value. This metric value is documented in RFC 1354.
FSD_Metric5
Specifies a routing-protocol-specific metric value. This metric value is documented in RFC 1354.
FSD_Flags
Indicates whether the route is valid. The routing protocol should first clear these flags, then set the route as either valid or invalid. The routing protocol should use the macros ClearRouteFlags(), SetRouteValid(), and ClearRouteValid() to perform these operations. These macros are defined in rtm.h.

Remarks

The RTM uses the FSD_Priority and FSD_Metric members to compute the best route to a particular destination network.

The FSD_Metric[1-5] members are for MIB II conformance. MIB II agents will display only these metric values. They will not display the FSD_Metric metric value. To have the FSD_Metric displayed, the routing protocol should also store the value in one of the FSD_Metric[1-5] members.

The RTM does not use the metric values in the FSD_Metric[1-5] members when computing the best route to a destination network. Therefore, the routing protocol should ensure that the FSD_Metric member has an appropriate metric value.

A routing protocol could use the FSD_Flags to mark a route as invalid, if it did not want the route to be considered by other routing protocols.

See Also

RTM_IP_ROUTE


IPX_NETWORK

The IPX_NETWORK structure describes an IPX network address.

typedef struct _IPX_NETWORK {
    DWORD    N_NetNumber;
} IPX_NETWORK, *PIPX_NETWORK;

Members

N_NetNumber;
Contains the IPX network number in machine byte order.

See Also

RTM_IPX_ROUTE


IPX_NEXT_HOP_ADDRESS

The IPX_NEXT_HOP_ADDRESS structure contains the address for the next-hop router for an IPX route.

typedef struct _IPX_NEXT_HOP_ADDRESS {
    BYTE    NHA_Mac[6];
} IPX_NEXT_HOP_ADDRESS, *PIPX_NEXT_HOP_ADDRESS;

Members

NHA_Mac[6]
MAC address of next hop router.

See Also

RTM_IPX_ROUTE


IPX_SPECIFIC_DATA

typedef struct _IPX_SPECIFIC_DATA {
    DWORD     FSD_Flags;
    USHORT    FSD_TickCount;
    USHORT        FSD_HopCount;
} IPX_SPECIFIC_DATA, *PIPX_SPECIFIC_DATA;

Members

FSD_Flags
Contains flags that describe the route. Currently, this member is either zero or the following flag value.
IPX_GLOBAL_CLIENT_WAN_ROUTE
Indicates that this route is for the global network allocated for all WAN clients.
FSD_TickCount
The number of ticks it takes to reach the destination network. Routing protocols other than RIP should convert their metrics into ticks.
FSD_HopCount
The hop count associated with the route.

See Also

RTM_IPX_ROUTE


PROTOCOL_SPECIFIC_DATA

The PROTOCOL_SPECIFIC_DATA structure contains memory reserved for data specific to a particular routing protocol.

typedef struct _PROTOCOL_SPECIFIC_DATA {
    DWORD    PSD_Data[4];
} PROTOCOL_SPECIFIC_DATA, *PPROTOCOL_SPECIFIC_DATA;

Members

PSD_Data[4]
Array of DWORD variables. This memory is reserved for routing protocol specific data.

See Also

RTM_IP_ROUTE, RTM_IPX_ROUTE


RTM_IP_ROUTE

The RTM_IP_ROUTE structure contains information that describes a route for the IP protocol family.

typedef struct _RTM_IP_ROUTE {
    FILETIME                  RR_TimeStamp;
    DWORD                     RR_RoutingProtocol;
    DWORD                     RR_InterfaceID;
    PROTOCOL_SPECIFIC_DATA    RR_ProtocolSpecificData;
    IP_NETWORK                RR_Network;
    IP_NEXT_HOP_ADDRESS       RR_NextHopAddress;
    IP_SPECIFIC_DATA          RR_FamilySpecificData;
} RTM_IP_ROUTE, * PRTM_IP_ROUTE;

Members

RR_TimeStamp
Contains the time that the route entry was created or last updated. This member is set by the Routing Table Manager (RTM). The time is expressed as an NT file time.
RR_RoutingProtocol
Identifies the routing protocol that added the route.
RR_InterfaceID
Identifies the interface through which the route was obtained.
RR_ProtocolSpecificData
A PROTOCOL_SPECIFIC_DATA structure containing memory reserved for routing protocol specific data.
RR_Network
An IP_NETWORK structure containing an IP network address.
RR_NextHopAddress
An IP_NEXT_HOP_ADDRESS structure containing the address of the next hop router.
RR_FamilySpecificData
An IP_SPECIFIC_DATA structure containing IP protocol-family-specific data.

Remarks

The members of the RTM_IP_ROUTE structure are all DWORD aligned.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rtm.h.

See Also

IP_NETWORK, IP_NEXT_HOP_ADDRESS, IP_SPECIFIC_DATA


RTM_IPX_ROUTE

The RTM_IPX_ROUTE structure contains information that describes a route for the IPX protocol family.

typedef struct _RTM_IPX_ROUTE {
    FILETIME                  RR_TimeStamp;
    DWORD                     RR_RoutingProtocol;
    DWORD                     RR_InterfaceID;
    PROTOCOL_SPECIFIC_DATA    RR_ProtocolSpecificData;
    IPX_NETWORK               RR_Network;
    IPX_NEXT_HOP_ADDRESS      RR_NextHopAddress;
    IPX_SPECIFIC_DATA         RR_FamilySpecificData;
} RTM_IPX_ROUTE, * PRTM_IPX_ROUTE;

Members

RR_TimeStamp
Contains the time that the route entry was created or last updated. This member is set by the Routing Table Manager (RTM). The time is expressed as an NT file time.
RR_RoutingProtocol
Identifies the routing protocol that added the route.
RR_InterfaceID
Identifies the interface through which the route was obtained.
RR_ProtocolSpecificData
A PROTOCOL_SPECIFIC_DATA structure containing memory reserved for routing protocol specific data.
RR_Network
An IPX_NETWORK structure containing an IP network address.
RR_NextHopAddress
An IPX_NEXT_HOP_ADDRESS structure containing the address of the next hop router.
RR_FamilySpecificData
An IPX_SPECIFIC_DATA structure containing IPX protocol-family-specific data.

Remarks

The members of the RTM_IPX_ROUTE structure are all DWORD aligned.

QuickInfo

Windows NT: Use version 5.0 and later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rtm.h.

See Also

IPX_NETWORK, IPX_NEXT_HOP_ADDRESS, IPX_SPECIFIC_DATA


Plugin Overview

Routing and Remote Access Service (RRAS) includes functionality that allows implementation of third-party routing protocols. Plugins provide the interface to incorporate such routing protocols into the Routing and Remote Access Administrator user interface (UI), and are integrated through three objects: the host object, the plugin object, and the plugin control. The host object is implemented by the Routing and Remote Access Administrator and provides services to the plugins, the plugin object provides the basic information required to display the plugin, and the plugin control is a Microsoft®n ActiveX® control responsible for displaying detailed information in the right-hand pane and in any floating windows.

These objects must be implemented in one DLL, and that DLL must expose DllRegisterServer. When the Routing and Remote Access Administrator is run on a remote machine, it will load the configuration DLL specified in the registry entry (described in Plugin Registry Settings) for the routing protocol, and call DllRegisterServer. When necessary, Routing and Remote Access Administrator will create the objects. For proper implementation the DLL should be installed in the path, in the local directory when Routing and Remote Access Administrator is run, or its absolute path must be specified in the registry.


Plugin Registry Settings

Registry settings allow the Routing and Remote Access Administrator to locate the plugin configuration DLL, and provides other pertinent information necessary for proper implementation of the configuration DLL.

The path for registry key creation and plugin configuration DLL settings is:

HKEY_LOCAL_MACHINE\Software\Microsoft\Router\CurrentVersion\

RouterManagers\IP\[name of Third Party Routing Protocol]

Registry entries in the third-party routing protocol must include:

Registry Entry | Type
ProtocolId | REG_DWORD
DLLName | REG_SZ
ConfigCLSID | REG_SZ

ProtocolId
The identifier of your routing protocol.
Title
The name of your routing protocol. Note that this is not the name that appears in the node; the title for the node is obtained through IMprUIPlugin::GetTitle.
DLLName
The name of the DLL that implements the routing protocol being added to the configuration.
ConfigDLL
This is the name of the DLL that will be registered by Routing and Remote Access Administrator.
ConfigCLSID
The GUID for your configuration DLL. This GUID is used in the initial CoCreateInstance to get the IMprUIPlugin object.


Host Object

The host object is implemented by Routing and Remote Access Administrator, and provides services to the plugins. The host object exposes two interfaces, IUnknown and IMprUIHost.

Interface Name: IMprUIHost

Derived From: IUnknown

Interface Identifier: {73A827F0-FF6E-11cf-AA6B-00805F0C9232}


FloatWindow

The FloatWindow function is used to create a floating window within the Routing and Remote Access Administrator user interface (UI). The floating window is used to contain the plugin control.

FloatWindow (
  REFCLSID rguidModule,      // CLSID representing the object
  REFCLSID rclsidCtrl,       // CLSID of ActiveX Control to create
  IMprUIPlugin* pConnection, // Plugin node making request
  DWORD dwContext,           // constant context to ActiveX Control
  PWCHAR pszTitle            // Title of floating window
);

Parameters

rguidModule
The Class Identifier (CLSID) of the plugin module object.
rclsidCtrl
The Class Identifier (CLSID) of the ActiveX® control to create.
pConnection
Pointer to the plugin module making the request.
dwContext
Constant context passed to the ActiveX control.
pszTitle
The Title of the floating window.

Return Values

The FloatWindow function has no return values.

Remarks

Use CoTaskMemAlloc to allocate memory for pszTitle.


GlobalRefresh

The GlobalRefresh function forces all nodes in the Routing and Remote Access Administrator User Interface to be refreshed.

GlobalRefresh (
);

Parameters

The GlobalRefresh function has no parameters.

Return Values

The GlobalRefresh function has no return values.


Plugin Object

The plugin object, implemented by the third-party, provides basic information required to display the plugin module. The Routing and Remote Access Administrator will create the plugin object via ::CoCreateInstance, and its Class Identifier (CLSID) should be specified in the ConfigCLSID registry entry, as described in Plugin Registry Settings. The plugin object implements two interfaces, IUnknown and IMprUIPlugin.

Interface Name: IMprUIPlugin

Derived From: IUnknown

Interface Identifier: {73A827F1-FF6E-11cf-AA6B-00805F0C9232}


ConnectToRouter

The ConnectToRouter function is used to connect the plugin module to the router. The plugin module should disconnect from the Routing and Remote Access Service Server when the IMprUIPlugin is released.

ConnectToRouter (
  LPCTSTR pRouterName,
  IMprUIHost *pMprUIHost
);

Parameters

pRouterName
Pointer to a string containing the name of the router to which the plugin module is to connect.
pMprUIHost
Pointer to the IMprUIHost interface.

Return Values

The ConnectToRouter function has no return values.

Remarks

Routing and Remote Access Administrator expects pRouterName to be a LPCWSTR, not a LPCTSTR. Though the plugin.h header file reports TCHAR, if third-party plugin modules are complied with ANSI, Routing and Remote Access Administrator will pass through a Unicode string.


GetTitle

The GetTitle function returns the title text for a plugin module.

GetTitle (
  PWSTR*      ppszTitle
);

Parameters

ppszTitle
Pointer to a string that will receive the title text.

Return Values

The GetTitle function has no return values.

Remarks

Use CoTaskMemAlloc to allocate memory for ppszTitle.


GetContextMenu

The GetContextMenu function provides a means to obtain a context menu for a plugin module. Note that the context menu will be destroyed by host.

GetContextMenu (
  HMENU*      phMenu
);

Parameters

phMenu
Pointer to a handle for the context menu of the plugin module.

Return Values

The GetContextMenu function has no return values.


ProcessCommand

The ProcessCommand function processes the command returned by the context menu, which is returned in the GetContextMenu function.

ProcessCommand (
  WPARAM      wParam,
  LPARAM      lParam,
  HWND        hWndParent
);

Parameters

wParam
Specifies the identifier of the menu item. For more information, see WM_COMMAND.
lParam
This parameter should be NULL. For more information, see WM_COMMAND.
hWndParent
Handle to the parent window.

Return Values

The ProcessCommand function has no return values.

Remarks

Several command identifiers have been reserved for specific keystrokes. These include IDM_HOTKEY_INSERT(1024), IDM_HOTKEY_DELETE(1025), and IDM_HOTKEY_RETURN(1026).


GetCLSID

The GetCLSID function provides an interface to obtain the CLSID (Class Identifier for the Microsoft® ActiveX® control that displays in the right-hand pane of the Routing and Remote Access Service Adinistrator user interface.

GetCLSID (
  CLSID**     ppClsid
);

Parameters

ppClsid
Pointer to a pointer that receives the CLSID for the ActiveX control.

Return Values

The GetCLSID function has no return values.

Remarks

Use CoTaskMemAlloc to allocate space for ppClsid.


Plugin Control

The plugin control is a Microsoft® ActiveX® control. The plugin control is responsible for displaying detailed information in the right-hand pane of Routing and Remote Access Administrator and in any floating windows. The control is only required to expose two methods.


MprUISetContext

The MprUISetContext ActiveX® control is called by the Routing and Remote Access Administrator after a third-party routing protocol plugin control is created. MprUISetContext specifies what information should be displayed for the third-party routing protocol.

// MprUISetContext is called by MPRADMIN after the control
        // is created in order to specify exactly what information
        // should be displayed.

[id(1)] long MprUISetContext(
                    // The following parameter is the pMprUIPlugin
                    // interface that the control is associated with.
                long pMprUIPlugin,
                    // The following parameter will be zero if the
                    // control is to be displayed in the Right Hand
                    // Pane.  If the control is to be displayed in a
                    // floating window then this parameter is the same
                    // value set to IMprUIHost::FloatWindow(…).
                long lContext
                );
[id(2)] long MprUIRefresh(
                );

Parameters

pMprUIPlugin
Pointer to the MprUIPlugin interface with which the plugin control is associated.
lContext
Determines whether the plugin control will be displayed in the right-hand frame of the Routing and Remote Access Administrator user interface, or if it will be displayed in a floating window. If the plugin control will be displayed in the right-hand frame, lContext will be zero. If the control is to be displayed in a floating window, lContext will be the same value set to iMprUIHost::FloatWindow.

See Also

FloatWindow


About Extensible Authentication Protocol (EAP)

Support for the Extensible Authentication Protocol (EAP) is available on Microsoft® Windows NT® Version 5.0 or later. EAP improves on previous authentication protocols such as Password Authentication Protocol (PAP) and Challenge Handshake Authentication Protocol (CHAP). Windows NT continues to support these earlier authentication protocols as well.

EAP allows third-party authentication modules to interact with the Windows NT Remote Access Service (RAS) Point to Point Protocol (PPP) implementation. EAPs availability on Windows NT is in response to increasing demand to augment RAS authentication with third-party security devices. EAP is an extension to PPP, providing a standard support mechanism for authentication schemes such as token cards, Kerberos, Public Key, and S/Key. EAP is fully supported on both the Windows NT Dial-Up Server and the Dial-Up Networking Client. EAP is a critical technology component for secure Virtual Private Networks (VPN), protecting them against brute force or dictionary attacks and password guessing.


EAP Installation

Microsoft® Windows NT®, vendors can implement EAPs, also known as authentication protocols, in Dynamic Link Libraries (DLLs). A DLL for the authentication protocol must reside on both the client and server computers. For simplicity, the client and server DLLs will often be identical; however, this is not a requirement. Also, note that the same DLL may support more than one authentication protocol.

The vendor should provide setup software to install and remove the DLL. The setup software should also create appropriate keys and values for the authentication protocol in the system registry. The installation of each EAP DLL should create the following registry key.

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Rasman\PPP\EAP\<eaptypeid>

In the preceding path, <eaptypeid> is the ID of the authentication protocol. The vendor must obtain this ID from the Internet Assigned Numbers Authority (IANA).

The setup software should remove this key when uninstalling the DLL. The system will remove this key if the user uninstalls RAS.


Authentication Protocol Registry Values

The setup software for the EAP DLL may create the following registry values beneath <eaptypeid>. These registry values are defined in the raseapif.h header file. The RAS_EAP_VALUENAME_PATH and RAS_EAP_VALUENAME_CONFIGUI values are required.

The setup software may create other keys/value beneath <eaptypeid> as well. These could be used by the authentication protocol itself.

Constant Name | Constant Value | Type | Description
RAS_EAP_VALUENAME_PATH | Path | REG_EXPAND_SZ | Specifies the path to the EAP DLL.
RAS_EAP_VALUENAME_CONFIGUI | ConfigUIPath | REG_EXPAND_SZ | Specifies the path to the DLL that implements the configuration user interface.
RAS_EAP_VALUENAME_INTERACTIVEUI | InteractiveUIPath | REG_EXPAND_SZ | Specifies the path to the DLL that implements the interactive user interface.
RAS_EAP_VALUENAME_FRIENDLY_NAME | FriendlyName | REG_SZ | Specifies a friendly name for the authentication protocol. This name will appear in the Dial-Up Networking user interface.
RAS_EAP_VALUENAME_DEFAULT_DATA | ConfigData | REG_BINARY | Specifies default configuration data for the authentication protocol.
RAS_EAP_VALUENAME_DEFAULT_IDENTITY | Identity | REG_SZ | Specifies a default identity for the user requesting authentication.
RAS_EAP_VALUENAME_REQUIRE_CONFIGUI | RequireConfigUI | REG_DWORD | Specifies whether the user must provide configuration data in the Dial-Up Networking user interface. If this value is 1, the user will not be allowed to exit the Dial-Up Networking UI unless they have provided configuration data.
RAS_EAP_VALUENAME_ENCRYPTION | MPPEEncryptionSupported | REG_DWORD | If this value is 1, the authentication protocol can generate keys for MPPE encryption. Possible values are 0 or 1. The default value is 0.
RAS_EAP_VALUENAME_INVOKE_STDUI | InvokeStandardCredentialsDialog | REG_DWORD | Specifies whether the RAS Connection Manager should display the standard Windows NT credentials dialog. If this value is 1, RAS will display the dialog. Possible values are 0 or 1. The default value is 1.


Registry Values Example

The following example shows possible data for some of the authentication protocol registry values.

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Rasman\PPP\EAP\40
  Path               (REG_EXPAND_SZ)  %SystemRoot%\system32\sample.dll
  FriendlyName       (REG_SZ)         Sample EAP Protocol
  ConfigUIPath       (REG_EXPAND_SZ)  %SystemRoot%\system32\sample.dll
  InteractiveUIPath  (REG_EXPAND_SZ)  %SystemRoot%\system32\sample.dll
  RequireConfigUI    (REG_DWORD)      1


EAP Interface with Windows NT

Microsoft® Windows NT® RAS interacts with EAP implementations through the use of function calls that must be exported by the third-party EAP DLL. Another component of EAP is its ability to interface with authentication providers, whether built into Windows NT (such as Windows NT domain authentication or Radius), or provided as a third-party authentication DLL. Some structures defined in EAP header files have members that are used only if an authentication provider is being used. Details on these structures and their use are provided in the individual structure reference pages.


EAP Implementation Details

This section details how the installed authentication protocol will interoperate with the RAS Connection Manager.


RAS Connection Manager Initialization

Upon initialization, the RAS Connection Manager (RAS) will query the registry for any installed authentication protocols. RAS will then call the exported function RasEapGetInfo for each authentication protocol. The RasEapGetInfo function passes a single parameter of type PPP_EAP_INFO. RAS will use the dwEapTypeId member of this structure to specify the authentication protocol for which information is requested (note that a single DLL may support more than one protocol). If RasEapGetInfo returns any value other than NO_ERROR, RAS assumes that the authentication protocol is unavailable.

On return from RasEapGetInfo the PPP_EAP_INFO structure contains pointers to the functions RasEapBegin, RasEapMakeMessage, and RasEapEnd in the EAP DLL.. RAS will use these functions to interoperate with the authentication protocol.


Authentication Protocol Initialization

When creating a phonebook entry for a particular connection, the user will select an authentication protocol to use for that connection. The authentication protocol may require configuration. If so, the Dial-Up Networking user interface (UI) will display a configuration user interface by calling the RasEapInvokeConfigUI function. The Dial-Up Networking UI stores the connection-specific configuration information returned by RasEapInvokeConfigUI in the phonebook entry. Additionally, the Dial-Up Networking UI stores the user-specific configuration information in the registry under HKEY_CURRENT_USER. The setup program for the authentication protocol may also store default configuration information in the registry. For more information, see EAP Installation.

The Dial-Up Networking UI will request an identity for the user. If the authentication protocol has RAS_EAP_VALUENAME_INVOKE_STDUI set to one in the registry, the Dial-Up Networking UI will display the standard Windows NT credentials dialog. Otherwise, the identity may be of a type specific to the authentication protocol, for example a certificate or numeric ID. In either case, the identity information will also be stored in the registry under HKEY_CURRENT_USER. The setup program for the authentication protocol may also store default identity information in the registry. For more information, see EAP Installation.

When RAS attempts to establish the connection, it will call the RasEapBegin function for the specified authentication protocol. This allows the protocol to allocate and initialize a work buffer that RAS will pass on subsequent calls to RasEapMakeMessage and RasEapEnd. In RasEapBegin, RAS will also pass a PPP_EAP_INPUT structure that contains a pointer to the configuration information for the connection.

Within the PPP_EAP_INPUT structure, the fAuthenticator member indicates whether the authentication protocol is being invoked as an authenticatee (client) or authenticator (server). On the client, RAS will always pass in values for the pszIdentity and pszPassword members. On the server, RAS will always pass in a value for pszIdentity.

If the RasEapBegin call returns any value other than NO_ERROR, the session will be disconnected. The returned error will be logged (on the server), or displayed to the user (on the client).


RAS and Authentication Protocol Interaction During Authentication

The RasEapMakeMessage function, is where the majority of the interaction takes place between the authentication protocol and the RAS Connection Manager Service. RasEapMakeMessage is used to process incoming EAP packets and to create EAP packets for transmission to the remote peer. It is also used to process events such as timeouts and authentication completion.

If a message is received from the remote peer, RAS will call RasEapMakeMessage, with the pReceivePacket parameter pointing to the received message.

If RAS calls RasEapMakeMessage with pReceivePacket set to NULL, RAS is either initiating the dialog with the authentication protocol, or requesting that the protocol resend the last packet. The authentication protocol should determine which is the case from its state and from the message context.

On return from the RasEapMakeMessage call, the value of the Action member of the PPP_EAP_OUTPUT structure indicates what action, if any, the RAS Connection Manager should take. The Action member takes values from the PPP_EAP_ACTION enumerated type.

If Action is EAPACTION_Send, EAPACTION_SendAndDone, EAPACTION_SendWithTimeout, or EAPACTION_SendWithTimeoutInteractive, the RAS Connection Manager will transmit the packet pointed to by the pSendPacket parameter to the remote peer.

If Action is EAPACTION_SendWithTimeout, or EAPACTION_SendWithTimeoutInteractive, the authentication protocol should set the dwIdExpected member of the PPP_EAP_OUTPUT structure to the identifier of the next packet expected from the remote peer. Regardless of whether the next packet received from the peer matches this value, RAS will pass the packet to the authentication protocol in a subsequent call to RasEapMakeMessage. The authentication protocol may silently discard the packet by simply returning ERROR_PPP_INVALID_PACKET. If a packet with the expected identifier, is not received within the configured timeout period, RAS will call RasEapMakeMessage with pReceivePacket set to NULL, to indicate that the previous packet needs to be resent.

The EAPACTION_SendWithTimeout value allows for a timeout, after which the RAS Connection Manager Service will assume the link was lost, and the session will be disconnected. The EAPACTION_SendWithTimeoutInteractive value allows an infinite amount of timeout to occur. The authenticator should use this value when expecting user input on the client. This timeout allows the user an unspecified amount of time to complete the required input.

If the Action member is EAPACTION_Done or EAPACTION_SendAndDone, RAS will examine the dwAuthResultCode member of PPP_EAP_OUTPUT. If dwAuthResultCode is NO_ERROR, the authentication succeeded. If dwAuthResultCode is a value other than NO_ERROR, the authentication failed. The error code returned for the failure case should come from raserror.h, mprerror.h, or winerror.h. Possible return codes include (but aren't limited to): ERROR_NO_DIALIN_PERMISSION, ERROR_PASSWD_EXPIRED, ERROR_ACCT_DISABLED, ERROR_RESTRICTED_LOGON_HOURS or ERROR_AUTH_INTERNAL.

The EAP success packet is a non-acknowledged packet. Therefore, it may be lost and not resent by the server. If the RAS Connection Manager on the client receives an NCP packet, RAS will assume that authentication was successful, but that the EAP success packet was lost, since the server has moved on to the NCP phase of PPP. In this case, RAS will call RasEapMakeMessage with the fSuccessPacketReceived member of the PPP_EAP_INPUT structure to TRUE.

Upon successful authentication, the authentication protocol on the server (the authenticator) should set the value of the szIdentity member of the PPP_EAP_OUTPUT structure. This value represents the identity of the authenticated user on the server.

During the course of the authentication session, the authentication protocol may need to interact directly with the user on the client. The authentication protocol vendor can provide an interactive user interface for this purpose. The authentication protocol can request that RAS display the interactive UI by setting the fInvokeInteractiveUI, pUIContextData, and dwSizeOfUIContextData members in the PPP_EAP_OUTPUT structure. For more information on using an interactive UI, see Interactive User Interface.

If during the authentication process, RasEapMakeMessage returns any value other than NO_ERROR or ERROR_PPP_INVALID_PACKET, the session will be disconnected and the error will be logged (on the server) or displayed to the user (on the client).


Completion of the Authentication Session

Whether authentication was successful, the RAS Connection Manager calls the RasEapEnd function to allow the authentication protocol to deallocate its work buffer. It is guaranteed that no further calls will be made to the authentication protocol with that particular user or context without first calling RasEapBegin.


Configuration User Interface

The vendor that implements the authentication protocol may also provide a configuration user interface (UI) for the protocol. The configuration UI may be implemented in the same DLL as the authentication protocol, or in a separate DLL. Also, the DLL that implements the configuration UI may support more than one authentication protocol. The path to the DLL for the configuration user interface is stored in a registry value under the key for the authentication protocol. For more information about creating this registry value, see EAP Installation.

The DLL for the configuration user interface should export entry points for the following functions:

RasEapFreeConfigUIData

RasEapInvokeConfigUI

When the user creates a phonebook entry for a particular RAS server in the Dial-Up Networking UI, the user is able to select the authentication protocol that RAS should use. If the authentication protocol is configurable, the Dial-Up Networking UI calls RasEapInvokeConfigUI to invoke the configuration UI. The Dial-Up Networking UI stores the connection-specific configuration information returned by RasEapInvokeConfigUI in the phonebook entry. Additionally, the Dial-Up Networking UI stores the user-specific configuration information in the registry under HKEY_CURRENT_USER.

When RAS calls the RasEapBegin function for the authentication protocol, it will pass a PPP_EAP_INPUT structure that contains a pointer to the configuration information. After RasEapBegin returns, RAS will call RasEapFreeConfigUIData to free the memory occupied by the configuration information. Therefore, the authentication protocol should copy the configuration information into a private memory buffer during the call to RasEapBegin.

The vendor may add registry values under their registry key that specify default configuration information, and whether the user is required to enter configuration information when they create a phonebook entry. For more information, see EAP Installation.


Interactive User Interface

The vendor that implements the authentication protocol may also provide an interactive user interface (UI) for the protocol. The interactive UI may be implemented in the same DLL as the authentication protocol, or in a separate DLL. Also, the DLL that implements the interactive UI may support more than one authentication protocol. The path to the DLL for the interactive UI is stored in a registry value under the key for the authentication protocol. For more information about creating this registry value, see EAP Installation.

The DLL for the interactive UI should export entry points for the following functions:

RasEapFreeInteractiveUIData

RasEapInvokeInteractiveUI

The interactive UI allows the authentication protocol to obtain additional information from the user as needed during the course of the authentication session.

To display the interactive UI, the authentication protocol should set the fInvokeInteractiveUI member of the PPP_EAP_OUTPUT structure to TRUE. The authentication protocol may optionally set the pUIContextData and dwSizeOfUIContextData members as well. RAS will use the values of these members to pass context data to the interactive UI. The authentication protocol returns this PPP_EAP_OUTPUT as a parameter in the RasEapMakeMessage function.

RAS invokes the interactive UI by calling RasEapInvokeInteractiveUI. RAS passes the authentication protocol a pointer to the data returned by the interactive UI in the subsequent call to RasEapMakeMessage. The pointer is passed as a member of a PPP_EAP_INPUT structure. After RasEapMakeMessage returns, RAS will call RasEapFreeInteractiveUIData to free the memory occupied by the information. Therefore, the authentication protocol should copy the information into a private memory buffer during the call to RasMakeMessage.


Extensible Authentication Protocol (EAP) Reference

Vendors should implement the following functions for authentication protocols, authentication providers, or accounting providers. This section also describes the structure types and enumerated types that vendors should use when implementing these functions.


EAP Functions

Vendors should implement the following functions for authentication protocols and authentication providers.


RasAuthenticateClient

The RasAuthenticateClient function authenticates the specified RAS client.

DWORD RasAuthenticateClient(
  HPORT                hPort,
  RAS_AUTH_ATTRIBUTE * pInAttributes
);

Parameters

hPort
Handle to the port on which the client is dialing in.
pInAttributes
Pointer to an array of RAS_AUTH_ATTRIBUTE structures that hold the information required to authenticate the client. The array is terminated by a structure with an raaType member that has a value of raatMinimum.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value should be an appropriate error code from winerror.h, raserror.h, or mprerror.h.

QuickInfo

Windows NT: Use version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in raseapif.h.
Import Library: User-defined.

See Also

RAS_AUTH_ATTRIBUTE, RAS_AUTH_ATTRIBUTE_TYPE


RasEapBegin

The RAS Connection Manager calls the RasEapBegin function to initialize an authentication session.

DWORD ( *RasEapBegin )(
  VOID *          ppWorkBuffer,  // buffer used in subsequent calls to protocol
  PPP_EAP_INPUT * pPppEapInput   // initialization information
);

Parameters

ppWorkBuffer
Pointer to a pointer that, on successful return, points to a work buffer. This buffer is opaque to RAS; the contents of the buffer are used only by the authentication protocol. The RAS Connection Manager will pass a pointer to this buffer to the authentication protocol in subsequent calls to RasEapMakeMessage.
pPppEapInput
Pointer to to a PPP_EAP_INPUT structure that contains initialization information for the authentication session.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value should be an appropriate error code from winerror.h, raserror.h, or mprerror.h.

Remarks

The RasEapBegin function is not part of the Routing and RAS API; it is implemented in the Extensible Authentication Protocol (EAP) DLL. When the RAS Connection Manager calls the RasEapGetInfo function, it receives a PPP_EAP_INFO structure for the authentication protocol. This structure contains a pointer to the RasEapBegin function.

The memory for the work buffer (pointed to by *ppWorkBuffer) is allocated by the authentication protocol. The authentication protocol should free this memory in its implementation of RasEapEnd.

QuickInfo

Windows NT: Use version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in raseapif.h.

See Also

RasEapEnd, RasEapGetInfo, RasEapMakeMessage, PPP_EAP_INFO, PPP_EAP_INPUT


RasEapEnd

The RAS Connection Manager calls the RasEapEnd function to end an authentication session. RAS will call RasEapEnd regardless of whether the session completed successfully.

DWORD ( *RasEapEnd ) (
  VOID * pWorkBuffer    // work buffer to free
);

Parameters

pWorkBuffer
Pointer to the work buffer to free.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value should be an appropriate error code from winerror.h, raserror.h, or mprerror.h. If RasEapEnd returns an error code, RAS will terminate the authentication session.

Remarks

The RasEapEnd function is not part of the Routing and RAS API; it is implemented in the Extensible Authentication Protocol (EAP) DLL. When the RAS Connection Manager calls the RasEapGetInfo function, it receives a PPP_EAP_INFO structure for the authentication protocol. This structure contains a pointer to the RasEapEnd function.

Provided that RasEapBegin returned successfully, the RAS Connection manager will call the RasEapEnd function when authentication has completed.

QuickInfo

Windows NT: Use version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in raseapif.h.

See Also

RasEapBegin, RasEapGetInfo, PPP_EAP_INFO, PPP_EAP_INPUT


RasEapFreeConfigUIData

The RAS Connection Manager will call RasEapFreeConfigUIData to free the memory buffer returned by the authentication protocol's configuration user interface.

DWORD  RasEapFreeConfigData (
  DWORD dwEapTypeId,        // identifies the protocol
  PBYTE pConnectionData,    // pointer to config data
  PBYTE pUserData           // pointer to config data
);

Parameters

dwEapTypeId
Identifies the authentication protocol of the configuration UI that allocated the memory that RasEapFreeConfigUIData should now free.
pConnectionData
Pointer to configuration data from the RasEapInvokeConfigUI function.
pUserData
Pointer to configuration data from the RasEapInvokeConfigUI function.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value should be an appropriate error code from winerror.h, raserror.h, or mprerror.h.

Remarks

The DLL that implements RasEapInvokeConfigUI and RasEapFreeConfigUIData may support more than one authentication protocol. The dwEapTypeId parameter specifies the authentication protocol for which the configuration data was originally obtained.

See Also

RasEapFreeInteractiveUIData, RasEapInvokeConfigUI


RasEapFreeInteractiveUIData

The RAS Connection Manager will call RasEapFreeInteractiveUIData to free the memory buffer returned by the authentication protocol's interactive user interface.

DWORD  RasEapFreeInteractiveUIData (
  DWORD dwEapTypeId,     // identifies the protocol
  PBYTE pDataFromUI      // pointer to data from interactive UI
);

Parameters

dwEapTypeId
Identifies the authentication protocol of the interactive UI that allocated the memory that RasEapFreeInteractiveUIData should now free.
pDataFromUI
Pointer to the interactive UI data returned from RasEapInvokeInteractiveUI function.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value should be an appropriate error code from winerror.h, raserror.h, or mprerror.h.

Remarks

The DLL that implements RasEapInvokeInteractiveUI and RasEapFreeInteractiveUIData may support more than one authentication protocol. The dwEapTypeId parameter specifies the authentication protocol for which the user data was originally obtained.

See Also

RasEapFreeConfigUIData, RasEapInvokeInteractiveUI


RasEapGetInfo

The RAS Connection Manager calls RasEapGetInfo to obtain a set of function pointers for a specified authentication protocol.

DWORD RasEapGetInfo(
  PPP_EAP_INFO * pEapInfo    // pointer to info for a particular EAP
);

Parameters

pEapInfo
Pointer to a PPP_EAP_INFO structure. The structure contains members that RAS will set to identify the structure version and the authentication protocol for which function pointers are requested. For more information, see PPP_EAP_INFO.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value should be an appropriate error code from winerror.h, raserror.h, or mprerror.h.

Remarks

Implementations of EAP must export the RasEapGetInfo function, since RAS uses RasEapGetInfo to obtain pointers to the other authentication protocol functions.

Upon initialization, the RAS Connection Manager Service will call RasEapGetInfo for each EAP DLL installed in the registry subkey, as explained in the EAP Overview.

If the function returns any value other than NO_ERROR, RAS will consider the authentication protocol to be non-functional. RAS will post an error to the Microsoft® Windows NT® Event Log indicating that this protocol did not start correctly and therefore is not available.

QuickInfo

Windows NT: Use version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in raseapif.h.

See Also

EAP (Extensible Authentication Protocol) Overview, PPP_EAP_INFO


RasEapInvokeConfigUI

The RAS Connection Manager calls the RasEapInvokeConfigUII function to display a dialog to obtain configuration information from the user. RAS calls RasEapInvokeConfigUI when a new phonebook entry is created or an existing phonebook entry is edited, provided that the authentication protocol for the entry provides a configuration user interface.

DWORD  RasEapInvokeConfigUI (
  DWORD     dwEapTypeId,                  // identifies the protocol
  HINSTANCE hInstance,                    // handle to DLL module
  HWND      hwndParent,                   // handle to parent window
  DWORD     dwFlags,                      // indicates whether caller is router or RAS client
  PBYTE *   ppConfigData,                 // config data returned
  DWORD *   lpdwSizeOfConfigData,         // size of config data
  PBYTE     pConnectionDataIn,            // current connection data
  DWORD     dwSizeOfConnectionDataIn,     // size of current connection data
  PBYTE     pUserDataIn,                  // current user data
  DWORD     dwSizeOfUserDataIn,           // size of current user data
  PBYTE *   ppConnectionDataOut,          // new connection data
  DWORD *   lpdwSizeOfConnectionDataOut,  // size of new connection data
  PBYTE *   ppUserDataOut,                // new user data
  DWORD *   lpdwSizeOfUserDataOut,        // size of new user data
  LPSTR     szIdentityOut[UNLEN+DNLEN+2]  // identity of user
);

Parameters

dwEapTypeId
Identifies the authentication protocol for which to invoke the configuration UI.
hInstance
Handle to the DLL module.
hwndParent
Handle to the parent window for the UI dialog.
dwFlags
Specifies whether the computer dialing in is a router or a RAS client. If the computer is a router, this parameter should be set to

RAS_EAP_FLAG_ROUTER

Otherwise, this parameter should be zero.

pConnectionDataIn
Pointer to the connection-specific data currently stored in the phonebook entry. If RasEapInvokeConfigUI is called during the creation of a new entry, this parameter will be NULL.
dwSizeOfConnectionDataIn
Size of the connection-specific data currently stored in the phonebook entry. If RasEapInvokeConfigUI is called during the creation of a new entry, this parameter will be zero.
pUserDataIn
Pointer to the user-specific data currently stored for this user in the registry. If RasEapInvokeConfigUI is called during the creation of a new entry, this parameter will be NULL
dwSizeOfUserDataIn
Size of the user-specific data currently stored for this user in the registry. If RasEapInvokeConfigUI is called during the creation of a new entry, this parameter will be zero.
ppConnectionDataOut
Pointer to a pointer that, on successful return, will point to the new connection-specific data to store in the phonebook entry.
lpdwSizeOfConnectionDataOut
Pointer to a DWORD that, on successful return, will point to the size of the new connection-specific data to store in the phonebook entry.
ppUserDataOut
Pointer to a pointer that, on successful return, will point to the new user-specific data to store in the registry.
lpdwSizeOfUserDataOut
Pointer to a DWORD that, on successful return, will point to the size of the new user-specific data to store in the registry.
szIdentity
Pointer to a buffer that contains an identifier for the user. The length of this buffer is UNLEN+DNLEN+2.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function wasn't able to allocate memory for the configuration data, the return value should be ERROR_NOT_ENOUGH_MEMORY.

If the function fails in some other way, the return value should be an appropriate error code from winerror.h, raserror.h, or mprerror.h.

Remarks

The DLL that implements RasEapInvokeInteractiveUI and RasEapFreeConfigUIData may support more than one authentication protocol. The dwEapTypeId parameter specifies which protocol to invoke the configuration UI for.

RAS stores the connection-specific data returned by RasEapInvokeConfigUI in the phonebook entry. RAS stores the user-specific data returned by RasEapInvokeConfigUI in the registry under HKEY_CURRENT_USER.

See Also

RasEapFreeConfigUIData, RasEapInvokeInteractiveUI


RasEapInvokeInteractiveUI

The RAS Connection Manager calls the RasEapInvokeInteractiveUI function to display a dialog to obtain authentication data from the user.

DWORD  RasEapInvokeInteractiveUI (
  DWORD     dwEapTypeId,               // identifies the protocol
  HINSTANCE hInstance,                 // handle to DLL module
  HWND      hwndParent,                // handle to parent window
  PBYTE     pUIContextData,            // pointer to context data
  DWORD     dwSizeofUIContextData,     // size of context data
  PBYTE *   ppConnectionData,          // connection-specific data returned from UI
  DWORD *   lpdwSizeOfConnectionData,  // size of connection-specific data returned from UI
  PBYTE *   ppUserData,                // user-specific data returned from UI
  DWORD *   lpdwSizeOfUserData,        // size of user-specific data returned from UI
  LPSTR     szIdentity[UNLEN+DNLEN+2]  // identity of user
);

Parameters

dwEapTypeId
Identifies the authentication protocol for which to invoke the interactive UI.
hInstance
Handle to the DLL module.
hwndParent
Handle to the parent window for the dialog.
pUIContextData
Pointer to context data for the interactive UI. The authentication protocol provides a pointer to this data as a member of the PPP_EAP_OUTPUT structure. The RAS Connection Manager receives the PPP_EAP_OUTPUT structure as an output parameter from the RasEapMakeMessage function.
dwSizeofUIContextData
Specifies the size of the context data. The authentication protocol provides the size as a member of the PPP_EAP_OUTPUT structure. The RAS Connection Manager receives the PPP_EAP_OUTPUT structure as an output parameter from the RasEapMakeMessage function.
ppConnectionData
Pointer to a pointer variable. On return, this pointer variable will point to a memory buffer that holds the connection-specific data obtained from the interactive UI. The interactive UI will allocate this memory buffer. The authentication protocol will free this memory by calling RasEapFreeInteractiveUIData.

If the interactive UI doesn't obtain any connection-specific data, the pointer that ppConnectionData points to should be set to NULL.

lpdwSizeOfConnectionData
Pointer to a DWORD variable to receive the size of the connection-specific data returned by the interactive UI. If the interactive UI doesn't obtain any data from the user, the DWORD variable should be set to zero.
ppUserData
Pointer to a pointer variable. On return, this pointer variable will point to a memory buffer that holds the user-specific data obtained by the interactive UI. The interactive UI will allocate this memory buffer. The authentication protocol will free this memory by calling RasEapFreeInteractiveUIData.

If the interactive UI doesn't obtain any user-specific data, the pointer that ppUserData points to should be set to NULL.

lpdwSizeOfUserData
Pointer to a DWORD variable to receive the size of the user-specific data returned from the interactive UI. If the interactive UI doesn't obtain any user-specific data, the DWORD variable should be set to zero.
szIdentity
Pointer to a buffer of length UNLEN+DNLEN+2. The authentication protocol may use this buffer to return a string that identifies the user requesting authentication.

Return Values

If the function succeeds, the return value is NO_ERROR. Check the ppConnectionData, lpdwSizeOfConnectionData, ppUserData and lpdwSizeOfUserData parameters to determine if the function returned data from the interactive UI.

If the function wasn't able to allocate memory for the connection-specific or user-specific data, the return value should be ERROR_NOT_ENOUGH_MEMORY.

If the function fails in some other way, the return value should be an appropriate error code from winerror.h, raserror.h, or mprerror.h.

Remarks

The DLL that implements the RasEapInvokeInteractiveUI and RasEapFreeInteractiveUIData functions may support more than one authentication protocol. The dwEapTypeId parameter specifies which authentication protocol to invoke the interactive UI for.

A pointer to the data returned from the interactive UI is passed back to the authentication protocol in the PPP_EAP_INPUT structure. The PPP_EAP_INPUT structure is passed as a parameter to the RasEapMakeMessage function.

See Also

RasEapFreeInteractiveUIData, RasEapInvokeConfigUI, RasEapMakeMessage, PPP_EAP_INPUT, PPP_EAP_OUTPUT


RasEapMakeMessage

The RasEapMakeMessage function is the framework within which incoming and outgoing EAP packets, timeouts, and other events such as authentication completion are processed for an EAP. RAS will call the RasEapMakeMessage function every time there is an incoming or outgoing packet.

DWORD   ( * RasEapMakeMessage ) (
  VOID *           pWorkBuf,        // pointer to the workbuffer for this authentication sesssion
  PPP_EAP_PACKET * pReceivePacket,  // pointer to incoming packet
  PPP_EAP_PACKET * pSendPacket,     // pointer to packet to transmit
  DWORD            cbSendPacket,    // max size of packet to transmit
  PPP_EAP_OUTPUT * pEapOutput,      // info/requests from EAP to RAS
  PPP_EAP_INPUT *  pEapInput        // info/requests from RAS to EAP
);

Parameters

pWorkBuf
Pointer to the work buffer. The authentication protocol provides RAS a pointer to this buffer via the RasEapBegin function.
pReceivePacket
Pointer to a PPP_EAP_PACKET structure that contains a received packet. A pReceivePacket value of NULL indicates either that RAS is initiating the dialog with the authentication protocol, or that a timeout has occurred and the authentication protocol should resend the last packet. The authentication protocol must determine based on context which of these two cases is true.
pSendPacket
Pointer to a PPP_EAP_PACKET structure. The authentication protocol can use this structure to specify a packet to send.
cbSendPacket
Specifies the size in bytes of the buffer pointed to by pSendPacket.
pEapOutput
Points to PPP_EAP_OUTPUT structure.
pEapInput
Points to a PPP_EAP_INPUT structure. This parameter may be NULL.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value should be an appropriate error code from winerror.h, raserror.h, or mprerror.h. Any error except for ERROR_PPP_INVALID_PACKET, will terminate the authentication session. For more information on the ERROR_PPP_INVALID_PACKET return code, see EAP Implementation Details.

Remarks

The RasEapMakeMessage function is not part of the Routing and RAS API; it is implemented in the Extensible Authentication Protocol (EAP) DLL. When the RAS Connection Manager calls the RasEapGetInfo function, it receives a PPP_EAP_INFO structure for the authentication protocol. This structure contains a pointer to the RasEapMakeMessage function.

RAS allocates the buffers pointed to by pReceivePacket, pSendPacket, pEapOutput, and pEapInput. The authentication protocol does not allocate any of these buffers.

QuickInfo

Windows NT: Use version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in raseapif.h.

See Also

RasEapGetInfo, PPP_EAP_INFO, PPP_EAP_INPUT, PPP_EAP_OUTPUT, PPP_EAP_PACKET


EAP Structures

Vendors should use the following structure types for authentication protocols and authentication providers.


PPP_EAP_INFO

The PPP_EAP_INFO structure provides the RAS Connection Manager information about the authentication protocol, including pointers to functions located in the EAP DLL.

typedef struct _PPP_EAP_INFO {
    DWORD dwSizeInBytes;  // size of struct identifies version
    DWORD dwEapTypeId;    // identifies the authentication protocol
    DWORD ( * RasEapBegin ) (
        VOID * *           ppWorkBuffer,
        PPP_EAP_INPUT *    pPppEapInput
    );
    DWORD ( * RasEapEnd ) (
        VOID *             pWorkBuffer
    );
    DWORD ( * RasEapMakeMessage ) (
        VOID*              pWorkBuf,
        PPP_EAP_PACKET*    pReceivePacket,
        PPP_EAP_PACKET*    pSendPacket,
        DWORD              cbSendPacket,
        PPP_EAP_OUTPUT*    pEapOutput,
        PPP_EAP_INPUT*     pEapInput
    );
} PPP_EAP_INFO, *PPPP_EAP_INFO;

Members

dwSizeInBytes
Specifies the size of the PPP_EAP_INFO structure. RAS will pass in this value to the EAP DLL. The DLL will use this value to determine which version of the PPP_EAP_INFO structure RAS is using.
dwEapTypeId
Identifies a particular authentication protocol. This identifier must be unique throughout industry-wide implementation of EAP (see IETF Internet Draft 1310). The implementer of an authentication protocol must obtain this identifier from the Internet Assigned Numbers Authority (IANA).
( * RasEapBegin )
Pointer to the RasEapBegin function for the requested authentication protocol. For more information, see the reference page for RasEapBegin. The authentication protocol will set the value of this member.
( * RasEapEnd )
Pointer to the RasEapEnd function for the authentication protocol. For more information, see the reference page for RasEapEnd. The authentication protocol will set the value of this member.
( * RasEapMakeMessage )
Pointer to the RasEapMakeMessage for the requested authentication protocol. For more information, see the reference page for RasEapMakeMessage. The authentication protocol will set the value of this member.

Remarks

A given EAP DLL may implement more than one authentication protocol. Use the dwEapTypeId member to specify for which protocol to retrieve information.

QuickInfo

Windows NT: Use version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in raseapif.h.

See Also

RasEapBegin, RasEapEnd, RasEapGetInfo, RasEapMakeMessage.


PPP_EAP_INPUT

The PPP_EAP_INPUT structure is used in the interaction between the RAS Connection Manager Service PPP implementation and the EAP to provide user information, and to facilitate the use authentication providers such as Microsoft® Windows Windows NT® domain authentication or Radius.

typedef struct _PPP_EAP_INPUT {
    DWORD     dwSizeInBytes   // size of this structure
    DWORD     fFlags          // specifies whether caller
                              // is a router or RAS client
    HANDLE    hPort;          // passed to backend authenticator
    BOOL      fAuthenticator; // act as authenticator or authenticatee
    CHAR *    pszIdentity;    // users's identity
    CHAR *    pszPassword;    // user's account password.
    RAS_AUTH_ATTRIBUTE * pUserAttributes;
    DWORD     ( * RasAuthenticateClient ) (
        HANDLE                  hPort,
        RAS_AUTH_ATTRIBUTE *    pInAttributes
        );
    BOOL      fAuthenticationComplete;
    DWORD     dwAuthError;
    DWORD     dwAuthResultCode;
    RAS_AUTH_ATTRIBUTE *    pAttributesFromAuthenticator;
    HANDLE    hTokenImpersonateUser    // handle to impersonate
                                       // user being authenticated
    DWORD     fSuccessPacketReceived   // true if success indicated
                                       // by NCP packet
    DWORD    fDataReceivedFromInteractiveUI  // true if user exits
                                             // from interactive UI
    PBYTE    pInteractiveConnectionData    // pointer to connection-
                                           // specific data from the
                                           // interactive UI
    DWORD    dwSizeOfInteractiveConnectionData  // size of connection
                                                // specific data from
                                                // the interactive UI
    PBYTE    pInteractiveUserData        // pointer to user-specific
                                         // data from interactive UI
    DWORD    dwSizeOfInteractiveUserData  // size of user-specific
                                          // data from interactive UI
    PBYTE    pConfigConnectionData         // pointer to connection-
                                           // specific data from
                                           // config UI
    DWORD    dwSizeOfConfigConnectionData  // size of connection-
                                           // specific data from
                                           // config UI
    PBYTE    pConfigUserData               // pointer to user-
                                           // specific data from
                                           // config UI
    DWORD    dwSizeOfConfigUserData        // size of user-specific
                                           // data from config UI
} PPP_EAP_INPUT, * PPPP_EAP_INPUT;

Members

dwSizeInBytes
Size in bytes of the PPP_EAP_INPUT structure. The value of this member can be used to distinguish between current and future versions of this structure.
fFlags
Specifies whether the computer dialing in is a router or a RAS client. If the computer is a router, this parameter should be set to

RAS_EAP_FLAG_ROUTER

Otherwise, this parameter should be zero.

hPort
Handle to the port for the user requesting authentication. This handle is passed to the authentication provider in the RasAuthenticateClient function.
fAuthenticator
Indicates whether the authentication protocol is operating on the server or client. A value of TRUE indicates that the authentication protocol is operating on the server as the authenticator. A value of FALSE indicates that the authentication protocol is operating on the client as the authenticatee.
pszIdentity
Pointer to an ASCIIZ character string containing an identifier for the user requesting authentication. Available only if fAuthenticator is FALSE.
pszPassword
Pointer to an ASCIIZ character string containing the user's account password. Available only if fAuthenticator is FALSE. This member may be NULL.
pUserAttributes
Pointer to an array of RAS_AUTH_ATTRIBUTE structures. The array is terminated by a structure with an raaType member that has a value of raatMinimum (see RAS_AUTH_ATTRIBUTE_TYPE)
( * RasAuthenticateClient )
Pointer to the RasAuthenticateClient function for the currently active authentication provider. This member is used only if the authentication protocol is using an authentication provider such as Radius or Windows NT domain authentication, and only if the fAuthenticator member is TRUE. The call to RasAuthenticateClient is asynchronous.
fAuthenticationComplete
Boolean value indicating whether the authenticator has completed the above call to RasAuthenticateClient. A value of TRUE indicates authentication completion. Ignore this field if the authentication protocol is not using an authentication provider.
dwAuthError
This member is only valid if fAuthenticationComplete is TRUE. Any value except NO_ERROR indicates an error occurred during authentication with the authentication provider. This field can be ignored if the EAP is not using an authentication provider. The following member (dwAuthResultCode) is valid only if dwAuthError is NO_ERROR.
dwAuthResultCode
Result of the authentication provider's authentication process. Successful authentication results in NO_ERROR. Authentication failure codes for dwAuthResultCode must come only from winerror.h, raserror.h or mprerror.h. Ignore this field if the authentication protocol is not using an authentication provider. This member is valid only if dwAuthError is NO_ERROR.
pAttributesFromAuthenticator
Pointer to an array of RAS_AUTH_ATTRIBUTE structures that contains attributes returned by the authentication provider (for example Radius or Windows NT domain authentication). The array is terminated by a structure with an raaType member that has a value of raatMinimum (see RAS_AUTH_ATTRIBUTE_TYPE)

This member will be valid only if fAuthenticationComplete is TRUE. The memory occupied by this array is not owned by the authentication protocol, and should be used only for read. Ignore this field if the authentication protocol is not using an authentication provider.

hTokenImpersonateUser
Handle to an impersonation token for the user requesting authentication. This member is valid only on the client side. For more information on impersonation tokens, see Access Tokens.
fSuccessPacketReceived
RAS will set this member to TRUE if the client receives an Network Control Protocol (NCP) packet even though the client has not yet received an EAP success packet. The EAP success packet is a non-acknowledged packet. Therefore, it may be lost and not resent by the server. In this situation, the receipt of an NCP packets indicates that authentication must have been successful, since the server has moved on to the NCP phase of PPP. This member should be examined only on the client side.
fDataReceivedFromInteractiveUI
RAS will set this member to TRUE whenever the user exits from the authentication protocol's interactive user interface (UI).
pInteractiveConnectionData
Pointer to connection-specific data received from the authentication protocol's interactive UI. This pointer will be non-NULL if the fDataReceivedFromInteractiveUI member is TRUE and the interactive UI did, in fact, return data. Otherwise, this pointer will be NULL.

If non-NULL, the authentication protocol should make a copy of the data in its own memory space. RAS will free the memory occupied by this data on return from the call in which the PPP_EAP_INPUT structure was passed. To free the memory RAS will call the RasEapFreeInteractiveUIData function.

dwSizeOfInteractiveConnectionData
Specifies the size in bytes of the data pointed to by pInteractiveConnectionData. If no data was returned from the interactive UI, this member will be zero.
pInteractiveUserData
Pointer to user-specific data received from the authentication protocol's interactive UI. This pointer will be non-NULL if the fDataReceivedFromInteractiveUI member is TRUE and the interactive UI did, in fact, return data. Otherwise, this pointer will be NULL.

If non-NULL, the authentication protocol should make a copy of the data in its own memory space. RAS will free the memory occupied by this data on return from the call in which the PPP_EAP_INPUT structure was passed. To free the memory RAS will call the RasEapFreeInteractiveUIData function.

dwSizeOfInteractiveUserData
Specifies the size in bytes of the data pointed to by pInteractiveUserData. If no data was returned from the interactive UI, this member will be zero.
pConfigConnectionData
Pointer to connection-specific data received from the authentication protocol's configuration user interface. This data will be available only when the PPP_EAP_INPUT structure is passed in RasEapBegin. It will not be available in calls to RasEapMakeMessage.

The authentication protocol should make a copy of this data in its own memory space. RAS will free the memory occupied by this data on return from the call in which the PPP_EAP_INPUT structure was passed. To free the memory RAS will call the RasEapFreeConfigUIData function.

If the authentication protocol's configuration UI did not return any data, this member will be NULL.

dwSizeOfConfigConnectionData
Specifies the size in bytes of the data pointed to by pConfigConnectionData. If pConfigConnectionData is NULL, this member will be zero.
pConfigUserData
Pointer to user-specific data received from the authentication protocol's configuration user interface. This data will be available only when the PPP_EAP_INPUT structure is passed in RasEapBegin. It will not be available in calls to RasEapMakeMessage.

The authentication protocol should make a copy of this data in its own memory space. RAS will free the memory occupied by this data on return from the call in which the PPP_EAP_INPUT structure was passed. To free the memory RAS will call the RasEapFreeConfigUIData function.

If the authentication protocol's configuration UI did not return any data, this member will be NULL.

dwSizeOfConfigUserDataI
Specifies the size in bytes of the data pointed to by pConfigUserData. If pConfigUserData is NULL, this member will be zero.

Remarks

The pszIdentity and pszPassword members of the PPP_EAP_INPUT structure are used by the RasEapBegin function to obtain user information, and are available only if the fAuthenticator member is FALSE.

If the authentication protocol is using an authentication provider, such as Radius or Windows NT domain authentication, the following members

pUserAttributes

RasAuthenticateClient

fAuthenticationComplete

dwAuthError

dwAuthResultCode

pAttributesFromAuthenticator

are used to interface with the authentication provider. Note that the array of RAS_AUTH_ATTRIBUTE structures is passed only if fAuthenticator is TRUE. This array contains current session information such as port identifier or local IP address.

QuickInfo

Windows NT: Use version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in raseapif.h.

See Also

RasEapBegin, RasEapFreeConfigUIData, RasEapFreeInteractiveUIData, RasEapMakeMessage, RAS_AUTH_ATTRIBUTE


PPP_EAP_OUTPUT

The authentication protocol uses the PPP_EAP_OUTPUT structure to communicate requests and status information to the RAS Connection Manager.

typedef struct _PPP_EAP_OUTPUT {
    PPP_EAP_ACTION       Action;                // action that RAS
                                                // should take
    DWORD                dwIdExpected;          // ID of expected
                                                // response packet
    DWORD                dwAuthResultCode;      // result of
                                                // authentication
    CHAR                 szIdentity[UNLEN+1];   // identifies the
                                                // authenticated user
    RAS_AUTH_ATTRIBUTE * pAuthenticatedUserAttributes;
                                                // array of attributes
                                                // structure
    BOOL                 fInvokeInteractiveUI;  // causes RAS
                                                // to invoke
                                                // interactive UI
    PBYTE                pUIContextData;        // data to send to
                                                // interactive UI
    DWORD                dwSizeOfUIContextData; // size of data
    BOOL                 fSaveConfigInfo;       // RAS should save
                                                // the config info
    PBYTE             pConnectionData;     // pointer to the per-
                                           // connection config info
    DWORD             dwSizeofConnectionData;  // size of the per-
                                           // connection config info
    PBYTE             pUserData;           // pointer to the per-
                                           // user config info
    DWORD             dwSizeofUserData;    // size of the per-
                                           // user config info
} PPP_EAP_OUTPUT, *PPPP_EAP_OUTPUT;

Members

Action
Specifies a PPP_EAP_ACTION value. The RAS Connection Manager will carry out this action on behalf of the authentication protocol.
dwIdExpected
Specifies the identifier (ID) for an incoming response packet. Use of this member tells RAS to drop packets that have identifiers that do not match this value. Set this member only if the Action member is EAPACTION_SendWithTimeout or EAPACTION_SendWithTimeoutInteractive.
dwAuthResultCode
Indicates whether authentication was successful. Any non-zero value for dwAuthResultCode indicates failure. The failure code must come from winerror.h, raserror.h or mprerror.h. This member is valid only if the Action member has a value of EAPACTION_Done or EAPACTION_SendAndDone.
szIdentity
Specifies an identifier for the authenticated user on the the server. The authentication protocol running on the server (that is, the authenticator) should set the szIdentity member when Action is EAPACTION_Done or EAPACTION_SendAndDone.
pAuthenticatedUserAttributes
Pointer to an optional array of RAS_AUTH_ATTRIBUTE structures. The array is terminated by a structure with an raaType member that has a value of raatMinimum (see RAS_AUTH_ATTRIBUTE_TYPE).

These structures are allocated by the authentication protocol only if the protocol is not using an existing authentication provider. It is up to the authentication protocol to free this memory in its RasEapEnd function. This member should be set on the authenticator side when Action is EAPACTION_Done or EAPACTION_SendAndDone, and dwAuthResultCode is zero.

fInvokeInteractiveUI
Specifies whether RAS should invoke the authentication protocol's interactive UI. If the authentication protocol sets this member to TRUE, RAS will invoke the interactive UI, by calling the RasEapInvokeInteractiveUI function provided by the authentication protocol.
pUIContextData
Pointer to context data that RAS should pass in the call to RasEapInvokeInteractiveUI. The authentication protocol should free this memory in its implementation of RasEapEnd.
dwSizeOfUIContextData
Specifies the size of the context data that RAS should pass in the call to RasEapInvokeInteractiveUI.
fSaveConfigInfo
Specifies whether RAS should save the config data pointed to by the pConnectionData and pUser data parameters. If this parameter is TRUE, RAS will save the config data in the phonebook entry for the connection.
pConnectionInfo
Pointer to connection-specific configuration data that RAS should save in the phonebook entry for the connection. The authentication protocol should free this memory during the call to RasEapEnd.
dwSizeofConnectionInfo
Specifies the size in bytes of the data pointed to by pConnectionData.
pUserData
Pointer to user-specific data that RAS should save for this connection. RAS will save this data in the registry under HKEY_CURRENT_USER. The authentication protocol should free this memory during the call to RasEapEnd.
dwSizeofUserData
Specifies the size in bytes of the data pointed to by pUserData.

Remarks

Use the RasEapMakeMessage function to pass the PPP_EAP_OUTPUT structure between the authentication protocol and the RAS Connection Manager

QuickInfo

Windows NT: Use version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in raseapif.h.

See Also

RAS_AUTH_ATTRIBUTE, PPP_EAP_ACTION, RasEapInvokeInteractiveUI, RasEapMakeMessage


PPP_EAP_PACKET

The PPP_EAP_PACKET structure specifies information about a packet being processed by the authentication protocol.

typedef struct _PPP_EAP_PACKET {
    BYTE    Code;       // 1-Request, 2-Response, 3-Success, 4-Failure
    BYTE    Id;         // Id of this packet
    BYTE    Length[2];  // Length of this packet
    BYTE    Data[1];    // Data, First byte is Type for
                        // Request/Response
} PPP_EAP_PACKET, * PPPP_EAP_PACKET;

Members

Code
The Code parameter can be one of four values, each indicating the type of packet being sent or received by the authentication protocol.

A value of 1 indicates the packet is a request.

A value of 2 indicates the packet is a response.

A value of 3 specifies the packet indicates success.

A value of 4 specifies the packet indicates failure.

Id
Identification of this packet. The authentication protocol is responsible for maintaining packet counts for sessions, as that packet count pertains to EAP activity.
Length[2]
Length of the packet.
Data[1]
Data. If the packet is a Request or a Response packet, the first byte of this member signifies its Type. For more information about packet Types and requirements for type reservation, refer to the PPP EAP Internet draft, found at http://ds2.internic.net/internet-drafts/draft-ietf-pppext-eap-auth-02.txt

QuickInfo

Windows NT: Use version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in raseapif.h.

See Also

RasEapGetInfo, RasEapMakeMessage, PPP_EAP_INFO, PPP_EAP_INPUT, PPP_EAP_OUTPUT


RAS_AUTH_ATTRIBUTE

The RAS_AUTH_ATTRIBUTE structure is used to pass authentication attributes, of type RAS_AUTH_ATTRIBUTE_TYPE, during an EAP session.

typedef struct _RAS_AUTH_ATTRIBUTE {
    RAS_AUTH_ATTRIBUTE_TYPE raaType;   // attribute type
    DWORD                   dwLength;  // length in bytes of Value
    PVOID                   Value;     // pointer to value or
                                       // contains value
}RAS_AUTH_ATTRIBUTE, *PRAS_AUTH_ATTRIBUTE;

Members

raaType
Specifies the type of attribute, as defined in the RAS_AUTH_ATTRIBUTE_TYPE enumerated type.
dwLength
Specifies the length in bytes of the value of this attribute. If the Value member is a pointer, dwLength specifies the length of the buffer pointed to. If the Value member is the value itself, dwLength specifies how much of the length of the Value member is taken up by the value.
Value
Specifies the value of the attribute. Although this member is typed PVOID, this member sometimes contains the value of the attribute rather than pointing to the value. The only way to know whether to interpret the Value member as a pointer to the value or the value itself, is to check the raaType member. See the reference page for RAS_AUTH_ATTRIBUTE_TYPE for information about how the Value member should be interpreted for different types.

Remarks

Often an array of these structures is used to store or obtain a set of attributes for a given user. Since the number of attributes for a session is unknown, the array must be dynamic. The array is terminated by a structure with an raaType member that has a value of raatMinimum

QuickInfo

Windows NT: Use version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rasauth.h.

See Also

RAS_AUTH_ATTRIBUTE_TYPE


EAP Enumerated Types

Vendors should use the following enumerated types for authentication protocols and authentication providers.


PPP_EAP_ACTION

The PPP_EAP_ACTION enumerated type specifies actions that the RAS Connection Manager Service should take on behalf of the authentication protocol.

typedef enum _PPP_EAP_ACTION {
    EAPACTION_NoAction,        // Be passive, i.e., listen without
                               // timeout (default)
    EAPACTION_Done,            // End auth session, dwAuthResultCode
                               // is set
    EAPACTION_SendAndDone,     // As above but send message without
                               // timeout first
    EAPACTION_Send,            // Send message, don't timeout waiting
                               // for reply
    EAPACTION_SendWithTimeout, // Send message, timeout if reply not
                               // received
    EAPACTION_SendWithTimeoutInteractive // As above, but don't
                                         // increment retry count
} PPP_EAP_ACTION;

Values

EAPACTION_NoAction
Instructs the RAS Connection Manager Service to be passive.
EAPACTION_Done
Instructs the RAS Connection Manager Service to end the authentication session. EAPACTION_Done indicates that the dwAuthResultCode member of the PPP_EAP_OUTPUT structure is set with an appropriate value.
EAPACTION_SendAndDone
Instructs the RAS Connection Manager Service to send a message (without a timeout), then end the authentication session. EAPACTION_SendAndDone indicates that the dwAuthResultCode member of the PPP_EAP_OUTPUT structure is set with an appropriate value.
EAPACTION_Send
Instructs the RAS Connection Manager Service to send a message without setting a timeout to wait for a reply.
EAPACTION_SendWithTimeout
Instructs the RAS Connection Manager Service to send a message, and to set a timeout to wait for a reply.
EAPACTION_SendWithTimeoutInteractive
Instructs the RAS Connection Manager Service to send a message, and to set a timeout to wait for a reply, but instructs the RAS Connection Manager Service not to increment the retry counter.

QuickInfo

Windows NT: Use version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in raseapif.h.

See Also

PPP_EAP_OUTPUT


RAS_AUTH_ATTRIBUTE_TYPE

The RAS_AUTH_ATTRIBUTE_TYPE enumerated type specifies attribute values used for session authentication. Further details for values in this enumerated type may be obtained by referring to one of the three following references: http://ds.internic.net/rfc/rfc2138.txt, http://ds.internic.net/rfc/rfc2139.txt, or http://ds.internic.net/internet-drafts/draft-ietf-radius-ext-00.txt.

typedef enum _RAS_AUTH_ATTRIBUTE_TYPE_ {
    raatMinimum = 0,           // Undefined
    raatUserName,              // Value field is a Pointer
    raatUserPassword,          // Value field is a Pointer
    raatMD5CHAPPassword,       // Value field is a Pointer
    raatNASIPAddress,          // Value field is a 32 bit integral value
    raatNASPort,               // Value field is a 32 bit integral value
    raatServiceType,           // Value field is a 32 bit integral value
    raatFramedProtocol,        // Value field is a 32 bit integral value
    raatFramedIPAddress,       // Value field is a 32 bit integral value
    raatFramedIPNetmask,       // Value field is a 32 bit integral value
    raatFramedRouting,         // Value field is a 32 bit integral value
    raatFilterId,              // Value field is a Pointer
    raatFramedMTU,             // Value field is a 32 bit integral value
    raatFramedCompression,     // Value field is a 32 bit integral value
    raatLoginIPHost,           // Value field is a 32 bit integral value
    raatLoginService,          // Value field is a 32 bit integral value
    raatLoginTCPPort,          // Value field is a 32 bit integral value
    raatUnassigned1,           // Undefined
    raatReplyMessage,          // Value field is a Pointer
    raatCallbackNumber,        // Value field is a Pointer
    raatCallbackId,            // Value field is a Pointer
    raatUnassigned2,           // Undefined
    raatFramedRoute,           // Value field is a Pointer
    raatFramedIPXNetwork,      // Value field is a 32 bit integral value
    raatState,                 // Value field is a Pointer
    raatClass,                 // Value field is a Pointer
    raatVendorSpecific,        // Value field is a Pointer
    raatSessionTimeout,        // Value field is a 32 bit integral value
    raatIdleTimeout,           // Value field is a 32 bit integral value
    raatTerminationAction,     // Value field is a 32 bit integral value
    raatCalledStationId,       // Value field is a Pointer
    raatCallingStationId,      // Value field is a Pointer
    raatNASIdentifier,         // Value field is a Pointer
    raatProxyState,            // Value field is a Pointer
    raatLoginLATService,       // Value field is a Pointer
    raatLoginLATNode,          // Value field is a Pointer
    raatLoginLATGroup,         // Value field is a Pointer
    raatFramedAppleTalkLink,   // Value field is a 32 bit integral value
    raatFramedAppleTalkNetwork,// Value field is a 32 bit integral value
    raatFramedAppleTalkZone,   // Value field is a Pointer
    raatAcctStatusType,        // Value field is a 32 bit integral value
    raatAcctDelayType,         // Value field is a 32 bit integral value
    raatAcctInputOctets,       // Value field is a 32 bit integral value
    raatAcctOutputOctets,      // Value field is a 32 bit integral value
    raatAcctSessionId,         // Value field is a Pointer
    raatAcctAuthentic,         // Value field is a 32 bit integral value
    raatAcctSessionTime,       // Value field is a 32 bit integral value
    raatAcctInputPackets,      // Value field is a 32 bit integral value
    raatAcctOutputPackets,     // Value field is a 32 bit integral value
    raatAcctTerminateCause,    // Value field is a 32 bit integral value
    raatAcctMultiSessionId,    // Value field is a Pointer
    raatAcctLinkCount,         // Value field is a 32 bit integral value
    raatMD5CHAPChallenge = 60, // Value field is a Pointer
    raatNASPortType,           // Value field is a 32 bit integral value
    raatPortLimit,             // Value field is a 32 bit integral value
    raatLoginLATPort,          // Value field is a Pointer
    raatPrompt,                // Value field is a 32 bit integral value
    raatConnectInfo,           // Value field is a Pointer
    raatSignature,             // Value field is a Pointer
    raatEAPMessage,            // Value field is a Pointer
    raatConfigurationToken,    // Value field is a Pointer
    raatPasswordRetry,         // Value field is a 32 bit integral value
    raatARAPPassword,          // Value field is a Pointer
    raatARAPFeatures,          // Value field is a Pointer
    raatARAPZoneAccess,        // Value field is a 32 bit integral value
    raatARAPSecurity,          // Value field is a 32 bit integral value
    raatARAPSecurityData,      // Value field is a Pointer
    raatPasswordRetry,         // Value field is a 32 bit integral value
    raatPrompt,                // Value field is a 32 bit integral value
    raatConnectInfo,           // Value field is a Pointer
    raatConfigurationToken,    // Value field is a Pointer
    raatEAPMessage,            // Value field is a Pointer
    raatSignature,             // Value field is a Pointer
    raatEAPProtocol =(0xFFFFFFFF-90),// Value field is a 32 bit integral
                                     // value
    raatEncryptionType,        // Value field is a 32 bit integral value
    raatEncryptionPolicy,      // Value field is a 32 bit integral value
    raatAuthenticationProtocol,// Value field is a 32 bit integral value
    raatTimeOfDay,             // Value field is a Pointer
    raatBAPRequired,           // Value field is a 32 bit integral value
    raatBAPLineDownTime,       // Value field is a 32 bit integral value
    raatBAPLineDownLimit,      // Value field is a 32 bit integral value
    raatAllowedPortType,       // Value field is a 32 bit integral value
    raatReserved = 0xFFFFFFFF  // Undefined
} RAS_AUTH_ATTRIBUTE_TYPE;

Values

raatMinimum
This value is equal to zero, and used as the NULL terminator in any array of RAS_AUTH_ATTRIBUTE structures.
raatUserName
Specifies the name of the user to be authenticated. The value field in RAS_AUTH_ATTRIBUTE for this type is a pointer. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatUserPassword
Specifies the password of the user to be authenticated. The value field in RAS_AUTH_ATTRIBUTE for this type is a pointer. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatMD5CHAPPassword
Specifies the password provided by the user in response to an MD5 Challenge Handshake Authentication Protocol (CHAP) challenge.. The value field in RAS_AUTH_ATTRIBUTE for this type is a pointer. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatNASIPAddress
Specifies the Network Access Server (NAS) IP address. An Access-Request should specify either an NAS IP address or an NAS identifier. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatNASPort
Identifies the physical or virtual private network (VPN) through which the user is connecting to the NAS. Note that this value is not a port number in the sense of TCP or UDP. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatServiceType
Specifies the type of service the user has requested or the type of service to be provided. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatFramedProtocol
Specifies the type of framed protocol to use for framed access, for example SLIP, PPP, or ARAP (AppleTalk Remote Access Protocol). The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatFramedIPAddress
Specifies the IP address that will be configured for the user requesting authentication. This attribute is typically returned by the authentication provider. However, the NAS may use it in an authentication request to specify a preferred IP address. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatFramedIPNetmask
Specifies the IP network mask for a user that is a router to a network. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatFramedRouting
Specifies the routing method for a user that is a router to a nework. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatFilterId
Identifies the filter list for the user requesting authentication. The value field in RAS_AUTH_ATTRIBUTE for this type is a pointer. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatFramedMTU
Specifies the Maximum Transmission Unit (MTU) for the user. This attribute is used in cases where the MTU is not negotiated through some other means, e.g. PPP. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatFramedCompression
Specifies a compression protocol to use for the connection. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. http://ds.internic.net/rfc/rfc2138.txt.
raatLoginIPHost
Specifies the system with which to connect the user. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatLoginService
Specifies the service to use to connect the user to the host specified by raatLoginIPHost. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatLoginTCPPort
Specifies the port to which to connect the user. This attribute is present only if the raatLoginService attribute is present. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatUnassigned1
This value is currently unassigned.
raatReplyMessage
Specifies a message to display to the user. The value field in RAS_AUTH_ATTRIBUTE for this type is a pointer. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatCallbackNumber
Specifies a callback number. The value field in RAS_AUTH_ATTRIBUTE for this type is a pointer. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatCallbackId
Identifies a location to callback. The value of this attribute will be interpreted by the NAS. The value field in RAS_AUTH_ATTRIBUTE for this type is a pointer. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatUnassigned2
This value is currently unassigned. The value field in RAS_AUTH_ATTRIBUTE for this type is also undefined.
raatFramedRoute
Provides routing information to configure on the NAS for the user. The value field in RAS_AUTH_ATTRIBUTE for this type is a pointer. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatFramedIPXNetwork
Specifies the IPX network number to configure for the user. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatState
Please refer to http://ds.internic.net/rfc/rfc2138.txt for detailed information about this value. The value field in RAS_AUTH_ATTRIBUTE for this type is a pointer.
raatClass
Specifies a value that is provided to the NAS by the authentication provider. The NAS should use this value when communicating with the the accounting provider. The value field in RAS_AUTH_ATTRIBUTE for this type is a pointer. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatVendorSpecific
Allows vendors to provide their own extended attributes. The value field in RAS_AUTH_ATTRIBUTE for this type is a pointer. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatSessionTimeout
Specifies the maximum number of seconds for which to provide service to the user. After this time, the session will be terminated. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatIdleTimeout
Specifies the maximum number of consecutive seconds the session can be idle. If the idle time exceeds this value, the session will be terminated. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatTerminationAction
Please refer to the above referenced files at ds.internic.net for detailed information about this value. The value field in RAS_AUTH_ATTRIBUTE for this type is 32 bit integral value. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatCalledStationId
Specifies the number that the user dialed to connect to the NAS. The value field in RAS_AUTH_ATTRIBUTE for this type is a pointer. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatCallingStationId
Specifies the number from which the user is calling. The value field in RAS_AUTH_ATTRIBUTE for this type is a pointer. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatNASIdentifier
Specifies the Network Access Server (NAS) identifier. An Access-Request should specify either an NAS identifier or an NAS IP address. The value field in RAS_AUTH_ATTRIBUTE for this type is a pointer. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatProxyState
Specifies a value that a proxy server will include when forwarding an authentication request. The value field in RAS_AUTH_ATTRIBUTE for this type is a pointer. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatLoginLATService
This attribute is not currently used for authentication on Windows NT. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatLoginLATNode
This attribute is not currently used for authentication on Windows NT. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatLoginLATGroup
This attribute is not currently used for authentication on Windows NT. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatFramedAppleTalkLink
Specifies the AppleTalk network number for the user when the user is another router. The value field in RAS_AUTH_ATTRIBUTE for this type is 32 bit integral value. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatFramedAppleTalkNetwork
Specifies the AppleTalk network number that the NAS should use to allocate an AppleTalk node for the user. This attribute is used only when the user is not another router. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatFramedAppleTalkZone
Specifies the AppleTalk default zone for the user. The value field in RAS_AUTH_ATTRIBUTE for this type is a pointer. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatAcctStatusType
Specifies whether the accounting provider should start or stop accounting for the user. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2139.txt for more information.
raatAcctDelayType
Specifies the length of time that the client has been attempting to send the current request. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2139.txt for more information.
raatAcctInputOctets
Specifies the number of octets that have been received during the current accounting session. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2139.txt for more information.
raatAcctOutputOctets
Specifies the number of octets that were sent during the current accounting session. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2139.txt for more information.
raatAcctSessionId
Specifies a value to enable the identification of matching start and stop records within a log file. The start and stop records are sent in the raatAcctStatusType attribute. The value field in RAS_AUTH_ATTRIBUTE for this type is a pointer. See http://ds.internic.net/rfc/rfc2139.txt for more information.
raatAcctAuthentic
Specifies to the accounting provider how the user was authenticated, for example by Windows NT Directory Services, RADIUS, or some other authentication provider. The value field in RAS_AUTH_ATTRIBUTEfor this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2139.txt for more information.
raatAcctSessionTime
Specifies the number of seconds that have elapsed in the current accounting session. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2139.txt for more information.
raatAcctInputPackets
Specifies the number of packets that have been received during the current accounting session. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2139.txt for more information.
raatAcctOutputPackets
Specifies the number of packets that have been sent during the current accounting session. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2139.txt for more information.
raatAcctTerminateCause
Specifies how the current accounting session was terminated. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2139.txt for more information.
raatAcctMultiSessionId
Specifies a value to enable the identification of related accounting sessions within a log file. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2139.txt for more information.
raatAcctLinkCount
Specifies the number of links if the current accounting session is using a multilink connection. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2139.txt for more information.
raatMD5CHAPChallenge
Specifies the CHAP challenge sent by the NAS to a CHAP user. The value field in RAS_AUTH_ATTRIBUTE for this type is a pointer. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatNASPortType
Specifies the type of the port through which the user is connecting, for example, asynchronous, ISDN, vitual. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2138.txt for more information.
raatPortLimit
Specifies the number of ports the NAS should make available to the user for multilink sessions. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/rfc/rfc2138.txt for more information
raatLoginLATPort
This attribute is not currently used for authentication on Windows NT. Please refer to the above referenced files at ds.internic.net for detailed information about this value.
raatARAPPassword
Specifies a password to use for AppleTalk Remote Access Protocol (ARAP) authentication. The value field in RAS_AUTH_ATTRIBUTE for this type is a pointer. See http://ds.internic.net/internet-drafts/draft-ietf-radius-ext-00.txt for more information.
raatARAPFeatures
Specifies information that an NAS should send back to the use in an ARAP "feature flags" packet. The value field in RAS_AUTH_ATTRIBUTE for this type is a pointer. See http://ds.internic.net/internet-drafts/draft-ietf-radius-ext-00.txt for more information.
raatARAPZoneAccess
Specifies how to use the ARAP zone list for the user. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/internet-drafts/draft-ietf-radius-ext-00.txt for more information.
raatARAPSecurity
Specifies an ARAP security module to use during a secondary authentication phase between the NAS and the user. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral. See http://ds.internic.net/internet-drafts/draft-ietf-radius-ext-00.txt for more information.
raatARAPSecurityData
Specifies the data to use with an ARAP security module. The value field in RAS_AUTH_ATTRIBUTE for this type is a pointer. See http://ds.internic.net/internet-drafts/draft-ietf-radius-ext-00.txt for more information.
raatPasswordRetry
Specifies the number of password retry attempts to permit the user. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. rfcext.
raatPrompt
Specifies whether the NAS should echo the users response to a challenge. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. See http://ds.internic.net/internet-drafts/draft-ietf-radius-ext-00.txt for more information.
raatConnectInfo
Provides information about the type of connection the user is using. The value field in RAS_AUTH_ATTRIBUTE for this type is a Pointer. See http://ds.internic.net/internet-drafts/draft-ietf-radius-ext-00.txt for more information.
raatConfigurationToken
Identifies user-profile information in communications between RADIUS Proxy Servers and RADIUS Proxy Clients. The value field in RAS_AUTH_ATTRIBUTE for this type is a Pointer. See http://ds.internic.net/internet-drafts/draft-ietf-radius-ext-00.txt for more information.
raatEAPMessage
Specifies Extensible Authentication Protocol (EAP) information to be sent directly between the user and the authentication provider. The value field in RAS_AUTH_ATTRIBUTE for this type is a Pointer. See http://ds.internic.net/internet-drafts/draft-ietf-radius-ext-00.txt for more information.
raatSignature
Specifies a signature to include with CHAP, EAP, or ARAP packets. The value field in RAS_AUTH_ATTRIBUTE for this type is a Pointer. See http://ds.internic.net/internet-drafts/draft-ietf-radius-ext-00.txt for more information.
raatEAPProtocol
Specifies a particular authentication protocol. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value
raatEncryptionType
Specifies an encryption key length (either 40 bit or 128 bit), and whether this length is allowed, disallowed, or required. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value
raatEncryptionPolicy
The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value
raatAuthenticationProtocol
Specifies a particular authentication protocol. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value.
raatTimeOfDay
Specifies the time (or times) of day during which the user may dial in. If this attribute is absent, the user may dial in at any time. The value field in RAS_AUTH_ATTRIBUTE for this type is a Pointer. The format of the string pointed to is

SUN|MON|TUE|WED|THU|FRI|SAT<SPACE>hh:mm-hh:mm{<SPACE>hh:mm-hh:mm}

The unit of time is 1 hour

An array of RAS_AUTH_ATTRIBUTE structures may contains multiple instances of raatTimeOfDay. If so, the user may dial in during any of the time listed in any of the structures.

raatBAPRequired
If this attribute is present, BAP is required for incoming multilink calls. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value
raatBAPLineDownTime
Specifies a time period in seconds. If a multilink connecton's capacity falls below that specified by raatBAPLineDownLimit for a length of time longer than the value of this attribute, one of the links in the multilink connection will be dropped. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value
raatBAPLineDownLimit
Specifies the percent capacity, below which, one of the links in a multilink connection may be dropped. See the raatBAPLineDownTime attribute for more information. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value
raatAllowedPortType
If this attribute is present, it encodes the port types that a user can use for dialing in. If this attribute is absent, the user can dial in on any type of port. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32 bit integral value. The value is a bitstring that represents the port types allowed.
raatReserved
The value field in RAS_AUTH_ATTRIBUTE for this type is undefined.

QuickInfo

Windows NT: Use version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in rasauth.h.

See Also

RAS_AUTH_ATTRIBUTE


About Tracing

The following documentation describes the implementation of the common tracing DLL, which provides a uniform mechanism for generating diagnostic output for the Microsoft® Windows NT® Routing and RAS components as well as any other application that wishes to use the DLL. The DLL provides dynamic configuration change, allowing a user to direct output to a console or to a specified file. In the case of files, the user can specify the maximum size for the file.


Using Tracing

Each application or service component calls TraceRegister() to obtain an identifier (ID) to use in calls to the output functions. On this call, the DLL reads configuration information for the caller from the registry, and sets up the console or file to which output will be sent. In addition, a critical section is created that will be used to synchronize calls to the tracing DLL functions by the registering component's threads. An event is associated with the registry key for the caller, so that changes to the tracing parameters for the caller can be handled dynamically.

After registering, the application may call the output functions, passing the ID returned by TraceRegister(). When the application no longer requires the tracing DLL's support, it should call TraceDeregister() so that handles associated with it can be closed.

There are two versions of each output function. One version prefixes the output it generates with standard information such as the name associated with the caller, the thread ID of the caller, and the current time. The other version allows the caller to omit the standard information normally generated. For instance, TracePrintf() includes standard information, but TracePrintfEx() does not, unless the flag passed to it specifies that it should.

Support for Unicode clients is built into the tracing DLL. All that is required is that the client define the constant UNICODE before including the header containing definitions for the tracing DLL functions.


Configuration

When a client "xyz" calls TraceRegister(), the tracing DLL looks under the registry key

\SYSTEM\CURRENTCONTROLSET\SERVICES\TRACING\XYZ

for the following values:

  • EnableConsoleTracing: this is a REG_DWORD that defaults to 1; this enables tracing to the console if non-zero.
  • EnableFileTracing: this is a REG_DWORD that defaults to 1; this enables tracing to a file named XYZ.LOG if non-zero.
  • ConsoleTracingMask: this is a REG_DWORD that defaults to 0xFFFF0000; the bits in the high-order word correspond to components in the client. If a call to one of the extended output functions has the flag TRACE_USE_MASK set, this registry value is compared against the high-order word of the flag passed to the output function, to decide whether or not to send the output to the console.
  • FileTracingMask: this is a REG_DWORD that defaults to 0xFFFF0000; it operates similarly to ConsoleTracingMask.
  • MaxFileSize: this is a REG_DWORD that defaults to 0x10000; this is the maximum size a tracing file can grow to before it is renamed.
  • FileDirectory: this is a REG_EXPAND_SZ that defaults to %WINDIR%\TRACING; this is the directory in which the tracing file is created.

The defaults are used only if the key is found (or can be created) but some values are absent from the key. If the registry key is not found and cannot be created, the call to TraceRegister() fails.

Alternatively, a client "xyz" could call TraceRegisterEx(), which takes a flag allowing the caller to specify the settings to use. Thus, a client could use the tracing DLL without creating any key in the registry. For instance,

TraceRegisterEx("xyz", TRACE_USE_CONSOLE);

would register the client "xyz" to use the console for tracing, and the tracing DLL would not attempt to read the registry at all. Similarly,

TraceRegisterEx("abc", TRACE_USE_FILE);

would register the client "abc" to use a file for tracing, bypassing the registry.


Console manipulation

The tracing DLL creates a thread that runs in the background, detecting changes to the configuration of clients that use the registry, as well as handling the following key-presses in the console:

Key pressed | Action taken
Control-Tab | displays the screen for the next console client
Control-Shift-Tab | displays the screen for the previous console client
Pause | toggles tracing for the displayed console client
Space-bar | toggles tracing for the displayed console client
Up-arrow | moves screen up by one line
Down-arrow | moves screen down by one line
Left-arrow | moves screen left by one column
Right-arrow | moves screen right by one column
Page-up | moves screen up by one page
Page-down | moves screen down by one page


Tracing Reference

Use the following functions to add tracing functionality to your software.


TraceRegister

Use the TraceRegister function to register services or applications with the tracing DLL. Its successful return value is an identifier that provides a handle to subsequent tracing functions available in Windows NT Routing and Remote Access Service. This function, or its extended functionality counterpart TraceRegisterEx, must be called before any other tracing functions are called. TraceDeregister or TraceDeregisterEx should be called when trace functions are no longer needed, in order to free resources.

DWORD TraceRegister(
  IN LPCTSTR lpszCallerName  //caller name
);

Parameters

lpszCallerName
Pointer to a null-terminated string containing the service or application name being registered. This is the name with which the service tracing functions will identify the caller.

Return Values

If successful, this function will return a DWORD to be used as the service or application's identifier (handle) for subsequent calls to tracing functions.

If the function fails, INVALID_TRACEID is returned. This indicates the caller could not be registered. Call GetLastError to retrieve the error code.

Remarks

Upon successful execution of TraceRegister, configuration for the service or application calling TraceRegister will be created and kept in the registry path \System\CurrentControlSet\Services\Tracing\<lpszCallerName> under the HKEY_LOCAL_MACHINE key. Such configuration parameters are kept intact, even if the service or application is deregistered from tracing utilities by calling TraceDeregister. If the registry entries cannot be created, the call to TraceRegister will fail. There are certain values within this key that can be modified to change the behavior of trace output.

EnableConsoleTracing
A REG_DWORD that determines whether tracing to the console is enabled. Console tracing is enabled if the value is non-zero. The default value is 1.
EnableFileTracing
A REG_DWORD that determines whether tracing information should be sent to a file called lpzsCallerName.log. File tracing is enabled if the value is non-zero. The default value is 1.
ConsoleTracingMask
A REG_DWORD that regulates whether output from an extended tracing function call is directed to the console. The bits in the high-order word correspond to components in the client; if a call to an extended output function has the flag TRACE_USE_MASK set, the value of ConsoleTracingMask is compared to the flag sent to the function to determine whether to send output to the console. The default value is 0xFFFF0000.
FileTracingMask
A REG_DWORD that works in a similar way to ConsoleTracingMask, regulating whether the extended tracing function calls direct their output to File Tracing. The default value is 0xFFFF0000.
MaxFileSize
A REG_DWORD that defines the maximum size a tracing file can become before it is renamed. The default value is 0x10000.
FileDirectory
A REG_EXPAND_SZ that controls the directory in which the tracing file is created. The default is %windir%\tracing.

QuickInfo

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

See Also

TraceRegisterEx, TraceDeregister, TracePrintf, TraceVprintf, TracePuts, TraceDump, GetLastError


TraceDeregister

The TraceDeregister function frees resources and closes files associated with tracing registration on behalf the calling service or application. Call TraceDeregister no more than once for a service or application, regardless of how many calls were made on the service or application's behalf.

DWORD TraceDeregister(
  IN DWORD dwTraceID  //handle from initial TraceRegister call
);

Parameters

dwTraceID
The handle returned by the calling service or application's initial TraceRegister call.

Return Values

If the function succeeds, the return value is 0.

If the function fails, the return value is an error code. Call GetLastError for further information.

QuickInfo

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

See Also

TraceDeregisterEx, TraceRegister, TracePrintf, TraceVprintf, TracePuts, TraceDump, GetLastError


TracePrintf

The TracePrintf function outputs tracing information, including the following: calling service or application's name, the current time, and tracing information in the format specified by the optional argument or arguments included in lpszFormat. See the note below for an example of TracePrintf results.

DWORD TracePrintf(
  IN DWORD dwTraceID,     // handle from initial TraceRegister call
  IN LPCTSTR lpszFormat,  // printf()-style formatting information
  IN ...OPTIONAL          // one or more optional arguments
);

Parameters

dwTraceID
The handle returned by the calling service or application's initial TraceRegister call.
lpszFormat
Pointer to a null-terminated string containing printf-style format control information.
...
One or more optional arguments, depending on the format control specified in lpszFormat.

Return Values

Successful execution of TracePrintf returns the number of characters output, excluding the terminating null-character.

Failure returns zero. The error code can be retrieved by calling GetLastError.

Remarks

The following is an example for the output from TracePrintf. In the following example, the service or application calling TracePrintf is IPRIP, and its associated Thread identifier for use with the RRAS tracing functionality is129:

[IPRIP:129] 21:01:20: new entry: dest=0.0.0.0, nexthop=157.55.80.1, metric=1, protocol=2
[IPRIP:129] 21:01:20: received RIP v1 response from 157.55.84.244 on address 157.55.94.40

To suppress the prefixes, use TracePrintfEx.

QuickInfo

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

See Also

TracePrintfEx, TraceRegister, TraceDeregister, TraceVprintf, TracePuts, TraceDump, GetLastError


TraceVprintf

Functionality of TraceVprintf is very similar to that of TracePrintf, except that it takes a prepared variable argument list as its third variable. See TracePrintf for more information.

DWORD TraceVprintf(
  IN DWORD dwTraceID,     //handle from initial TraceRegister call
  IN LPCTSTR lpszFormat,  //printf-style formatting information
  IN va_list arglist      //prepared list of variable arguments
);

Parameters

dwTraceID
The handle returned by the calling service or application's initial TraceRegister call.
lpszFormat
Pointer to a null-terminated string containing printf-style format control information.
arglist
A prepared list of printf()-style arguments that define the format of TraceVprintf output.

Return Values

Successful execution of TraceVprintf returns the number of characters output, excluding the terminating null-character.

Failure returns a zero. The error code can be retrieved by calling GetLastError.

QuickInfo

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

See Also

TraceVprintfEx, TraceRegister, TraceDeregister, TracePrintf, TracePuts, TraceDump, GetLastError


TracePuts

The TracePuts function is an efficient way to retrieve information associated with a registered service or application's identifier (dwTraceID). TracePuts also outputs the string literal passed as the function's second argument.

DWORD TracePuts(
  IN DWORD dwTraceID,
  IN LPCTSTR lpszString
);

Parameters

dwTraceID
The handle returned by the calling service or application's initial TraceRegister call.
lpszString
The string to be output.

Return Value

Successful execution of TracePuts returns the number of characters output, excluding the terminating null-character.

Failure of the TracePuts call returns zero. Call GetLastError to get the error code.

TracePuts outputs the name associated with dwTraceID, the internal thread identifier used to identify the caller, the current time, and the literal string specified by lpszString. Since TracePuts performs no formatting on its arguments, it is more efficient than TracePrintf or TraceVprintf. To suppress the prefixes and prevent output from starting on a new line, see TracePutsEx.

QuickInfo

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

See Also

TracePutsEx, TraceRegister, TraceDeregister, TracePrintf, TraceVprintf, TraceDump, GetLastError


TraceDump

The TraceDump function outputs a hexadecimal dump of size dwByteCount, prefixed with the name associated with the calling service or application's dwTraceID, the associated Thread identifier used with the RRAS tracing functionality, the current system time, and a brief description of the dump.

DWORD TraceDump(
  IN DWORD dwTraceID,     //handle from initial TraceRegister call
  IN LPBYTE lpbBytes,     //pointer to dump buffer
  IN DWORD dwByteCount,   //number of bytes to dump
  IN DWORD dwGroupSize,   //size of byte grouping (1,2 or4)
  IN BOOL bAddressPrefix,  //include memory address toggle
  IN LPCTSTR lpszPrefix   //prefix
);

Parameters

dwTraceID
The handle returned by the calling service or application's initial TraceRegister call.
lpbBytes
A pointer to the buffer from which the hex dump is to be generated
dwByteCount
The number of bytes to dump from the buffer.
dwGroupSize
The output's byte grouping size. Valid values are 1, 2, or 4.
bAddressPrefix
Boolean value that determines whether each line of the hex dump has its memory address as a prefix. A value of TRUE includes the memory address.
lpszPrefix
Pointer to the prefix.

Return Values

Successful execution of TraceDump returns the number of characters output.

Otherwise, TraceDump returns zero. Call GetLastError to get the error code.

Remarks

TraceDump generates debug style dumps, with the byte-ordering dependent on the processor's endian setting. Also note that the last line of the dump is padded with zeroes.

QuickInfo

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

See Also

TraceDumpEx, TraceRegister, TraceDeregister, TracePrintf, TraceVprintf, TracePuts, GetLastError


TraceRegisterEx

The TraceRegisterEx function registers services or applications with the tracing DLL. TraceRegisterEx differentiates itself from TraceRegister by providing extended flexibility (Ex) with regard to the creation or reading of registry keys.

Successful execution of TraceRegisterEx returns an identifier used as a handle to subsequent tracing functions available in Microsoft® Windows NT® Routing and Remote Access Service. This function, or its counterpart TraceRegister, must be called before any other tracing functions are called. If no flags are passed to TraceRegisterEx (if dwFlags is zero), TraceRegisterEx behaves exactly as TraceRegister. TraceDeregister or TraceDeregisterEx should be called when trace functions are no longer needed, in order to free resources.

DWORD TraceRegisterEx(
  IN LPCTSTR lpszCallerName,
  IN DWORD dwFlags OPTIONAL
);

Parameters

lpszCallerName
A pointer to a null-terminated string containing the service or application name being registered. This is the name with which the service tracing functions will identify the caller.
dwFlags
Flags that control the nature of the calling service or application's registration. Ensure dwFlags is one or more of the following:
TRACE_USE_CONSOLE
Tracing output is sent to the console; using this parameter avoids loading or writing settings from the registry.
TRACE_USE_FILE
Tracing output is sent to a file; using this parameter avoids reading or writing settings from the registry.

Return Values

Success will return a DWORD to be used as the service or application identifier (handle) for subsequent calls to tracing functions.

INVALID_TRACEID
The caller could not be registered. Call GetLastError to retrieve the error code.

Remarks

Upon successful execution of TraceRegisterEx, configuration for the service or application calling TraceRegisterEx will be taken from the parameters passed as dwFlags, and registry reads or writes will not occur. If the value of dwFlags is zero, then a call to TraceRegisterEx will behave exactly as a call to TraceRegister, and initialization and configuration parameters will be created and kept in the registry path \System\CurrentControlSet\Services\Tracing\<lpszCallerName> under the HKEY_LOCAL_MACHINE key.

Make multiple calls to TraceRegisterEx to modify the output settings. This is achieved by changing the parameters passed in dwFlags. When making additional TraceRegisterEx calls to modify dwFlags settings, ensure dwFlags is always non-zero.

QuickInfo

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

See Also

TraceRegister, TraceDeregisterEx, TracePrintfEx, TraceVprintfEx, TracePutsEx, TraceDumpEx, GetLastError


TracePrintfEx

The TracePrintfEx function outputs tracing information. TracePrintfEx differentiates itself from TracePrintf by offering extended options (Ex) implemented through non-zero dwFlags values. Output generated by TracePrintfEx includes up to the following: calling service or application's name, the current time, and tracing information in the format specified by the optional included in lpszFormat.

If dwFlags is zero, TracePrintfEx behaves exactly as TracePrintf.

DWORD TracePrintfEx(
  IN DWORD dwTraceID,
  IN DWORD dwFlags OPTIONAL,
  IN LPCTSTR lpszFormat,
  IN ... OPTIONAL
);

Parameters

dwTraceID
The handle returned by the calling service or application's initial TraceRegister call.
dwFlags
Flags that control appearance of TracePrintfEx output. Ensure dwFlags is one or more of the following:
TRACE_NO_STDINFO
Suppresses output of the standard information associated with dwTraceID.
TRACE_USE_MASK
Determines whether file and/or console output will be generated by comparing the high-order word of dwFlags against registry values FileTracingMask and ConsoleTracingMask.
lpszFormat
Pointer to a null-terminated string containing printf-style format control information.
...
One or more optional arguments, depending on the format control specified in lpszFormat.

Return Values

Successful execution of TracePrintfEx returns the number of characters output, excluding the terminating null-character.

Failure returns a zero. The error code can be retrieved by calling GetLastError.

QuickInfo

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

See Also

TracePrintf, TraceRegisterEx, TraceDeregisterEx, TraceVprintfEx, TracePutsEx, TraceDumpEx, GetLastError


TraceVprintfEx

Functionality of TraceVprintfEx is very similar to that of TracePrintfEx, except that it takes a prepared variable argument list as its third variable. TraceVprintfEx differentiates itself from TraceVprintf in its ability to customize output through the use of non-zero flags. See TracePrintfEx for more information.

DWORD TraceVprintfEx(
  IN DWORD dwTraceID,
  IN DWORD dwFlags OPTIONAL,
  IN LPCTSTR lpszFormat,
  IN va_list arglist
);

Parameters

dwTraceID
The handle returned by the calling service or application's initial TraceRegister call.
dwFlags
Flags that control appearance of TraceVprintfEx output. Ensure dwFlags is one or more of the following:
TRACE_NO_STDINFO
Suppresses output of the standard information associated with dwTraceID.
TRACE_USE_MASK
Determines whether file and/or console output will be generated by comparing the high-order word of dwFlags against registry values FileTracingMask and ConsoleTracingMask.
lpszFormat
Pointer to a null-terminated string containing printf-style format control information.
arglist
A prepared list of printf()-style arguments that define the format of TraceVprintf output.

Return Values

Successful execution of TraceVprintfEx returns the number of characters output, excluding the terminating null-character.

Failure returns a zero. The error code can be retrieved by calling GetLastError.

QuickInfo

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

See Also

TraceVprintf, TraceRegisterEx, TraceDeregisterEx, TracePrintfEx, TracePutsEx, TraceDumpEx, GetLastError


TracePutsEx

The TracePutsEx function is an efficient way to retrieve information associated with a registered service or application's identifier (dwTraceID). TracePutsEx differs from TracePuts in its extended (Ex) flexibility with regard to output, achieved through the use of non-zero flags implemented with dwFlags. TracePutsEx also outputs the string literal passed as the function's second argument.

DWORD TracePutsEx(
  IN DWORD dwTraceID,
  IN DWORD dwFlags OPTIONAL,
  IN LPCTSTR lpszString
);

Parameters

dwTraceID
The handle returned by the calling service or application's initial TraceRegister call.
dwFlags
Flags that control appearance of TracePutsEx output. Ensure dwFlags is one or more of the following:
TRACE_NO_STDINFO
Suppresses output of the standard information associated with dwTraceID.
TRACE_USE_MASK
Determines whether file and/or console output will be generated by comparing the high-order word of dwFlags against registry values FileTracingMask and ConsoleTracingMask.
lpszString
The string to be output.

Return Values

Successful execution of TracePuts returns the number of characters output, excluding the terminating null-character.

Otherwise, TracePuts returns zero. Call GetLastError to get the error code.

QuickInfo

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

See Also

TracePuts, TraceRegisterEx, TraceDeregisterEx, TracePrintfEx, TraceVprintfEx, TraceDumpEx, GetLastError


TraceDumpEx

The TraceDumpEx function outputs a hexadecimal dump of size dwByteCount. TraceDumpEx differentiates itself from TraceDump in its extended (Ex) output options, implemented through the use of non-zero dwFlags values. Output from TraceDumpEx can include information with a prefix of the name associated with the calling service or application's dwTraceID, the associated Thread identifier used with the RRAS tracing functionality, the current system time, and a brief description of the dump.

DWORD TraceDumpEx(
  IN DWORD dwTraceID,
  IN DWORD dwFlags OPTIONAL,
  IN LPBYTE lpbBytes,
  IN DWORD dwByteCount,
  IN DWORD dwGroupSize,
  IN BOOL bAddressPrefix,
  IN LPCTSTR lpszPrefix
);

Parameters

dwTraceID
The handle returned by the calling service or application's initial TraceRegister call.
dwFlags
Flags that control appearance of TraceDumpEx output. Ensure dwFlags is one or more of the following:
TRACE_NO_STDINFO
Suppresses output of the standard information associated with dwTraceID.
TRACE_USE_MASK
Determines whether file and/or console output will be generated by comparing the high-order word of dwFlags against registry values FileTracingMask and ConsoleTracingMask.
lpbBytes
A pointer to the buffer from which the hex dump is to be generated.
dwByteCount
The number of bytes to dump from the buffer.
dwGroupSize
The output's byte grouping size. Valid values are 1, 2, or 4.
bAddressPrefix
Boolean value that determines whether each line of the hex dump is prefixed with its memory address. A value of TRUE includes the memory address.
lpszPrefix
Pointer to the prefix.

Return Values

Successful execution of TraceDump returns the number of characters output.

Otherwise, TraceDump returns zero. Call GetLastError to get the error code.

Remarks

TraceDumpEx generates debug style dumps, with the byte-ordering dependent on the processor's endian setting. Also note that the last line of the dump is padded with zeroes.

QuickInfo

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

See Also

TraceDump, TraceRegisterEx, TraceDeregisterEx, TracePrintfEx, TraceVprintfEx, TracePutsEx, GetLastError


Transport Identifiers

The following transport Ids are also listed in mprapi.h.

PID_IPX

PID_IP

PID_NBF


Protocol Identifiers

The following protocol Ids are also listed in routprot.h.

IP Protocols

IP_OTHER

IP_LOCAL

IP_NETMGMT

IP_ICMP

IP_EGP

IP_GGP

IP_HELLO

IP_RIP

IP_IS_IS

IP_ES_IS

IP_CISCO

IP_BBN

IP_OSPF

IP_BGP

IP_BOOTP

IP_NT_AUTOSTATIC

In addition, the ID for the IP router manager is:

IPRTRMGR_PID

This ID can be used instead of a routing protocol ID for MIB calls with the IP Router Manager. This ID is used for MIB-II, Forwarding MIB, and some enterprise specific information. This ID is also listed in iprtrmib.h.

IPX Protocols

IPX_PROTOCOL_RIP

IPX_PROTOCOL_SAP

IPX_PROTOCOL_NLSP

In addition, the ID for the IPX router manager is:

IPX_PROTOCOL_BASE

Use this ID instead of a routing protocol ID for MIB calls with the IPX Router Manager.


Remote Access Privileges

The following remote access privilege constants are defined in mprapi.h.

RASPRIV_NoCallback

RASPRIV_AdminSetCallback

RASPRIV_CallerSetCallback

RASPRIV_DialinPrivilege

Use the following constant as a mask to isolate the call back privilege. (This constant is also defined in mprapi.h.)

RASPRIV_CallbackType


Routing Table Manager Protocol Family Identifiers

The following transport Ids are listed in rtm.h. Use these Ids with the Routing Table Manager (RTM) API.

RTM_PROTOCOL_FAMILY_IPX

RTM_PROTOCOL_FAMILY_IP


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

Remedy: Insert the MSDN Library CD into the CD-ROM drive.