Remote Access Service

Purpose

The Remote Access Service (RAS) API is included in Microsoft® Windows NT® version 4.0. Use RAS to create client applications. These applications display RAS common dialog boxes, manage remote access connections and devices, and manipulate phone-book entries.

Where Applicable

The Remote Access Service is applicable in any computing environment that uses Wide Area Network (WAN) link or a Virtual Private Network (VPN). RAS makes it possible to connect a remote client computer to a network server over a WAN link or a VPN. The remote computer then functions on the server's LAN as though the remote computer was connected to the LAN directly. The RAS API enables programmers to access the features of RAS programmatically.

Developer Audience

The RAS API is designed for use by C/C++ programmers. Microsoft® Visual Basic® programmers may also find the API useful. Programmers should be familiar with networking concepts.

Run-Time Requirements

Some of the functions in the RAS API are used only on network servers, such as Windows NT Server 4.0 and Microsoft® Windows® 2000 Server. Other functions are used only on network clients such as Windows 95, Windows 98, Windows NT Workstation 4.0, and Windows 2000 Professional. The documentation devotes separate sections to the server and client functions. For more specific information about which operating systems support a particular function, refer to the Requirements sections (formerly "QuickInfo") in the documentation.

See Also

Routing and Remote Access Service

Overview

General information about Remote Access Service.

Reference

Documentation for Remote Access Service functions, structures, and other code elements.

Feedback

Make error reports and feature requests directly to Microsoft.

Microsoft Platform SDK, February 2001 Edition.
This content last built on Thursday, February 15, 2001.


About Remote Access Service

Remote Access Service (RAS) provides remote access capabilities to client applications on computers using Microsoft® Windows® 95 or later and Windows NT® version 3.5 and later, including Windows 2000, operating systems. RAS applications can perform the following tasks:

  • Display any of the RAS common dialog boxes. This includes the main Dial-Up Networking dialog box, the Dial-Up Networking Monitor property sheet, and other dialog boxes for creating, editing, copying, or dialing a phone-book entry.
  • Start and end a RAS connection operation using the common dialog boxes or the low-level dialing functions.
  • Create, edit, or copy phone-book entries using the common dialog boxes or the low-level phone-book functions.
  • Work with entries in the RAS AutoDial mapping database. This database maps network addresses to the phone-book entry that can establish a connection to the address.
  • Get RAS information, including information about existing RAS connections, information about the RAS-capable devices configured on the local computer, and notifications when a RAS connection begins or ends.

Windows NT 4.0 also provides support for RAS server administration and for third-party extensions to RAS server security and connection management. Windows 95 does not provide RAS server support.

This section describes the following topics:

  • RAS Common Dialog Boxes
  • RAS Connection Operations
  • RAS Phone Books
  • RAS AutoDial
  • RAS Configuration and Connection Information
  • RAS Server Administration
  • RAS Security Host Support
  • RAS Custom Scripting


RAS Common Dialog Boxes

Windows NT 4.0 provides a set of functions that display the RAS dialog boxes provided by the system. These functions make it easy for applications to display a familiar user interface so that users can perform RAS tasks. For example, users can establish and monitor connections, or work with phone-book entries. Windows 95 does not currently support these functions.

The RasPhonebookDlg function displays the main Dial-Up Networking dialog box. From this dialog box, the user can dial, edit, or delete a selected phone-book entry, create a new phone-book entry, or specify user preferences. The RasPhonebookDlg function uses the RASPBDLG structure to specify additional input and output parameters. For example, you can set members of the structure to control the position of the dialog box on the screen. You can use the RASPBDLG structure to specify a RasPBDlgFunc callback function that receives notifications of user activity while the dialog box is open. For example, RAS calls your RasPBDlgFunc function if the user dials, edits, creates, or deletes a phone-book entry.

You can use the RasDialDlg function to start a RAS connection operation without displaying the main Dial-Up Networking dialog box. With RasDialDlg, you specify a phone number or phone-book entry to call. The function displays a stream of dialog boxes that indicate the state of the connection operation. The RasDialDlg function uses a RASDIALDLG structure to specify additional input and output parameters, such as position of the dialog box and the phone-book subentry to call.

To display the Dial-Up Networking Monitor property sheet, call the RasMonitorDlg function. This dialog box enables the user to monitor the status of existing connections. The RasMonitorDlg function uses a RASMONITORDLG structure to specify additional input and output parameters, such as the position of the dialog box and the property sheet page to display on top.

You can call the RasEntryDlg function to display a property sheet for creating, editing, or copying a phone-book entry. The RasEntryDlg function uses a RASENTRYDLG structure to specify additional input and output parameters, such as the position of the dialog box and the type of phone-book operation.


RAS Connection Operations

Windows NT 4.0 and later versions provide the RasPhonebookDlg and RasDialDlg functions that display the built-in user interface for starting a RAS connection operation. For most applications, this is the preferred way to start a RAS connection operation. Windows 95 does not currently support these functions.

The remainder of this section describes the low-level functions for starting a RAS connection. These functions are available on both Windows NT 4.0 (and later versions), and Windows 95.

A RAS client application uses the RasDial function to establish a connection to a RAS server. The RasDial function starts the connection operation, which is then carried out by the Remote Access Connection Manager.

The Remote Access Connection Manager is a service that handles the details of establishing the connection to the remote server. This service also provides the client with status information during the connection operation. The Remote Access Connection Manager starts automatically when an application loads the RASAPI32.DLL.

The RasDial call specifies the following information when it starts a connection operation:

  • The connection information that the Remote Access Connection Manager needs to establish the connection.
  • An optional notification handler that receives progress notifications during the connection operation. If the RasDial call specifies a notification handler, the call is asynchronous; otherwise, it is synchronous.
  • An optional RASDIALEXTENSIONS structure to enable or disable extensions to the RasDial operation. The extensions permit a RAS client to directly enable some modem settings, to control whether RAS uses the prefixes and suffixes in a phone-book entry, and to support paused states during the connection operation.


Synchronous Operations

When RasDial is invoked as a synchronous operation, the function does not return until the connection has been established or an error occurs. Synchronous mode provides a simple way for a RAS client to establish a connection. The client can simply call RasDial, wait for the function to return, and then call the RasGetConnectStatus function to determine whether the connection operation was successful. Once the connection has been established, the client application can terminate without breaking the connection. If an error occurs, the client application must shut down the connection operation before terminating.

The disadvantage of synchronous mode is that the client does not receive progress notifications as the connection operation proceeds. As a workaround for this lack of progress notifications, a synchronous mode client can use a separate thread that calls RasGetConnectStatus to poll for and display the current state. However, for RAS clients that want to receive progress information, the preferred technique is to invoke RasDial asynchronously.


Asynchronous Operations

When RasDial is invoked as an asynchronous operation, the function returns immediately. In asynchronous mode, the RasDial call must specify a notification handler that the Remote Access Connection Manager uses to inform the client whenever the connection operation changes states or an error occurs.

The notification handler can be a window to receive messages, or a RasDialFunc, RasDialFunc1, or RasDialFunc2 callback function. The Remote Access Connection Manager makes its asynchronous notifications in the context of the thread that made the RasDial call. For this reason, the calling thread must not terminate until the connection operation has been successfully established or an error occurs. As in synchronous mode, the client application can safely terminate once the connection has been established, and it must shut down the connection operation if an error occurs.


Phone-Book Files and Connection Information

A RasDial call must specify the information that the Remote Access Connection Manager needs to establish the connection. Typically, the RasDial call provides the connection information by specifying a phone-book entry. The connection information in a phone-book entry includes phone numbers, bps rates, user authentication information, and other connection information.

A RAS client uses the parameters of the RasDial function to specify a phone-book file and an entry in that file. The lpszPhonebookPath parameter can specify the name of a phone-book file, or it can be NULL to indicate that the default phone-book file should be used. The lpRasDialParams parameter points to a RASDIALPARAMS structure that specifies the name of the phone-book entry to use.

To display a list of phone-book entries from which the user can select a connection, a RAS client can call the RasEnumEntries function to enumerate the entries in a phone-book file.

To make a connection without using a phone-book entry, the RasDial call can specify an empty string for the szEntryName member of the RASDIALPARAMS structure. The RASDIALPARAMS.szPhoneNumber member must contain the number to call. In this case, the Remote Access Connection Manager uses the first available modem port and default values for all other settings.


User Authentication Information

The Remote Access Connection Manager service on the client computer sends a user name and password to the RAS server on the remote computer. Before it will establish a connection, the remote server uses this information to authenticate the user. By default, the Remote Access Connection Manager sends the user name and password of the currently logged-on user. The RAS client can use the RASDIALPARAMS structure specified in the RasDial call to specify a different user name and password.

If the remote server cannot authenticate the user with the specified information, it can allow the connection operation to enter a paused state to enable the RAS client to collect different authentication data from the user.


Other Connection Information

The members of the RASDIALPARAMS structure can also specify the following connection information:

  • A phone number to override the number in the phone-book entry.
  • A callback phone number that the remote server can call back to establish the connection.
  • The name of the remote network domain on which the authentication is to occur.

For the callback number and the domain, the RASDIALPARAMS members can either indicate that RAS should use the information in the phone-book entry, or it can provide information that overrides the phone-book data.

A RAS client can use the lpRasDialExtensions parameter of the RasDial function to control whether RAS uses a phone number prefix or suffix specified in a phone-book entry.


Connection States

During the process of connecting to a remote server, the Remote Access Connection Manager and the RAS server on the remote computer perform several steps to establish the connection. Each of these steps is identified by a connection state. The RASCONNSTATE enumeration is a set of values that correspond to these connection states. The connection states can be divided into the following three groups:

Running states
The running states are the parts of the connection operation that RAS handles automatically, such as connecting to the necessary devices, authenticating the user, and waiting for a callback from the remote server. Unless an error occurs, the RAS client need take no action other than to pass the notification on to the user.
Paused states
The paused states occur when the remote server pauses the connection operation to get additional input from the user. During a paused state, the user can type a callback number, a different user name and password if the user authentication fails, or a new password if the old one has expired.
Terminal states
The terminal states occur when the connection has been successfully established, the connection operation has failed, or the connection has been broken by a RasHangUp call.

There are several mechanisms that a RAS client can use to determine the current state of a connection operation. When a RAS client executes the RasDial function asynchronously, the Remote Access Connection Manager sends progress notifications to the client's notification handler whenever the connection state changes. In addition, the client can use the RasGetConnectStatus function to get the current state of any RAS connection operation.


Notification Handlers

An asynchronous RasDial call must specify a notification handler. During an asynchronous connection operation, the Remote Access Connection Manager uses the notification handler to inform the RAS client whenever the connection state changes or an error occurs.

The actions performed by a notification handler can be divided into the following categories:

  • Handling errors.
  • Providing feedback to the user as the connection operation proceeds through the various connection states. See Informational Notifications.
  • Handling paused states.
  • Signaling the RAS client application when the connection operation has been completed. See Completion Notifications.

There are three types of notification handlers, each of which receives the same basic information: the current connection state and an error code that is nonzero only if an error has occurred.

Value | Definition
RasDialFunc | A callback function prototype that receives only the current connection state and error code information.
RasDialFunc1 | A callback function prototype that receives the HRASCONN connection handle and extended error information in addition to the basic information. The connection handle parameter makes RasDialFunc1 useful for client applications that support multiple simultaneous connection operations. This allows the client to specify the same callback function for all operations, and enables the callback function to determine which connection is changing states.
RasDialFunc2 | A callback function similar to RasDialFunc1. However, RasDialFunc2 is enhanced to support multilink connections.
Window handle | A window handle to which RAS sends WM_RASDIALEVENT messages containing the current connection state and error code information. Use this method if your source code must be compatible with 16-bit Windows, because 16-bit Windows does not support either of the callback functions.

The Remote Access Connection Manager suspends the connection operation until the notification handler returns. For this reason, the handler should return as soon as possible unless an error has occurred.

The RasDial function should not be called from within a notification handler. The other remote access functions (RasGetConnectStatus, RasEnumEntries, RasEnumConnections, RasGetErrorString, and RasHangUp) can be called from within a handler.


Handling RAS Errors

When an error occurs, the Remote Access Connection Manager invokes the client's notification handler. The notification indicates the connection state when the error occurred, and a code that identifies the error. In these cases, the notification handler should call RasHangUp to end the RAS connection.

The RAS client can use the RasGetErrorString function to get a display string describing the error.


Informational Notifications

For the connection states known as running states, no action is required of the notification handler unless an error occurs. Running states occur during the parts of the connection operation that RAS handles automatically, such as connecting to the necessary devices, authenticating the user, and waiting for a callback from the remote server. The notification is simply a progress report to the client.

The client can choose to pass these informational notifications on to the user. In some running states, the client may want to display additional information. For example, a notification handler that receives a RASCS_ConnectDevice notification can call the RasGetConnectStatus function to get the name and type of the device being connected to. Another example is when the client receives a RASCS_Projected notification. This occurs when the RAS projection phase of the connection operation has been completed. The client can call the RasGetProjectionInfo function to get additional information about the projection. The client can use this information to notify the user as to which network protocols can be used by this connection.

You should avoid writing code that depends on the order or occurrence of particular informational states, because this may vary between platforms.


Completion Notifications

The Remote Access Connection Manager continues progress notifications until the connection operation has been completed. This occurs in the following situations:

  • The handler receives a RASCS_Connected, or RASCS_Disconnected notification. The RAS client application can exit without breaking any established connection.
  • An error occurs. The handler receives a notification indicating the error and the connection state when the error occurred. The RAS client application can exit.

The RAS client application should not assume the connection operation is complete after calling RasHangUp. It should wait for one of the preceding conditions before exiting.


Paused States

During a connection operation, there can be times when the remote server cannot proceed without additional information from the local user. Beginning with Microsoft® Windows NT® version 3.5, the RasDial function supports paused states. A paused state allows the Remote Access Connection Manager to suspend a connection operation so the RAS client application can collect information from the user.

Paused states are useful in the following situations:

  • When the user needs to provide a callback number.
  • When the user authentication fails, the user can type in a different user name and password.
  • When the user's password has expired, the user can provide a new password.

By default, paused state support is disabled. RAS clients that want to support paused states must set the RDEOPTS_PausedStates flag in the RASDIALEXTENSIONS structure passed as a parameter to RasDial.

When a paused state occurs, the Remote Access Connection Manager invokes the client's notification handler. If paused state support is disabled, the notification message indicates an error, and the connection operation fails. If it is enabled, the Connection Manager pauses the connection operation to wait for the RAS client's response. The RAS client can resume the connection operation by a second RasDial call, or terminate it by calling the RasHangUp function.

After getting the user's input, the RAS client restarts the connection operation by calling RasDial again. This second RasDial call must specify the following information:

  • The connection handle that was returned by the original RasDial call.
  • The same notification handler as the original RasDial call.
  • The user's input in the appropriate members of the RASDIALPARAMS structure. Other members of the RASDIALPARAMS structure should have the same information as specified in the original RasDial call.

The second RasDial call cannot be made from within the notification handler.


Callback Connections

RAS supports connections in which the remote server hangs up and then calls back to the client to establish the connection.

For each user that can connect to a RAS server, the server stores a callback attribute that controls how the connection is made. The default attribute is No Callback, which means that the user can connect to the RAS server without a callback. Alternatively, the administrator of the RAS server can assign to a user either the Preset or Set-By-Caller callback attribute.

For a user assigned the Preset restriction, the administrator specifies a phone number that the RAS server must call back to establish a connection. The user cannot specify a different number, and the connection cannot be made without a callback.

A Preset callback operation is handled automatically by the Remote Access Connection Manager and the remote server. The RAS client application does not need to do anything other than provide feedback to the user when the notification handler is called during the various states of the callback operation.

A user assigned the Set By Caller privilege can choose to connect either with or without a callback. The RasDial call uses the szCallBackNumber member of the RASDIALPARAMS structure to indicate the choice.

The szCallBackNumber member can simply specify the callback number; or, to establish the connection without a callback, szCallBackNumber can point to an empty string, "". In either of these cases, the Remote Access Connection Manager handles the connection operation automatically. As with a Preset callback operation, the RAS client does not need to perform any action other than to provide feedback to the user.

If the RasDial call enables paused states, szCallBackNumber can point to an asterisk string, "*", to indicate that the connection operation should enter a paused state to allow the user to type in the callback number. In this case, the connection operation for a Set By Caller user enters a paused state after the remote server has authenticated the user. During the paused state, the RAS client gets the callback number input from the user. The client then resumes the connection operation by making a second RasDial call in which szCallBackNumber specifies the number supplied by the user.

Note If paused states are not enabled there is a different meaning when szCallBackNumber points to an asterisk string, "*". In this case, the asterisk indicates that the callback number is stored in the phone-book file specified by the RasDial call.

In the event of a callback, the call to RasDial does not return until after the server has called back the client.


Disconnecting

When a RAS client application starts a connection operation, the RasDial call receives an HRASCONN connection handle to identify the connection. If the returned handle is not NULL, the client must eventually call the RasHangUp function to end the connection. If an error occurs during the connection operation, the client must call RasHangUp even though the connection was never established.

The application that calls RasHangUp should not exit immediately, because the Remote Access Connection Manager needs time to properly terminate the connection. Instead, the application should wait until the RasGetConnectStatus function returns ERROR_INVALID_HANDLE, indicating that the connection has been deleted.

A RAS client application might need to end a connection even though it does not have the handle returned by RasDial. For example, the application that called RasDial might have exited once the connection was successfully established. In this case, the disconnecting application can use the RasEnumConnections function to get all the current connections. For each connection, RasEnumConnections returns a RASCONN structure containing the HRASCONN connection handle and the phone-book entry name or phone number specified when the connection operation was started. This information can be used to display a list of connections from which the user can select the connection to end.


Custom Dialers

[This is preliminary documentation and subject to change.]

Windows 2000 allows developers to provide their own custom dialers that work with the Windows 2000 Remote Access Service (RAS). The custom dialer is implemented as a single dynamic-link library (DLL) that exports the following entry points:

  • RasCustomDial
  • RasCustomDialDlg
  • RasCustomHangup
  • RasCustomEntryDlg
  • RasCustomDeleteEntryNotify

The custom-dial DLL must export all of these entry points, and it must implement the entry points as Unicode functions. For more information about these functions, see the reference page for each function in the Windows SDK Remote Access Service Reference.

In order for a RAS connection to use the custom dialer, the phone-book entry for the connection must contain the path to the custom-dial DLL. Use the RAS API functions RasGetEntryProperties and RasSetEntryProperties to set this path in the szCustomDialDLL member of the RASENTRY structure for the phone-book entry.

Using Custom Dialers at System Logon

Windows 2000 allows a user to establish a RAS connection at the time of logon. To do so, the user checks "Logon using Dial-up Networking" in the Logon Information dialog box. After the user clicks the Okay button, the system displays the available connections. In order for the system to dial a connection that uses a custom dialer, the path to the custom-dial DLL must exist in the following registry value.

\\HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Rasman\Parameters REG_MULTI_SZ: CustomDLL

Because this value is of type REG_MULTI_SZ, it can hold paths to multiple custom-dial DLLs. You need to set the path to the custom-dial DLL in this registry value, in addition to the phone-book entry for the connection.

By default, this registry value is writeable only by a user with Administrator or System privileges. For security reasons, do not change the permissions on this registry key.

Security Considerations

In most cases, a custom dialer operates with the security privileges of the user that invokes it. However, if the custom dialer is invoked at logon, it operates with system privileges. Therefore, design the custom dialer so that it cannot be used to violate system security. For example, the dialer should not present a user interface that allows the user write access to the computer's file system. User interfaces that provide such access include the Find-File dialog, the File-Open common dialog, and Windows Help.

Custom Dialer User Interface Must Support IDCANCEL

If the custom dialer displays a user interface, the user interface must support WM_COMMAND messages where LOWORD(wParam) equals IDCANCEL.


RAS Custom Scripting

[This is preliminary documentation and subject to change.]

Developers can create a custom-scripting DLL that resides on a RAS client computer. This DLL can communicate with the server during the process of establishing a connection.

Custom scripting is available only on Windows 2000 and later.

Setting up the DLL

To set up the DLL, create a value with the name CustomScriptDllPath under the following registry key:

\\HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Rasman\Parameters\

This value should be of type REG_EXPAND_SZ. The value should contain the path to the custom-scripting DLL. Only one custom-scripting DLL is supported for each RAS client computer.

Interaction Between the Server, RAS, and the Custom-Scripting DLL

The custom scripting DLL should export a single entry point: RasCustomScriptExecute. RAS calls this function during the RASCS_Interactive state of the connection process. The RASCS_Interactive state is a paused state, which allows the user to interact with a user interface presented by the custom-scripting DLL. See RASCONNSTATE for more information about connection states.

RAS will pass as parameters to the RasCustomScriptExecute function:

  • A handle to the port on the client computer that is being used for the connection.
  • Strings that identify the phone book and entry for the connection.
  • RAS also passes in a handle to a window to enable the DLL to present a user interface.
  • A set of function pointers that the DLL can use to communicate with the server.

See RasCustomScriptExecute for more information about these parameters.

Windows 2000 SP2 and later: RAS passes a pointer to a RASCUSTOMSCRIPTEXTENSIONS structure as the last parameter to RasCustomScriptExecute. This structure contains a pointer to a function of type PFNRASSETCOMMSETTINGS. The custom-scripting DLL calls this function to modify the communication settings on the port being used by the connection.

RAS mediates the interaction between the server and the custom-scripting DLL. Typically, the server initiates the dialog. For example, the server may request the user name and password of the the user.

When using custom-scripting to establish a connection, the server need not be running Windows NT 4.0 Server or Windows 2000.

Custom Scripting User Interface Must Support IDCANCEL

If the custom dialer displays a user interface, the user interface must support WM_COMMAND messages where LOWORD(wParam) equals IDCANCEL.

Configuring the Connection

The RasCustomScriptExecute entry point can be invoked from RasDialDlg or, on Whistler, from RasDial.

To invoke RasCustomScriptExecute from RasDialDlg, set the RASEO_CustomScript option in the phone-book entry for the connection. See the dwfOptions member of RASENTRY for a description of phone-book entry options. Use the RasGetEntryProperties and RasSetEntryProperties functions to set this option programmatically.

Whistler: To invoke RasCustomScriptExecute from RasDial, the call to RasDial must specify a RASDIALEXTENSIONS structure, and this structure must specify the RDEOPT_UseCustomScripting flag. In addition, the phone-book entry for the connection must specify the RASEO_CustomScript option as described in the preceding paragraph.

Invoking the Custom Scripting DLL

If the user activates a connection for a phone-book entry that has RASEO_CustomScript set, RAS invokes the custom-scripting DLL. In this scenario, RAS invokes the custom-scripting DLL from RasDialDlg.

To invoke the custom-scripting DLL programmatically, establish the connection using the RasDialDlg function. On Whistler, the RasDial function also invokes the custom-scripting DLL.


Virtual Private Network Connections

The Remote Access Service (RAS) supports Virtual Private Network (VPN) connections in addition to conventional remote access connections that use Point-to-Point Protocol (PPP).In a VPN connection, the VPN packets are encapsulated in IP packets and sent across an IP network such as the Internet. Therefore, access to an IP network is a requirement in order to establish a VPN connection. If the client computer has an always-on connection to an IP network, for example a connection to an IP LAN, the client can establish the VPN connection using a single call to the RasDial function.

If the client computer does not have an always-on connection to an IP network, two calls to RasDial are required to establish the VPN connection. The first call establishes a dial-up connection to the IP network; the second call establishes the VPN connection.

The szLocalPhoneNumber member of the RASENTRY structure for the VPN connection should contain either the DNS name or IP address of the destination VPN server.

Each connection requires a separate phone-book entry. The first call to RasDial specifies the phone-book entry for the IP network. The second call specifies the phone-book entry for the VPN.

The RasDial function takes a pointer to a RASDIALPARAMS structure as a parameter. This structure specifies the authentication credentials to use for the network specified by the phone-book entry. The credentials required to access the IP network are typically different from those for the VPN. The first call to RasDial should specify credentials for the IP network. The second call should specify credentials for the VPN.

If the RasDial function is successful, it returns a handle for the connection. Use this handle in a call to RasHangUp to terminate the connection.

In the preceding scenario, the two calls to RasDial return separate connection handles for the IP network and the VPN. Calling RasHangUp with the handle for the VPN connection terminates the VPN connection but leaves the connection to the IP network intact.


Point-to-Point Protocol over Ethernet Connections

The Whistler release of Windows provides support for Point-to-Point Protocol over Ethernet (PPPoE). For a PPPoE connection, set the following values in the RASENTRY structure.

Member | Value
RASENTRY.dwType | RASET_Broadband
RAENTRY.szDeviceType | RASDT_PPPoE
RASENTRY.szLocalPhoneNumber | The service name.

Use the RasSetEntryProperties function to set these values.

You can also use RasEntryDlg and the RASEDFLAG_NewBroadbandEntry flag for RASENTRYDLG to display a wizard for creating a PPPoE phonebook entry.


RAS Phone Books

Phone books provide a standard way to collect and specify the information that the Remote Access Connection Manager needs to establish a remote connection. Phone books associate entry names with information such as phone numbers, COM ports, and modem settings. Each phone-book entry contains the information needed to establish a RAS connection.

Windows NT/2000: Phone books are stored in phone-book files, which are text files that contain the entry names and associated information. RAS creates a phone-book file called RASPHONE.PBK. The user can use the main Dial-Up Networking dialog box to create personal phone-book files. The Win32 API does not currently provide support for creating a phone-book file. Some RAS functions, such as the RasDial function, have a parameter that specifies a phone-book file. If the caller does not specify a phone-book file, the function uses the default phone-book file, which is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.

Windows NT 4.0 provides the RasPhonebookDlg and RasEntryDlg functions that display the built-in RAS user interface that enable users to work with phone books and phone-book entries.

Windows 95: Dial-up networking stores phone-book entries in the registry rather than in a phone-book file. Windows 95 does not support personal phone-book files. Windows 95 does not support the functions that display the built-in RAS dialog boxes.


Phone-Book Entries

Phone-book entries contain the information necessary to establish a RAS connection. A user or administrator can use the Dial-Up Networking dialog box to create, edit, and dial phone-book entries.

Windows 95: Windows 95 supports a limited set of the Win32 functions for working with phone-book entries. You can use the RasCreatePhonebookEntry and RasEditPhonebookEntry functions to create or edit a phone-book entry. These functions display a dialog box in which the user can specify information about the phone-book entry. You can use the RasGetEntryDialParams and RasSetEntryDialParams functions to set or retrieve the connection parameters for a phone-book entry. The RasEnumEntries function retrieves an array of RASENTRYNAME structures that contain the phone-book entry names.

Windows NT 4.0 supports the functions described for Windows 95, as well as a number of additional functions that an application can use to work with phone books and phone-book entries.

The RasEntryDlg function displays a property sheet that enables the user to create, edit, or copy phone-book entries. The RasCreatePhonebookEntry and RasEditPhonebookEntry functions call the RasEntryDlg function. You can use the RasRenameEntry function to rename a phone-book entry, or the RasDeleteEntry to delete an entry. The RasValidateEntryName determines whether a specified string has the correct format to be used as an entry name.

You can use the RasGetEntryProperties and RasSetEntryProperties to get and set additional information about a phone-book entry. These functions use a RASENTRY structure.

The RasGetCredentials and RasSetCredentials functions get and set the user credentials associated with a specified RAS phone-book entry. These functions use a RASCREDENTIALS structure.

The RasGetCountryInfo function retrieves country-specific dialing information from the Windows Telephony list of countries. RasGetCountryInfo uses the RASCTRYINFO structure.


Subentries and Multilink Connections

Windows NT 4.0 provides support for phone-book subentries, which enable multilink connections. A multilink connection combines the bandwidth of multiple connections to provide a single connection with higher bandwidth.

A RAS phone-book entry can have zero or more subentries. The RasGetEntryProperties function retrieves a RASENTRY structure that includes information about the subentries of a phone-book entry. The dwSubEntries member of the RASENTRY structure indicates the number of subentries. Phone-book entries initially have no subentries. To add subentries to a phone-book entry, use the RasSetSubEntryProperties function.

The properties for each subentry include a phone number and the name and type of the TAPI device to use when dialing the subentry. In addition, a subentry can include a list of alternate phone numbers to dial if RAS cannot make a connection using the primary number. The RasSetSubEntryProperties and RasGetSubEntryProperties functions use the RASSUBENTRY structure to set and retrieve the properties of a specified phone-book subentry. Subentries are identified by a one-based index.

You can call the RasSetEntryProperties function to configure a multilink RAS entry to connect all subentries when it is first dialed. Alternatively, you can configure an entry to provide variable bandwidth. In this case, RAS connects a single subentry initially, and then connects or disconnects additional subentries as needed. For a variable-bandwidth multilink connection, you can use the RASDIALPARAMS structure to specify the initial subentry to connect when you call the RasDial function. When using the RasDialDlg function to connect a multilink entry, you can use the RASDIALDLG structure to specify the initial subentry to connect.

For a variable-bandwidth multilink connection, use the RASENTRY structure with the RasSetEntryProperties function to specify the parameters for connecting and disconnecting the individual subentries. RAS connects an additional subentry when the bandwidth being used exceeds a specified percentage of the available bandwidth for a specified interval.

If you call the RasDial function to establish a multilink connection, you can specify a RasDialFunc2 callback function to receive notifications about the connection. RasDialFunc2 is similar to the RasDialFunc1 callback function, except that it provides additional information for a multilink connection, such as the index of the subentry that caused the notification. RAS calls your RasDialFunc2 function when it connects or disconnects a subentry.

You can use an HRASCONN connection handle to hang up or retrieve information about a multilink connection. You can get a connection handle for each of the subentry connections that make up the multilink, as well as for the combined multilink connection. When you call the RasDial function to establish a multilink connection, RasDial returns a handle to the combined multilink connection. Similarly, RasEnumConnections returns the combined multilink handle when you enumerate connections. To get a handle to one of the subentry connections in a multilink connection, call the RasGetSubEntryHandle function.

You can use the combined multilink connection handle and the subentry connection handles in the RasHangUp, RasGetConnectStatus, and RasGetProjectionInfo functions. Calling RasHangUp with a combined multilink handle terminates the entire connection; calling it with a subentry handle hangs up only that subentry connection. Similarly, RasGetConnectStatus returns information for the combined or individual connection, depending on the handle specified. The projection information returned by RasGetProjectionInfo for a multilink entry is the same for each of the subentry connection handles as it is for the main connection handle.


RAS AutoDial

Windows NT 4.0 supports a feature known as AutoDial. Windows 95 and Microsoft® Windows NT® version 3.51 and earlier do not support the AutoDial feature.

When an attempt to connect to a network address fails because the host cannot be reached, the AutoDial feature can automatically start a dial-up connection operation. To do this, AutoDial searches its database of network addresses to find a phone-book entry that it can use to establish the connection.


AutoDial Mapping Database

The AutoDial mapping database maps network addresses to RAS phone-book entries. The database can include IP addresses (for example, "255.255.255.0"), Internet host names (for example, "www.microsoft.com"), or NetBIOS names (for example, "products1"). Associated with each address in the AutoDial database is a set of one or more RASAUTODIALENTRY entries. Each of these entries specifies a phone-book entry that RAS can dial to connect to the address from a particular Telephony Application Programming Interface (TAPI) dialing location. For more information about TAPI dialing locations, see the TAPI documentation.

AutoDial automatically creates entries in the AutoDial mapping database in two situations:

  • When an attempt to connect to a network address fails

    If there is no entry for the address in the mapping database, and the computer is not connected to a network, either directly or through RAS, AutoDial prompts the user to specify the information necessary to establish a dial-up connection. If the user provides the information and the dial-up connection operation is successful, AutoDial stores the information in the mapping database.

  • When the computer is connected to a network through RAS

    Whenever the user connects to a network address, AutoDial creates an entry in the database. The entry maps the network address to the phone-book entry that was used to establish the RAS connection.

You can use the RasSetAutodialAddress function to add an address to the AutoDial mapping database, delete an address from the database, or change the AutoDial entries associated with an existing address in the database. You can use the RasGetAutodialAddress function to retrieve the AutoDial entries associated with a specified network address in the AutoDial mapping database. The RasEnumAutodialAddresses function returns a list of all addresses in the AutoDial mapping database.


AutoDial Connection Operations

When an attempt to connect to a network address fails because the host cannot be reached, the system searches the AutoDial mapping database for the address. If the address is in the database, the system initiates an AutoDial operation for the RASAUTODIALENTRY, if any, that corresponds to the local TAPI dialing location.

The Win32 API provides functions that enable you to set and query AutoDial parameters that control AutoDial connections. You can call the RasSetAutodialEnable function to enable or disable the AutoDial feature for a specified TAPI dialing location. The RasGetAutodialEnable function indicates whether the AutoDial feature is enabled for a specified TAPI dialing location. For more information about TAPI dialing locations, see the TAPI documentation. You can call the RasSetAutodialParam function to set other AutoDial connection parameters. For example, you can disable AutoDial connections for the current logon session. Call the RasGetAutodialParam function to determine the current value of the AutoDial connection parameters.

The system provides a default user interface for AutoDial dialing operations. However, you can create an AutoDial dynamic-link library (DLL) to provide a custom user interface for AutoDial dialing operations involving specified phone-book entries. Your AutoDial DLL must export both an ANSI and a Unicode version of a RASADFunc AutoDial handler.

To enable your custom AutoDial handler for a phone-book entry, call the RasSetEntryProperties function to set the properties for that entry. The szAutodialDll and szAutodialFunc members of the RASENTRY structure passed to RasSetEntryProperties specify the name of your AutoDial DLL and the name of your RASADFunc function, excluding the "A" or "W" suffix.

When the system starts an AutoDial operation for a phone-book entry with a custom AutoDial handler, it calls the specified RASADFunc. The RASADFunc function receives a pointer to a RASADPARAMS structure that indicates the location and parent window for the window of your user interface. Your RASADFunc can start a thread to perform the custom dialing operation. The RASADFunc function returns TRUE to indicate that it took over the dialing, or FALSE to allow the system to perform the dialing. Your custom dialing operation must use the RasDial function to do the actual dialing. When the dialing operation has been completed, the custom dialing operation indicates success or failure by setting the variable pointed to by the lpdwRetCode parameter passed to RASADFunc.


RAS Configuration and Connection Information

Applications running on Windows NT 4.0 and later versions, and Windows 95, can use the RasEnumConnections function to get information about the existing connections on the local computer. The information for each connection includes a connection handle and the name of the phone-book entry used to establish the connection. You can use the connection handle in a call to the RasGetConnectStatus function get the current status of the connection.

Windows NT 4.0 and later versions provide two new functions for retrieving RAS information. Windows 95 does not support these functions.

The RasEnumDevices function returns the name and type of the RAS-capable devices that are configured on the local computer.

The RasConnectionNotification function specifies an event object that the system signals when a RAS connection is created or terminated.


RAS Server Administration

Windows NT 4.0 provides a set of functions for administering user permissions and ports on Windows NT/Windows 2000 RAS servers. Windows 95 does not support these functions. Using these functions, you can develop a RAS server administration application to perform the following tasks:

  • Enumerate those users who have a specified set of RAS permissions
  • Assign or revoke RAS permissions for a specified user
  • Enumerate the configured ports on a RAS server
  • Get information and statistics about a specified port on a RAS server
  • Reset the statistics counters for a specified port
  • Disconnect a specified port

You can also install a RAS server administration DLL for auditing user connections and assigning IP addresses to dial-in users. The DLL exports a set of functions that the RAS server calls whenever a user tries to connect or disconnect.


RAS User Account Administration

A Windows NT 4.0 RAS server uses a user account database that contains information about a set of user accounts. The information includes a user's RAS privileges, which are a set of bit flags that determine how the RAS server responds when the user calls to connect. The RAS server administration functions enable you to locate the user account database, and to get and set the RAS privileges for user accounts.

A Windows NT 4.0 RAS server can be part of a Windows NT/Windows 2000 domain, or it can be a stand-alone Microsoft® Windows NT® Server or Microsoft® Windows NT® Workstation that is not part of a domain. For a server that is part of a domain, the user account database is stored on the Windows NT/Windows 2000 server that is the primary domain controller (PDC). A stand-alone server stores its own local user account database. To get the name of the server that stores the user account database used by a specified RAS server, you can call the RasAdminGetUserAccountServer function. You can then use the name of the user account server in a call to the NetQueryDisplayInformation function to enumerate the users in a user account database. You can also use the server name in calls to the RasAdminUserGetInfo and RasAdminUserSetInfo functions to get and set the RAS privileges for a specified user account.

The RasAdminUserGetInfo and RasAdminUserSetInfo functions use the RAS_USER_0 structure to specify a user's RAS privileges and call-back phone number. The RAS privileges indicate the following information:

  • Whether the user can make a remote connection to the server or the domain to which the server belongs.
  • Whether the user can establish a connection through a call-back, in which the RAS server hangs up and then calls back to the user to establish the connection.

Each user account specifies one of the following flags to indicate the user's call-back privilege.

Value | Meaning
RASPRIV_NoCallback | The RAS server will not call back the user to establish a connection.
RASPRIV_AdminSetCallback | When the user calls, the RAS server hangs up and calls a preset call-back phone number stored in the user account database. The szPhoneNumber member of the RAS_USER_0 structure contains the user's call-back phone number.
RASPRIV_CallerSetCallback | When the user calls, the RAS server provides the option of specifying a call-back phone number. The user can also choose to connect immediately without a call back. The szPhoneNumber member contains a default number that the user can override.


RAS Server and Port Administration

The RAS server administration functions enable you to get information about a specified RAS server and its ports. These functions also enable you to terminate a connection on a specified RAS server port.

The RasAdminServerGetInfo function returns a RAS_SERVER_0 structure that contains information about the configuration of a RAS server. The returned information includes the number of ports currently available for connection, the number of ports currently in use, and the server version number.

The RasAdminPortEnum function retrieves an array of RAS_PORT_0 structures that contains information for each of the ports configured on a RAS server. The information for each port includes:

  • The name of the port
  • Information about the device attached to the port
  • Whether the RAS server associated with the port is a Windows NT/Windows 2000 Server
  • Whether the port is currently in use, and if it is, information about the connection

You can call the RasAdminPortGetInfo function to get additional information about a specified port on a RAS server. This function returns a RAS_PORT_1 structure that contains a RAS_PORT_0 structure and additional information about the current state of the port. The RasAdminPortGetInfo function also returns an array of RAS_PARAMETERS structures that describe the values of any media-specific keys associated with the port. A RAS_PARAMETERS structure uses a value from the RAS_PARAMS_FORMAT enumeration to indicate the format of the value for each media-specific key.

The RasAdminPortGetInfo function also returns a RAS_PORT_STATISTICS structure that contains various statistic counters for the current connection, if any, on the port. For a port that is part of a multilink connection, RasAdminPortGetInfo returns statistics for the individual port and cumulative statistics for all ports involved in the connection. You can use the RasAdminPortClearStatistics function to reset the statistic counters for the port. The RasAdminPortDisconnect function disconnects a port that is in use.

Use the RasAdminFreeBuffer function to free memory allocated by the RasAdminPortEnum and RasAdminPortGetInfo functions. Use the RasAdminGetErrorString function to get a string that describes a RAS error code returned by one of the RAS server administration (RasAdmin) functions.


RAS Administration DLL

Windows NT 4.0 enables you to install a RAS administration DLL on a Windows NT 4.0 RAS server. The DLL exports functions that the RAS server calls whenever a user tries to connect or disconnect. You can use the DLL to perform the following administrative functions:

  • Decide whether to allow a user to connect to the server. This can provide a security check in addition to the standard RAS user authentication.
  • Record the time that each user connects to and disconnects from the server. This can be useful for billing or auditing purposes.
  • Assign an IP address to each user. This can be useful for security purposes to map a user's connection to a specific computer.

Implement the following functions when developing a RAS server administration DLL.

  • RasAdminAcceptNewConnection
  • RasAdminConnectionHangupNotification
  • RasAdminGetIpAddressForUser
  • RasAdminReleaseIpAddress

A RAS administration DLL must implement and export all of the above functions. If any of the functions are not implemented, the remote access service will fail to start.

The RasAdminAcceptNewConnection and RasAdminConnectionHangupNotification functions enable the DLL to audit user connections to the server. A Windows NT/Windows 2000 RAS server calls the RasAdminAcceptNewConnection function whenever a user tries to connect. The function can prevent the user from connecting. You can also use the function to generate an entry in a log for billing or auditing. When the user disconnects, the RAS server calls the RasAdminConnectionHangupNotification function, which can log the time at which the user disconnected.

After the RAS server has authenticated a caller, it calls the RasAdminGetIpAddressForUser function to get an IP address for the remote client. The DLL can use this function to provide an alternate scheme for mapping an IP address to a dial-in user. If RasAdminGetIpAddressForUser is not implemented, a RAS server connects a remote user to an IP address selected from a static pool of IP addresses, or one selected by a Dynamic Host Configuration Protocol (DHCP) server. The RasAdminGetIpAddressForUser function allows the DLL to override this default IP address and specify a particular IP address for each user. The RasAdminGetIpAddressForUser function can set a flag that causes RAS to call the RasAdminReleaseIPAddress function when the user disconnects. The DLL can use RasAdminReleaseIPAddress to update its user-to-IP-address map.

RAS serializes calls into the administration DLL. A call into one of the DLL's functions for a given RAS client will never be preempted by a call to that function for a different RAS client; the initial call is guaranteed to be complete before RAS calls the function for the other client. Furthermore, serialization extends to certain groups of functions. The IP address functions are serialized as a group; a call into either RasAdminGetIpAddressForUser or RasAdminReleaseIpAddress will block calls into both until the initial call is complete. RasAdminAcceptNewConnection and RasAdminConnectionHangupNotification are also serialized as a group.

RAS executes the functions for assigning IP addresses in one process and executes the functions for connection and disconnection notifications in another process. Consequently, the DLL should not depend on shared data between the two sets of functions.

The RAS server logs an error in the system event log if an error occurs when it tries to load a RAS administration DLL or when calling one of the DLL's functions. This can happen, for example, if the DLL specified the wrong name for an exported function, or if it did not include the function name in the .def file. The entry in the event log indicates the reason for the failure.

Windows 2000 and later: RAS administration DLLs that implement this function interface will not work on Windows 2000 and later versions. Instead, use the MprAdmin function interface provided with the more recent versions of Windows. For more information, see the RAS Administration Reference in the Routing and RAS documentation.


RAS Administration DLL Registry Setup

The setup program for a third-party RAS administration DLL must register the DLL with RAS by providing information under the following key in the registry:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDll

To register the DLL, set the following values under this key.

Value name | Value data
DisplayName | A REG_SZ string that contains the user-friendly display name of the DLL.
DLLPath | A REG_SZ string that contains the full path of the DLL.

For example, the registry entry for a RAS administration DLL from a fictional company named ProElectron, Inc. might be:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDll

DisplayName : REG_SZ : ProElectron RAS Admin DLL

DLLPath : REG_SZ : C:\nt\system32\ntwkadm.dll

The setup program for a RAS administration DLL should also provide remove/uninstall functionality. If a user removes the DLL, the setup program should delete the DLL's registry entries.


RAS Security Host Support

Windows NT 4.0 provides a way for a third-party RAS security DLL to enhance the built-in RAS security features. Windows 95 does not provide this support.

The Windows NT/Windows 2000 RAS server provides security mechanisms for validating the network access of remote users. When a RAS server receives a call, it validates the user's credentials against the local or domain account database. RAS also supports call-back security, in which the RAS server hangs up and then calls back to the remote user to establish the connection. For networks in which this level of security is not enough, you can install a third-party RAS security DLL. The security DLL can then authenticate a remote user by reading security information from a database other than the standard Windows NT/Windows 2000 user account database.

When the RAS server receives a call, it invokes the security DLL to authenticate the remote user. The RAS security host support provides a mechanism for the security DLL to communicate with the remote user through a terminal window on the remote computer. In a typical scenario, the security DLL asks for the logon name of the remote user. The DLL then uses its private security database to formulate a challenge to send to the remote terminal. For example, the challenge could be a code that the user must provide as input to a cardkey reader. The cardkey reader then displays a response that the remote user types in the terminal window. The security DLL then validates the response against the user's information in the private security database.

If the security DLL authenticates the remote user, the RAS server performs its own authentication. This ensures that RAS security always authenticates a remote user, even if a security DLL is installed that grants access to all users.

Note Windows NT/Windows 2000 currently provides RAS security host support only for asynchronous connections; other media, such as ISDN, are not supported.


Registering a RAS Security DLL

The setup program for a RAS security DLL must register the DLL with the Windows NT/Windows 2000 RAS server. Only one RAS security DLL can be registered; Windows NT/Windows 2000 does not support multiple security DLLs. To register a RAS security DLL, set the DLLPath value under the following key in the registry:

  HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\SecurityHost
Value Name | Value Data
DLLPath | A REG_SZ string that contains the path of the DLL. This string should specify the full path unless the DLL is in a directory listed in the system path.

The setup program for a RAS security DLL must also provide remove/uninstall functionality. If a user removes the DLL, the setup program must delete the DLLPath value from the registry. The RAS service will not start if the DLLPath value specifies a DLL that cannot be found.

A RAS security DLL must export the RasSecurityDialogBegin and RasSecurityDialogEnd functions.


RAS Server Security Authentication

When a Windows NT/Windows 2000 RAS server receives a call, it invokes the RasSecurityDialogBegin function of the registered RAS security DLL, if there is one. This call notifies the security DLL to begin its authentication of the remote user. The RAS server calls RasSecurityDialogBegin before performing its PPP or RAS authentication.

The RasSecurityDialogBegin call passes the following information to the security DLL:

  • A port handle to identify the connection
  • Pointers to buffers to use when communicating with the remote user
  • A pointer to a RasSecurityDialogComplete function to call when the authentication has been completed

The port handle and buffer pointers are valid until the security DLL calls RasSecurityDialogComplete to terminate the authentication transaction.

The RasSecurityDialogComplete notifies the RAS server of the results of the security DLL's authentication of the remote user. If the security DLL reports success, the RAS server proceeds with its PPP and RAS authentication of the remote user. If the security DLL reports that the remote user failed the authentication, or that an error occurred, the RAS server hangs up and logs the error or failed authentication in the Windows NT/Windows 2000 event log.


RAS Security DLL Authentication Transaction

The Windows NT/Windows 2000 RAS server calls the security DLL's RasSecurityDialogBegin function to begin an authentication of a remote user. The RAS server is blocked and cannot accept any other calls until RasSecurityDialogBegin returns. For this reason, RasSecurityDialogBegin should copy the input parameters, create a thread to perform the authentication, and return as quickly as possible.

The thread created by the security DLL uses the RasSecurityDialogSend and RasSecurityDialogReceive functions to communicate with the remote computer. These functions are not available for static import from any library. Instead, the security DLL must use the LoadLibrary and GetProcAddress functions to dynamically link to these functions in RASMAN.DLL.

During an authentication transaction, the RAS connection manager on the remote computer displays a terminal window. The thread of the security DLL calls RasSecurityDialogSend to send a message to display in the terminal window. The thread then calls RasSecurityDialogReceive to receive the input that the remote user types in the terminal window. The thread can make any number of RasSecurityDialogSend calls, with each call followed by a RasSecurityDialogReceive call. After each call to RasSecurityDialogReceive, the thread must call one of the wait functions, such as WaitForSingleObject, to wait for the asynchronous send and receive operations to be completed. The RAS server signals an event object when the receive operation has been completed or when an optional time-out interval has elapsed.

When the thread has finished authenticating the remote user, it calls the RasSecurityDialogComplete function. This call passes a SECURITY_MESSAGE structure containing the results of the authentication transaction to the RAS server. The RAS server then performs a cleanup sequence that includes a call to the DLL's RasSecurityDialogEnd function. This gives the security DLL an opportunity to perform any necessary cleanup.

The security DLL can call the RasSecurityDialogGetInfo function to retrieve information about the port associated with an authentication transaction. RasSecurityDialogGetInfo fills in a RAS_SECURITY_INFO structure that indicates the state of the last RasSecurityDialogReceive call for the port.


Using Remote Access Service

The following topic explains how to use Remote Access Service features in an application.

  • Linking to the Remote Access DLL


Linking to the Remote Access DLL

If an application links statically to the RASAPI32 DLL, the application will fail to load if Remote Access Service is not installed. A RAS application can load when RAS is not installed by using LoadLibrary to load the DLL, and GetProcAddress to obtain pointers to the RAS functions.

The Win32 RAS functions are in RASAPI32.DLL. The import library for these functions is RASAPI32.LIB. To use the RAS functions, your programs must include the following files:

File | Description
RAS.H | Contains the RAS function prototypes, constants, and structure definitions.
RASERROR.H | Contains the RAS error codes.


Remote Access Service Reference

The following functions, structures, messages, and enumeration types are used to implement Remote Access Service (RAS) client applications:

  • Remote Access Service Functions
  • Remote Access Service Structures
  • Remote Access Service Messages
  • Remote Access Service Enumeration Types
  • RAS Custom Scripting DLL Functions


Remote Access Service Functions

Use the following functions to implement RAS functionality:

ORASADFunc

RASADFunc

RasClearConnectionStatistics

RasClearLinkStatistics

RasConnectionNotification

RasCreatePhonebookEntry

RasCustomDeleteEntryNotify

RasCustomDial

RasCustomDialDlg

RasCustomEntryDlg

RasCustomHangUp

RasDeleteEntry

RasDeleteSubEntry

RasDial

RasDialDlg

RasDialFunc

RasDialFunc1

RasDialFunc2

RasEditPhonebookEntry

RasEntryDlg

RasEnumAutodialAddresses

RasEnumConnections

RasEnumDevices

RasEnumEntries

RasFreeEapUserIdentity

RasGetAutodialAddress

RasGetAutodialEnable

RasGetAutodialParam

RasGetConnectionStatistics

RasGetConnectStatus

RasGetCountryInfo

RasGetCredentials

RasGetCustomAuthData

RasGetEapUserData

RasGetEapUserIdentity

RasGetEntryDialParams

RasGetEntryProperties

RasGetErrorString

RasGetLinkStatistics

RasGetProjectionInfo

RasGetSubEntryHandle

RasGetSubEntryProperties

RasHangUp

RasInvokeEapUI

RasMonitorDlg

RasPBDlgFunc

RasPhonebookDlg

RasRenameEntry

RasSetAutodialAddress

RasSetAutodialEnable

RasSetAutodialParam

RasSetCommSettings

RasSetCredentials

RasSetCustomAuthData

RasSetEapUserData

RasSetEntryDialParams

RasSetEntryProperties

RasSetSubEntryProperties

RasValidateEntryName


ORASADFunc

The ORASADFunc function is an application-defined callback function that is used to provide a customized user interface for autodialing.

This prototype is provided for compatibility with earlier versions of Windows. New applications should use the RASADFunc callback function. Support for this prototype may be removed in future versions of RAS.

BOOL WINAPI ORASADFunc(
  HWND hwndOwner,      // handle of an owner window
  LPSTR lpszEntry,     // pointer to a phone-book entry
  DWORD dwFlags,       // reserved; must be zero
  LPDWORD lpdwRetCode  // receives the results of a dialing operation
);

Parameters

hwndOwner
[in] Handle of the owner window.
lpszEntry
[in] Pointer to a null-terminated string that specifies the phone-book entry to use.
dwFlags
[in] Reserved; must be zero.
lpdwRetCode
[in] Pointer to a variable that the callback function fills in with the results of the dialing operation. If the dialing operation succeeds, set this variable to ERROR_SUCCESS. If the dialing operation fails, set it to a nonzero value.

Return Values

If the callback function performs the dialing operation, return TRUE. Use the lpdwRetCode parameter to indicate the results of the dialing operation.

If the callback function does not perform the dialing operation, return FALSE. In this case, the system uses the default user interface for dialing.

Remarks

If the ORASADFunc function performs the dialing operation, it presents its own user interface for dialing and calls the RasDial function to do the actual dialing. The ORASADFunc then returns TRUE to indicate that it took over the dialing. When the dialing operation has been completed, set the variable pointed to by lpdwRetCode to indicate success or failure.

To enable an ORASADFunc handler for a phone-book entry, use the RASENTRY structure in a call to the RasSetEntryProperties function. The szAutodialDll member specifies the name of the DLL that contains the handler, and the szAutodialFunc member specifies the exported name of the handler.

The ORASADFunc function is a placeholder for the library-defined function name. The ORASADFUNC type is a pointer to an ORASADFunc function.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RASADFunc, RasDial, RASENTRY, RasSetEntryProperties


RASADFunc

The RASADFunc function is an application-defined callback function that is used to provide a customized user interface for autodialing.

BOOL WINAPI RASADFunc(
  LPTSTR lpszPhonebook,  // pointer to full path and file name of
                         //  phone-book file
  LPTSTR lpszEntry,      // pointer to the entry name to validate
  LPRASADPARAMS lpAutoDialParams,
                         // pointer to a RASADPARAMS structure
  LPDWORD lpdwRetCode    // receives results of dialing operation
);

Parameters

lpszPhonebook
[in] Windows NT/2000 or later: Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
[in] Pointer to a null-terminated string that specifies the phone-book entry to use.
lpAutoDialParams
[in] Pointer to a RASADPARAMS structure that indicates how to position the window of the AutoDial user interface. The structure may also specify a parent window for the AutoDial window.
lpdwRetCode
[out] Pointer to a variable that receives a value if the function performsthe dialing operation. If the dialing operation succeeds, set this variable to ERROR_SUCCESS. If the dialing operation fails, set it to a nonzero value.

Return Values

If the application performs the dialing operation, return TRUE. Use the lpdwRetCode parameter to indicate the results of the dialing operation.

If the application does not perform the dialing operation, return FALSE. In this case, the system uses the default user interface for dialing.

Remarks

When the system starts an AutoDial operation for a phone-book entry with a custom AutoDial handler, it calls the specified RASADFunc. The RASADFunc can start a thread to perform the custom-dialing operation. The RASADFunc function returns TRUE to indicate that it took over the dialing, or FALSE to allow the system to perform the dialing.

If the RASADFunc function performs the dialing operation, it presents its own user interface for dialing and calls the RasDial function to do the actual dialing. The RASADFunc then returns TRUE to indicate that it took over the dialing. When the dialing operation has been completed, set the variable pointed to by the lpdwRetCode parameter to indicate success or failure.

The AutoDial DLL must provide both a RASADFUNCA (ANSI) and a RASADFUNCW (Unicode) version of the RASADFunc handler. To enable a RASADFunc AutoDial handler for a phone-book entry, use the RASENTRY structure in a call to the RasSetEntryProperties function. The szAutodialDll member specifies the name of the DLL that contains the handler, and the szAutodialFunc member specifies the exported name of the handler. The szAutodialFunc member should not include the "A" or "W" suffix.

RASADFunc is a placeholder for the library-defined function name. The RASADFUNC type is a pointer to a RASADFunc function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Unicode: Declared as Unicode and ANSI prototypes.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasDial, RASENTRY, RasSetEntryProperties


RasClearConnectionStatistics

The RasClearConnectionStatistics functions clears any accumulated statistics for the specified RAS connection.

DWORD RasClearConnectionStatistics (
  HRASCONN hRasConn  // handle to connection
);

Parameters

hRasConn
[in] Handle to the connection. Use RasDial or RasEnumConnections to obtain this handle.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The hRasConn parameter does not specify a valid connection.
ERROR_NOT_ENOUGH_MEMORY | The function could not allocate sufficient memory to complete the operation.
Other | Use FormatMessage to retrieve the system error message that corresponds to the error code returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasClearLinkStatistics, RasDial, RasEnumConnections, RasGetConnectionStatistics, RAS_STATS


RasClearLinkStatistics

The RasClearLinkStatistics functions clears any accumulated statistics for the specified link in a RAS multilink connection.

DWORD RasClearLinkStatistics(
  HRASCONN hRasConn,  // handle to connection
  DWORD dwSubEntry    // SubEntry for link
);

Parameters

hRasConn
[in] Handle to the connection. Use RasDial or RasEnumConnections to obtain this handle.
dwSubEntry
[in] Specifies the subentry that corresponds to the link for which to clear statistics.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The hRasConn parameter does not specify a valid connection.
ERROR_INVALID_PARAMETER | The dwSubEntry parameter is zero.
ERROR_NO_CONNECTION | RAS could not find a connected port that corresponds to the value in the dwSubEntry parameter.
ERROR_NOT_ENOUGH_MEMORY | The function could not allocate sufficient memory to complete the operation.
Other | Use FormatMessage to retrieve the system error message that corresponds to the error code returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasClearConnectionStatistics, RasGetLinkStatistics


RasConnectionNotification

The RasConnectionNotification function specifies an event object that the system sets to the signaled state when a RAS connection is created or terminated.

DWORD RasConnectionNotification(
  HRASCONN hrasconn,  // handle to a RAS connection
  HANDLE hEvent,      // handle to an event object
  DWORD dwFlags       // type of event to receive notifications for
);

Parameters

hrasconn
[in] Handle to the RAS connection for which to receive notifications. This can be a handle returned by the RasDial or RasEnumConnections function. If this parameter is INVALID_HANDLE_VALUE, notifications are received for all RAS connections on the local computer.
hEvent
[in] Specifies the handle of an event object. Use the CreateEvent function to create an event object.
dwFlags
[in] Specifies the RAS event that causes the system to signal the event object specified by the hEvent parameter. This parameter is a combination of the following values.
Value | Meaning
RASCN_Connection | If hrasconn is INVALID_HANDLE_VALUE, hEvent is signaled when any RAS connection is created.
RASCN_Disconnection | hEvent is signaled when the hrasconn connection is terminated. If hrasconn is a multilink connection, the event is signaled when all subentries are disconnected. If hrasconn is INVALID_HANDLE_VALUE, the event is signaled when any RAS connection is terminated.
RASCN_BandwidthAdded | Windows NT 4.0 and earlier versions only: If hrasconn is a handle to a combined multilink connection, hEvent is signaled when a subentry is connected.
RASCN_BandwidthRemoved | Windows NT 4.0 and earlier versions only: If hrasconn is a handle to a combined multilink connection, hEvent is signaled when a subentry is disconnected.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero error code.

Remarks

To determine when the event object is signaled, use any of the wait functions.

When the event is signaled, use other RAS functions, such as RasEnumConnections, to get more information about the RAS connection that was created or terminated.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, CreateEvent, RasEnumConnections


RasCreatePhonebookEntry

The RasCreatePhonebookEntry function creates a new phone-book entry. The function displays a dialog box in which the user types information for the phone-book entry.

Windows NT/2000 or later: The RasCreatePhonebookEntry function calls the RasEntryDlg function. Applications written for Windows NT version 4.0 should use RasEntryDlg.

DWORD RasCreatePhonebookEntry(
  HWND hwnd,              // handle to the parent window of the dialog box
  LPCTSTR lpszPhonebook,  // pointer to the full path and
                          //  file name of the phone-book file
);

Parameters

hwnd
[in] Handle to the parent window of the dialog box.
lpszPhonebook
[in] Windows NT/2000 or later: Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.

Windows 95: Dial-up networking stores phone-book entries in the registry rather than in a phone-book file

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is the following error code.

Value | Description
ERROR_CANNOT_OPEN_PHONEBOOK | The phone book is corrupted or missing components.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasEditPhonebookEntry, RasEntryDlg, RasGetEntryDialParams, RasSetEntryDialParams


RasCustomDeleteEntryNotify

The RasCustomDeleteEntryNotify function is an application-defined function that is exported by a third-party custom-dialing DLL. This function allows third-party vendors to implement custom dialogs for managing phone-book entries.

typedef DWORD (WINAPI *RasCustomDeleteEntryNotifyFn) (
  LPCTSTR lpszPhonebook,
  LPCTSTR lpszEntry,
  DWORD dwFlags
);

Parameters

lpszPhonebook
[in] Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
[in] Pointer to a null-terminated string that contains the name of the phone-book entry to dial.
dwFlags
[in] Specifies one or more of the following flags:

RCD_SingleUser

RCD_AllUsers

RCD_Eap

Return Values

The function should return NO_ERROR.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasCustomDial, RasCustomDialDlg, RasCustomEntryDlg, RasCustomHangUp, RasDial


RasCustomDial

The RasCustomDial function is an application-defined function that is exported by a third-party custom-dialing DLL. This function allows third-party vendors to implement custom remote-access dialing routines.

DWORD (WINAPI  * RasCustomDial) (
  HINSTANCE hInstDll,               // handle to DLL instance
  LPRASDIALEXTENSIONS lpRasDialExtensions,  // pointer to
                                            //  function extensions data
  LPCTSTR lpszPhonebook,            // pointer to full path
                                    //  and file name of
                                    //  phone-book file
  LPRASDIALPARAMS lpRasDialParams,  // pointer to calling
                                    //  parameters data
  DWORD dwNotifierType,             // specifies type of
                                    //  RasDial event handler
  LPVOID lpvNotifier,               // specifies a handler
                                    //  for RasDial events
  LPHRASCONN lphRasConn             // pointer to variable
                                    //  to receive connection handle
);

Parameters

hInstDll
Handle to the instance of the custom-dial DLL that was loaded.
lpRasDialExtensions
Pointer to a RASDIALEXTENSIONS structure that specifies a set of RasDial extended features to enable. Set this parameter to NULL if there is no need to enable the extensions.
lpszPhonebook
Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpRasDialParams
Pointer to a RASDIALPARAMS structure that specifies calling parameters for the RAS connection.

The caller must set the RASDIALPARAMS structure's dwSize member to sizeof(RASDIALPARAMS) to identify the version of the structure being passed.

dwNotifierType
This parameter is the same as the dwNotifierType parameter for the RasDial function. See the RasDial reference page for more information.
lpvNotifier
This parameter is the same as the lpvNotifier parameter for the RasDial function. See the RasDial reference page for more information.
lphRasConn
Pointer to a variable of type HRASCONN. Set the HRASCONN variable to NULL before calling RasDial. If RasDial succeeds, it stores a handle to the RAS connection into *lphRasConn.

Return Values

If the function succeeds, the immediate return value is zero. In addition, the function stores a handle to the RAS connection in the variable pointed to by the lphRasConn parameter.

If the function fails, the immediate return value is a nonzero error value, either from the set listed in Raserror.h or ERROR_NOT_ENOUGH_MEMORY.

Remarks

RAS calls this entry point from RasDial, if the szCustomDialDll member of the RASENTRY structure for the entry being dialed specifies a custom-dialing DLL.

If this entry point calls RasDial, the lpRasDialExtensions parameter must not be NULL, and the dwFlags member of the RASDIALEXTENSIONS structure must have the RDEOPT_CustomDial flag set.

If the custom-dial DLL does not support this entry point, RAS returns ERROR_CANNOT_DO_CUSTOMDIAL to the caller of RasDial.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Unicode: Declared as Unicode and ANSI prototypes.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasCustomDialDlg, RasCustomEntryDlg, RasCustomHangUp, RasDial, RASENTRY


RasCustomDialDlg

The RasCustomDialDlg function is an application-defined function that is exported by a third-party custom-dialing DLL. This function allows third-party vendors to implement custom RAS connection dialog boxes.

BOOL (WINAPI  * RasCustomDialDlg) (
  HINSTANCE hInstDll,      // handle to DLL instance
  DWORD dwFlags,           // reserved
  LPTSTR lpszPhonebook,    // pointer to the full path and
                           //  file name of the phone-book file
  LPTSTR lpszEntry,        // pointer to the name of the
                           //  phone-book entry to dial
  LPTSTR lpszPhoneNumber,  // pointer to replacement phone
                           //  number to dial
  LPRASDIALDLG lpInfo      // pointer to a structure that
                           //  contains additional parameters
);

Parameters

hInstDll
Handle to the instance of the custom-dialing DLL that was loaded.
dwFlags
The parameter is reserved for future use.
lpszPhonebook
Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
Pointer to a null-terminated string that contains the name of the phone-book entry to dial.
lpszPhoneNumber
Pointer to a null-terminated string that contains a phone number that overrides the numbers stored in the phone-book entry. If this parameter is NULL, RasDialDlg uses the numbers in the phone-book entry.
lpInfo
Pointer to a RASDIALDLG structure that contains additional input and output parameters. On input, the dwSize member of this structure must specify sizeof(RASDIALDLG). If an error occurs, the dwError member returns an error code; otherwise, it returns zero.

Return Values

If the function establishes a RAS connection, the return value should be a nonzero value.

If an error occurs, or if the user selects a Cancel button during dialing box operation, the return value should be zero. If an error occurs, set the dwError member of the RASDIALDLG structure to a nonzero system error or a RAS error code from Raserror.h.

Remarks

RAS will call this entry point from RasDialDlg, if the szCustomDialDll member of the RASENTRY structure for the entry being dialed specifies a custom-dialing DLL.

If this entry point calls RasDial, the lpRasDialExtensions parameter must not be NULL, and the dwFlags member of the RASDIALEXTENSIONS structure must have the RDEOPT_CustomDial flag set.

The custom-dial dialog must support WM_COMMAND messages where LOWORD(wParam) equals IDCANCEL.

If the custom-dial DLL does not support this entry point, RAS returns ERROR_CANNOT_DO_CUSTOMDIAL to the caller of RasDialDlg.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Rasdlg.h.
Unicode: Declared as Unicode and ANSI prototypes.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasCustomDial, RasCustomEntryDlg, RasCustomHangUp, RasDialDlg, RASENTRY


RasCustomEntryDlg

The RasCustomEntryDlg function is an application-defined function that is exported by a third-party custom-dialing DLL. This function allows third-party vendors to implement custom dialogs for managing phone-book entries.

BOOL (WINAPI  * RasCustomEntryDlg) (
  HINSTANCE hInstDll,    // handle to DLL instance
  LPTSTR lpszPhonebook,  // pointer to the full path and
                         //  file name of the phone-book file
  LPTSTR lpszEntry,      // pointer to the name of the
                         //  phone-book entry to edit,
                         //  copy, or create
  LPRASENTRYDLG lpInfo   // pointer to a structure that
                         //  contains additional parameters
);

Parameters

hInstDll
Handle to the instance of the custom-dial DLL that was loaded.
lpszPhonebook
Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
Pointer to a null-terminated string that contains the name of the phone-book entry to edit, copy, or create.

If you are editing or copying an entry, this parameter is the name of an existing phone-book entry. If you are copying an entry, set the RASEDFLAG_CloneEntry flag in the dwFlags member of the RASENTRYDLG structure.

If you are creating an entry, this parameter is a default new entry name that the user can change. If this parameter is NULL, the function provides a default name. If you are creating an entry, set the RASEDFLAG_NewEntry flag in the dwFlags member of the RASENTRYDLG structure.

lpInfo
Pointer to a RASENTRYDLG structure that contains additional input and output parameters. On input, the dwSize member of this structure must specify sizeof(RASENTRYDLG). Use the dwFlags member to indicate whether creating, editing, or copying an entry. If an error occurs, the dwError member returns an error code; otherwise, it returns zero.

Return Values

If the user creates, copies, or edits a phone-book entry, the return value should be a nonzero value.

If an error occurs, or if the user cancels the operation, the return value should be zero. If an error occurs, the RasCustomEntryDlg should set the dwError member of the RASENTRYDLG structure to a nonzero system error code or a RAS error code from Raserror.h.

Remarks

RAS will call this entry point from RasEntryDlg, if the szCustomDialDll member of the RASENTRY structure for the entry being dialed specifies a custom-dialing DLL.

If the custom-dial DLL does not support this entry point, RAS returns ERROR_NO_CUSTOMENTRYDLG to the caller of RasEntryDlg.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Rasdlg.h.
Unicode: Declared as Unicode and ANSI prototypes.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasCustomDial, RasCustomDialDlg, RasCustomHangUp, RasEntryDlg, RASENTRY


RasCustomHangUp

The RasCustomHangUp function is an application-defined function that is exported by a third-party custom-dialing DLL. This function allows third-party vendors to implement custom connection hang-up routines.

DWORD (WINAPI  * RasCustomHangUp) (
  HRASCONN hRasConn  // handle to a RAS connection
);

Parameters

hRasConn
Handle to the RAS connection to hang up.

Return Values

If the function succeeds, the return value should be zero.

If the function fails, the return value should be a nonzero error value listed in Raserror.h, or ERROR_INVALID_HANDLE.

Remarks

RAS will call this entry point from RasHangUp, if the szCustomDialDll member of the RASENTRY structure for the entry being dialed specifies a custom-dialing DLL.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasCustomDial, RasCustomDialDlg, RasCustomEntryDlg, RasHangUp, RASENTRY


RasDeleteEntry

The RasDeleteEntry function deletes an entry from a phone book.

DWORD RasDeleteEntry(
  LPCTSTR lpszPhonebook,  // pointer to full path and file
                          //  name of phone-book file
  LPCTSTR lpszEntry       // pointer to an entry name to delete
);

Parameters

lpszPhonebook
[in] Windows NT/2000 or later: Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
[in] Pointer to a null-terminated string that specifies the name of an existing entry to be deleted.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is ERROR_INVALID_NAME.

Remarks

The following sample code deletes the phone-book entry specified by the variable lpszEntry.

nRet = RasDeleteEntry(NULL, lpszEntry);
if (nRet != ERROR_SUCCESS)
{
    printf("RasDeleteEntry failed: Error = %d\n", nRet);
}
else
{
    printf("Entry %s deleted successfully\n", lpszEntry);
}

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 OSR2 or later.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasCreatePhonebookEntry, RasEnumEntries


RasDeleteSubEntry

[This is preliminary documentation and subject to change.]

The RasDeleteSubEntry function deletes the specified subentry from the specified phone-book entry.

DWORD RasDeleteSubEntry(
  LPCTSTR lpszPhonebook,
  LPCTSTR lpszEntry,
  DWORD dwSubEntryId
);

Parameters

lpszPhonebook
[in] Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file.
lpszEntry
[in] Pointer to a null-terminated string that contains the name of an existing entry from which a subentry is to be deleted.
dwSubEntryId
[in] Specifies the one-based index of the subentry.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is ERROR_INVALID_NAME.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.

See Also

RasDeleteEntry, RASENTRY, RASSUBENTRY


RasDial

The RasDial function establishes a RAS connection between a RAS client and a RAS server. The connection data includes callback and user-authentication information.

DWORD RasDial(
  LPRASDIALEXTENSIONS lpRasDialExtensions,
                          // pointer to function extensions data
  LPCTSTR lpszPhonebook,  // pointer to full path and file
                          //  name of phone-book file
  LPRASDIALPARAMS lpRasDialParams,
                          // pointer to calling parameters data
  DWORD dwNotifierType,   // specifies type of RasDial event handler
  LPVOID lpvNotifier,     // specifies a handler for RasDial events
  LPHRASCONN lphRasConn   // pointer to variable to receive
                          //  connection handle
);

Parameters

lpRasDialExtensions
[in] Windows NT/2000 or later: Pointer to a RASDIALEXTENSIONS structure that specifies a set of RasDial extended features to enable. Set this parameter to NULL if there is not a need to enable these features.

Windows 95: This parameter is ignored. On Windows 95, RasDial always uses the default behaviors for the RASDIALEXTENSIONS options.

lpszPhonebook
[in] Windows NT/2000 or later: Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.

Windows 95: This parameter is ignored. Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.

lpRasDialParams
[in] Pointer to a RASDIALPARAMS structure that specifies calling parameters for the RAS connection.

The caller must set the RASDIALPARAMS structure's dwSize member to sizeof(RASDIALPARAMS) to identify the version of the structure being passed.

dwNotifierType
[in] Specifies the nature of the lpvNotifier parameter. If lpvNotifier is NULL, dwNotifierType is ignored. If lpvNotifier is not NULL, set dwNotifierType to one of the following values.
Value | Meaning
0xFFFFFFFF The lpvNotifier parameter is a handle to a window to receive progress notification messages. In a progress notification message, wParam is the equivalent of the rasconnstate parameter of RasDialFunc and RasDialFunc1, and lParam is the equivalent of the dwError parameter of RasDialFunc and RasDialFunc1.

The progress notification message uses a system registered message code. You can obtain the value of this message code as follows:

{UINT unMsg =
  RegisterWindowMessageA( RASDIALEVENT );
 if (unMsg == 0)
       unMsg = WM_RASDIALEVENT;
 }
0 | The lpvNotifier parameter points to a RasDialFunc callback function.
1 | The lpvNotifier parameter points to a RasDialFunc1 callback function.
2 | Windows NT/2000 or later: The lpvNotifier parameter points to a RasDialFunc2 callback function.

lpvNotifier
[in] Specifies a window handle or a RasDialFunc, RasDialFunc1, or RasDialFunc2 callback function to receive RasDial event notifications. The dwNotifierType parameter specifies the nature of lpvNotifier. Please refer to its description preceding for further detail.

If this parameter is not NULL, RasDial sends the window a message, or calls the callback function, for each RasDial event. Additionally, the RasDial call operates asynchronously: RasDial returns immediately, before the connection is established, and communicates its progress via the window or callback function.

If lpvNotifier is NULL, the RasDial call operates synchronously: RasDial does not return until the connection attempt has completed successfully or failed.

If lpvNotifier is not NULL, notifications to the window or callback function can occur at any time after the initial call to RasDial. Notifications end when one of the following events occurs:

  • The connection is established. In other words, the RAS connection state is RASCS_Connected.
  • The connection fails. In other words, dwError is nonzero.
  • RasHangUp is called on the connection.

The callback notifications are made in the context of a thread captured during the initial call to RasDial.

lphRasConn
[in] Pointer to a variable of type HRASCONN. Set the HRASCONN variable to NULL before calling RasDial. If RasDial succeeds, it stores a handle to the RAS connection into *lphRasConn.

Return Values

If the function succeeds, the immediate return value is zero. In addition, the function stores a handle to the RAS connection into the variable pointed to by lphRasConn.

If the function fails, the immediate return value is a nonzero error value, either from the set listed in the RAS header file or ERROR_NOT_ENOUGH_MEMORY.

Remarks

Errors that occur after the immediate return can be detected by RasGetConnectStatus. Data is available until an application calls RasHangUp to hang up the connection.

An application must eventually call RasHangUp whenever a non-NULL connection handle is stored into *lphRasConn. This applies even if RasDial returns a nonzero (error) value.

An application can safely call RasHangUp from a RasDial notifier callback function. If this is done, however, the hangup does not occur until the routine returns.

Windows NT/2000 or later: If the structure pointed to by lpRasDialExtensions enables RDEOPT_PausedStates, the RasDial function pauses whenever it enters a state in which the RASCS_PAUSED bit is set to one. To restart RasDial from such a paused state, call RasDial again, passing the connection handle returned from the original RasDial call in *lphRasConn. The same notifier used in the original RasDial call must be used when restarting from a paused state.

Windows 2000 or later: RAS supports referenced connections. If the entry being dialed is already connected, RasDial will return SUCCESS and the connection will be referenced. To disconnect the connection, each RasDial on the connection should be matched by a RasHangUp.

Windows 2000 or later: Because some phone-book entries require Extensible Authentication Protocol (EAP) for authentication, the caller should call RasGetEapUserIdentity before calling RasDial. If RasGetEapUserIdentity returns ERROR_INVALID_ENTRY_FOR_FUNCTION, the phone-book entry does not require EAP. However, if RasGetEapUserIdentity returns NO_ERROR, the caller should copy the EAP identity information from RasGetEapUserIdentity into the RasEapInfo member of RASDIALEXTENSIONS, and the szUserName member of RASDIALPARAMS. See RasGetEapUserIdentity for more information. If the phone-book entry requires EAP, the dwfOptions member of the RASENTRY structure for the entry contains the RASEO_RequireEAP flag.

To specify that RasDial should enter a RASCS_CallbackSetByCaller state, set lpRasDialParams->szCallbackNumber to "*" on the initial call to RasDial. When the notification handler is called with this state, set the callback number to a number supplied by the user.

Windows 95: Windows 95 does not support the RASCS_CallbackSetByCaller state or any of the other paused states.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, Dialable Addresses, Virtual Private Network Connections, RasDialDlg, RasDialFunc, RasDialFunc1, RasDialFunc2, RasGetConnectStatus, RasHangUp, RASDIALEXTENSIONS, RASDIALPARAMS, WM_RASDIALEVENT


RasDialDlg

The RasDialDlg function establishes a RAS connection using a specified phone-book entry and the credentials of the logged-on user. The function displays a stream of dialog boxes that indicate the state of the connection operation.

BOOL RasDialDlg(
  LPTSTR lpszPhonebook,   // pointer to the full path and file name of
                          //  the phone-book file
  LPTSTR lpszEntry,       // pointer to the name of the phone-book
                          //  entry to dial
  LPTSTR lpszPhoneNumber, // pointer to replacement phone number to
                          //  dial
  LPRASDIALDLG lpInfo     // pointer to a structure that contains
                          //  additional parameters
);

Parameters

lpszPhonebook
[in] Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
[in] Pointer to a null-terminated string that specifies the name of the phone-book entry to dial.
lpszPhoneNumber
[in] Pointer to a null-terminated string that specifies a phone number that overrides the numbers stored in the phone-book entry. If this parameter is NULL, RasDialDlg uses the numbers in the phone-book entry.
lpInfo
[in] Pointer to a RASDIALDLG structure that specifies additional input and output parameters. The dwSize member of this structure must specify sizeof(RASDIALDLG). If an error occurs, the dwError member returns an error code; otherwise, it returns zero.

Return Values

If the function establishes a RAS connection, the return value is a nonzero value.

If an error occurs, or if the user selects the Cancel button during the dialing operation, the return value is zero. If an error occurs, the dwError member of the RASDIALDLG structure returns a nonzero system or RAS error code.

Remarks

The RasDialDlg function displays a series of dialog boxes that are similar to the dialog boxes that main Dial-Up Networking dialog box displays when the user selects the Dial button. Use the RasDialDlg function to display a standard user interface for a connection operation without presenting the main phone-book dialog box. For example, the RAS AutoDial service uses this function to establish a connection using the phone-book entry associated with a remote address.

The RasDialDlg function displays dialog boxes during the connection operation to provide feedback to the user about the progress of the operation. For example, the dialog boxes might indicate when the operation is dialing, when it is authenticating the user's credentials on the remote server, and so on. The dialog boxes also provide a Cancel button for the user to terminate the operation.

RasDialDlg returns when the connection is established, or when the user cancels the operation.

The following sample code dials the entry in the default phone-book specified by the variable lpszEntry.

lpInfo = (LPRASDIALDLG) GlobalAlloc(GPTR, sizeof(RASDIALDLG));
lpInfo->dwSize = sizeof(RASDIALDLG);

printf("Dialing %s...\n", lpszEntry);

//    Calling RasDialDlg()

nRet = RasDialDlg(NULL, lpszEntry, NULL, lpInfo);
if (nRet == 0)
{
    printf("RasDialDlg failed: Error = %d\n", lpInfo->dwError);
}
else
{
    printf("Connection established.\n");
}
GlobalFree(lpInfo);

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Rasdlg.h.
Library: Use Rasdlg.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RASDIALDLG, RasPhonebookDlg


RasDialFunc

The RasDialFunc function is an application-defined or library-defined callback function that the RasDial function calls when a change of state occurs during a RAS connection process.

VOID WINAPI RasDialFunc(
  UINT unMsg,                // type of event that has occurred
  RASCONNSTATE rasconnstate, // connection state about to be entered
  DWORD dwError              // error that may have occurred
);

Parameters

unMsg
[in] Specifies the type of event that has occurred. Currently, the only event defined is WM_RASDIALEVENT.
rasconnstate
[in] Specifies the RASCONNSTATE enumerator value that indicates the state the RasDial remote access connection process is about to enter.
dwError
[in] Specifies the error that has occurred, or zero if no error has occurred.

RasDial calls RasDialFunc with dwError set to zero upon entry to each connection state. If an error occurs within a state, RasDialFunc is called again with a nonzero dwError value.

Return Values

None.

Remarks

A RasDial connection operation is suspended during a call to a RasDialFunc callback function. For that reason, the RasDialFunc implementation should generally return as quickly as possible. There are two exceptions to that rule. Asynchronous (slow) devices such as modems often have time-out periods measured in seconds rather than milliseconds; a slow return from a RasDialFunc function is generally not a problem. The prompt return requirement also does not apply when dwError is nonzero, indicating that an error has occurred. It is safe, for example, to put up an error dialog box and wait for user input.

The RasDialFunc implementation should not depend on the order or occurrence of particular RASCONNSTATE connection states, because this may vary between platforms.

Do not call the RasDial function from within a RasDialFunc callback function. Call the RasGetConnectStatus, RasEnumEntries, RasEnumConnections, RasGetErrorString, and RasHangUp functions from within the callback function. For example, calling RasGetConnectStatus from within a callback function would be useful for determining the name and type of the connecting device.

Note For convenience, RasHangUp can be called from within a RasDialFunc callback function. However, much of the hang-up processing occurs after the RasDialFunc callback function has returned.

RasDialFunc is a placeholder for the application-defined or library-defined function name.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Ras.h.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RASCONNSTATE, RasDial, RasDialFunc1, RasDialFunc2, RasEnumConnections, RasEnumEntries, RasGetConnectStatus, RasGetErrorString, RasHangUp


RasDialFunc1

A RasDialFunc1 function is an application-defined or library-defined callback function that the RasDial function calls when a change of state occurs during a remote access connection process. A RasDialFunc1 function is comparable to a RasDialFunc function, but is enhanced by the addition of two parameters: a handle to the RAS connection, and an extended error code.

VOID WINAPI RasDialFunc1(
  HRASCONN hrasconn,    // handle to RAS connection
  UINT unMsg,           // type of event that has occurred
  RASCONNSTATE rascs,   // connection state about to be entered
  DWORD dwError,        // error that may have occurred
  DWORD dwExtendedError // extended error information for some errors
);

Parameters

hrasconn
[in] Handle to the RAS connection, as returned by RasDial.
unMsg
[in] Specifies the type of event that has occurred. Currently, the only event defined is WM_RASDIALEVENT.
rascs
[in] Specifies the RASCONNSTATE enumerator value that indicates the state the RasDial remote access connection process is about to enter.
dwError
[in] Specifies the error that has occurred. If no error has occurred, dwError is zero.

RasDial calls RasDialFunc1 with dwError set to zero upon entry to each connection state. If an error occurs within a state, RasDial calls RasDialFunc1 again with a nonzero dwError value.

In some error cases, the dwExtendedError parameter contains extended error information.

dwExtendedError
[in] Specifies extended error information for certain nonzero values of dwError. For all other values of dwError, dwExtendedError is zero.

The contents of dwExtendedError are defined for values of dwError as follows.
dwError | dwExtendedError
ERROR_SERVER_NOT_RESPONDING | Specifies the NetBIOS error that occurred.
ERROR_NETBIOS_ERROR | Specifies the NetBIOS error that occurred.
ERROR_AUTH_INTERNAL | Specifies an internal diagnostics code.
ERROR_CANNOT_GET_LANA | Specifies a routing error code, which is a RAS error.

Return Values

None.

Remarks

A RasDial connection operation is suspended during a call to a RasDialFunc1 callback function. For that reason, the RasDialFunc1 implementation generally returns as quickly as possible. There are two exceptions to that rule. Asynchronous (slow) devices such as modems often have time-out periods measured in seconds rather than milliseconds; a slow return from a RasDialFunc1 function is generally not a problem. The prompt return requirement also does not apply when dwError is nonzero, indicating that an error has occurred. It is safe, for example, to put up an error dialog box and wait for user input.

The RasDialFunc1 implementation should not depend on the order or occurrence of particular RASCONNSTATE connection states, because this may vary between platforms.

Do not call the RasDial function from within a RasDialFunc1 callback function. Call the RasGetConnectStatus, RasEnumEntries, RasEnumConnections, RasGetErrorString, and RasHangUp functions from within the callback function. For example, calling RasGetConnectStatus from within a callback function would be useful for determining the name and type of the connecting device.

Note that, for convenience, RasHangUp can be called from within a RasDialFunc1 callback function. However, much of the hang-up processing occurs after the RasDialFunc1 callback function has returned.

RasDialFunc1 is a placeholder for the application-defined or library-defined function name.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Ras.h.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasDial, RasDialFunc, RasDialFunc2, RASCONNSTATE, RasEnumConnections, RasEnumEntries, RasGetConnectStatus, RasGetErrorString, RasHangUp


RasDialFunc2

A RasDialFunc2 function is an application-defined or library-defined callback function that the RasDial function calls when a change of state occurs during a remote access connection process. A RasDialFunc2 function is similar to the RasDialFunc1 callback function, except that it provides additional information for multilink connections.

DWORD WINAPI RasDialFunc2(
  DWORD dwCallbackId,    // user-defined value specified in
                         //  RasDial call
  DWORD dwSubEntry,      // subentry index in multilink connection
  HRASCONN hrasconn,     // handle to RAS connection
  UINT unMsg,            // type of event that has occurred
  RASCONNSTATE rascs,    // connection state about to be entered
  DWORD dwError,         // error that may have occurred
  DWORD dwExtendedError  // extended error information for
                         //  some errors
);

Parameters

dwCallbackId
[in] Provides an application-defined value that was specified in the dwCallbackId member of the RASDIALPARAMS structure passed to RasDial.
dwSubEntry
[in] Specifies a subentry index for the phone-book entry associated with this connection. This value indicates the subentry that generated this call to the RasDialFunc2 callback function.
hrasconn
[in] Handle to the RAS connection, as returned by RasDial.
unMsg
[in] Specifies the type of event that has occurred. Currently, the only event defined is WM_RASDIALEVENT.
rascs
[in] Specifies the RASCONNSTATE enumerator value that indicates the state the RasDial remote access connection process is about to enter.
dwError
[in] Specifies the error that has occurred. If no error has occurred, dwError is zero.

The RasDial function calls RasDialFunc2 with dwError set to zero upon entry to each connection state. If an error occurs within a state, RasDial calls RasDialFunc2 again with a nonzero dwError value.

In some error cases, the dwExtendedError parameter contains extended error information.

dwExtendedError
[in] Specifies extended error information for certain nonzero values of dwError. For all other values of dwError, dwExtendedError is zero.

The contents of dwExtendedError are defined for values of dwError as follows.
dwError | dwExtendedError
ERROR_SERVER_NOT_RESPONDING | Specifies the NetBIOS error that occurred.
ERROR_NETBIOS_ERROR | Specifies the NetBIOS error that occurred.
ERROR_AUTH_INTERNAL | Specifies an internal diagnostics code.
ERROR_CANNOT_GET_LANA | Specifies a routing error code, which is a RAS error.

Return Values

If the RasDialFunc2 function returns a nonzero value, RasDial continues to send callback notifications.

If the RasDialFunc2 function returns zero, RasDial stops sending callback notifications for all subentries.

Remarks

A RasDial connection operation is suspended during a call to a RasDialFunc2 callback function. For that reason, the RasDialFunc2 implementation generally returns as quickly as possible. There are two exceptions to that rule. Asynchronous (slow) devices such as modems often have time-out periods measured in seconds rather than milliseconds; a slow return from a RasDialFunc2 function is generally not a problem. The prompt return requirement also does not apply when dwError is nonzero, indicating that an error has occurred. It is safe, for example, to put up an error dialog box and wait for user input.

The RasDialFunc2 implementation should not depend on the order or occurrence of particular RASCONNSTATE connection states, because this may vary between platforms.

Do not call the RasDial function from within a RasDialFunc2 callback function. Call the RasGetConnectStatus, RasEnumEntries, RasEnumConnections, RasGetErrorString, and RasHangUp functions from within the callback function. For example, calling RasGetConnectStatus from within a callback function would be useful for determining the name and type of the connecting device.

Note For convenience, RasHangUp can be called from within a RasDialFunc2 callback function. However, much of the hang-up processing occurs after the RasDialFunc2 callback function has returned.

RasDialFunc2 is a placeholder for the application-defined or library-defined function name.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasDial, RasDialFunc, RasDialFunc1, RASCONNSTATE, RasEnumConnections, RasEnumEntries, RasGetConnectStatus, RasGetErrorString, RasHangUp


RasEditPhonebookEntry

The RasEditPhonebookEntry function edits an existing phone-book entry. The function displays a dialog box in which the user can modify the existing information.

Windows NT/2000 or later: The RasEditPhonebookEntry function calls the RasEntryDlg function. Applications written for Windows NT version 4.0 should use RasEntryDlg.

DWORD RasEditPhonebookEntry(
  HWND hwnd,             // handle to the parent window of
                         //  the dialog box
  LPCTSTR lpszPhonebook, // pointer to the full path and
                         //  file name of the phone-book file
  LPCTSTR lpszEntryName  // pointer to the phone-book entry name
);

Parameters

hwnd
[in] Handle to the parent window of the dialog box.
lpszPhonebook
[in] Windows NT/2000 or later: Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.

Windows 95: Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.

lpszEntryName
[in] Pointer to a null-terminated string that specifies the name of an existing entry in the phone-book file.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value can be one of the following error codes.

Value | Description
ERROR_BUFFER_INVALID | The phone-book entry buffer is invalid.
ERROR_CANNOT_OPEN_PHONEBOOK | The phone book is corrupted or missing components.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY | The phone-book entry does not exist.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasCreatePhonebookEntry, RasEntryDlg, RasGetEntryDialParams, RasSetEntryDialParams


RasEntryDlg

The RasEntryDlg function displays modal property sheets that allow a user to manipulate phone-book entries. If editing or copying an existing phone-book entry, the function displays a phone-book entry property sheet. The RasEntryDlg function returns when the user closes the property sheet.

BOOL RasEntryDlg(
  LPTSTR lpszPhonebook, // pointer to the full path and
                        //  file name of the phone-book file
  LPTSTR lpszEntry,     // pointer to the name of the phone-book
                        //  entry to edit, copy, or create
  LPRASENTRYDLG lpInfo  // pointer to a structure that
                        //  contains additional parameters
);

Parameters

lpszPhonebook
[in] Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
[in] Pointer to a null-terminated string that specifies the name of the phone-book entry to edit, copy, or create.

If you are editing or copying an entry, this parameter is the name of an existing phone-book entry. If you are copying an entry, set the RASEDFLAG_CloneEntry flag in the dwFlags member of the RASENTRYDLG structure.

If you are creating an entry, this parameter is a default new entry name that the user can change. If this parameter is NULL, the function provides a default name. If you are creating an entry, set the RASEDFLAG_NewEntry flag in the dwFlags member of the RASENTRYDLG structure.

lpInfo
[in] Pointer to a RASENTRYDLG structure that specifies additional input and output parameters. The dwSize member of this structure must specify sizeof(RASENTRYDLG). Use the dwFlags member to indicate whether you are creating, editing, or copying an entry. If an error occurs, the dwError member returns an error code; otherwise, it returns zero.

Return Values

If the user creates, copies, or edits a phone-book entry, the return value is a nonzero value.

If an error occurs, or if the user cancels the operation, the return value is zero. If an error occurs, the dwError member of the RASENTRYDLG structure returns a nonzero system error code or RAS error code.

Remarks

The RasCreatePhonebookEntry and RasEditPhonebookEntry functions call the RasEntryDlg function.

The following sample code brings up a property sheet to create a new entry. The lpszEntry variable specifies the default name for the new entry.

lpInfo = (LPRASENTRYDLG) GlobalAlloc(GPTR, sizeof(RASENTRYDLG));
ZeroMemory(lpInfo, sizeof(RASENTRYDLG));
lpInfo->dwSize = sizeof(RASENTRYDLG);

lpInfo->dwFlags |= RASEDFLAG_NewEntry;
nRet = RasEntryDlg(NULL, lpszEntry, lpInfo);

if (nRet)
    printf("New entry created: %s\n", lpInfo->szEntry);
else
{
    if (lpInfo->dwError != 0)
    {
        printf("RasEntryDlg failed: Error = %d\n", lpInfo->dwError);
    }
    else
        printf("User pressed Cancel\n");
}

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Rasdlg.h.
Library: Use Rasdlg.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasCreatePhonebookEntry, RasEditPhonebookEntry, RASENTRYDLG


RasEnumAutodialAddresses

The RasEnumAutodialAddresses function returns a list of all addresses in the AutoDial mapping database.

DWORD RasEnumAutodialAddresses(
  LPTSTR *lppAddresses,    // pointer to buffer that
                           //  receives network address strings
  LPDWORD lpdwcbAddresses, // pointer to size, in bytes,
                           //  of the buffer
  LPDWORD lpdwcAddresses   // pointer to number of strings returned
);

Parameters

lppAddresses
[in, out] Pointer to an array of string pointers, with additional space for the storage of the strings themselves at the end of the buffer.

On output, each string receives the name of an address in the AutoDial mapping database.

If lppAddresses is NULL on input, RasEnumAutodialAddresses sets the lpdwcbAddresses and lpdwcAddresses parameters to indicate the required size, in bytes, and the number of address entries in the database.

lpdwcbAddresses
[in, out] Pointer to a variable that, on input,contains the size, in bytes, of the buffer specified by the lppAddresses parameter.

On output, the function sets this variable to the number of bytes returned, or the number of bytes required if the buffer is too small.

lpdwcAddresses
[out] Pointer to a variable that receives the number of address strings returned in the lppAddresses buffer.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is the following error code.

Value | Meaning
ERROR_INVALID_PARAMETER | NULL was passed for the lpdwcbAddresses or lpdwcAddresses parameter.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RASAUTODIALENTRY, RasGetAutodialAddress, RasSetAutodialAddress


RasEnumConnections

The RasEnumConnections function lists all active RAS connections. It returns each connection's handle and phone-book entry name.

DWORD RasEnumConnections(
  LPRASCONN lprasconn,   // buffer to receive connections data
  LPDWORD lpcb,          // size in bytes of buffer
  LPDWORD lpcConnections // number of connections written to buffer
);

Parameters

lprasconn
[in, out] Pointer to a buffer that receives, on output,an array of RASCONN structures, one for each RAS connection.

On input, an application must set the dwSize member of the first RASCONN structure in the buffer to sizeof(RASCONN) in order to identify the version of the structure being passed.

lpcb
[in, out] Pointer to a variable that, on input, contains the size, in bytes, of the buffer specified by lprasconn.

On output, the function sets this variable to the number of bytes required to enumerate the RAS connections.

lpcConnections
[out] Pointer to a variable that receives the number of RASCONN structures written to the buffer specified by lprasconn.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is either a nonzero error value listed in the RAS header file or ERROR_BUFFER_TOO_SMALL or ERROR_NOT_ENOUGH_MEMORY.

Remarks

If a connection was made without specifying a phone-book entry name, the information returned for that connection gives the connection phone number preceded by ".".

The following sample code enumerates the current RAS connection. This code assumes that, at most, only one connection is currently active. Note that the code sets the dwSize member of the RASCONN structure to specify the version of the structure.

RASCONN * lpRasConn;
DWORD     lpcb;
DWORD     lpcConnections;

lpRasConn = (LPRASCONN) GlobalAlloc(GPTR, sizeof(RASCONN));
lpRasConn->dwSize = sizeof(RASCONN);
lpcb = sizeof(RASCONN);

nRet = RasEnumConnections(lpRasConn, &lpcb, &lpcConnections);
if (nRet != 0)
{
    printf("RasEnumConnections failed: Error = %d", nRet);
}
else
{
    printf("The following RAS connections are currently active\n\n");
    for (i = 0; i < lpcConnections; i++)
    {
        printf("Entry name: %s\n", lpRasConn->szEntryName);
        lpRasConn++;
    }
}

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RASCONN, RasEnumEntries, RasGetConnectStatus


RasEnumDevices

The RasEnumDevices function returns the name and type of all available RAS-capable devices.

DWORD RasEnumDevices(
  LPRASDEVINFO lpRasDevInfo,  // buffer to receive
                              //  information about RAS devices
  LPDWORD lpcb,               // size, in bytes, of the buffer
  LPDWORD lpcDevices          // receives the number of
                              //  entries written to the buffer
);

Parameters

lpRasDevInfo
[in] Pointer to a buffer that receives an array of RASDEVINFO structures, one for each RAS-capable device. Before calling the function, set the dwSize member of the first RASDEVINFO structure in the buffer to sizeof(RASDEVINFO) to identify the version of the structure.
lpcb
[in, out] Pointer to a variable that, on input,contains the size, in bytes, of the lpRasDevInfo buffer.

On output, the function sets this variable to the number of bytes required to enumerate the devices.

To determine the required buffer size, call RasEnumDevices with the lpRasDevInfo parameter set to NULL and the variable pointed to by lpcb set to zero. The function returns the required buffer size in the variable pointed to by lpcb. (See sample code under Remarks section.)

lpcDevices
[out] Pointer to a variable that receives the number of RASDEVINFO structures written to the lpRasDevInfo buffer.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero RAS error value or one of following error codes.

Value | Meaning
ERROR_BUFFER_TOO_SMALL | The lpRasDevInfo buffer is not large enough. The function returns the required buffer size in the variable pointed to by lpcb.
ERROR_NOT_ENOUGH_MEMORY | Indicates insufficient memory.
ERROR_INVALID_PARAMETER | Indicates an invalid parameter value.
ERROR_INVALID_USER_BUFFER | The address or buffer specified by lpRasDevInfo is invalid.

Remarks

The following sample code enumerates the devices on the current machine. The code initially calls RasEnumDevices with a lpRasDevInfo parameter of NULL, to obtain the size of the buffer that should be passed in. The code also sets the dwSize member of the first RASDEVINFO structure to sizeof(RASDEVINFO) to specify the version of the structure.

RasEnumDevices(NULL, &lpcb, &lpcDevices);
lpRasDevInfo = (LPRASDEVINFO) GlobalAlloc(GPTR, lpcb);
lpRasDevInfo->dwSize = sizeof(RASDEVINFO);

nRet = RasEnumDevices(lpRasDevInfo, &lpcb, &lpcDevices);
if (nRet != 0)
{
    printf("RasEnumDevices failed: Error %d", nRet);
}
else
{
    printf("The following RAS capable devices were found on this machine:\n\n");
    for (i=0; i < lpcDevices; i++)
    {
        printf("%s\n",lpRasDevInfo->szDeviceName);
        lpRasDevInfo++;
    }
}

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 OSR2 or later.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RASDEVINFO


RasEnumEntries

The RasEnumEntries function lists all entry names in a remote access phone book.

DWORD RasEnumEntries (
  LPCTSTR reserved,              // reserved, must be NULL
  LPTCSTR lpszPhonebook,         // pointer to full path and
                                 //  file name of phone-book file
  LPRASENTRYNAME lprasentryname, // buffer to receive
                                 //  phone-book entries
  LPDWORD lpcb,                  // size in bytes of buffer
  LPDWORD lpcEntries             // number of entries written
                                 //  to buffer
);

Parameters

reserved
[in] Reserved; must be NULL.
lpszPhonebook
[in] Windows NT/2000 or later: Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.

Windows 2000 or later: If this paramter is NULL, the entries are enumerated from all the remote access phone-book files in the AllUsers profile and the user's profile.

Windows 95: This parameter is ignored. Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.

lprasentryname
[in, out] Pointer to a buffer that, on output,receives an array of RASENTRYNAME structures, one for each phone-book entry.

On input, an application must set the dwSize member of the first RASENTRYNAME structure in the buffer to sizeof(RASENTRYNAME) in order to identify the version of the structure being passed.

lpcb
[in, out] Pointer to a variable that, on input,contains the size, in bytes, of the buffer specified by lprasentryname.

On output, the function sets this variable to the number of bytes required to successfully complete the call.

lpcEntries
[out] Pointer to a variable that receives to the number of phone-book entries written to the buffer specified by lprasentryname.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero error value listed in the RAS header file or one of the following values.

Value | Meaning
ERROR_BUFFER_TOO_SMALL | The buffer pointed to by the lprasentryname parameter is not large enough to hold all the entries.
ERROR_INVALID_SIZE | The value of dwSize in the RASENTRYNAME structure pointed to by lprasentryname, specifies a version of the structure that is not supported on the current platform. For example, on Windows 95, RasEnumEntries returns this error if dwSize indicates that RASENTRYNAME includes the dwFlags and szPhonebookPath members, since these members are not supported on Windows 95 (they are supported only on Windows 2000 and later).
ERROR_NOT_ENOUGH_MEMORY | The function could not allocate sufficient memory to complete the operation.

Remarks

The following sample code enumerates the RAS phone-book entries on the current machine. The code initially calls RasEnumEntries to obtain the size of the buffer to pass in. The code then calls RasEnumEntries again, to enumerate the entries. Note that for both calls, the code sets the dwSize member of the first RASENTRY structure in the buffer to sizeof(RASENTRY) to specify the structure version.

lpRasEntryName = (LPRASENTRYNAME)GlobalAlloc(GPTR, sizeof(RASENTRYNAME));
lpRasEntryName->dwSize = sizeof(RASENTRYNAME);
if ((nRet = RasEnumEntries(NULL, NULL, lpRasEntryName, &cb, &cEntries))
    == ERROR_BUFFER_TOO_SMALL)
{
    lpRasEntryName = (LPRASENTRYNAME)GlobalAlloc(GPTR, cb);
    lpRasEntryName->dwSize = sizeof(RASENTRYNAME);
}

// Calling RasEnumEntries to enumerate the phone-book entries
nRet = RasEnumEntries(NULL, NULL, lpRasEntryName, &cb, &cEntries);

if (nRet != ERROR_SUCCESS)
{
    printf("RasEnumEntries failed: Error %d\n", nRet);
}
else
{
    printf("Phone-book entries in the default phone book:\n\n");
    for(i=0;i < cEntries;i++)
    {
        printf("%s\n",lpRasEntryName->szEntryName);
        lpRasEntryName++;
    }
}

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RASENTRYNAME, RasEnumConnections


RasFreeEapUserIdentity

Use the RasFreeEapUserIdentity function to free the memory buffer returned by RasGetEapUserIdentity.

DWORD RasFreeEapUserIdentity(
  LPRASEAPUSERIDENTITY pRasEapUserIdentity  // pointer to memory to free
);

Parameters

pRasEapUserIdentity
[in] Pointer to the RASEAPUSERIDENTITY structure returned by the RasGetEapUserIdenity function. RasFreeEapUserIdentity frees the memory occupied by this structure.

Return Values

If the function succeeds, the return value is NO_ERROR.

Otherwise, the function returns an error code from raserror.h or winerror.h.

Remarks

RasFreeEapUserIdentity may be called with the pRasEapUserIdentity parameter equal to NULL.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

RASEAPUSERIDENTITY, RasGetEapUserIdentity


RasGetAutodialAddress

The RasGetAutodialAddress function retrieves information about all the AutoDial entries associated with a network address in the AutoDial mapping database.

DWORD RasGetAutodialAddress(
  LPCTSTR lpszAddress,   // pointer to a network address string
  LPDWORD lpdwReserved,  // reserved; must be NULL
  LPRASAUTODIALENTRY lpAutoDialEntries,
                         // pointer to buffer for AutoDial entry data
  LPDWORD lpdwcbAutoDialEntries,
                         // pointer to size, in bytes, of buffer
  LPDWORD lpdwcAutoDialEntries
                         // pointer to number of entries returned
);

Parameters

lpszAddress
[in] Pointer to a null-terminated string that specifies the address for which information is requested. This can be an IP address, Internet host name ("www.microsoft.com"), or NetBIOS name ("products1").

Whistler or later: If this parameter is NULL, the function retrieves the default Internet connection. The function returns the per-user default Internet connection if one is configured. Otherwise, the function returns the global default Internet connection. If no default Internet connections are configured, the function returns zero for the lpdwcbAutoDialEntries and lpdwcAutoDialEntries parameters.

lpdwReserved
[in] Reserved; must be NULL.
lpAutoDialEntries
[in, out] Pointer to a buffer that, on output, receives an array of RASAUTODIALENTRY structures, one for each AutoDial entry associated with the address specified by the lpszAddress parameter.

On input, set the dwSize member of the first RASAUTODIALENTRY structure in the buffer to sizeof(RASAUTODIALENTRY) to identify the version of the structure.

If lpAutoDialEntries is NULL, RasGetAutodialAddress sets the lpdwcbAutoDialEntries and lpdwcAutoDialEntries parameters to indicate the required buffer size, in bytes, and the number of AutoDial entries.

lpdwcbAutoDialEntries
[in, out] Pointer to a variable that, on input, specifies the size, in bytes, of the lpAutoDialEntries buffer.

On output, this variable receives the number of bytes returned, or the number of bytes required if the buffer is too small.

lpdwcAutoDialEntries
[out] Pointer to a variable that receives the number of structure elements returned in the lpAutoDialEntries buffer.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_XXX_NOT_FOUND | The address was not found in the mapping database.
ERROR_INVALID_SIZE | The dwSize member of the RASAUTODIALENTRY structure is an invalid value.
ERROR_INVALID_PARAMETER | The lpszAddress, lpdwcbAutoDialEntries, or lpdwcAutoDialEntries parameter was NULL.

Remarks

Whistler or later: The Remote Access Service (RAS) supports default Internet connections. RAS supports a default Internet connection that is global to the local computer, and in addition, supports a default Internet connection for each user.

The name of the global default Internet connection is stored in the registry below the following registry key:

HKEY_LOCAL_MACHINE\Software\Microsoft\Ras Autodial\Default

The value that stores the name of the connection is:

DefaultInternet

This value is of type REG_SZ.

The global default Internet connection must be configured as a "For all users" connection in the Connections Folder user interface.

The name of the per-user default Internet connection is stored in the registry below the following registry key:

HKEY_CURRENT_USER\Software\Microsoft\Ras Autodial\Default

The value that stores the name of the connection is:

DefaultInternet

This value is of type REG_SZ.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RASAUTODIALENTRY, RasEnumAutodialAddresses, RasSetAutodialAddress


RasGetAutodialEnable

The RasGetAutodialEnable function indicates whether the AutoDial feature is enabled for a specified TAPI dialing location. For more information about TAPI dialing locations, see the TAPI Programmer's Reference in the Platform SDK.

DWORD RasGetAutodialEnable(
  DWORD dwDialingLocation,
                     // identifier of the TAPI dialing location
  LPBOOL lpfEnabled  // pointer to variable that receives
                     //  AutoDial state for this location
);

Parameters

dwDialingLocation
[in] Specifies the identifier of a TAPI dialing location.
lpfEnabled
[out] Pointer to a BOOL variable that receives a nonzero value if AutoDial is enabled for the specified dialing location, or zero if it is not enabled.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero value.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasSetAutodialEnable


RasGetAutodialParam

The RasGetAutodialParam function retrieves the value of an AutoDial parameter.

DWORD RasGetAutodialParam(
  DWORD dwKey,         // indicates the parameter to retrieve
  LPVOID lpvValue,     // pointer to a buffer that receives the value
  LPDWORD lpdwcbValue  // size, in bytes, of the buffer
);

Parameters

dwKey
[in] Specifies the AutoDial parameter to retrieve. This parameter can be one of the following values.
Value | Meaning
RASADP_DisableConnectionQuery | The lpvValue parameter returns a DWORD value. If this value is zero (the default), AutoDial displays a dialog box to query the user before creating a connection. If this value is 1, and the AutoDial database has the phone-book entry to dial, AutoDial creates a connection without displaying the dialog box.
RASADP_LoginSessionDisable | The lpvValue parameter returns a DWORD value. If this value is 1, the system disables all AutoDial connections for the current logon session. If this value is zero (the default), AutoDial connections are enabled. The AutoDial system service changes this value to zero when a new user logs on to the workstation.
RASADP_SavedAddressesLimit | The lpvValue parameter returns a DWORD value that indicates the maximum number of addresses that AutoDial stores in the registry. AutoDial first stores addresses that it used to create an AutoDial connection; then it stores addresses that it learned after a RAS connection was created. Addresses written using the RasSetAutodialAddress function are always saved, and are not included in calculating the limit. The default value is 100.
RASADP_FailedConnectionTimeout | The lpvValue parameter returns a DWORD value that indicates a time-out value, in seconds. When an AutoDial connection attempt fails, the AutoDial system service disables subsequent attempts to reach the same address for the time-out period. This prevents AutoDial from displaying multiple connection dialog boxes for the same logical request by an application. The default value is 5.
RASADP_ConnectionQueryTimeout | The lpvValue parameter points to a DWORD value that indicates a time-out value, in seconds. Before attempting an AutoDial connection, the system will display a dialog asking the user to confirm that the system should dial. The dialog has a countdown timer that will terminate the dialog with a "Do not dial" selection if the user takes no action. The DWORD value pointed to by lpvValue specifies the initial time on this countdown timer.

lpvValue
[out] Pointer to a buffer that receives the value for the specified parameter.
lpdwcbValue
[in, out] Pointer to a DWORD value.

On input, set this value to indicate the size, in bytes, of the lpvValue buffer.

On output, this value indicates the actual size of the value written to the buffer.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | The dwKey or lpvValue parameter is invalid.
ERROR_INVALID_SIZE | The size specified by the lpdwcbValue is too small.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasSetAutodialAddress, RasSetAutodialParam


RasGetConnectionStatistics

The RasGetConnectionStatistics function retrieves accumulated connection statistics for the specified connection.

DWORD RasGetConnectionStatistics(
  HRASCONN hRasConn,       // handle to the connection
  RAS_STATS *lpStatistics  // buffer to receive statistics
);

Parameters

hRasConn,
[in] Handle to the connection. Use RasDial or RasEnumConnections to obtain this handle.
lpStatistics
[in, out] Pointer to the RAS_STATS structure that, on output, receives the statistics.

On input, set the dwSize member of this structure to sizeof(RAS_STATS).

This parameter cannot be NULL.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
E_INVALID_ARG | At least one of the following is true: the hRasConn parameter is zero, the lpStatistics parameter is NULL, or the value specified by the dwSize member of the RAS_STATS structure specifies a version of the structure that is not supported by the operating system in use.
ERROR_NOT_ENOUGH_MEMORY | The function could not allocate sufficient memory to complete the operation.
Other | Use FormatMessage to retrieve the system error message that corresponds to the error code returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasClearConnectionStatistics, RasDial, RasEnumConnections, RasGetLinkStatistics


RasGetConnectStatus

The RasGetConnectStatus function retrieves information on the current status of the specified remote access connection. An application can use this call to determine when an asynchronous RasDial call is complete.

DWORD RasGetConnectStatus(
  HRASCONN hrasconn,  // handle to RAS connection of interest
  LPRASCONNSTATUS lprasconnstatus
                      // buffer to receive status data
);

Parameters

hrasconn
[in] Specifies the remote access connection for which to retrieve the status. This handle must have been obtained from RasDial or RasEnumConnections.
lprasconnstatus
[in, out] Pointer to the RASCONNSTATUS structure that, on output, receives the status information.

On input, set the dwSize member of the structure to sizeof(RASCONNSTATUS) in order to identify the version of the structure being passed.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero error value listed in the RAS header file or either ERROR_BUFFER_TOO_SMALL or ERROR_NOT_ENOUGH_MEMORY.

Remarks

The return value for RasGetConnectStatus is not necessarily equal to the value of the dwError member of the RASCONNSTATUS structure returned by RasGetConnectStatus. The return value of RasGetConnectStatus indicates errors that occur during the RasGetConnectStatus function call, whereas the dwError member indicates errors that prevented the connection from being established.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RASCONNSTATUS, RasDial, RasEnumConnections


RasGetCountryInfo

The RasGetCountryInfo function retrieves country-specific dialing information from the Windows Telephony list of countries.

For more information about country-specific dialing information and Telephony Application Programming Interface (TAPI) country identifiers, see the TAPI portion of the Platform SDK.

DWORD RasGetCountryInfo(
  LPRASCTRYINFO lpRasCtryInfo,
                    // buffer that receives country information
  LPDWORD lpdwSize  // size, in bytes, of the buffer
);

Parameters

lpRasCtryInfo
[in, out] Pointer to a RASCTRYINFO structure that, on output, receives the country-specific dialing information followed by additional bytes for a country description string.

On input, set the dwSize member of the structure to sizeof(RASCTRYINFO) to identify the version of the structure. Also, set the dwCountryId member to the TAPI country identifier of the country for which to get information.

Allocate at least 256 bytes for the buffer.

lpdwSize
[in, out] Pointer to a variable that, on input, specifies the size, in bytes, of the buffer pointed to by the lpRasCtryInfo parameter.

On output, this variable receives the number of bytes required.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_INVALID_USER_BUFFER | The address or buffer specified by lpRasCtryInfo is invalid.
ERROR_INVALID_PARAMETER | The dwCountryId member of the structure pointed to by lpRasCtryInfo was not a valid value.
ERROR_BUFFER_TOO_SMALL | The size of the lpRasCtryInfo buffer specified by the lpdwSize parameter was not large enough to store the information for the country identified by the dwCountryId member. The function returns the required buffer size in the variable pointed to by lpdwSize.
ERROR_TAPI_CONFIGURATION | TAPI subsystem information was corrupted.

Remarks

To enumerate information for all countries in the Windows Telephony list, set the dwCountryId member of the RASCTRYINFO structure to 1 in the initial RasGetCountryInfo call. This causes the function to return information for the first country in the list. The value returned in the dwNextCountryId member is the country identifier of the next country in the list. Use this value in repeated calls to RasGetCountryInfo until dwNextCountryID returns zero, indicating the last country in the list.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 OSR2 or later.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RASCTRYINFO


RasGetCredentials

[This is preliminary documentation and subject to change.]

The RasGetCredentials function retrieves the user credentials associated with a specified RAS phone-book entry.

DWORD RasGetCredentials(
  LPCTSTR lpszPhonebook,          // pointer to the full path and
                                  //  file name of a phone-book file
  LPCTSTR lpszEntry,              // pointer to the name of a
                                  //  phone-book entry
  LPRASCREDENTIALS lpCredentials  // pointer to structure that
                                  //  receives credentials
);

Parameters

lpszPhonebook
[in] Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
[in] Pointer to a null-terminated string that specifies the name of a phone-book entry.
lpCredentials
[in, out] Pointer to the RASCREDENTIALS structure that, on output,receives the user credentials associated with the specified phone-book entry.

On input, set the dwSize member of the structure to sizeof(RASCREDENTIALS), and set the dwMask member to indicate the credential information to retrieve. When the function returns, dwMask indicates the members that were successfully retrieved.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_CANNOT_OPEN_PHONEBOOK | The specified phone book cannot be found.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY | The specified entry does not exist in the phone book.
ERROR_INVALID_PARAMETER | The lpCredentials parameter was NULL.
ERROR_INVALID_SIZE | The dwSize member of the RASCREDENTIALS structure is an unrecognized value.

Remarks

The RasGetCredentials function retrieves the credentials of the last user in order to connect using the specified phone-book entry, or the credentials subsequently specified in a call to the RasSetCredentials function for the phone-book entry.

The RasGetCredentials function retrieves the user credentials that are stored securely for the specified phone-book entry. This function is the preferred way of securely retrieving the credentials associated with a RAS phone-book entry. RasGetCredentials supersedes the RasGetEntryDialParams function, which may not be supported in future releases of Windows 2000.

Windows 2000 and later versions: RasGetCredentials does not return the actual password. Instead, the szPassword member of the RASCREDENTIALS structure contains a handle to the saved password. Substitute this handle for the saved password in subsequent calls to RasSetCredentials and RasDial. When presented with this handle, RasDial will retrieve and use the saved password The value of this handle may change in future versions of the operating system; do not develop code that depends on the contents or format of this value.

Windows 2000 and later versions: The dwMask member of RASCREDENTIALS contains the RASCM_Password flag if the system has saved a password for the specified entry. If the system has no password saved for this entry, dwMask does not contain RASCM_Password.

Whistler or later: If the dwMask of the RASCREDENTIALS structure contains the RASCM_DefaultCreds flag, the credentials returned are the default credentials for an all-user connection.

Whistler or later: To retrieve a pre-shared key, use the RASCM_PreSharedKey flag in the RASCREDENTIALS.dwMask field.

The following sample code retrieves the credentials for the phone-book entry with the name "mazy".

ZeroMemory(&lpCred, sizeof(lpCred));
lpCred.dwSize = sizeof(RASCREDENTIALS);
lpCred.dwMask=RASCM_UserName | RASCM_Password | RASCM_Domain ;
res = RasGetCredentials(NULL, "mazy", &lpCred);
if(res == 0)
    printf("The following credentials were retreived:\n%s\n%s\n%s\n",
      lpCred.szUserName,lpCred.szPassword,lpCred.szDomain);
else
    printf("Error: %u\n",res);

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RASCREDENTIALS, RasGetEntryDialParams, RasSetCredentials


RasGetCustomAuthData

Use the RasGetCustomAuthData function to retrieve connection-specific authentication information. This information is not specific to a particular user.

DWORD RasGetCustomAuthData (
  LPCWSTR pszPhonebook,            // path to phone book to use
  LPCWSTR pszEntry,                // name of entry in phone book
  BYTE * pbCustomAuthData,         // buffer to receive data
  DWORD * pdwSizeofCustomAuthData  // size of buffer
);

Parameters

pszPhonebook
[in] Pointer to a null-terminated string that specifies the full path of the phone-book (PBK) file. If this parameter is NULL, the function will use the system phone book.
pszEntry
[in] Pointer to a null-terminated string that specifiesan existing entry name.
pbCustomAuthData
[out] Pointer to a buffer that receives the authentication data. The caller should allocate the memory for this buffer. If the buffer is not large enough, RasGetCustomAuthData will return ERROR_BUFFER_TOO_SMALL, and the pdwSizeofEapData parameter will contain the required size.
pdwSizeofCustomAuthData
[in, out] Pointer to a DWORD variable that, on input, specifiesthe size of the buffer pointed to by the pbCustomAuthData parameter.

If the buffer specified by the pbCustomAuthData parameter is not large enough, pdwSizeofEapData receives, on output, the required size.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the retun value is one of the following error codes.

Value | Meaning
E_INVALIDARG | The pdwSizeofCustomAuthData parameter is NULL.
ERROR_BUFFER_TOO_SMALL | The buffer pointed to by pbCustomAuthData is too small to receive the data. The pdwSizeofCustomAuthData contains the required size.
ERROR_CANNOT_OPEN_PHONEBOOK | RasGetEapUserData was unable to open the specified phone-book file.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY | RasGetEapUserData was unable to find the specified entry in the phone book.
Other | Use FormatMessage to retrieve the system error message that corresponds to the error code returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

RasGetEapUserData, RasSetCustomAuthData


RasGetEapUserData

Use the RasGetEapUserData function to retrieve user-specific Extensible Authentication Protocol (EAP) information for the specified phone-book entry.

DWORD RasGetEapUserData (
  HANDLE hToken,           // access token for user
  LPCTSTR pszPhonebook,    // path to phone book to use
  LPCTSTR pszEntry,        // name of entry in phone book
  BYTE *pbEapData,         // retrieved data for the user
  DWORD *pdwSizeofEapData  // size of retrieved data
);

Parameters

hToken
[in] Handle to a primary or impersonation access token that represents the user for which to retrieve data. This parameter can be NULL if the function is called from a process already running in the user's context.
pszPhonebook
[in] Pointer to a null-terminated string that specifies the full path of the phone-book (PBK) file. If this parameter is NULL, the function will use the system phone book.
pszEntry
[in] Pointer to a null-terminated string that specifies an existing entry name.
pbEapData
[out] Pointer to a buffer that receives the retrieved EAP data for the user. The caller should allocate the memory for this buffer. If the buffer is not large enough, RasGetEapUserData will return ERROR_BUFFER_TOO_SMALL, and the pdwSizeofEapData parameter will contain the required size.
pdwSizeofEapData
[in, out] Pointer to a DWORD variable that, on input, specifies the size of the buffer pointed to by the pbEapData parameter.

If the buffer specified by the pbEapData parameter is not large enough, pdwSizeofEapData receives, on output, the required size.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the retun value is one of the following error codes.

Value | Meaning
E_INVALIDARG | The pdwSizeofEapData parameter is NULL.
ERROR_BUFFER_TOO_SMALL | The buffer pointed to by pbEapData is too small to receive the data. The pdwSizeofEapData contains the required size.
ERROR_CANNOT_OPEN_PHONEBOOK | RasGetEapUserData was unable to open the specified phone-book file.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY | RasGetEapUserData was unable to find the specified entry in the phone book.
Other | Use FormatMessage to retrieve the system error message that corresponds to the error code returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasSetEapUserData, RASEAPINFO


RasGetEapUserIdentity

The RasGetEapUserIdentity function retrieves identity information for the current user. Use this information to call RasDial with a phone-book entry that requires Extensible Authentication Protocol (EAP).

DWORD RasGetEapUserIdentity(
  LPCSTR pszPhonebook,    // path to phone book to use
  LPCSTR pszEntry,        // name of entry in phone book
  DWORD dwFlags,          // flags that qualify authentication
  HWND hwnd,              // handle to UI parent
  LPRASEAPUSERIDENTITY * ppRasEapUserIdentity,
                          // identity info
);

Parameters

pszPhonebook
[in] Pointer to a null-terminated string that specifies the full path of the phone-book (PBK) file. If this parameter is NULL, the function uses the system phone book.
pszEntry
[in] Pointer to a null-terminated string that specifies an existing entry name.
dwFlags
[in] Specifies zero or more of the following flags that qualify the authentication process.
Flag | Description
RASEAPF_NonInteractive | Specifies that the authentication protocol should not bring up a graphical user-interface. If this flag is not present, it is okay for the protocol to display a user interface.
RASEAPF_Logon | Specifies that the user data is obtained from Winlogon.
RASEAPF_Preview | Specifies that the user should be prompted for identity information before dialing.

hwnd
[in] Handle to the parent window for the UI dialog. If the fInvokeUI parameter is FALSE, then hwnd should be NULL.
ppRasEapUserIdentity
[out] Pointer to a pointer that, on successful return, receives the addressof the RASEAPUSERIDENTITY structure that contains EAP user identity information. RasGetEapUserIdentity allocates the memory buffer for the RASEAPUSERIDENTITY structure. Free this memory by calling RasFreeEapUserIdentity.

Return Values

If the function succeeds, the return value is NO_ERROR.

Otherwise, the function will return one of the following error codes.

Value | Meaning
E_INVALID_ARG | The pcbEapUserIdentity parameter is NULL.
ERROR_INTERACTIVE_MODE | The function was called with the RASEAPF_NonInteractive flag. However, the authentication protocol must display a UI in order to obtain the required identity information from the user.
ERROR_INVALID_FUNCTION_FOR_ENTRY | Either the authentication method for this phone-book entry is not EAP, or the authentication method is EAP but the protocol uses the standard Windows NT/Windows 2000 credentials dialog to obtain user identity information. In either case, the caller does not need to pass EAP identity information to RasDial.
ERROR_RASMAN_CANNOT_INITIALIZE | The Remote Access Service failed to initialize properly.
Other | Use FormatMessage to retrieve the system error message that corresponds to the error code returned.

Remarks

RasGetEapUserIdentiy calls the RAS function RasGetEapUserData and the EAP function RasEapGetIdentity. RasEapGetIdentity is implemented by the authentication protocol.

If the function succeeds, that is the return value is NO_ERROR, the caller should copy the EAP identity information from the structure pointed to by ppRasEapUserIdentity to the RASDIALPARAMS and RASDIALEXTENSIONS structures used in the call to RasDial. The following sample code demonstrates how to copy the identity information.

lstrcpy(DialParms.szUserName, pRasEapUserIdentity->szUserName);
pDialExts->RasEapInfo.dwSizeofEapInfo = pRasEapUserIdentity->dwSizeofEapInfo;
pDialExts->RasEapInfo.pbEapInfo = pRasEapUserIdentity->pbEapInfo;

If the remote access application being developed has a graphical user interface, the caller of RasGetEapUserIdentity should not specify the RASEAPF_NonInteractive flag. If the application has a command-line user interface, the caller may want to specify the RASEAPF_NonInteractive flag to prevent the authentication protocol from displaying a graphical user interface.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

RASEAPUSERIDENTITY, RasDial, RasEapGetIdentity, RasFreeEapUserIdentity, RasGetEapUserData, RasSetEapUserData


RasGetEntryDialParams

The RasGetEntryDialParams function retrieves the connection information saved by the last successful call to the RasDial or RasSetEntryDialParams function for a specified phone-book entry.

DWORD RasGetEntryDialParams(
  LPCTSTR lpszPhonebook,  // pointer to the full path and
                          //  file name of the phone-book file
  LPRASDIALPARAMS lprasdialparams,
                          // pointer to a structure that
                          //  receives the connection parameters
  LPBOOL lpfPassword      // indicates whether the user's
                          //  password was retrieved
);

Parameters

lpszPhonebook
[in] Windows NT/2000 or later: Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.

Windows 95: Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.

lprasdialparams
[in, out] Pointer to the RASDIALPARAMS structure.

On input, the dwSize member specifiesthe size of the RASDIALPARAMS structure, and the szEntryName member specifies a valid phone-book entry.

On output, the structure receives the connection parameters associated with the specified phone-book entry.

Note that the szPhoneNumber member of the structure does not receive the phone number associated with the phone-book entry. To get the phone number associated with a phone-book entry, call the RasGetEntryProperties function.

Windows 2000 and later versions: RasGetEntryDialParams does not return the actual password. Instead, the szPassword member of the RASDIALPARAMS structure contains a handle to the saved password. Substitute this handle for the saved password in subsequent calls to RasSetEntryDialParams and RasDial. When presented with this handle, RasDial will retrieve and use the saved password. The value of this handle may change in future versions of the operating system; do not develop code that depends on the contents or format of this value.

lpfPassword
[out] Pointer to a flag that indicates whether the function retrieved the password associated with the user name for the phone-book entry. The function sets this flag to TRUE if the user's password was returned in the szPassword member of the RASDIALPARAMS structure pointed to by lprasdialparams.

Windows 2000 and later: The lpfPassword parameter is TRUE if the system has saved a password for the specified entry. If the system has no password saved for this entry, lpfPassword is FALSE.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is one of the following error codes.

Value | Description
ERROR_BUFFER_INVALID | The lprasdialparams or lpfPassword pointer is invalid, or the lprasdialparams buffer is invalid.
ERROR_CANNOT_OPEN_PHONEBOOK | The phone book is corrupted or missing components.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY | The phone-book entry does not exist.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasDial, RASDIALPARAMS, RasCreatePhonebookEntry, RasEditPhonebookEntry, RasSetEntryDialParams


RasGetEntryProperties

The RasGetEntryProperties function retrieves the properties of a phone-book entry.

DWORD RasGetEntryProperties(
  LPCTSTR lpszPhonebook,      // pointer to full path and
                              //  file name of phone-book file
  LPCTSTR lpszEntry,          // pointer to an entry name
  LPRASENTRY lpRasEntry,      // buffer that receives entry information
  LPDWORD lpdwEntryInfoSize,  // size, in bytes, of the
                              //  lpRasEntry buffer
  LPBYTE lpbDeviceInfo,       // buffer that receives
                              //  device-specific configuration information
  LPDWORD lpdwDeviceInfoSize  // size, in bytes, of the
                              //  lpbDeviceInfo buffer
);

Parameters

lpszPhonebook
[in] Windows NT/2000 or later: Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
[in] Pointer to a null-terminated string that specifies an existing entry name. If an empty string is specified, the function returns default values in the buffers pointed to by the lpRasEntry and lpbDeviceInfo parameters.
lpRasEntry
[in, out] Pointer to a RASENTRY structure followed by additional bytes for the alternate phone number list, if there is one.

On output, the structure receives the connection data associated with the phone-book entry specified by the lpszEntry parameter.

On input, set the dwSize member of the structure to sizeof(RASENTRY) to identify the version of the structure.

This parameter can be NULL.

lpdwEntryInfoSize
[in, out] Pointer to a variable that, on input,specifies the size, in bytes, of the lpRasEntry buffer.

On output, this variable receives the number of bytes required.

This parameter can be NULL if the lpRasEntry parameter is NULL.

To determine the required buffer size, call RasGetEntryProperties with lpRasEntry set to NULL and *lpdwEntryInfoSize set to zero. The function returns the required buffer size in *lpdwEntryInfoSize.

lpbDeviceInfo
[out] Pointer to a buffer that receives device-specific configuration information. Do not directly manipulate this opaque TAPI device information. For more information about TAPI device configuration, see the lineGetDevConfig function in the TAPI Programmer's Reference in the Platform SDK.

This parameter can be NULL.

Windows NT/2000 or later: This parameter is unused. The calling function should set this parameter to NULL.

lpdwDeviceInfoSize
[in, out] Pointer to a variable that, on input, specifies the size, in bytes, of the buffer specified by the lpbDeviceInfo parameter.

On output, this variable receivesthe number of bytes required.

This parameter can be NULL if the lpbDeviceInfo parameter s NULL.

To determine the required buffer size, call RasGetEntryProperties with lpbDeviceInfo set to NULL and *lpdwDeviceInfoSize set to zero. The function returns the required buffer size in *lpdwDeviceInfoSize.

Windows NT/2000 or later: This parameter is unused. The calling function should set this parameter to NULL.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | The function was called with an invalid parameter.
ERROR_INVALID_SIZE | The value of the dwSize member of the lpRasEntry is too small.
ERROR_BUFFER_INVALID | The address or buffer specified by lpRasEntry is invalid.
ERROR_BUFFER_TOO_SMALL | The buffer size indicated in lpdwEntryInfoSize is too small.
ERROR_CANNOT_OPEN_PHONEBOOK | The phone book is corrupted or is missing components.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY | The phone-book entry does not exist.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 OSR2 or later.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RASENTRY, RasSetEntryProperties


RasGetErrorString

The RasGetErrorString function obtains an error message string for a specified RAS error value.

DWORD RasGetErrorString(
  UINT uErrorValue,        // error to get string for
  LPTSTR lpszErrorString,  // buffer to hold error string
  DWORD cBufSize           // size, in characters, of buffer
);

Parameters

uErrorValue
[in] Specifies the error value of interest. These are values returned by one of the RAS functions: those listed in the RAS header file.
lpszErrorString
[out] Pointer to a buffer that receives the error string. This parameter must not be NULL.
cBufSize
[in] Specifies the size, in characters, of the buffer pointed to by lpszErrorString.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero error value. This value is ERROR_INVALID_PARAMETER or the GetLastError value returned from the functions GlobalAlloc or LoadString. The function does not set a thread's last error information; that is, there is no GetLastError information set by the RasGetErrorString function.

Remarks

There is no way to determine in advance the exact size in characters of an error message, and thus the size of buffer required. Error messages will generally be 80 characters or fewer in size; a buffer size of 256 characters will always be adequate. A buffer of insufficient size causes the RasGetErrorString function to fail, returning ERROR_INSUFFICIENT_BUFFER. Note that buffer sizes are specified in characters, not bytes; thus, the Unicode version of RasGetErrorString requires a 512 byte buffer to guarantee that every error message will fit.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, GlobalAlloc, LoadString


RasGetLinkStatistics

The RasGetLinkStatistics function retrieves accumulated statistics for the specified link in a RAS multilink connection.

DWORD RasGetLinkStatistics (
  HRASCONN hRasConn,      // handle to connection
  DWORD dwSubEntry,       // SubEntry for link
  RAS_STATS *lpStatistics // buffer to receive statistics
);

Parameters

hRasConn
[in] Handle to the connection. Use RasDial or RasEnumConnections to obtain this handle.
dwSubEntry
[in] Specifies the subentry that corresponds to the link for which to retrieve statistics.
lpStatistics
[in, out] Pointer to the RAS_STATS structure that, on output, receives the statistics.

On input, the dwSize member of this structure specifies the size of RAS_STATS. Use sizeof(RAS_STATS) to obtain this size.

This parameter cannot be NULL.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
E_INVALID_ARG | At least one of the following is true: the hRasConn parameter is zero, the dwSubEntry parameter is zero, the lpStatistics parameter is NULL, or the value specified by the dwSize member of the RAS_STATS structure specifies a version of the structure that is not supported by the operating system in use.
ERROR_NOT_ENOUGH_MEMORY | The function could not allocate sufficient memory to complete the operation.
Other | Use FormatMessage to retrieve the system error message that corresponds to the error code returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasClearLinkStatistics, RasDial, RasEnumConnections, RasGetConnectionStatistics


RasGetProjectionInfo

The RasGetProjectionInfo function obtains information about a remote access projection operation for a specified remote access component protocol.

DWORD RasGetProjectionInfo(
  HRASCONN hrasconn,            // handle that specifies
                                //  remote access connection of interest
  RASPROJECTION rasprojection,  // specifies type of
                                //  projection information to obtain
  LPVOID lpprojection,          // points to buffer that
                                //  receives projection information
  LPDWORD lpcb                  // points to variable that
                                //  specifies buffer size
);

Parameters

hrasconn
[in] Handle to the remote access connection of interest. An application obtains a RAS connection handle from the RasDial or RasEnumConnections function.
rasprojection
[in] Specifies the RASPROJECTION enumerated type value that identifies the protocol of interest.

Whistler or later: The RASP_Amb and RASP_PppNbf values are not supported.

Windows 2000 64-bit Edition: The RASP_PppIpx value is not supported.

lpprojection
[out] Pointer to a buffer that receives the information specified by the rasprojection parameter. The information will be in a structure appropriate to the rasprojection value.
rasprojection value | Data structure
RASP_Amb | RASAMB
RASP_PppCcp | RASPPPCCP
RASP_PppIp | RASPPPIP
RASP_PppIpx | RASPPPIPX
RASP_PppLcp | RASPPPLCP
RASP_PppNbf | RASPPPNBF
RASP_Slip | RASPSLIP

Whistler or later: The RASAMB and RASPPPNBF structures are not supported.

Windows 2000 64-bit Edition: The RASPPPIPX structure is not supported.

lpcb
[in, out] Pointer to a variable that, on input, specifies the size in bytes of the buffer pointed to by lpprojection.

On output, this variable receives the size of the buffer needed to contain the specified projection information.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is an error code. The function may return a nonzero RAS error code, or one of the following error codes.

Value | Meaning
ERROR_BUFFER_TOO_SMALL | The buffer pointed to by lpprojection is not large enough to contain the requested information.
ERROR_INVALID_HANDLE | The hrasconn parameter is not a valid handle.
ERROR_INVALID_PARAMETER | One of the parameters is invalid.
ERROR_INVALID_SIZE | The dwSize member of the structure pointed to by lpprojection specifies an invalid size.
ERROR_PROTOCOL_NOT_CONFIGURED | The control protocol for which information was requested neither succeeded nor failed, because the connection's phone-book entry did not require that an attempt to negotiate the protocol be made. This is a RAS error code.

Remarks

Remote access projection is the process whereby a remote access server and a remote client negotiate network protocol-specific information. A remote access server uses this network protocol-specific information to represent a remote client on the network.

Windows NT/2000 or later: Remote access projection information is not available until the operating system has executed the RasDial RASCS_Projected state on the remote access connection. If RasGetProjectionInfo is called prior to the RASCS_Projected state, it returns ERROR_PROJECTION_NOT_COMPLETE.

Windows 95: Windows 95 Dial-Up Networking does not support the RASCS_Projected state. The projection phase may be done during the RASCS_Authenticate state. If the authentication is successful, the connection operation proceeds to the RASCS_Authenticated state, and projection information is available for successfully configured protocols. If RasGetProjectionInfo is called prior to the RASCS_Authenticated state, it returns ERROR_PROTOCOL_NOT_CONFIGURED.

Whistler or later: Whistler and later operating systems do not support the NetBEUI protocol or authentication message blocks (AMB).

64-bit Windows 2000 or later: The 64-bit edition of Windows 2000 does not support the IPX protocol.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RASAMB, RasDial, RasEnumConnections, RASPPPNBF, RASPPPIPX, RASPPPIP, RASPROJECTION


RasGetSubEntryHandle

The RasGetSubEntryHandle function retrieves a connection handle for a specified subentry of a multilink connection.

DWORD RasGetSubEntryHandle(
  HRASCONN hrasconn,
  DWORD dwSubEntry,
  LPHRASCONN lphrasconn
);

Parameters

hrasconn
[in] Specifies the HRASCONN connection handle returned by the RasDial function for a multilink phone-book entry.
dwSubEntry
[in] Specifies a valid subentry index for the phone-book entry.
lphrasconn
[out] Pointer to the HRASCONN variable that receives a connection handle that represents the subentry connection.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The hrasconn connection handle does not represent a connected phone-book entry.
ERROR_PORT_NOT_OPEN | The hrasconn and dwSubEntry parameters are valid, but the specified subentry is not connected.
ERROR_NO_MORE_ITEMS | The value specified by dwSubEntry exceeds the maximum number of subentries for the phone-book entry.

Remarks

The connection handle specified in the hrasconn parameter refers to the entire multilink connection, but the connection handle returned in the *lphrasconn parameter refers only to the subentry connection. Use the subentry connection handle in any function that accepts an hrasconn parameter, including the RasHangUp, RasGetConnectStatus, and RasGetProjectionInfo functions. The projection information returned by RasGetProjectionInfo for a multilink entry is the same for the each of the subentry connection handles as it is for the main connection handle.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasDial, RasGetConnectStatus, RasGetProjectionInfo, RasHangUp


RasGetSubEntryProperties

The RasGetSubEntryProperties function retrieves information about a subentry for a specified phone-book entry.

DWORD RasGetSubEntryProperties(
  LPCTSTR lpszPhonebook,   // pointer to full path and file name of
                           //  phone-book file
  LPCTSTR lpszEntry,       // pointer to an entry name
  DWORD dwSubEntry,        // index of the subentry
  LPRASSUBENTRY lpRasSubEntry,
                           // pointer to structure that receives
                           //  information about subentry
  LPDWORD lpdwcb,          // size, in bytes, of the structure
  LPBYTE lpbDeviceConfig,  // pointer to TAPI device configuration
  LPDWORD lpcbDeviceConfig // pointer to size of device configuration
);

Parameters

lpszPhonebook
[in] Windows NT/2000 or later: Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
[in] Pointer to a null-terminated string that specifies the name of an existing entry in the phone book.
dwSubEntry
[in] Specifies the one-based index of the subentry.
lpRasSubEntry
[in, out] Pointer to the RASSUBENTRY structure followed by additional bytes for the alternate phone number list, if there is one.

On output, the structure receives information about the specified subentry.

On input, the dwSize member specifies the size of the structure. The size identifies the version of the structure. Obtain this size using sizeof(RASSUBENTRY).

This parameter can be NULL.

lpdwcb
[in, out] Pointer to a variable that specifies, on input, the size, in bytes, of the lpRasSubEntry buffer.

On output, the variable receives the number of bytes returned, or the number of bytes required if the buffer is too small.

This parameter can be NULL if lpRasSubEntry is NULL.

lpbDeviceConfig
[in] Pointer to a TAPI device configuration block. This parameter is currently unused. The caller should pass NULL for this parameter. For more information about TAPI device configuration blocks, see the function lineGetDevConfig.
lpcbDeviceConfig
[in] Pointer to a DWORD that specifies the size of the TAPI device configuration block. This parameter is currently unused. The caller should pass NULL for this parameter.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | The function was called with an invalid parameter.
ERROR_BUFFER_INVALID | The address or buffer specified by lpRasSubEntry is invalid.
ERROR_BUFFER_TOO_SMALL | The lpRasSubEntry buffer is too small. The lpdwcb variable receives the required buffer size.
ERROR_CANNOT_OPEN_PHONEBOOK | The phone book is corrupted or is missing components.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY | The phone-book entry does not exist.

Remarks

A RAS phone-book entry can have zero or more subentries, each minimally consisting of a device and a phone number. A phone-book entry with multiple subentries can be configured to dial the first available or all subentries when the entry is dialed.

Use the RasGetEntryProperties function to retrieve a RASENTRY structure containing information about the subentries of a phone-book entry. The dwSubEntries member indicates the number of subentries and the dwDialMode member indicates the dialing configuration.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasGetEntryProperties, RASENTRY, RasSetSubEntryProperties, RASSUBENTRY


RasHangUp

The RasHangUp function terminates a remote access connection. The connection is specified with a RAS connection handle. The function releases all RASAPI32.DLL resources associated with the handle.

DWORD RasHangUp(
  HRASCONN hrasconn  // handle to the RAS connection to hang up
);

Parameters

hrasconn
[in] Specifies the remote access connection to terminate. This is a handle returned from a previous call to RasDial or RasEnumConnections.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero error value listed in the RAS header file, or ERROR_INVALID_HANDLE.

Remarks

The connection is terminated even if the RasDial call has not yet been completed.

After this call, the hrasconn handle can no longer be used.

An application should not call RasHangUp and then immediately exit. The connection state machine needs time to properly terminate. If the system prematurely terminates the state machine, the state machine may fail to properly close a port, leaving the port in an inconsistent state. A simple way to avoid this problem is to call Sleep(3000) after returning from RasHangUp; after that pause, the application can exit. A more responsive way to avoid the problem is, after returning from RasHangUp, to call RasGetConnectStatus(hrasconn) and Sleep(0) in a loop until RasGetConnectStatus returns ERROR_INVALID_HANDLE.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RASCONN, RasCustomHangUp, RasDial, RasEnumConnections, RasGetConnectStatus, Sleep


RasInvokeEapUI

The RasInvokeEapUI function displays a custom user interface to obtain Extensible Authentication Protocol (EAP) information from the user.

DWORD RasInvokeEapUI(
  HRASCONN hRasConn,  // handle to connection
  DWORD dwSubEntry,   // subentry from callback
  LPRASDIALEXTENSIONS lpExtensions,
  HWND hwnd           // handle to parent window for user interface
);

Parameters

hRasConn
[in] Handle to the connection returned by RasDial.
dwSubEntry
[in] Specifies the subentry returned in the callback.
lpExtensions
[in] Pointer to the RASDIALEXTENSIONS structure. This structure should be the same as that passed to RasDial when restarting from a paused state. Ensure that the dwSize member of the RASDIALEXTENSIONS structure specifies the size of the structure. Obtain the size using sizeof(RASDIALEXTENSIONS). This parameter cannot be NULL.
hwnd
[in] Handle to the parent window to use when displaying the EAP user interface.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The hRassConn parameter is zero, or the lpExtensions parameter is NULL.
ERROR_INVALID_SIZE | The value of the dwSize member of the RASDIALEXTENSIONS structure specifies a version of the structure that isn't supported by the operating system in use.
Other | Use FormatMessage to retrieve the system error message that corresponds to the error code returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasDial, RASDIALEXTENSIONS, RASEAPINFO


RasMonitorDlg

The RasMonitorDlg function displays the Dial-Up Networking Monitor property sheet that describes the status of RAS connections.

BOOL RasMonitorDlg(
  LPTSTR lpszDeviceName,  // pointer to the name of the device to
                          // display initially
  LPRASMONITORDLG lpInfo  // pointer to structure that contains
                          // input and output parameters
);

Parameters

lpszDeviceName
[in] Pointer to a null-terminated string that specifies the name of the device to display initially. If this parameter is NULL, or if the specified device does not exist, the property sheet displays the first device.
lpInfo
[in, out] Pointer to the RASMONITORDLG structure that specifies additional input and output parameters.

On input, the dwSize member of this structure specifies sizeof(RASMONITORDLG).

If an error occurs, the dwError member receives, on output, an error code; otherwise, it receives zero.

Return Values

If the user hangs up a connection, the return value is a nonzero value.

If an error occurs, or if the user closes the dialog box without hanging up a connection, the return value is zero. If an error occurs, the dwError member of the RASMONITORDLG structure returns a nonzero system error code or RAS error code.

Remarks

The following sample code invokes the RAS monitor dialog.

lpInfo = (LPRASMONITORDLG)GlobalAlloc(GPTR, sizeof(RASMONITORDLG));

ZeroMemory(lpInfo, sizeof(RASMONITORDLG));
// Essential, since garbage values cause the API to fail
lpInfo->dwSize=sizeof(RASMONITORDLG);

nRet = RasMonitorDlg(NULL,lpInfo);

if (nRet)
    printf("User hung up the connection\n");
else
{
    if (lpInfo->dwError != 0)
    {
        printf("RasMonitorDlg failed: Error = %d\n", lpInfo->dwError);
        return -1;
    }
    else
        printf("User pressed Close\n");
}

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Rasdlg.h.
Library: Use Rasdlg.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RASMONITORDLG


RasPBDlgFunc

The RasPBDlgFunc function is an application-defined callback function that receives notifications of user activity while the RasPhonebookDlg dialog box is open.

VOID WINAPI RasPBDlgFunc(
  DWORD dwCallbackId,  // an application-defined value
  DWORD dwEvent,       // indicates the event that occurred
  LPTSTR pszText,      // pointer to an additional string argument
  LPVOID pData         // pointer to an additional buffer argument
);

Parameters

dwCallbackId
[in] Specifies the application-defined value that was specified in the dwCallback member of the RASPBDLG structure passed to the RasPhonebookDlg function.
dwEvent
[in] A set of bit flags that specifies the event that occurred. This parameter is one of the following values.
Value | Meaning
RASPBDEVENT_AddEntry | Received when the user creates a new phone-book entry or copies an existing phone-book entry. The pszText parameter is the name of the new or copied entry. The pData parameter is undefined.
RASPBDEVENT_EditEntry | Received when the user changes an existing phone-book entry. The pszText parameter is the name of the modified entry. The pData parameter is undefined.
RASPBDEVENT_RemoveEntry | Received when the user deletes a phone-book entry. The pszText parameter is the name of the deleted entry. The pData parameter is undefined.
RASPBDEVENT_DialEntry | Received when the user successfully dials an entry. The pszText parameter is the name of the newly connected entry. The pData parameter is undefined.
RASPBDEVENT_EditGlobals Received when the user makes changes in the User Preferences property sheet. The pszText parameter is the full path of the default phone-book file selected by the user. The pData parameter is undefined.

This event is also received during dialog startup if the lpszPhonebook parameter of the RasPhonebookDlg call is NULL. In this case, the event informs the caller of the path of the default phone book.
RASPBDEVENT_NoUser | Received during dialog box initialization when the RASPBDFLAG_NoUser flag is set. The pData parameter is a pointer to a RASNOUSER structure. The callback function should fill the structure with the user's logon credentials and dialog time out. The RasPhonebookDlg function then uses the supplied credentials for authentication by the remote server. The pszText parameter is undefined.
RASPBDEVENT_NoUserEdit | Received if the RASPBDFLAG_NoUser flag is set and the user changes the credentials that are supplied during the RASPBDEVENT_NoUser event. The pData parameter is a pointer to the RASNOUSER structure that contains the updated credentials. This occurs during a dialing operation if the user changes his or her password, or if the authentication fails and the user retries authentication with different credentials. The pszText parameter is undefined.

pszText
[in] Pointer to an additional string argument whose meaning depends on the event indicated in the dwEvent parameter.
pData
[in] Pointer to an additional buffer argument whose meaning depends on the event indicated in the dwEvent parameter.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Rasdlg.h.
Unicode: Declared as Unicode and ANSI prototypes.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RASNOUSER, RasPhonebookDlg


RasPhonebookDlg

The RasPhonebookDlg function displays the main Dial-Up Networking dialog box. From this modal dialog box, the user can dial, edit, or delete a selected phone-book entry, create a new phone-book entry, or specify user preferences. The RasPhonebookDlg function returns when the dialog box closes.

BOOL RasPhonebookDlg(
  LPTSTR lpszPhonebook,  // pointer to the full path and
                         //  file name of the phone-book file
  LPTSTR lpszEntry,      // pointer to the name of the
                         //  phone-book entry to highlight
  LPRASPBDLG lpInfo      // pointer to a structure that
                         //  contains additional parameters
);

Parameters

lpszPhonebook
[in] Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
[in] Pointer to a null-terminated string that specifies the name of the phone-book entry to highlight initially. If this parameter is NULL, or if the specified entry does not exist, the dialog box highlights the first entry in the alphabetic list.
lpInfo
[in, out] Pointer to the RASPBDLG structure that specifies additional input and output parameters.

On input, the dwSize member of this structure specifies sizeof(RASPBDLG).

If an error occurs, the dwError member of the structure receives, on output, an error code; otherwise, it receives zero.

Return Values

If the user selects the Dial button and the function establishes a connection, the return value is a nonzero value.

If an error occurs, or if the user selects the Close button to close the dialog box, the return value is zero. If an error occurs, the dwError member of the RASPBDLG structure returns a nonzero system error code or RAS error code.

The following sample code brings up the Dial-Up Networking dialog. The dialog will display dialing information for the first entry from the default phone-book file.

lpInfo = (LPRASPBDLG)GlobalAlloc(GPTR, sizeof(RASPBDLG));
// Essential, since garbage values cause the API to fail
ZeroMemory(lpInfo, sizeof(RASPBDLG));
lpInfo->dwSize=sizeof(RASPBDLG);

nRet = RasPhonebookDlg(NULL,NULL,lpInfo);

if (nRet)
    printf("User pressed Dial\n");
else
{
    if (lpInfo->dwError != 0)
    {
        printf("RasPhonebookDlg failed: Error = %d\n", lpInfo->dwError);
    }
    else
        printf("User pressed Close\n");
}

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Rasdlg.h.
Library: Use Rasdlg.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RASPBDLG


RasRenameEntry

The RasRenameEntry function changes the name of an entry in a phone book.

DWORD RasRenameEntry(
  LPCTSTR lpszPhonebook, // pointer to full path and file
                         //  name of phone-book file
  LPCTSTR lpszOldEntry,  // pointer to the old entry name
  LPCTSTR lpszNewEntry   // pointer to the new entry name
);

Parameters

lpszPhonebook
[in] Windows NT/2000 or later: Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.

Windows 95: This parameter should always be NULL. Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.

lpszOldEntry
[in] Pointer to a null-terminated string that specifies an existing entry name.
lpszNewEntry
[in] Pointer to a null-terminated string that specifies the new entry name. Before calling RasRenameEntry, call the RasValidateEntryName function to validate the new entry name.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_NAME | The lpszNewEntry name is invalid.
ERROR_ALREADY_EXISTS | An entry with the lpszNewEntry name already exists.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY | The phone-book entry does not exist.

Remarks

The RasRenameEntry function allows entry names that would not be accepted by the dial-up networking user interface. The entry names specified in RasRenameEntry can consist of any string that adheres to the following conditions:

  1. The string cannot have a length greater than RAS_MaxEntryName (as defined in Ras.h).
  2. The string cannot consist entirely of space or tab characters.
  3. The first character in the string cannot be a period character (".").

The following code sample renames the phone-book entry with the name specified by lpszOldEntry to the new name specified by lpszNewEntry.

nRet = RasRenameEntry(NULL, lpszOldEntry, lpszNewEntry);

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 OSR2 or later.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasValidateEntryName


RasSetAutodialAddress

The RasSetAutodialAddress function can add an address to the AutoDial mapping database. Alternatively, the function can delete or modify the data associated with an existing address in the database.

DWORD RasSetAutodialAddress(
  LPCTSTR lpszAddress,        // pointer to a network address string
  DWORD dwReserved,           // reserved; must be zero
  LPRASAUTODIALENTRY lpAutoDialEntries,
                              // pointer to buffer containing
                              //  AutoDial entry data
  DWORD dwcbAutoDialEntries,  // size, in bytes, of the buffer
  DWORD dwcAutoDialEntries    // number of entries in the buffer
);

Parameters

lpszAddress
[in] Pointer to a null-terminated string that specifies the address to add, delete, or modify. This can be an IP address, Internet host name ("www.microsoft.com"), or NetBIOS name ("products1").

Windows Me: This parameter must be NULL.

Whistler or later: If this parameter is NULL, the function sets the default Internet connection (see Remarks). If this parameter points to a zero-length string, the function deletes the default Internet connection.

dwReserved
[in] Reserved; must be zero.
lpAutoDialEntries
[in] Pointer to an array of one or more RASAUTODIALENTRY structures to be associated with the lpszAddress address. If lpAutoDialEntries is NULL and dwcbAutodialEntries is zero, RasSetAutodialAddress deletes all structures associated with lpszAddress from the mapping database.

Windows Me: Pointer to a single RASAUTODIALENTRY structure. This structure specifies the name of the phone-book entry that is the default entry for dialing the Internet. The dwDialingLocation member of this structure is ignored.

dwcbAutoDialEntries
[in] Specifies the size, in bytes, of the lpAutodialEntries buffer.
dwcAutoDialEntries
[in] Specifies the number of RASAUTODIALENTRY structures in the lpAutoDialEntries buffer.

Windows Me: This parameter must be one.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_SIZE | The dwSize member of the RASAUTODIALENTRY structure is an invalid value.
ERROR_INVALID_PARAMETER | The lpszAddress parameter was NULL.

Remarks

An address in the AutoDial mapping database can have any number of associated RASAUTODIALENTRY entries. Each entry specifies AutoDial information for a particular TAPI dialing location.

If the address specified by the lpszAddress parameter is an existing address in the database and the lpAutoDialEntries parameter is not NULL, the RasSetAutodialAddress function modifies the set of AutoDial entries associated with the address. If an entry in the lpAutoDialEntries array specifies a dialing location for which the address already has an entry, the function replaces the existing entry with the new entry. Otherwise, the function simply adds the lpAutoDialEntries entries to the set of entries for the address.

If the lpszAddress address exists in the database and lpAutoDialEntries is NULL and dwcbAutodialEntries is zero, RasSetAutodialAddress deletes the address from the database.

If the lpszAddress address does not exist in the database, RasSetAutodialAddress adds the address to the database. The lpAutoDialEntries parameter specifies the AutoDial entries to associate with the new address.

Windows Me: Only a single phone-book entry is supported. Therefore, the dwDialingLocation member of the RASAUTODIALENTRY structure is ignored. The phone-book entry is the default connection used to access the Internet. Therefore, the lpszAddress parameter is NULL.

Whistler or later: The Remote Access Service (RAS) supports default Internet connections. RAS supports a default Internet connection that is global to the local computer, and in addition, supports a default Internet connection for each user.

The name of the global default Internet connection is stored in the registry below the following registry key:

HKEY_LOCAL_MACHINE\Software\Microsoft\Ras Autodial\Default

The value that stores the name of the connection is:

DefaultInternet

This value is of type REG_SZ.

The global default Internet connection must be configured as a "for-all-users" connection in the Connections Folder user interface.

The name of the per-user default Internet connection is stored in the registry below the following registry key:

HKEY_CURRENT_USER\Software\Microsoft\Ras Autodial\Default

The value that stores the name of the connection is:

DefaultInternet

This value is of type REG_SZ.

If the lpszAddress parameter is NULL, and the lpAutoDialEntries parameter specifies a connection name that does not currently exist, RasSetAutodialAddress still succeeds. If a connection is later created with that name, it becomes the default Internet connection.

It is possible to have two connections that have the same name as long as one is configured as a "for-all-users" connection and the other is configured as a "for-me-only" connection. If the lpAutoDialEntries parameter specifies a connection name that corresponds to both a global and a per-user connection, the per-user connection is set.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RASAUTODIALENTRY, RasEnumAutodialAddresses, RasGetAutodialAddress


RasSetAutodialEnable

The RasSetAutodialEnable function enables or disables the AutoDial feature for a specified TAPI dialing location. For more information about TAPI dialing locations, see the Telephony Application Programming Interfaces (TAPI) Programmer's Reference in the Platform SDK documentation.

DWORD RasSetAutodialEnable(
  DWORD dwDialingLocation,  // identifier of the TAPI dialing location
  BOOL fEnabled             // AutoDial state for this location
);

Parameters

dwDialingLocation
[in] Specifies the identifier of a TAPI dialing location.
fEnabled
[in] Specifies TRUE to enable AutoDial for the dialing location indicated by the dwDialingLocation parameter. Specifies FALSE to disable it.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero error code.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasGetAutodialEnable


RasSetAutodialParam

The RasSetAutodialParam function sets the value of an AutoDial parameter.

DWORD RasSetAutodialParam(
  DWORD dwKey,     // indicates the parameter to set
  LPVOID lpvValue, // pointer to a buffer that specifies the value
  DWORD dwcbValue  // size, in bytes, of the buffer
);

Parameters

dwKey
[in] Specifies the AutoDial parameter to set. This parameter can be one of the following values.
Value | Meaning
RASADP_DisableConnectionQuery | The lpvValue parameter points to a DWORD value. If this value is zero (the default), AutoDial displays a dialog box to query the user before creating a connection. If this value is one, and the AutoDial database has the phone-book entry to dial, AutoDial creates a connection without displaying the dialog box.
RASADP_LoginSessionDisable | The lpvValue parameter points to a DWORD value. If this value is one, the system disables all AutoDial connections for the current logon session. If this value is zero (the default), AutoDial connections are enabled. The AutoDial system service changes this value to zero when a new user logs on to the workstation.
RASADP_SavedAddressesLimit | The lpvValue parameter points to a DWORD value that indicates the maximum number of addresses that AutoDial stores in the registry. AutoDial first stores addresses that it used to create an AutoDial connection; then it stores addresses that it learned after a RAS connection was created. Addresses written using the RasSetAutodialAddress function are always saved, and are not included in calculating the limit. The default value is 100.
RASADP_FailedConnectionTimeout | The lpvValue parameter points to a DWORD value that indicates a time-out value, in seconds. When an AutoDial connection attempt fails, the AutoDial system service disables subsequent attempts to reach the same address for the time-out period. This prevents AutoDial from displaying multiple connection dialog boxes for the same logical request by an application. The default value is five.
RASADP_ConnectionQueryTimeout | The lpvValue parameter points to a DWORD value that indicates a time-out value, in seconds. Before attempting an AutoDial connection, the system will display a dialog asking the user to confirm that the system should dial. The dialog has a countdown timer that terminates the dialog with a "Do not dial" selection if the user takes no action. The DWORD value pointed to by lpvValue specifies the initial time on this countdown timer.

lpvValue
[out] Pointer to a buffer that receives the new value for the specified parameter.
dwcbValue
[in] Specifies the size, in bytes, of the value in the lpvValue buffer.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | The dwKey or lpvValue parameter is invalid.
ERROR_INVALID_SIZE | The size specified by the dwcbValue is invalid.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasGetAutodialParam, RasSetAutodialAddress


RasSetCredentials

[This is preliminary documentation and subject to change.]

The RasSetCredentials function sets the user credentials associated with a specified RAS phone-book entry.

DWORD RasSetCredentials(
  LPCTSTR lpszPhonebook,   // pointer to the full path and
                           //  file name of a phone-book file
  LPCTSTR lpszEntry,       // pointer to the name of a
                           //  phone-book entry
  LPRASCREDENTIALS lpCredentials,
                           // pointer to structure that
                           //  specifies the credentials
  BOOL fClearCredentials   // if true, credentials are cleared
                           // if false, credentials are set
);

Parameters

lpszPhonebook
[in] Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
[in] Pointer to a null-terminated string that specifies the name of a phone-book entry.
lpCredentials
[in] Pointer to a RASCREDENTIALS structure that specifies the user credentials to set for the specified phone-book entry. Before calling RasSetCredentials, set the dwSize member of the structure to sizeof(RASCREDENTIALS). Set the dwMask member to indicate the credential information to be set.
fClearCredentials
[in] Specifies whether RasSetCredentials clears existing credentials by setting them to the empty string, "". If this flag is TRUE, the dwMask member of the RASCREDENTIALS structure indicates the credentials that the function sets to the empty string. If this flag is FALSE, the function sets the indicated credentials according to the contents of their corresponding RASCREDENTIALS members.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_CANNOT_OPEN_PHONEBOOK | The specified phone book cannot be found.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY | The specified entry does not exist in the phone book.
ERROR_INVALID_PARAMETER | The lpCredentials parameter was NULL.
ERROR_INVALID_SIZE | The dwSize member of the RASCREDENTIALS structure is an unrecognized value.
ERROR_ACCESS_DENIED | The calling application attempted to set default credentials for a per-user connection. Default credentials can be set only for an all-user connection.

Remarks

The RasSetCredentials function sets the user credentials associated with a specified RAS phone-book entry. The credentials stored with a phone-book entry are the credentials of the last user to successfully connect using the specified phone-book entry, or the credentials subsequently specified in a call to the RasSetCredentials or RasSetEntryDialParams function for the phone-book entry.

The RasSetCredentials function is the preferred way of securely storing credentials with a phone-book entry. RasSetCredentials supersedes the RasSetEntryDialParams function, which may not be supported in future releases of Windows 2000.

Windows 2000 and later versions: If the szPassword member of the RASCREDENTIALS structure contains the password handle returned by RasGetCredentials or RasGetEntryDialParams, RasSetCredentials returns successfully without changing any currently saved password.

Whistler or later: To set the default credentials for an all-user connection, set the RASCM_DefaultCreds flag in the dwMask member of the RASCREDENTIALS structure pointed to by the lpCredentials parameter. If you attempt to set default credentials for a per-user connection, RasSetCredentials returns ERROR_ACCESS_DENIED.

Whistler or later: To set a pre-shared key, use the RASCM_PreSharedKey flag in the RASCREDENTIALS.dwMask field.

The following code sample sets the credentials for the phone-book entry with the name "mazy".

ZeroMemory(&lpCred, sizeof(lpCred));

lpCred.dwSize = sizeof(lpCred);
lstrcpy(lpCred.szUserName, "test");
lstrcpy(lpCred.szPassword, "");
lstrcpy(lpCred.szDomain, "BANANA40");
lpCred.dwMask=RASCM_UserName | RASCM_Password | RASCM_Domain ;

res=RasSetCredentials(NULL, "mazy", &lpCred, 0);
if(res == 0)
    printf("Set Credentials to:\n%s\n%s\n%s\n\n",
      lpCred.szUserName,lpCred.szPassword,lpCred.szDomain);
else
    printf("Error: %u\n\n,",res);

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RASCREDENTIALS, RasGetCredentials, RasSetEntryDialParams


RasSetCustomAuthData

Use the RasSetCustomAuthData function to set connection-specific authentication information. This information should not be specific to a particular user.

DWORD RasSetCustomAuthData (
  LPCWSTR pszPhonebook,         // path to phone book to use
  LPCWSTR pszEntry,             // name of entry in phone book
  BYTE *pbCustomAuthData,       // pointer to data
  DWORD dwSizeofCustomAuthData  // size of data
);

Parameters

pszPhonebook
[in] Pointer to a null-terminated string that specifies the full path of the phone-book (PBK) file. If this parameter is NULL, the function will use the system phone book.
pszEntry
[in] Pointer to a null-terminated string that specifies an existing entry name.
pbCustomAuthData
[in] Pointer to a buffer that specifies the new authentication data.
dwSizeofCustomAuthData
[in] Specifies the size of the data pointed to by the pbCustomAuthData parameter.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the retun value is one of the following error codes.

Value | Meaning
E_INVALIDARG | The dwSizeofCustomAuthData parameter is zero, or the pbCustomAuthData parameter is NULL.
ERROR_CANNOT_OPEN_PHONEBOOK | RasSetEapUserData was unable to open the specified phone-book file.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY | RasSetEapUserData was unable to find the specified entry in the phone book.
Other | Use FormatMessage to retrieve the system error message that corresponds to the error code returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

RasGetCustomAuthData, RasSetEapUserData


RasSetEapUserData

Use the RasSetEapUserData function to store user-specific Extensible Authentication Protocol (EAP) information for the specified phone-book entry in the registry.

DWORD RasSetEapUserData(
  HANDLE hToken,          // access token for user
  LPCTSTR pszPhonebook,   // path to phone book to use
  LPCTSTR pszEntry,       // name of entry in phone book
  BYTE *pbEapData,        // data to store for the user
  DWORD dwSizeofEapData,  // size of data
);

Parameters

hToken
[in] Handle to a primary or impersonation access token that represents the user for which to store data. This parameter can be NULL if the function is called from a process already running in the user's context.
pszPhonebook
[in] Pointer to a null-terminated string that specifies the full path of the phone-book (PBK) file. If this parameter is NULL, the function will use the system phone book.
pszEntry
[in] Pointer to a null-terminated string that specifiesan existing entry name.
pbEapData
[in] Pointer to the data to store for the user.
dwSizeofEapData
[in] Specifies the size of the data pointed to by the pbEapData parameter.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the retun value is one of the following error codes.

Value | Meaning
E_INVALIDARG | The dwSizeofEapData parameter is zero, or the pbEapData parameter is NULL.
ERROR_CANNOT_OPEN_PHONEBOOK | RasSetEapUserData was unable to open the specified phone-book file.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY | RasSetEapUserData was unable to find the specified entry in the phone book.
Other | Use FormatMessage to retrieve the system error message that corresponds to the error code returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasGetEapUserData, RasInvokeEapUI


RasSetEntryDialParams

The RasSetEntryDialParams function changes the connection information saved by the last successful call to the RasDial or RasSetEntryDialParams function for a specified phone-book entry.

DWORD RasSetEntryDialParams(
  LPCTSTR lpszPhonebook, // pointer to the full path and
                         //  file name of the phone book file
  LPRASDIALPARAMS lprasdialparams,
                         // pointer to a structure with the
                         //  new connection parameters
  BOOL fRemovePassword   // indicates whether to remove
                         //  password from entry's parameters
);

Parameters

lpszPhonebook
[in] Windows NT/2000 or later: Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.

Windows 95: Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.

lprasdialparams
[in] Pointer to the RASDIALPARAMS structure that specifies the connection parameters to be associated with the phone-book entry. RasSetEntryDialParams uses the structure's members as follows.
Member | Description
dwSize | Must specify the sizeof(RASDIALPARAMS) to identify the version of the structure.
szEntryName | A null-terminated string that identifies the phone-book entry to set parameters for.
szPhoneNumber | Not used. Set to NULL.
szCallbackNumber | A null-terminated string that contains the callback phone number. If szCallbackNumber is an empty string ( "" ), the callback number is not changed.
szUserName | A null-terminated string that contains the logon name of the user associated with this entry. If szUserName is an empty string, the user name is not changed.
szPassword A null-terminated string that contains the password for the user specified by szUserName. If szUserName is an empty string, the password is not changed. If szPassword is an empty string and fRemovePassword is FALSE, the password is set to the empty string. If fRemovePassword is TRUE, the password stored in this phone-book entry for the user specified by szUserName is removed regardless of the contents of the szPassword string.

Windows NT 4.0 and later: The password is changed to the string specified by szPassword regardless of whether szUserName is an empty string.

Windows 2000 and later: If szPassword contains the password handle returned by RasGetCredentials or RasGetEntryDialParams, RasSetEntryDialParams returns successfully without changing any currently saved password.
szDomain | A null-terminated string that contains the name of the domain on which to log on . If szDomain is an empty string, the domain name is not changed.
dwSubEntry | Specifies the (one-based) index of the initial subentry to dial when establishing the connection.
dwCallbackId | Not used; should be zero.

fRemovePassword
[in] Specifies whether to remove the phone-book entry's stored password for the user indicated by lprasdialparams->szUserName. If fRemovePassword is TRUE, the password is removed. Setting fRemovePassword to TRUE is equivalent to checking the "Unsave Password" checkbox in Dial-Up Networking. When setting the password or other properties of a phone book entry, set fRemovePassword to FALSE.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value can be one of the following error codes.

Value | Description
ERROR_BUFFER_INVALID | The address or buffer specified by lprasdialparams is invalid.
ERROR_CANNOT_OPEN_PHONEBOOK | The phone book is corrupted or missing components.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY | The phone-book entry does not exist.

Remarks

To create a new phone-book entry, use the RasSetEntryProperties function.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RASDIALPARAMS, RasCreatePhonebookEntry, RasEditPhonebookEntry, RasGetEntryDialParams, RasSetEntryProperties


RasSetEntryProperties

The RasSetEntryProperties function changes the connection information for an entry in the phone book or creates a new phone-book entry.

DWORD RasSetEntryProperties(
  LPCTSTR lpszPhonebook,  // pointer to full path and file
                          //  name of phone-book file
  LPCTSTR lpszEntry,      // pointer to an entry name
  LPRASENTRY lpRasEntry,  // buffer that contains entry information
  DWORD dwEntryInfoSize,  // size, in bytes, of the
                          //  lpRasEntry buffer
  LPBYTE lpbDeviceInfo,   // buffer that contains device-
                          //  specific configuration information
  DWORD dwDeviceInfoSize  // size, in bytes, of the
                          //  lpbDeviceInfo buffer
);

Parameters

lpszPhonebook
[in] Windows NT/2000 or later: Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
[in] Pointer to a null-terminated string that specifies an entry name.

If the entry name matches an existing entry, RasSetEntryProperties modifies the properties of that entry.

If the entry name does not match an existing entry, RasSetEntryProperties creates a new phone-book entry. For new entries, call the RasValidateEntryName function to validate the entry name before calling RasSetEntryProperties.

lpRasEntry
[in] Pointer to the RASENTRY structure that specifies the new connection data to be associated with the phone-book entry indicated by the lpszEntry parameter.

The caller must provide values for the following members in the RASENTRY structure.

szPLocalPhoneNumber

szDeviceName

szDeviceType

dwFramingProtocol

dwfOptions

If values are not provided for these members, RasSetEntryProperties fails with ERROR_INVALID_PARAMETER.

The structure might be followed by an array of null-terminated alternate phone number strings. The last string is terminated by two consecutive null characters. The dwAlternateOffset member of the RASENTRY structure contains the offset to the first string.

dwEntryInfoSize
[in] Specifies the size, in bytes, of the buffer identified by the lpRasEntry parameter.
lpbDeviceInfo
[in] Pointer to a buffer that specifies device-specific configuration information. This is opaque TAPI device configuration information. For more information about TAPI device configuration, see the lineGetDevConfig function in the TAPI Programmer's Reference in the Platform SDK.

Windows NT/2000 or later: This parameter is unused. The calling function should set this parameter to NULL.

dwDeviceInfoSize
[in] Specifies the size, in bytes, of the lpbDeviceInfo buffer.

Windows NT/2000 or later: This parameter is unused. The calling function should set this parameter to zero.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_BUFFER_INVALID | The address or buffer specified by lpRasEntry is invalid.
ERROR_CANNOT_OPEN_PHONEBOOK | The phone book is corrupted or missing components.
ERROR_INVALID_PARAMETER | The RASENTRY structure pointed to by the lpRasEntry parameter does notcontain adequate information. See the description for lpRasEntry to see what information is required.

Remarks

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 OSR2 or later.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RASENTRY, RasCreatePhonebookEntry, RasGetEntryProperties, RasValidateEntryName


RasSetSubEntryProperties

The RasSetSubEntryProperties function creates a new subentry or modifies an existing subentry of a specified phone-book entry.

DWORD RasSetSubEntryProperties(
  LPCTSTR lpszPhonebook,   // pointer to full path and file
                           //  name of the phone-book file
  LPCTSTR lpszEntry,       // pointer to an entry name
  DWORD dwSubEntry,        // index of the subentry
  LPRASSUBENTRY lpRasSubEntry,
                           // pointer to structure
                           //  containing information about subentry
  DWORD dwcbRasSubEntry    // size, in bytes, of the structure
  LPBYTE lpbDeviceConfig,  // pointer to TAPI device configuration
  DWORD dwcbDeviceConfig   // size of TAPI device configuration
);

Parameters

lpszPhonebook
[in] Windows NT/2000 or later: Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
lpszEntry
[in] Pointer to a null-terminated string that specifies the name of an existing entry in the phone book.
dwSubEntry
[in] Specifies the one-based index of the subentry. If the index matches an existing subentry index, the function changes the properties of that subentry. If the index does not match an existing index, the function creates a new subentry.
lpRasSubEntry
[in] Pointer to the RASSUBENTRY structure that specifies the data for the subentry.

The structure might be followed by an array of null-terminated alternate phone number strings. The last string is terminated by two consecutive null characters. The dwAlternateOffset member of the RASSUBENTRY structure contains the offset to the first string.

dwcbRasSubEntry
[in] Specifies the size, in bytes, of the lpRasSubEntry buffer.
lpbDeviceConfig
[in] Pointer to a TAPI device configuration block. This parameter is currently unused. The caller should pass NULL for this parameter. For more information about TAPI device configuration blocks, see the function lineGetDevConfig.
dwcbDeviceConfig
[in] Specifies the size of the TAPI device configuration block. This parameter is currently unused. The caller should pass zero for this parameter.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_BUFFER_INVALID | The address or buffer specified by lpRasEntry is invalid.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY | The phone-book entry does not exist.
ERROR_CANNOT_OPEN_PHONEBOOK | The phone book is corrupted or missing components.
ERROR_INVALID_PARAMETER | The function was called with an invalid parameter.

Remarks

A RAS phone-book entry can have zero or more subentries, each minimally consisting of a device and a phone number. A phone-book entry with multiple subentries can be configured to dial either the first available subentry or all subentries when the entry is dialed.

Use the RasGetEntryProperties function to retrieve the RASENTRY structure containing information about the subentries of a phone-book entry. The dwSubEntries member indicates the number of subentries and the dwDialMode member indicates the dialing configuration.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasGetEntryProperties, RASENTRY, RASSUBENTRY


RasValidateEntryName

[This is preliminary documentation and subject to change.]

The RasValidateEntryName function validates the format of a connection entry name. The name must contain at least one non-white-space alphanumeric character.

DWORD RasValidateEntryName(
  LPCTSTR lpszPhonebook,  // pointer to full path and file
                          //  name of phone-book file
  LPCTSTR lpszEntry       // pointer to the entry name to validate
);

Parameters

lpszPhonebook
[in] Windows NT/2000 or later: Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file.
lpszEntry
[in] Pointer to a null-terminated string that specifies an entry name.

Windows NT/2000 or later: The entry name cannot begin with a period (".").

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the functions fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ALREADY_EXISTS | The entry name already exists in the specified phonebook.
ERROR_CANNOT_FIND_PHONEBOOK | The specified phonebook doesn't exist.
ERROR_INVALID_NAME | The format of the specified entry name is invalid.

Remarks

The following sample code validates the phone-book entry specified by the variable lpszEntry.

nRet = RasValidateEntryName(NULL, lpszEntry);
switch (nRet)
{
    case ERROR_SUCCESS:
        printf("Entry name: %s is valid but doesn't exist in the default phone book\n", lpszEntry);
        break;
    case ERROR_INVALID_NAME:
        printf("Entry name: %s is invalid\n", lpszEntry);
        break;
    case ERROR_ALREADY_EXISTS:
        printf("Entry name: %s already exists in the default phone book\n", lpszEntry);
        break;
    default:
        printf("RasValidateEntryName failed: Error = %d\n", nRet);
        break;
}

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 OSR2 or later.
Header: Declared in Ras.h.
Library: Use Rasapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RasCreatePhonebookEntry, RasGetEntryProperties


RAS Custom Scripting DLL Functions

Implement the following functions when developing a RAS custom-scripting DLL.

  • RasCustomScriptExecute
  • RasGetBuffer
  • RasFreeBuffer
  • RasSendBuffer
  • RasReceiveBuffer
  • RasRetrieveBuffer


RasCustomScriptExecute

[This is preliminary documentation and subject to change.]

RAS calls the RasCustomScriptExecute function when establishing a connection for a phone-book entry that has the RASEO_CustomScript option set.

DWORD RasCustomScriptExecute(
  HANDLE hPort,
  LPCWSTR lpszPhonebook,
  LPCWSTR lpszEntryName,
  PFNRASGETBUFFER pfnRasGetBuffer,
  PFNRASFREEBUFFER pfnRasFreeBuffer,
  PFNRASSENDBUFFER pfnRasSendBuffer,
  PFNRASRECEIVEBUFFER pfnRasReceiveBuffer,
  PFNRASRETRIEVEBUFFER pfnRasRetrieveBuffer,
  HWND hWnd,
  RASDIALPARAMS *pRasDialParams,
  RASCUSTOMSCRIPTEXTENSIONS *pRasCustomScriptExtensions
);

Parameters

hPort
[in] Handle to the port on which the connection is established. Use this handle when sending or receving data on the port.
lpszPhonebook
[in] Pointer to a Unicode string that contains the path to the phone book in which the entry for the connection resides.
lpszEntryName
[in] Pointer to a Unicode string that contains the name of the entry that was dialed to establish the connection.
pfnRasGetBuffer
[in] Pointer to a function of type PFNRASGETBUFFER. The custom-scripting DLL should use this function to allocate memory to send data to the server.
pfnRasFreeBuffer
[in] Pointer to a function of type PFNRASFREEBUFFER. The custom-scripting DLL should use this function to free memory allocated by the pfnRasGetBuffer function.
pfnRasSendBuffer
[in] Pointer to a function of type PFNRASSENDBUFFER. The custom-scripting DLL uses this function to communicate with the server over the specified port.
pfnRasReceiveBuffer
[in] Pointer to a function of type PFNRASRECEIVEBUFFER. The custom-scripting DLL uses this function to communicate with the server over the specified port.
pfnRasRetrieveBuffer
[in] Pointer to a function of type PFNRASRETRIEVEBUFFER. The custom-scripting DLL uses this function to communicate with the server over the specified port.
hWnd
[in] Handle to a window that the custom-scripting DLL can use to present a user interface to the user.
pRasDialParams
[in] Pointer to a Unicode RASDIALPARAMS structure. This structure contains the authentication credentials for the user. The custom-scripting DLL can modify the szUserName, szPassword, and szDomain members of this structure. The Point-to-Point Protocol (PPP) will use whatever is stored in these members when RasCustomScriptExecute returns.
pRasCustomScriptExtensions
[in] Windows 2000 SP2 and later: Pointer to a RASCUSTOMSCRIPTEXTENSIONS structure. This structure contains pointers to additional functions for the custom-scripting DLL.

Return Values

If the function succeeds, the return value should be ERROR_SUCCESS.

If the function fails, the return value should be an appropriate error code from Winerror.h or Raserror.h.

Remarks

When RAS calls RasCustomScriptExecute, the pRasDialParams parameter will point to the Unicode RASDIALPARAMS structure. That is, the structure contains only Unicode strings.

In some cases, the szUserName of the RASDIALPARAMS structure will be an empty string. In these cases, the custom-scripting DLL should use the Unicode version of the GetUserName function to obtain the name of the current user.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Unicode: Declared only as Unicode.

See Also

RAS Custom-Scripting, RasGetBuffer, RasFreeBuffer, RasSendBuffer, RasReceiveBuffer, RasRetrieveBuffer


RasGetBuffer

The custom-scripting DLL calls RasGetBuffer to allocate memory for sending or receiving data over the port connected to the server.

typedef DWORD (APIENTRY *PFNRASGETBUFFER) (
  PBYTE *   ppBuffer,
  PDWORD    pdwSize
);

Parameters

ppBuffer
Pointer to a pointer that receives the address of the returned buffer.
pdwSize
Pointer to a DWORD variable that, on input, contains the requested size of the buffer. On output, this variable contains the actual size of the buffer allocated.

Return values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is the following error code.

Value | Meaning
ERROR_OUT_OF_BUFFERS | RAS cannot allocate anymore buffer space.

Remarks

The maximum buffer size that can be obtained from is 1500 bytes.

The custom-scripting DLL calls RasGetBuffer through a function pointer. The function pointer is passed to the custom-scripting DLL as a parameter when RAS calls the DLL's implementation of RasCustomScriptExecute.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.

See Also

RAS Custom-Scripting, RasCustomScriptExecute, RasFreeBuffer


RasFreeBuffer

The custom-scripting DLL calls RasFreeBuffer to release a memory buffer that was allocated by a previous call to RasGetBuffer.

typedef DWORD (APIENTRY *PFNFREEBUFFER) (
  PBYTE    pBuffer
);

Parameters

pBuffer
Pointer to the memory buffer to free. This memory must have been obtained by a previous call to RasGetBuffer.

Return values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_BUFFER_INVALID | The pointer to the buffer passed in the pBuffer parameter is invalid.
ERROR_INVALID_PORT_HANDLE | The handle specified by the hPort parameter is invalid.

Remarks

The custom-scripting DLL calls RasFreeBuffer through a function pointer. The function pointer is passed to the custom-scripting DLL as a parameter when RAS calls the DLL's implementation of RasCustomScriptExecute.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.

See Also

RAS Custom-Scripting, RasCustomScriptExecute, RasGetBuffer


RasSendBuffer

The custom-scripting DLL calls the RasSendBuffer function to send data to the server over the specified port.

typedef DWORD (APIENTRY *PFNRASSENDBUFFER) (
  HANDLE    hPort,
  PBYTE     pBuffer,
  DWORD     dwSize
);

Parameters

hPort
Handle to the port on which to send the data in the buffer. This handle should be the handle passed in by RAS as the first parameter of the RasCustomScriptExecute function.
pBuffer
Pointer to a buffer of data to send over the port specified by the hPort parameter. Obtain this buffer using RasGetBuffer function.
dwSize
Specifies the size of the data in the buffer pointed to by the pBuffer parameter.

Return values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_BUFFER_INVALID | The pointer to the buffer passed in the pBuffer parameter is invalid.
ERROR_INVALID_PORT_HANDLE | The handle specified by the hPort parameter is invalid.

Remarks

The custom-scripting DLL calls RasSendBuffer through a function pointer. The function pointer is passed to the custom-scripting DLL as a parameter when RAS calls the DLL's implementation of RasCustomScriptExecute.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.

See Also

RAS Custom-Scripting, RasCustomScriptExecute, RasReceiveBuffer, RasRetrieveBuffer


RasReceiveBuffer

The custom-scripting DLL calls the RasReceiveBuffer function to inform RAS that it is ready to receive data from the server over the specified port.

typedef DWORD (APIENTRY *PFNRASRECEIVEBUFFER) (
  HANDLE    hPort,
  PBYTE     pBuffer,
  PDWORD    pdwSize,
  DWORD     dwTimeout,
  HANDLE    hEvent
);

Parameters

hPort
Handle to the port on which to receive the data. This handle should be the handle passed in by RAS as the first parameter of the RasCustomScriptExecute function.
pBuffer
Pointer to a buffer to receive the data from the port specified by the hPort parameter. Obtain this buffer using RasGetBuffer function.
pdwSize
Pointer to a DWORD variable that receives the size of the data returned in the buffer pointed to by the pBuffer parameter.
dwTimeout
Specifies a time-out period in milliseconds after which the custom-scripting DLL will no longer wait for the data.
hEvent
Handle to an event object that RAS will signal when the received data is available.

Return values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_BUFFER_INVALID | The pointer to the buffer passed in the pBuffer parameter is invalid.
ERROR_INVALID_PORT_HANDLE | The handle specified by the hPort parameter is invalid.

Remarks

RasReceiveBuffer is an asynchronous function. RasReceiveBuffer returns immediately even if the data is not yet available. The custom-scripting DLL must wait on the event object specified by the hEvent parameter. When the data is available, RAS signals this event. The custom-scripting DLL should then call the RasRetrieveBuffer function to obtain the data. The custom-scripting DLL may pass the same buffer pointer in RasRetrieveBuffer that it passed in RasReceiveData.

RAS also signals the event object if, for some reason, the port is disconnected before the data is posted. In this case, RasRetrieveBuffer returns an error defined in Raserror.h, that indicates the cause of the failure.

The custom-scripting DLL calls RasReceiveBuffer through a function pointer. The function pointer is passed to the custom-scripting DLL as a parameter when RAS calls the DLL's implementation of RasCustomScriptExecute.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.

See Also

RAS Custom-Scripting, RasCustomScriptExecute, RasSendBuffer


RasRetrieveBuffer

The custom-scripting DLL calls the RasRetrieveBuffer function to obtain data received from the RAS server over the specified port. The custom-scripting DLL should call RasRetrieveBuffer only after RAS has signaled the event object passed in the call to RasReceiveBuffer.

typedef DWORD (APIENTRY * PRASPORTRETRIEIVEBUFFER ) (
  HPORT    hPort,
  PBYTE    pBuffer,
  PDWORD   pdwSize
);

Parameters

hPort
Handle to the port on which to receive the data. This handle should be the handle passed in by RAS as the first parameter of the RasCustomScriptExecute function.
pBuffer
Pointer to a buffer to receive the data from the port specified by the hPort parameter. Obtain this buffer using RasGetBuffer function. The value of this parameter may be the same as the pointer to the buffer passed into the RasReceiveBuffer function.
pdwSize
Pointer to a DWORD variable that receives the size of the data returned in the buffer pointed to by the pBuffer parameter.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_BUFFER_INVALID | The pointer to the buffer passed in the pBuffer parameter is invalid.
ERROR_INVALID_PORT_HANDLE | The handle specified by the hPort parameter is invalid.

RAS signals the event object if the port gets disconnected for some reason before the data is posted. In this case, RasRetrieveBuffer returns an error defined in Raserror.h, that indicates the cause of the failure.

Remarks

The RasRetrieveBuffer function is synchronous. When it returns, the buffer pointed to by the pBuffer parameter contains the data received over the specified port. The custom-scripting DLL should call RasRetrieveBuffer only after RAS has signaled the event object that the DLL passed in the call to RasReceiveBuffer.

The custom-scripting DLL calls RasRetrieveBuffer through a function pointer. The function pointer is passed to the custom-scripting DLL as a parameter when RAS calls the DLL's implementation of RasCustomScriptExecute.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.

See Also

RAS Custom-Scripting, RasCustomScriptExecute, RasReceiveBuffer, RasSendBuffer


RasSetCommSettings

[This is preliminary documentation and subject to change.]

Call RasSetCommSettings from a custom-scripting DLL to change the settings on the port for the connection.

typedef DWORD (APIENTRY *PFNRASSETCOMMSETTINGS) (
  HANDLE    hPort,
  RASCOMMSETTINGS    * pRasCommSettings,
  PVOID    pvReserved
);

Parameters

hPort
[in] Handle to the port on which to apply the settings. This handle is passed to the custom-scripting DLL in the RasCustomScriptExecute function.
pRasCommSettings
[in] Pointer to a RASCOMMSETTINGS structure that specifies the settings to be applied to the port.
pvReserved
[in] Reserved for future use. This parameter must be NULL.

Remarks

RAS passes the custom-scripting DLL a pointer to RasSetCommSettings when RAS calls RasCustomScriptExecute. The pointer is stored in the RASCUSTOMSCRIPTEXTENSIONS structure that is passed as the last parameter of RasCustomScriptExecute.

Requirements

Windows NT/2000 or later: Requires Windows 2000 SP2 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.

See Also

RAS Custom-Scripting, RasCustomScriptExecute, RASCOMMSETTINGS


Remote Access Service Structures

Use the following structures to implement RAS functionality:

RASADPARAMS

RASAMB

RASAUTODIALENTRY

RASCOMMSETTINGS

RASCONN

RASCONNSTATUS

RASCREDENTIALS

RASCUSTOMSCRIPTEXTENSIONS

RASCTRYINFO

RASDEVINFO

RASDIALDLG

RASDIALEXTENSIONS

RASDIALPARAMS

RASEAPINFO

RASEAPUSERIDENTITY

RASENTRY

RASENTRYDLG

RASENTRYNAME

RASIPADDR

RASMONITORDLG

RASNOUSER

RASPBDLG

RASPPPCCP

RASPPPIP

RASPPPIPX

RASPPPLCP

RASPPPNBF

RASSLIP

RASSUBENTRY


RASADPARAMS

The RASADPARAMS structure describes the parameters that AutoDial passes to a RASADFunc AutoDial handler.

typedef struct tagRASADPARAMS {
  DWORD       dwSize;
  HWND        hwndOwner;
  DWORD       dwFlags;
  LONG        xDlg;
  LONG        yDlg;
} RASADPARAMS;

Members

dwSize
Specifies the size, in bytes, of the RASADPARAMS structure. The system sets dwSize to sizeof(RASADPARAMS) to identify the version of the structure.
hwndOwner
Specifies the parent window for the AutoDial user interface. This member can be NULL.
dwFlags
Specifies a flag that indicates how to position the window of the AutoDial user interface. The following flag is defined.
Flag Description
RASADFLG_PositionDlg If this flag is set, position the window according to the coordinates specified by the xDlg and yDlg members.

If this flag is not set, center the window on the window specified by the hwndOwner member. If hwndOwner is NULL, center the window on the screen.

xDlg
Specifies the horizontal screen coordinate of the window's upper-left corner. Ignore this member if the RASADFLG_PositionDlg bit is not set in the dwFlags member.
yDlg
Specifies the vertical screen coordinate of the window's upper-left corner. Ignore this member if the RASADFLG_PositionDlg bit is not set in the dwFlags member.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, RASADFunc


RASAMB

The RASAMB structure contains the result of a remote access server (RAS) Authentication Message Block (AMB) projection operation.

The RasGetProjectionInfo function returns a RASAMB data structure when its rasprojection parameter has the value RASP_Amb.

typedef  struct  _RASAMB {
  DWORD    dwSize;
  DWORD    dwError;
  TCHAR    szNetBiosError[ NETBIOS_NAME_LEN + 1 ];
  BYTE     bLana;
} RASAMB;

Members

dwSize
Specifies the size of the structure, in bytes. Before calling the RasGetProjectionInfo function, set this member to sizeof(RASAMB). The function can then determine the version of the RASAMB data structure that the caller of RasGetProjectionInfo is expecting. This allows backward compatibility for compiled applications if there are future enhancements to the data structure.
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, the error that prevented the projection from completing successfully.
szNetBiosError
If dwError has the value ERROR_NAME_EXISTS_ON_NET, the szNetBiosError field contains a zero-terminated string that is the NetBIOS name that caused the conflict. For other values of dwError, this field contains the null string.
bLana
Specifies the NetBIOS network adapter identifier, or LANA, on which the remote access connection was established. This member contains the value 0xFF if a connection was not established.

Remarks

The AMB protocol is used with servers that were released before PPP was adopted as the primary framing protocol; for example, Windows NT 3.1 and OS/2 1.3 RAS servers.

Whistler or later: Whistler and later operating systems do not support authentication message blocks (AMB).

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Ras.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, RasGetProjectionInfo, RASPROJECTION


RASAUTODIALENTRY

The RASAUTODIALENTRY structure describes an AutoDial entry associated with a network address in the AutoDial mapping database. An AutoDial entry specifies a phone-book entry that AutoDial dials in a particular TAPI dialing location.

The RasGetAutodialAddress and RasSetAutodialAddress functions use this structure to set and retrieve information about an AutoDial entry.

typedef struct {
  DWORD    dwSize;
  DWORD    dwFlags;
  DWORD    dwDialingLocation;
  TCHAR    szEntry[RAS_MaxEntryName + 1];
} RASAUTODIALENTRY;

Members

dwSize
Specifies the size, in bytes, of the RASAUTODIALENTRY structure. Before calling RasGetAutodialAddress or RasSetAutodialAddress, set dwSize to sizeof(RASAUTODIALENTRY) to identify the version of the structure.
dwFlags
Reserved; must be zero.

Whistler or later: The following flag is supported.
Flag | Meaning
RASADE_PersonalDefaultInternet | The autodial connection is the default Internet connection for the current user, that is, it is not the global default Internet connection. This flag is valid only if RasGetAutodialAddress or RasGetAutodialAddress is called with the lpszAddress parameter set to NULL.

dwDialingLocation
Specifies a TAPI dialing location. For more information about TAPI dialing locations, see the TAPI Programmer's Reference in the Platform SDK.
szEntry
Specifies a null-terminated string that names an existing phone-book entry.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, RasGetAutodialAddress, RasSetAutodialAddress


RASCOMMSETTINGS

[This is preliminary documentation and subject to change.]

The RASCOMMSETTINGS structure specifies the settings for a serial communications port.

typedef struct tagRASCOMMSETTINGS {
  DWORD   dwSize;
  BYTE    bParity;
  BYTE    bStop;
  WORD    wAlign;
} RASCOMMSETTINGS;

Members

dwSize
Specifies the size of the structure. Set this member to sizeof(RASCOMMSETTINGS).
bParity
Specifies the parity bits for the port. See the Remarks section for more information.
bStop
Specifies the stop bits for the port. See the Remarks section for more information.
wAlign
This member is not used at this time.

Remarks

The bParity and bStop members use the same values as though used in the DCB structure when calling SetCommState. These bit values are defined in winbase.h.

The RASCOMMSETTINGS structure is used by the RasSetCommSettings function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 SP2 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.

See Also

RasSetCommSettings, SetCommState, DCB


RASCONN

[This is preliminary documentation and subject to change.]

The RASCONN structure provides information about a remote access connection. The RasEnumConnections function returns an array of RASCONN structures.

typedef struct _RASCONN {
  DWORD     dwSize;
  HRASCONN  hrasconn;
  TCHAR     szEntryName[RAS_MaxEntryName + 1];

#if (WINVER >= 0x400)
  TCHAR    szDeviceType[ RAS_MaxDeviceType + 1 ];
  TCHAR    szDeviceName[ RAS_MaxDeviceName + 1 ];
#endif
#if (WINVER >= 0x401)
  TCHAR    szPhonebook [ MAX_PATH ];
  DWORD    dwSubEntry;
#endif
#if (WINVER >= 0x500)
  GUID     guidEntry;
#endif
#if (WINVER >= 0x501)
  DWORD     dwSessionId;
  DWORD     dwFlags;
#endif
} RASCONN ;

Members

dwSize
Specifies the size, in bytes, of the RASCONN structure.
hrasconn
Specifies the remote access connection. This handle is used in other remote access API calls.
szEntryName
A string that specifies the phone-book entry used to establish the remote access connection. If the connection was established using an empty entry name, this string consists of a PERIOD followed by the connection phone number.
szDeviceType
Windows NT 4.0 and later: A null-terminated string that contains the device type through which the connection is made. See RASENTRY for a list of possible device types.
szDeviceName
Windows NT 4.0 and later: A null-terminated string that contains the device name through which the connection is made.
szPhonebook [ MAX_PATH ]
Windows NT 4.0 and later: The full path and file name to the phone book containing the entry for this connection.
dwSubEntry
Windows NT 4.0 and later: For multilink connections, specifies the subentry index of one of the connected links. Subentry indices are one based.
guidEntry
Windows 2000 or later: A GUID (Globally Unique IDentifier) that represents the phone-book entry. The value of this member corresponds to that of the guidid member in the RASENTRY structure.
dwSessionId
Whistler or later: Specifies the logon session identifier of the user who established the connection.
dwFlags
Whistler or later: Specifies zero or more of the following flags.
Flag | Meaning
RASCF_AllUsers | Specifies that the connection is a "for-all-users" connection.
RASCF_GlobalCreds | Specifies that the credentials used for this connection are the default credentials. For more information, see RASCM_DefaultCreds under RasSetCredentials.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Ras.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, RasEnumConnections, RasGetConnectStatus


RASCONNSTATUS

[This is preliminary documentation and subject to change.]

A RASCONNSTATUS structure describes the current status of a remote access connection. It is returned by the RasGetConnectStatus function.

typedef struct _RASCONNSTATUS {
  DWORD         dwSize;
  RASCONNSTATE  rasconnstate;
  DWORD         dwError;
  TCHAR         szDeviceType[RAS_MaxDeviceType + 1];
  TCHAR         szDeviceName[RAS_MaxDeviceName + 1];
} RASCONNSTATUS;

Members

dwSize
Specifies the structure size, in bytes.
rasconnstate
Specifies a RASCONNSTATE enumerator value that indicates the current state of the RasDial connection process; that is, the piece of the RasDial process that is currently executing.

Two state values are especially significant.
State | Meaning
RASCS_Connected | Indicates that the connection has been successfully established.
RASCS_Disconnected | Indicates that the connection has failed.

dwError
If nonzero, indicates the reason for failure. The value is one of the error values from the RAS header file or one of ERROR_NOT_ENOUGH_MEMORY or ERROR_INVALID_HANDLE.
szDeviceType
A string that specifies the type of the current device, if available. For example, common device types supported by RAS are "modem", "pad", "switch", "isdn", or "null". See RASENTRY for a complete list of possible device types.
szDeviceName
A string that specifies the name of the current device, if available. This would be the name of the modem — for example, "Hayes Smartmodem 2400"; the name of the PAD, for example "US Sprint"; or the name of a switch device, for example "Racal-Guardata".

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Ras.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, RasGetConnectStatus, RasDial, RASCONNSTATE


RASCREDENTIALS

[This is preliminary documentation and subject to change.]

The RASCREDENTIALS structure is used with the RasGetCredentials and RasSetCredentials functions to specify the user credentials associated with a RAS phone-book entry.

typedef struct {
  DWORD dwSize;
  DWORD dwMask;
  TCHAR    szUserName[UNLEN + 1];
  TCHAR    szPassword[PWLEN + 1];
  TCHAR    szDomain[DNLEN + 1];
} RASCREDENTIALS, *LPRASCREDENTIALS;

Members

dwSize
Specifies the size, in bytes, of the RASCREDENTIALS structure.
dwMask
Specifies a set of bit flags. These flags indicate the members of this structure that are valid. On input, set the flags to indicate the members of interest. On output, the function sets the flags to indicate the members that contain valid data. This member can be a combination of the following values.
Value | Meaning
RASCM_UserName | The szUserName member is valid.
RASCM_Password | The szPassword member is valid.
RASCM_Domain | The szDomain member is valid.
Whistler or later: RASCM_DefaultCreds | Indicates that the credentials are default credentials for an all-user connection.
Whistler or later: RASCM_PreSharedKey | Specifiy this flag to either set or retrieve a pre-shared key. This flag cannot be used in combination with any other flag.

Windows 2000 or later versions: When retrieving credentials using the RasGetCredentials function, the dwMask member contains the RASCM_Password flag if the system has saved a password for the specified entry. If the system has no password saved for this entry, dwMask does not contain RASCM_Password.

Whistler: Use the RASCM_DefaultCreds flag with RasSetCredentials in order to set the default credentials for an all-user connection. If RasGetCredentials returns a RASCREDENTIALS structure with the RASCM_DefaultCreds flag set, the credentials returned are the default credentials for the connection.

szUserName
Specifies a null-terminated string that contains a user name.
szPassword
Specifies a null-terminated string that contains a password.

Windows 2000 and later versions: When retrieving credentials using the RasGetCredentials function, the szPassword member does not receive the actual password. Instead, szPassword receives a handle to the saved password. Substitute this handle for the saved password in calls to RasSetCredentials and RasDial. When presented with this handle, RasDial will retrieve and use the saved password. The value of this handle may change in future versions of the operating system; do not develop code that depends on the contents or format of this value.

szDomain
A null-terminated string that contains a domain name.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, RasGetCredentials, RasSetCredentials


RASCTRYINFO

The RASCTRYINFO structure describes the direct dialing procedures for calls placed within a specified country. The RasGetCountryInfo function uses this structure to retrieve country-specific dialing information from the Windows Telephony list of country information.

For more information about country-specific dialing information, see the TAPI Programmer's Reference in the Platform SDK.

typedef struct RASCTRYINFO {
  DWORD   dwSize;
  DWORD   dwCountryID;
  DWORD   dwNextCountryID;
  DWORD   dwCountryCode;
  DWORD   dwCountryNameOffset;
} RASCTRYINFO;

Members

dwSize
Specifies the size, in bytes, of the RASCTRYINFO structure. Before calling RasGetCountryInfo, set dwSize to sizeof(RASCTRYINFO) to identify the version of the structure.
dwCountryID
Specifies a TAPI country identifier. Before calling RasGetCountryInfo, set dwCountryID to identify the country of interest. For more information about TAPI country identifiers, see the TAPI Programmer's Reference in the Platform SDK.

If this member is 1, RasGetCountryInfo returns information about the first country in the Windows Telephony list of country information.

dwNextCountryID
Specifies the TAPI country identifier of the next country to enumerate in the Windows Telephony list. This member is zero for the last country in the list.
dwCountryCode
Specifies the country code for the country identified by the dwCountryID member.
dwCountryNameOffset
Specifies the offset, in bytes, from the start of the structure to the start of a null-terminated string describing the country. The description string is either ANSI or Unicode, depending on whether you use the ANSI or Unicode version of RasGetCountryInfo.

Remarks

For more information on dialing procedures and telephony configuration, see the TAPI Programmer's Reference in the Platform SDK.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 OSR2 or later.
Header: Declared in Ras.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, RasGetCountryInfo


RASCUSTOMSCRIPTEXTENSIONS

[This is preliminary documentation and subject to change.]

The RASCUSTOMSCRIPTEXTENSIONS structure specifies pointers to additional functions for use by the custom-scripting DLL.

struct RASCUSTOMSCRIPTEXTENSIONS {
  DWORD dwSize,
  PFNRASSETCOMMSETTINGS   pfRasSetCommSettings
}

Members

dwSize
Specifies the size of the structure. Set this member sizeof(RASCUSTOMSCRIPTEXTENSIONS).
pfRasSetCommSettings
Pointer to a function of type PFNRASSETCOMMSETTINGS. The custom-scripting DLL uses this function to set communication parameters for the specified port.

Remarks

RAS passes the custom-scripting DLL a pointer to this structure when it calls the RasCustomScriptExecute function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 SP2 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.

See Also

RAS Custom-Scripting, RasCustomScriptExecute, RasSetCommSettings


RASDEVINFO

[This is preliminary documentation and subject to change.]

The RASDEVINFO structure contains information that describes a TAPI device capable of establishing a RAS connection. The RasEnumDevices function uses this structure to retrieve information about RAS-capable devices.

typedef struct tagRASDEVINFO {
  DWORD    dwSize;
  TCHAR    szDeviceType[ RAS_MaxDeviceType + 1 ];
  TCHAR    szDeviceName[ RAS_MaxDeviceName + 1 ];
} RASDEVINFO;

Members

dwSize
Specifies the size, in bytes, of the RASDEVINFO structure. Before calling RasEnumDevices, set dwSize to sizeof(RASDEVINFO) to identify the version of the structure.
szDeviceType
Specifies a null-terminated string indicating the RAS device type referenced by szDeviceName. See RASENTRY for a list of possible device types.Windows 95: The RASDT_Vpn device type is supported on Windows 95 only if Microsoft Dial-Up Networking Version 1.2 is installed. The RASDT_X25 and RASDT_Pad device types are not supported on Windows 95.

Windows 98/Me: The RASDT_Vpn device type is supported on Windows 98. However, the RASDT_X25 and RASDT_Pad device types are not currently supported on Windows 98

szDeviceName
Specifies a null-terminated string containing the name of a TAPI device.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 OSR2 or later.
Header: Declared in Ras.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, RasEnumDevices


RASDIALDLG

The RASDIALDLG structure is used in the RasDialDlg function to specify additional input and output parameters.

typedef struct tagRASDIALDLG {
  IN  DWORD          dwSize;
  IN  HWND           hwndOwner;
  IN  DWORD          dwFlags;
  IN  LONG           xDlg;
  IN  LONG           yDlg;
  IN  DWORD          dwSubEntry;
  OUT DWORD          dwError;
  IN  DWORD          reserved;
  IN  DWORD          reserved2;
} RASDIALDLG;

Members

dwSize
Specifies the size of this structure, in bytes. Before calling RasDialDlg, set this member to sizeof(RASDIALDLG) to indicate the version of the structure. If dwSize is not a valid size, RasDialDlg fails and sets the dwError member to ERROR_INVALID_SIZE.
hwndOwner
Specifies the window that owns the modal RasDialDlg dialog boxes. This member can be any valid window handle, or it can be NULL if the dialog box has no owner.
dwFlags
A bit flag that indicates the options that are enabled for the dialog box. The following value is supported..
Value Meaning
RASDDFLAG_PositionDlg If this flag is set, RasDialDlg uses the values specified by the xDlg and yDlg members to position the dialog box.

If this flag is not set, the dialog box is centered on the owner window, unless hwndOwner is NULL, in which case, the dialog box is centered on the screen.

xDlg
Specifies the horizontal screen coordinate of the upper-left corner of the dialog box. This value is used only if the RASDDFLAG_PositionDlg flag is set.
yDlg
Specifies the vertical screen coordinate of the upper-left corner of the dialog box. This value is used only if the RASDDFLAG_PositionDlg flag is set.
dwSubEntry
Specifies the subentry or subentries to dial. If dwSubEntry is zero, RasDialDlg dials all subentries associated with the specified phone-book entry. Otherwise, to indicate the index of the individual subentry to dial, dwSubEntry must be a number from one to the number of subentries.
dwError
The RasDialDlg function sets this member to a system error code or RAS error code if an error occurs. If no error occurs, the function sets dwError to zero. This value is ignored on input.
reserved
Reserved; must be zero.
reserved2
Reserved; must be zero.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Rasdlg.h.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, RasDialDlg


RASDIALEXTENSIONS

The RASDIALEXTENSIONS structure contains information about extended features of the RasDial function. Enable one or more of these extensions by passing a pointer to a RASDIALEXTENSIONS structure when you call RasDial. If you do not pass a pointer to a RASDIALEXTENSIONS structure to RasDial, RasDial uses the default settings that are noted in the following descriptions.

typedef  struct  tagRASDIALEXTENSIONS {
  DWORD     dwSize;
  DWORD     dwfOptions;
  HWND      hwndParent;
  ULONG_PTR reserved;
#if (WINVER >= 0x500)
  ULONG_PTR reserved1;
  RASEAPINFO RasEapInfo;
#endif
} RASDIALEXTENSIONS;

Members

dwSize
Specifies the size of this structure, in bytes. Set this member to sizeof(RASDIALEXTENSIONS). This indicates the version of the structure.
dwfOptions
A set of bit flags that specify RasDial extensions. The following bit flags are defined; set all undefined bits to zero.
Value | Description
RDEOPT_UsePrefixSuffix If this bit flag is one, RasDial uses the prefix and suffix that is in the RAS phone book.

If this bit flag is zero, RasDial ignores the prefix and suffix that is in the RAS phone book.

If no phone-book entry name is specified in the call to RasDial, the actual value of this bit flag is ignored, and it is assumed to be zero.
RDEOPT_PausedStates If this bit flag is one, RasDial accepts paused states. Examples of paused states are terminal mode, retry logon, change password, set callback number, and EAP authentication.

If this bit flag is zero, RasDial reports a fatal error if it enters a paused state.

RDEOPT_IgnoreModemSpeaker If this bit flag is one, RasDial ignores the modem speaker setting that is in the RAS phone book, and uses the setting specified by the RDEOPT_SetModemSpeaker bit flag.

If this bit flag is zero, RasDial uses the modem speaker setting that is in the RAS phone book, and ignores the setting specified by the RDEOPT_SetModemSpeaker bit flag.

If no phone-book entry name is specified in the call to RasDial, the choice is between using a default setting or the setting specified by the RDEOPT_SetModemSpeaker bit flag. The default setting is used if RDEOPT_IgnoreModemSpeaker is zero. The setting specified by RDEOPT_SetModemSpeaker is used if RDEOPT_IgnoreModemSpeaker is one.
RDEOPT_SetModemSpeaker If this bit flag is one, and RDEOPT_IgnoreModemSpeaker is one, RasDial sets the modem speaker on.

If this bit flag is zero, and RDEOPT_IgnoreModemSpeaker is one, RasDial sets the modem speaker off.

If RDEOPT_IgnoreModemSpeaker is zero, RasDial ignores the value of RDEOPT_SetModemSpeaker, and sets the modem speaker based on the RAS phone-book setting or the default setting.
RDEOPT_IgnoreSoftwareCompression If this bit flag is one, RasDial ignores the software compression setting that is in the RAS phone book, and uses the setting specified by the RDEOPT_SetSoftwareCompression bit flag.

If this bit flag is zero, RasDial uses the software compression setting that is in the RAS phone book, and ignores the setting specified by the RDEOPT_SetSoftwareCompression bit flag.

If no phone-book entry name is specified in the call to RasDial, the choice is between using a default setting or the setting specified by the RDEOPT_SetSoftwareCompression bit flag. The default setting is used if RDEOPT_IgnoreSoftwareCompression is zero. The setting specified by RDEOPT_SetSoftwareCompression is used if RDEOPT_IgnoreSoftwareCompression is one.
RDEOPT_SetSoftwareCompression If this bit flag is one, and RDEOPT_IgnoreSoftwareCompression is one, RasDial uses software compression.

If this bit flag is zero, and RDEOPT_IgnoreSoftwareCompression is one, RasDial does not use software compression.

If RDEOPT_IgnoreSoftwareCompression is zero, RasDial ignores the value of RDEOPT_SetSoftwareCompression, and sets the software compression state based on the RAS phone-book setting or the default setting.
RDEOPT_PauseOnScript | Used internally by the RasDialDlg function so that a Windows-95-style logon script is executed in a terminal window visible to the user. Applications should not set this flag.
RDEOPT_UseCustomScripting Whistler: Specifies that RasDial should invoke a custom-scripting DLL after establishing the connection to the server.

RasDial will only invoke the DLL if all of the following conditions are met:

This bit flag is one.

A custom-scripting DLL is correctly registered with the system.

The RASEO_CustomScript option is specified in the phone-book entry.

See RAS Custom-Scripting for more information.

The default value for each of these bit flags is zero.

hwndParent
Handle to a parent window that a security DLL can use for dialog box creation and centering.

Note that this is not the window that receives RasDial progress notifications.

This member is optional; it is not required when no security DLL is defined.

The default value for this member is NULL.

reserved
This member is reserved for future use. It must be set to zero.
reserved1
Windows 2000 or later: This member is reserved for future use. It must be set to zero.
RasEapInfo
Windows 2000 or later: A RASEAPINFO structure that contains user-specific Extensible Authentication Protocol (EAP) information.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, RasDial, RasInvokeEapUI


RASDIALPARAMS

The RASDIALPARAMS structure contains parameters that are used by RasDial to establish a remote access connection.

typedef struct _RASDIALPARAMS {
  DWORD  dwSize;
  TCHAR  szEntryName[RAS_MaxEntryName + 1];
  TCHAR  szPhoneNumber[RAS_MaxPhoneNumber + 1];
  TCHAR  szCallbackNumber[RAS_MaxCallbackNumber + 1];
  TCHAR  szUserName[UNLEN + 1];
  TCHAR  szPassword[PWLEN + 1];
  TCHAR  szDomain[DNLEN + 1] ;
#if (WINVER >= 0x401)
  DWORD      dwSubEntry;
  ULONG_PTR  dwCallbackId;
#endif
} RASDIALPARAMS;

Members

dwSize
Specifies the structure size, in bytes.
szEntryName
Specifies a string containing the phone-book entry to use to establish the connection. An empty string ("") specifies a simple modem connection on the first available modem port, in which case a nonempty szPhoneNumber must be provided.

Windows NT 4.0 and later versions: The callback number is no longer stored in the registry. Specifying an asterisk for szCallbackNumber causes RAS to return error 704: ERROR_BAD_CALLBACK_NUMBER.

szPhoneNumber
Specifies a string that contains an overriding phone number. An empty string ("") indicates that the phone-book entry's phone number should be used. If szEntryName is "", szPhoneNumber cannot be "".
szCallbackNumber
Specifies a string that contains a callback phone number. An empty string ("") indicates that callback should not be used. This string is ignored unless the user has "Set By Caller" callback permission on the RAS server. An asterisk indicates that the number stored in the phone book should be used for callback.
szUserName
Specifies a string that contains the user's user name. This string is used to authenticate the user's access to the remote access server.
szPassword
Specifies a string that contains the user's password. This string is used to authenticate the user's access to the remote access server.

Windows NT/2000 or later: Use szPassword to send a new password to the remote server when you restart a RasDial connection from a RASCS_PasswordExpired paused state. When changing a password on an entry that calls Microsoft servers limit the new password to 14 characters in length to avoid down-level compatibility problems.

Windows 2000 and later versions: When retrieving the password using the RasGetEntryDialParams function, the szPassword member does not receive the actual password. Instead, szPassword receives a handle to the saved password. Substitute this handle for the saved password in calls to RasSetDialParams, and RasDial. When presented with this handle, RasDial retrieves and uses the saved password. The value of this handle may change in future versions of the operating system; do not develop code that depends on the contents or format of this value.

szDomain
Specifies a string that contains the domain on which authentication is to occur. An empty string ("") specifies the domain in which the remote access server is a member. An asterisk specifies the domain stored in the phone book for the entry.
dwSubEntry
Specifies the index of the initial subentry to dial. If the dial mode is RASEDM_DialAsNeeded, RAS dials this subentry. If dwSubEntry is not a valid subentry index, RAS dials the first subentry.

If the dial mode of the phone-book entry is RASEDM_DialAll, dwSubEntry is ignored. If the phone-book entry has no subentries, dwSubEntry is ignored.

The subentry indexes are one-based. That is, the first subentry has an index of one, the second subentry as an index of two, and so on.

The RASENTRY structure returned by RasGetEntryProperties indicates the dial mode (dwDialMode) and number of subentries (dwSubEntries) for the phone-book entry.

Windows 2000 and later: If dwSubEntry specifies a valid subentry index, RAS dials the specified subentry regardless of the dial mode. If the dial mode is RASEDM_DialAll and dwSubEntry is zero, RAS dials all of the subentries.

dwCallbackId
Specifies an application-defined value that RAS passes to the RasDialFunc2 callback function.

Remarks

The szUserName and szPassword strings are used to authenticate the user's access to the remote access server.

Windows NT/2000 or later: RAS does not actually log the user onto the network. The user does this in the usual manner, for example, by logging on with cached credentials prior to making the connection, or by using CTRL+ALT+DEL after the RAS connection is established.

If both the szUserName and szPassword members are empty strings (""), RAS uses the user name and password of the current logon context for authentication. For a user-mode application, RAS uses the credentials of the currently logged-on interactive user. For a Win32 service process, RAS uses the credentials associated with the service.

Windows 95: RAS uses the szUserName and szPassword strings to log the user onto the network.

Windows 95 cannot obtain the password of the currently logged-on user, so if both the szUserName and the szPassword members are empty strings (""), RAS leaves the user name and password empty during authentication.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Ras.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, RasDial, RasGetEntryProperties, RasSetEntryDialParams, RASENTRY


RASEAPINFO

The RASEAPINFO structure contains user-specific Extensible Authentication Protocol (EAP) information. Use RASEAPINFO to pass this information to the RasDial function.

typedef struct tagRASEAPINFO {
  DWORD    dwSizeofEapInfo;
  BYTE  *  pbEapInfo;
};

Members

dwSizeofEapInfo
Specifies the size of the binary information pointed to by the pbEapInfo member.
pbEapInfo
Pointer to binary EAP information. RasDial uses this information for authentication.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, RasGetEapUserData, RASDIALEXTENSIONS


RASEAPUSERIDENTITY

The RASEAPUSERIDENTITY structure stores identity information for a particular user. This information is required for remote access connections that use Extensible Authentication Protocol (EAP) for authentication.

struct RASEAPUSERIDENTITY {
  TCHAR    szUserName[ UNLEN + 1 ];  // user name
  DWORD    dwSizeofEapInfo;          // size of identity info
  BYTE     pbEapInfo[ 1 ];           // identity info
};

Members

szUserName[ UNLEN + 1 ]
Pointer to user name of the user reqesting authentication.
dwSizeofEapInfo
Size of the identity information required by the extensible authentication protocol.
pbEapInfo[ 1 ]
Pointer to the identity information required by the extensible authentication protocol.

Remarks

Obtain the EAP information for the current user by calling RasGetEapUserIdentity. This function will return a RASEAPUSERIDENTITY structure containing the EAP information. Free the memory occupied by this structure by calling RasFreeEapUserIdentity.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.

See Also

RasFreeEapUserIdentity, RasGetEapUserIdentity


RASENTRY

[This is preliminary documentation and subject to change.]

The RASENTRY structure describes a phone-book entry. The RasSetEntryProperties and RasGetEntryProperties functions use this structure to set and retrieve the properties of a phone-book entry.

typedef struct tagRASENTRY {
  DWORD      dwSize;
  DWORD      dwfOptions;
  //
  // Location/phone number.
  //
  DWORD      dwCountryID;
  DWORD      dwCountryCode;
  TCHAR      szAreaCode[ RAS_MaxAreaCode + 1 ];
  TCHAR      szLocalPhoneNumber[ RAS_MaxPhoneNumber + 1 ];
  DWORD      dwAlternateOffset;
  //
  // PPP/Ip
  //
  RASIPADDR  ipaddr;
  RASIPADDR  ipaddrDns;
  RASIPADDR  ipaddrDnsAlt;
  RASIPADDR  ipaddrWins;
  RASIPADDR  ipaddrWinsAlt;
  //
  // Framing
  //
  DWORD      dwFrameSize;
  DWORD      dwfNetProtocols;
  DWORD      dwFramingProtocol;
  //
  // Scripting
  //
  TCHAR      szScript[ MAX_PATH ];
  //
  // AutoDial
  //
  TCHAR       szAutodialDll[ MAX_PATH ];
  TCHAR       szAutodialFunc[ MAX_PATH ];
  //
  // Device
  //
  TCHAR      szDeviceType[ RAS_MaxDeviceType + 1 ];
  TCHAR      szDeviceName[ RAS_MaxDeviceName + 1 ];
  //
  // X.25
  //
  TCHAR      szX25PadType[ RAS_MaxPadType + 1 ];
  TCHAR      szX25Address[ RAS_MaxX25Address + 1 ];
  TCHAR      szX25Facilities[ RAS_MaxFacilities + 1 ];
  TCHAR      szX25UserData[ RAS_MaxUserData + 1 ];
  DWORD      dwChannels;
  //
  // Reserved
  //
  DWORD       dwReserved1;
  DWORD       dwReserved2;
#if (WINVER >= 0x401)
  //
  // Multilink and BAP
  //
  DWORD       dwSubEntries;
  DWORD       dwDialMode;
  DWORD       dwDialExtraPercent;
  DWORD       dwDialExtraSampleSeconds;
  DWORD       dwHangUpExtraPercent;
  DWORD       dwHangUpExtraSampleSeconds;
  //
  // Idle time out
  //
  DWORD       dwIdleDisconnectSeconds;
#endif
#if (WINVER >= 0x500)
  DWORD     dwType;               // entry type
  DWORD     dwEncryptionType;     // type of encryption to use
  DWORD     dwCustomAuthKey;      // authentication key for EAP
  GUID      guidId;               // guid that represents
                                  // the phone-book entry
  TCHAR    szCustomDialDll[MAX_PATH];    // DLL for custom dialing
  DWORD    dwVpnStrategy;         // specifies type of VPN protocol
#endif
#if (WINVER >= 0x501)
  DWORD     dwfOptions2;
  DWORD     dwfOptions3;
  WCHAR     szDnsSuffix;
#endif
} RASENTRY;

Members

dwSize
Specifies the size, in bytes, of the RASENTRY structure. Before calling RasSetEntryProperties or RasGetEntryProperties, set dwSize to sizeof(RASENTRY) to identify the version of the structure.
dwfOptions
A set of bit flags that specify connection options. Set one or more of the following flags.
Flag | Description
RASEO_UseCountryAndAreaCodes If this flag is set, the dwCountryID, dwCountryCode, and szAreaCode members are used to construct the phone number. If this flag is not set, these members are ignored.

This flag corresponds to the Use Country and Area Codes check boxes in the Phone dialog box.
RASEO_SpecificIpAddr If this flag is set, RAS tries to use the IP address specified by ipaddr as the IP address for the dial-up connection. If this flag is not set, the value of the ipaddr member is ignored.

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

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

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

Setting the RASEO_SpecificNameServers flag corresponds to selecting the Specify Name Server Addresses setting in the TCP/IP Settings dialog box. Clearing the RASEO_SpecificNameServers flag corresponds to selecting the Server Assigned Name Server Addresses setting in the TCP/IP Settings dialog box.
RASEO_IpHeaderCompression If this flag is set, RAS negotiates to use IP header compression on PPP connections.

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

This flag corresponds to the Use IP Header Compression check box in the TCP/IP settings dialog box. It is generally advisable to set this flag because IP header compression significantly improves performance. The flag should be cleared only when connecting to a server that does not correctly negotiate IP header compression.
RASEO_RemoteDefaultGateway If this flag is set, the default route for IP packets is through the dial-up adapter when the connection is active. If this flag is clear, the default route is not modified.

This flag corresponds to the Use Default Gateway on Remote Network check box in the TCP/IP settings dialog box.
RASEO_DisableLcpExtensions | If this flag is set, RAS disables the PPP LCP extensions defined in RFC 1570. This may be necessary to connect to certain older PPP implementations, but interferes with features such as server callback. Do not set this flag unless specifically required.
RASEO_TerminalBeforeDial If this flag is set, RAS displays a terminal window for user input before dialing the connection.

This flag works only if this phone-book entry is dialed by the RasDialDlg function. This flag has no effect if the entry is dialed by the RasDial function.
RASEO_TerminalAfterDial If this flag is set, RAS displays a terminal window for user input after dialing the connection.

Do not set this flag if a dial-up networking script is to be associated with the connection, because scripting has its own terminal implementation.

This flag works only if this phone-book entry is dialed by the RasDialDlg function. This flag has no effect if the entry is dialed by the RasDial function.
RASEO_ModemLights | Windows 2000 or later: If this flag is set, a status monitor will be displayed in the Task Bar.
RASEO_SwCompression | If this flag is set, software compression is negotiated on the link. Setting this flag causes the PPP driver to attempt to negotiate CCP with the server. This flag should be set by default, but clearing it can reduce the negotiation period if the server does not support a compatible compression protocol.
RASEO_RequireEncryptedPw If this flag is set, only secure password schemes can be used to authenticate the client with the server. This prevents the PPP driver from using the PAP plain-text authentication protocol to authenticate the client. The CHAP and SPAP authentication protocols are also supported. Clear this flag for increased interoperability, and set it for increased security.

This flag corresponds to the Require Encrypted Password check box in the Security dialog box. See also RASEO_RequireMsEncryptedPw.
RASEO_RequireMsEncryptedPw If this flag is set, only the Microsoft secure password scheme, MSCHAP, can be used to authenticate the client with the server. This flag prevents the PPP driver from using the PPP plain-text authentication protocol (PAP), MD5-CHAP, or SPAP. See Also the following flags: RASEO_RequireMsCHAP, RASEO_RequireMsCHAP2, and RASEO_RequireW95MsCHAP.

This flag corresponds to the Require Microsoft Encrypted Password check box in the Security dialog box. See also RASEO_RequireDataEncryption.
RASEO_RequireDataEncryption If this flag is set, data encryption must be negotiated successfully or the connection should be dropped. This flag is ignored unless RASEO_RequireMsEncryptedPw is also set.

This flag corresponds to the Require Data Encryption check box in the Security dialog box.
RASEO_NetworkLogon If this flag is set, RAS logs on to the network after the point-to-point connection is established.

This flag currently has no effect under Windows NT/2000.
RASEO_UseLogonCredentials If this flag is set, RAS uses the user name, password, and domain of the currently logged-on user when dialing this entry. This flag is ignored unless RASEO_RequireMsEncryptedPw is also set.

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

This flag corresponds to the Use Current Username and Password check box in the Security dialog box.
RASEO_PromoteAlternates This flag has an effect when alternate phone numbers are defined by the dwAlternateOffset member. If this flag is set, an alternate phone number that connects successfully becomes the primary phone number, and the current primary phone number is moved to the alternate list.

This flag corresponds to the check box in the Alternate Numbers dialog box.
RASEO_SecureLocalFiles | Windows NT/2000 or later: If this flag is set, RAS checks for existing remote file system and remote printer bindings before making a connection with this entry. Typically, set this flag is set on phone-book entries for public networks to remind users to break connections to their private network before connecting to a public network.
RASEO_RequireEAP | Windows 2000 or later: If this flag is set, an Extensible Authentication Protocol (EAP) must be supported for authentication.
RASEO_RequirePAP | Windows 2000 or later: If this flag is set, Password Authentication Protocol must be supported for authentication.
RASEO_RequireSPAP | Windows 2000 or later: If this flag is set, Shiva's Password Authentication Protocol must be supported for authentication.
RASEO_Custom | Windows 2000 or later: If this flag is set, the connection will use custom encryption.
RASEO_PreviewPhoneNumber | Windows 2000 or later: If this flag is set, the remote access dialer displays the phone number to be dialed.
RASEO_SharedPhoneNumbers | Windows 2000 or later: If this flag is set, phone numbers are shared.
RASEO_PreviewUserPw | Windows 2000 or later: If this flag is set, the remote access dialer displays the user's name and password prior to dialing.
RASEO_PreviewDomain | Windows 2000 or later: If this flag is set, the remote access dialer displays the domain name prior to dialing.
RASEO_ShowDialingProgress | Windows 2000 or later: If this flag is set, the remote access dialer displays its progress in establishing the connection.
RASEO_RequireCHAP | Windows 2000 or later: If this flag is set, the Challenge Handshake Authentication Protocol must be supported for authentication.
RASEO_RequireMsCHAP | Windows 2000 or later: If this flag is set, the Microsoft Challenge Handshake Authentication Protocol must be supported for authentication.
RASEO_RequireMsCHAP2 | Windows 2000 or later: If this flag is set, version 2 of the Microsoft Challenge Handshake Authentication Protocol must be supported for authentication.
RASEO_RequireW95MSCHAP | Windows 2000 or later: If this flag is set, MS-CHAP must send the LanManager-hashed password.
RASEO_CustomScript | Windows 2000 or later: This flag must be set in order for RAS to invoke a custom-scripting DLL after establishing the connection to the server.

dwCountryID
Specifies the TAPI country identifier. Use the RasGetCountryInfo function to enumerate country identifiers. This member is ignored unless the dwfOptions member specifies the RASEO_UseCountryAndAreaCodes flag.
dwCountryCode
Specifies the country code portion of the phone number. The country code must correspond to the country identifier specified by dwCountryID. If dwCountryCode is zero, the country code is based on the country identifier specified by dwCountryID. This member is ignored unless dwfOptions specifies the RASEO_UseCountryAndAreaCodes flag.
szAreaCode
Specifies the area code as a null-terminated string. If the dialing location does not have an area code, specify an empty string (""). Do not include parentheses or other delimiters in the area code string. For example, "206" is a valid area code; "(206)" is not. This member is ignored unless the dwfOptions member specifies the RASEO_UseCountryAndAreaCodes flag.
szLocalPhoneNumber
Specifies a null-terminated string that contains a telephone number. The way RAS uses this string depends on whether the dwfOptions member specifies the RASEO_UseCountryAndAreaCodes flag. If the flag is set, RAS combines szLocalPhoneNumber with the country and area codes specified by the dwCountryID, dwCountryCode , and szAreaCode members. If the flag is not set, RAS uses the szLocalPhoneNumber string as the entire phone number.

Windows 2000 and later: Specifies a device-type specific destination string. The following table describes the contents of the szLocalPhoneNumber member for various device types.
Device | szLocalPhoneNumber
RASDT_Modem | Telephone number
RASDT_Atm Virtual Path Identifier (VPI) and Virtual Channel Identifier (VCI) values of a permanent vitual circuit. Use the following format:

P<vpi>,<vci>

Example: "P0,40"
RASDT_PPPoE | Service name
RASDT_Vpn | DNS name or IP address

dwAlternateOffset
Specifies the offset, in bytes, from the beginning of the structure to a list of consecutive null-terminated strings. The last string is terminated by two consecutive null characters. The strings are alternate phone numbers that RAS dials in the order listed if the primary number (see szLocalPhoneNumber) fails to connect. The alternate phone number strings are ANSI or Unicode, depending on whether you use the ANSI or Unicode version of the structure.

You are not able to use the RAS API to set area codes or country codes for alternate phone numbers.

ipaddr
Specifies the IP address to be used while this connection is active. This member is ignored unless dwfOptions specifies the RASEO_SpecificIpAddr flag.
ipaddrDns
Specifies the IP address of the DNS server to be used while this connection is active. This member is ignored unless dwfOptions specifies the RASEO_SpecificNameServers flag.
ipaddrDnsAlt
Specifies the IP address of a secondary or backup DNS server to be used while this connection is active. This member is ignored unless dwfOptions specifies the RASEO_SpecificNameServers flag.
ipaddrWins
Specifies the IP address of the WINS server to be used while this connection is active. This member is ignored unless dwfOptions specifies the RASEO_SpecificNameServers flag.
ipaddrWinsAlt
Specifies the IP address of a secondary WINS server to be used while this connection is active. This member is ignored unless dwfOptions specifies the RASEO_SpecificNameServers flag.
dwFrameSize
Specifies the network protocol frame size. The value should be either 1006 or 1500. This member is ignored unless dwFramingProtocol specifies the RASFP_Slip flag.
dwfNetProtocols
Specifies the network protocols to negotiate. This member can be a combination of the following flags.
Flag | Description
RASNP_NetBEUI | Negotiate the NetBEUI protocol.
RASNP_Ipx | Negotiate the IPX protocol.
RASNP_Ip | Negotiate the TCP/IP protocol.

Whistler or later: The RASNP_NetBEUI flag is not supported.

Windows 2000 64-bit Edition: The RASNP_Ipx flag is not supported.

dwFramingProtocol
Specifies the framing protocol used by the server. PPP is the emerging standard. SLIP is used mainly in UNIX environments. This member can be one of the following flags.
Flag | Description
RASFP_Ppp | Point-to-Point Protocol (PPP)
RASFP_Slip | Serial Line Internet Protocol (SLIP)
RASFP_Ras | Asynchronous NetBEUI, Microsoft proprietary protocol implemented in Windows NT 3.1 and Windows for Workgroups 3.11

To use Compressed SLIP, set the RASFP_Slip flag and set the RASEO_IpHeaderCompression flag in the dwfOptions member.

Windows 2000 or later: The RASFP_Ras flag is no longer supported. As a result, Windows 2000 and later computers will not be able to connect to Lan Manager, Windows for Workgroups 3.11, or Windows NT 3.1 servers. However, these earlier platforms will continue to be able to connect to Windows 2000 and later servers.

szScript
Specifies a null-terminated string that contains the name of the script file. The file name should be a full path.

Windows NT/2000 or later: To indicate a Windows NT/Windows 2000 SWITCH.INF script name, set the first character of the name to "[".

szAutodialDll
Specifies a null-terminated string that contains the full path and file name of the dynamic-link library (DLL) for the customized AutoDial handler. If szAutodialDll contains an empty string (""), RAS uses the default dialing user interface and the szAutodialFunc member is ignored.
szAutodialFunc
Specifies a null-terminated string that contains the exported name of the RASADFunc function for the customized AutoDial handler. An AutoDial DLL must provide both ANSI and Unicode versions of the RASADFunc handler. However, do not include the "A" or "W" suffix in the name specified by szAutodialFunc.
szDeviceType
Specifies a null-terminated string that indicates the RAS device type referenced by szDeviceName. This member can be one of the following string constants.
String | Description
RASDT_Modem | A modem accessed through a COM port.
RASDT_Isdn | An ISDN card with corresponding NDISWAN driver installed.
RASDT_X25 | An X.25 card with corresponding NDISWAN driver installed.
RASDT_Vpn | Windows 2000 or later: A virtual private network connection. For more information, see VPN Connections
RASDT_Pad | Windows 2000 or later: A Packet Assembler/Disassembler.
RASDT_Generic | Windows 2000 or later: Generic
RASDT_Serial | Windows 2000 or later: Direct serial connection through a serial port.
RASDT_FrameRelay | Windows 2000 or later: Frame Relay
RASDT_Atm | Windows 2000 or later: Asynchronous Transfer Mode (ATM).
RASDT_Sonet | Windows 2000 or later: Sonet
RASDT_SW56 | Windows 2000 or later: Switched 56K Access
RASDT_Irda | Windows 2000 or later: Infrared Data Association (IrDA) compliant device.
RASDT_Parallel | Windows 2000 or later: Direct parallel connection through a parallel port.
RASDT_PPPoE | Whistler: Point-to-Point Protocol over Ethernet. For more information, see PPPoE Connections

Windows 95: The RASDT_Vpn device type is supported on Windows 95 only if Microsoft Dial-Up Networking Version 1.2 is installed. The RASDT_X25 and RASDT_Pad device types are not supported on Windows 95.

Windows 98/Me: The RASDT_Vpn device type is supported on Windows 98. However, the RASDT_X25 and RASDT_Pad device types are not currently supported on Windows 98.

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

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

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

Windows 2000 and later: In order for RAS to dial all subentries, dwDialMode must be set to RASEDM_DialAll and the dwSubEntry member of RASDIALPARAMS must be set to zero. To dial the first available subentry, set dwDialMode to zero, and set the dwSubEntry member of RASDIALPARAMS to zero as well.

dwDialExtraPercent
Windows 2000 or later: Specifies a percent of the total bandwidth available from the currently connected subentries. RAS dials an additional subentry when the total bandwidth used exceeds dwDialExtraPercent percent of the available bandwidth for at least dwDialExtraSampleSeconds seconds.

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

dwDialExtraSampleSeconds
Windows 2000 or later: Specifies the number of seconds that current bandwidth usage must exceed the threshold specified by dwDialExtraPercent before RAS dials an additional subentry.

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

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

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

dwHangUpExtraSampleSeconds
Windows 2000 or later: Specifies the number of seconds that current bandwidth usage must be less than the threshold specified by dwHangUpExtraPercent before RAS terminates an existing subentry connection.

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

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

dwType
Windows 2000 and later: The type of phone-book entry. This member can be one of the following types.
Type | Description
RASET_Phone | Phone line, for example, modem, ISDN, X.25.
RASET_Vpn | Virtual Private Network
RASET_Direct | Direct serial or parallel connection
RASET_Internet | Connection Manager (CM) connection. This value is reserved for system use.
RASET_Broadband | Whistler: Broadband connections, e.g. Digital Subscriber Line (DSL).

Whistler: To create a Point-to-Point Protocol over Ethernet (PPPoE) connection programmatically, use the RASET_Broadband entry type. For more information, see PPoE Connections.

dwEncryptionType
Windows 2000 or later: The type of encryption to use for Microsoft Point to Point Encryption (MPPE) with the connection. This member can be one of the following values.
Value | Meaning
ET_None | No encryption
ET_Require | Require encryption
ET_RequireMax | Require maximum-strength encryption.
ET_Optional | Do encryption if possible. No encryption is okay.

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

dwCustomAuthKey
Windows 2000 or later: This member is used for Extensible Authentication Protocol (EAP). This member contains the authentication key provided to the EAP vendor.
guidId
Windows 2000 or later: The GUID (Globally Unique IDentifier) that represents this phone-book entry. This member is read-only.
szCustomDialDll[MAX_PATH]
Windows 2000 or later: A null-terminated string that contains the full path and file name for the dynamic link library (DLL) that implements the custom-dialing functions. This DLL should export Unicode versions of functions named RasCustomDial, RasCustomHangup, RasCustomEntryDlg, and RasCustomDialDlg. These functions should have prototypes RasCustomDialFn and RasCustomHangUpFn as defined in Ras.h, and RasCustomDialDlgFn and RasCustomEntryDlgFn as defined in Rasdlg.h.

If szCustomDialDll contains an empty string, RAS uses the default system dialer.

dwVpnStrategy
Windows 2000 or later: The VPN strategy to use when dialing a VPN connection. This member can have one of the following values.
Value | Meaning
VS_Default | With this strategy, RAS dials PPTP first. If PPTP fails, L2TP is attempted. Whichever protocol succeeds is tried first in subsequent dialing for this entry.
VS_PptpOnly | RAS will dial only PPTP.
VS_PptpFirst | RAS will always dial PPTP first.
VS_L2tpOnly | RAS will dial only L2TP.
VS_L2tpFirst | RAS will always dial L2TP first.

dwfOptions2
Windows 2000 SP2 and later: A set of bits that specify connection options. This parameter is a continuation of the bits specified in the dwfOptions parameter. Set one or more of the following bit flags.
Flag | Description
RASEO_SecureFileAndPrint | Setting this bit flag prevents remote users from using file and print services over the RAS connection. Setting this flag is equivalent to clearing the File and Print Sharing for Microsoft Networks checkbox in the connection properties dialog box.
RASEO_SecureClientForMSNet | Setting this bit flag is equivalent to clearing the Client for Microsoft Networks checkbox in the connection properties dialog box.
RASEO_DontNegotiateMultilink | If this bit flag is set, the default behavior for the RAS client is not to negotiate multilink.
RASEO_DontUseRasCredentials | If this bit flag is set, RAS uses the default credentials to access network resources.

dwfOptions3
This parameter is reserved for future use.
szDnsSuffix
Whistler or later: Pointer to a Unicode string that specifies the Domain Name Service (DNS) suffix for the connection.

Remarks

Unless the operating system is Windows 2000 or later, the RAS Connection Manager ignores the dwDialMode, dwDialExtraPercent, dwDialExtraSampleSeconds, dwHangUpExtraPercent, and dwHangUpExtraSampleSeconds members. RAS uses these members for the Bandwidth Allocation Protocol (BAP). BAP is available only on Windows 2000 or later versions.

Windows 2000 and later: If the RAS client is using Bandwidth Allocation Protocol (BAP) with server callback, the registry value BapListenTimeout specifies the length of time, in seconds, the client will wait for the server to callback. This value is located beneath the registry key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\RasMan\ppp

BapListenTimeout is of type REG_DWORD. BapListenTimeout can be any number in the range 0 to 0xFFFFFFFF. It has a default value of 30.

Windows 2000 and later: If dwEncryptionType is ET_None, but RASEO_RequireDataEncryption is specified, it is as though dwEncryptionType was ET_Require.

Whistler or later: Whistler and later operating systems do not support the NetBEUI protocol.

Windows 2000 64-bit Edition: The 64-bit edition Windows 2000 does not support the IPX protocol.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 OSR2 or later.
Header: Declared in Ras.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, Point-to-Point Protocol over Ethernet Connections, RASADFunc, RasGetCountryInfo, RasGetEntryProperties, RasSetEntryProperties, RasSetSubEntryProperties


RASENTRYDLG

[This is preliminary documentation and subject to change.]

The RASENTRYDLG structure is used in the RasEntryDlg function to specify addtional input and output parameters.

typedef struct tagRASENTRYDLG {
  IN  DWORD dwSize;
  IN  HWND  hwndOwner;
  IN  DWORD dwFlags;
  IN  LONG  xDlg;
  IN  LONG  yDlg;
  OUT WCHAR szEntry[ RAS_MaxEntryName + 1 ];
  OUT DWORD dwError;
  IN  DWORD reserved;
  IN  DWORD reserved2;
} RASENTRYDLG;

Members

dwSize
Specifies the size of this structure, in bytes. Before calling RasEntryDlg, set this member to sizeof(RASENTRYDLG) to indicate the version of the structure. If dwSize is not a valid size, RasEntryDlg fails and sets the dwError member to ERROR_INVALID_SIZE.
hwndOwner
Specifies the window that owns the modal RasEntryDlg dialog box. This member can be any valid window handle, or it can be NULL if the dialog box has no owner.
dwFlags
A set of bit flags that indicate the options enabled for the dialog box. This parameter can be a combination of the RASEDFLAG_PositionDlg flag and one of the other flags listed following to indicate whether the RasEntryDlg function is creating, copying, or editing a phone-book entry.
Value | Meaning
RASEDFLAG_PositionDlg | Causes RasEntryDlg to use the values specified by the xDlg and yDlg members to position the dialog box. If this flag is not set, the dialog box is centered on the owner window, unless hwndOwner is NULL, in which case, the dialog box is centered on the screen.
RASEDFLAG_NewEntry | Causes RasEntryDlg to display a wizard for creating a new phone-book entry.
RASEDFLAG_CloneEntry | Causes RasEntryDlg to create a new entry by copying the properties of an existing entry. The function displays a property sheet containing the properties associated with the phone-book entry specified by the lpszEntry parameter of RasEntryDlg. The user can edit the properties and specify a name for the new entry.
RASEDFLAG_NoRename | Causes RasEntryDlg to display a property sheet for editing the properties of the phone-book entry specified by the lpszEntry parameter of RasEntryDlg. The user can change the properties of the entry but not its name.
RASEDFLAG_ShellOwned | Windows 2000 or later: Reserved for system use.
RASEDFLAG_NewPhoneEntry | Windows 2000 or later: Similar to RASEDFLAG_NewEntry. However, this flag causes the wizard to go directly to the page for a new phone-line entry.
RASEDFLAG_NewTunnelEntry | Windows 2000 or later: Similar to RASEDFLAG_NewEntry. However, this flag causes the wizard to go directly to the page for a new tunnel entry.
RASEDFLAG_NewDirectEntry | Windows 2000 or later: Similar to RASEDFLAG_NewEntry. However, this flag causes the wizard to go directly to the page for a new direct-connection entry.
RASEDFLAG_NewBroadbandEntry | Whistler: Causes RasEntryDlg to display a wizard that creates a new broadband phonebook entry.

xDlg
Specifies the horizontal screen coordinate of the upper-left corner of the dialog box. This value is used only if the RASEDFLAG_PositionDlg flag is set.
yDlg
Specifies the vertical screen coordinate of the upper-left corner of the dialog box. This value is used only if the RASEDFLAG_PositionDlg flag is set.
szEntry
On exit, szEntry is set to the name of the phone-book entry that was edited or created.
dwError
The RasEntryDlg function sets this member to a system error code or RAS error code if an error occurs. If no error occurs, the function sets dwError to zero. This value is ignored on input.
reserved
Reserved; must be zero.
reserved2
Reserved; must be zero.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Rasdlg.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, RasEntryDlg


RASENTRYNAME

The RASENTRYNAME structure contains an entry name from a remote access phone book. The RasEnumEntries function returns an array of these structures.

typedef struct _RASENTRYNAME {
  DWORD  dwSize;
  TCHAR  szEntryName[RAS_MaxEntryName + 1];
#if (WINVER >= 0x500)
  DWORD dwFlags;
  CHAR  szPhonebookPath[MAX_PATH + 1];
#endif
} RASENTRYNAME;

Members

dwSize
Specifies the structure size, in bytes. Before using RASENTRYNAME in a function call, set this member to sizeof(RASENTRYNAME).
szEntryName
Specifies a string containing the name of a remote access phone-book entry.
dwFlags
Windows 2000 or later: Specifies whether the entry is in the system phone book in the AllUsers profile, or in the user's profile phone book. This member should be one of the following values.
Value | Meaning
REN_AllUsers | The phone book is a system phone book and is in the AllUsers profile.
REN_User | The phone book is in the user's profile.

szPhonebookPath
Windows 2000 or later: Specifies the full path and file name of the phone-book (PBK) file.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Ras.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, RasEnumEntries


RASIPADDR

The RASIPADDR structure contains an IP address. The RASENTRY structure uses this structure to specify the IP addresses of various servers associated with an entry in a RAS phone book.

typedef struct RASIPADDR {
  BYTE    a;
  BYTE    b;
  BYTE    c;
  BYTE    d;
} RASIPADDR;

Members

a, b, c, and d
These members specify the value of the corresponding location in the "a.b.c.d" IP address.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, RASENTRY


RASMONITORDLG

The RASMONITORDLG structure is used in the RasMonitorDlg function to specify additional input and output parameters.

typedef struct tagRASMONITORDLG {
  IN  DWORD dwSize;
  IN  HWND  hwndOwner;
  IN  DWORD dwFlags;
  IN  DWORD dwStartPage;
  IN  LONG  xDlg;
  IN  LONG  yDlg;
  OUT DWORD dwError;
  IN  DWORD reserved;
  IN  DWORD reserved2;
} RASMONITORDLG;

Members

dwSize
Specifies the size of this structure, in bytes. Before calling RasMonitorDlg, set this member to sizeof(RASMONITORDLG) to indicate the version of the structure. If dwSize is not a valid size, RasMonitorDlg fails and sets the dwError member to ERROR_INVALID_SIZE.
hwndOwner
Specifies the window that owns the modal RasMonitorDlg property sheet. This member can be any valid window handle, or it can be NULL if the property sheet has no owner.
dwFlags
A bit flag that indicates the options that are enabled for the property sheet. Specify the following value.
Value | Meaning
RASMDFLAG_PositionDlg | Causes RasMonitorDlg to use the values specified by the xDlg and yDlg members to position the dialog box. If this flag is not set, the dialog box is centered on the owner window, unless hwndOwner is NULL, in which case, the dialog box is centered on the screen.

dwStartPage
A set of bit flags that indicate the initial page of the property sheet to display on top. Specify one of the following values.
Value | Meaning
RASMDPAGE_Status | Display the Status page on top. This is the default.
RASMDPAGE_Summary | Display the Summary page on top.
RASMDPAGE_Preferences | Display the Preferences page on top.

xDlg
Specifies the horizontal screen coordinate of the upper-left corner of the property sheet. This value is used only if the RASMDFLAG_PositionDlg flag is set.
yDlg
Specifies the vertical screen coordinate of the upper-left corner of the property sheet. This value is used only if the RASMDFLAG_PositionDlg flag is set.
dwError
The RasMonitorDlg function sets this member to a system error code or RAS error code if an error occurs. If no error occurs, the function sets dwError to zero. This value is ignored on input.
reserved
Reserved; must be zero.
reserved2
Reserved; must be zero.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Rasdlg.h.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, RasMonitorDlg


RASNOUSER

The RASNOUSER structure is used with the RasPBDlgFunc callback function to specify authentication credentials and other information. This structure enables dial-up networking operations that begin before a user has logged on. It is provided to support the WinLogon application, and is not typically used by other applications.

typedef struct tagRASNOUSER {
  IN  DWORD dwSize;
  IN  DWORD dwFlags;
  OUT DWORD dwTimeoutMs;
  OUT TCHAR szUserName[ UNLEN + 1 ];
  OUT TCHAR szPassword[ PWLEN + 1 ];
  OUT TCHAR szDomain[ DNLEN + 1 ];
} RASNOUSER;

Members

dwSize
Specifies the size of this structure, in bytes. This member indicates the version of the structure.
dwFlags
Reserved; must be zero.
dwTimeoutMs
Specifies the time, in milliseconds, before the RasPhonebookDlg dialog box closes and returns to the caller as if the user had pressed the Close button. This feature is required for code that displays a window during WinLogon. If the user leaves his or her terminal for some time, the dialog box closes and WinLogon reverts to the CTRL+ALT+DEL prompt.
szUserName
Specifies a null-terminated string that contains the name of the user. This string is used to authenticate the user's right to access the remote access server.
szPassword
Specifies a null-terminated string that contains the user's password. This string is used to authenticate the user's right to access the remote access server.
szDomain
Specifies a null-terminated string that contains the domain on which authentication is to occur. An empty string ("") specifies the domain in which the remote access server is a member.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Rasdlg.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, RasPBDlgFunc, RasPhonebookDlg


RASPBDLG

The RASPBDLG structure is used with the RasPhonebookDlg function to specify additional input and output parameters.

typedef struct tagRASPBDLG {
  IN  DWORD         dwSize;
  IN  HWND          hwndOwner;
  IN  DWORD         dwFlags;
  IN  LONG          xDlg;
  IN  LONG          yDlg;
  IN  DWORD         dwCallbackId;
  IN  RASPBDLGFUNC  pCallback;
  OUT DWORD         dwError;
  IN  DWORD         reserved;
  IN  DWORD         reserved2;
} RASPBDLG;

Members

dwSize
Specifies the size of this structure, in bytes. Before calling RasPhonebookDlg, set this member to sizeof(RASPBDLG) to indicate the version of the structure. If dwSize is not a valid size, RasPhonebookDlg fails and sets the dwError member to ERROR_INVALID_SIZE.
hwndOwner
Specifies the window that owns the modal RasPhonebookDlg dialog box. This member can be any valid window handle, or it can be NULL if the dialog box has no owner.
dwFlags
A set of bit flags that indicate the options enabled for the dialog box. This parameter can be a combination of the following values.
Value | Meaning
RASPBDFLAG_PositionDlg | Causes RasPhonebookDlg to use the values specified by the xDlg and yDlg members to position the dialog box. If this flag is not set, the dialog box is centered on the owner window, unless hwndOwner is NULL, in which case, the dialog box is centered on the screen.
RASPBDFLAG_ForceCloseOnDial | Turns on the close-on-dial option, overriding the user's preference. This option is appropriate with features such as RAS AutoDial where the user's goal is to make a connection immediately.
RASPBDFLAG_NoUser | Causes the RasPBDlgFunc callback function specified by the pCallback member to receive a RASPBDEVENT_NoUser notification when the dialog box is starting up. This flag is for use in situations in which there is no logged-on user, as in the WinLogon application. Typically, applications should not use this flag.
RASPBDFLAG_UpdateDefaults | Causes the default window position to be saved on exit. This flag is used primarily by RASPHONE.EXE and should not be used by typical applications.

xDlg
Specifies the horizontal screen coordinate of the upper-left corner of the dialog box. This value is used only if the RASPBDFLAG_PositionDlg flag is set.
yDlg
Specifies the vertical screen coordinate of the upper-left corner of the dialog box. This value is used only if the RASPBDFLAG_PositionDlg flag is set.
dwCallbackId
Specifies an application-defined value that is passed to the callback function specified by pCallback. Use dwCallbackId to pass a pointer to application-specific context information.
pCallback
Pointer to a RasPBDlgFunc callback function that receives notifications of user activity while the dialog box is open. This member is NULL if notifications are not required.
dwError
The RasPhonebookDlg function sets this member to a system error code or RAS error code if an error occurs. If no error occurs, the function sets dwError to zero. This value is ignored on input.
reserved
Reserved; must be zero.
reserved2
Reserved; must be zero.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Rasdlg.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, RasPBDlgFunc, RasPhonebookDlg


RASPPPCCP

The RASPPPCCP structure contains information that describes the results of a Compression Control Protocol (CCP) negotiation.

typedef  struct tagRASPPPCCP  {
  DWORD    dwSize;
  DWORD    dwError;
  DWORD    dwCompressionAlgorithm;
  DWORD    dwOptions;
  DWORD    dwServerCompressionAlgorithm;
  DWORD    dwServerOptions;
} RASPPPCCP;

Members

dwSize
Size of the RASPPPCCP structure. Ensure that this member contains the size of the structure before using the structure in a function call.
dwError
If the negotiation was unsuccessful, dwError contains the error that occurred.
dwCompressionAlgorithm
The compression algorithm in use by the client. The following table shows the possible values for this member.
Value | Meaning
RASCCPCA_MPPC | Microsoft Point to Point Compression (MPPC) Protocol (RFC 2118)
RASCCPCA_STAC | STAC option 4 (RFC 1974)

dwOptions
Specifies the compression options on the client. The following options are supported.
Option | Meaning
RASCCPO_Compression | Compression without encryption.
RASCCPO_HistoryLess | Microsoft Point to Point Encryption (MPPE) in stateless mode. The session key is changed after every packet. This mode improves performance on high latency networks, or networks that experience significant packet loss.
RASCCPO_Encryption56bit | MPPE using 56 bit keys.
RASCCPO_Encryption40bit | MPPE using 40 bit keys.
RASCCPO_Encryption128bit | MPPE using 128 bit keys.

The last three options are used when a connection is made over Layer 2 Tunneling Protocol (L2TP), and the connection uses IPSec encryption.

dwServerCompressionAlgorithm
The compression algorithm in use by the server. The following table shows the possible values for this member.
Value | Meaning
RASCCPCA_MPPC | Microsoft Point to Point Compression (MPPC) Protocol
RASCCPCA_STAC | STAC option 4

dwServerOptions
Specifies the compression options on the server. The following options are supported.
Option | Meaning
RASCCPO_Compression | Compression without encryption.
RASCCPO_HistoryLess | Microsoft Point to Point Encryption (MPPE) in stateless mode. The session key is changed after every packet. This mode improves performance on high latency networks, or networks that experience significant packet loss.
RASCCPO_Encryption56bit | MPPE using 56 bit keys.
RASCCPO_Encryption40bit | MPPE using 40 bit keys.
RASCCPO_Encryption128bit | MPPE using 128 bit keys.

The last three options are used when a connection is made over Layer 2 Tunneling Protocol (L2TP), and the connection uses IPSec encryption.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, RasGetProjectionInfo, RASPROJECTION, RASPPPLCP


RASPPPIP

The RASPPPIP structure contains the result of a PPP IP projection operation.

The RasGetProjectionInfo function returns a RASPPPIP data structure when its rasprojection parameter has the value RASP_PppIp.

typedef  struct  _RASPPPIP {
  DWORD    dwSize;
  DWORD    dwError;
  TCHAR    szIpAddress[ RAS_MaxIpAddress + 1 ];
#ifndef WINNT35COMPATIBLE
  TCHAR    szServerIpAddress[ RAS_MaxIpAddress + 1 ];
#endif
#if (WINVER >= 0x500)
  DWORD    dwOptions;
  DWORD    dwServerOptions;
#endif
} RASPPPIP;

Members

dwSize
Specifies the size of the structure, in bytes. Before calling the RasGetProjectionInfo function, set this member to indicate the version of the RASPPPIP structure. For information about earlier versions of this structure, see the following Remarks section.
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, the error that prevented the projection from completing successfully.
szIpAddress
Contains a zero-terminated string that is the client's IP address on the RAS connection. This address string has the form a.b.c.d.
szServerIpAddress
Contains a null-terminated string that is the IP address of the remote PPP peer (that is, the server's IP address). This string is in "a.b.c.d" form. PPP does not require that servers provide this address, but Windows NT/Windows 2000 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, "".
dwOptions
Windows 2000 and later: Specifies IPCP options for the local computer. Currently, the only option is RASIPO_VJ. This option indicates that IP datagrams sent by the local computer are compressed using Van Jacobson compression.
dwServerOptions
Windows 2000 and later: Specifies IPCP options for the remote peer. Currently, the only option is RASIPO_VJ. This option indicates that IP datagrams sent by the remote peer (that is, received by the local computer) are compressed using Van Jacobson compression.

Remarks

The szServerIpAddress member was added to the RASPPPIP structure beginning with Windows NT 3.51 and the initial release of Windows 95. Beginning with these systems, RasGetProjectionInfo will support both the current form of the structure and the old form without the szServerIpAddress member. Use the dwSize member to indicate the version of the structure.

For Windows NT 4.0 and earlier versions, RasGetProjectionInfo returns ERROR_INVALID_SIZE if dwSize specifies the current structure size. To retrieve PPP IP information from older systems, dwSize must specify the size of the old structure without the szServerIpAddress member.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Ras.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, RasGetProjectionInfo, RASPROJECTION


RASPPPLCP

The RASPPPLCP structure constains information that describes the results of a PPP Link Control Protocol (LCP)/multi-link negotiation.

typedef  struct  tagRASPPPLCP {
  DWORD dwSize;
  BOOL  fBundled;
#if (WINVER >= 0x500)
  DWORD  dwError;
  DWORD  dwAuthenticationProtocol;
  DWORD  dwAuthenticationData;
  DWORD  dwEapTypeId;
  DWORD  dwServerAuthenticationProtocol;
  DWORD  dwServerAuthenticationData;
  DWORD  dwServerEapTypeId;
  BOOL   fMultilink;
  DWORD  dwTerminateReason;
  DWORD  dwServerTerminateReason;
  TCHAR  szReplyMessage[RAS_MaxReplyMessage];
  DWORD  dwOptions;
  DWORD  dwServerOptions;
#endif
}  RASPPPLCP;

Members

dwSize
Size of the RASPPPLCP structure. Ensure that this member contains the size of the structure before using the structure in a function call.
fBundled
If this member is TRUE, the connection is composed of multiple links. Otherwise, this member is FALSE.
dwError
If the negotiation was unsuccessful, dwError contains the error that occurred.
dwAuthenticationProtocol
The authentication protocol used to authenticate the client. This member can be one of the following values.
Value | Meaning
RASLCPAP_PAP | Password Authentication Protocol
RASLCPAP_SPAP | Shiva Password Authentication Protocol
RASLCPAP_CHAP | Challenge Handshake Authentication Protocol
RASLCPAP_EAP | Extensible Authentication Protocol

dwAuthenticationData
Provides additional information about the authentication protocol specified by the dwAuthenticationProtocol member. This member can be one of the following values.
Value | Meaning
RASLCPAD_CHAP_MD5 | MD5 CHAP
RASLCPAD_CHAP_MS | Microsoft CHAP
RASLCPAD_CHAP_MSV2 | Microsoft CHAP version 2

dwEapTypeId
Provides the type ID of the extensible authentication protocol (EAP) used to authenticate the local computer. The value of this member is valid only if dwAuthenticationProtocol is RASLCPAPP_EAP.
dwServerAuthenticationProtocol
The authentication protocol used to authenticate the server. See the dwAuthenticationProtocol member for a list of possible values.
dwServerAuthenticationData
Provides additional information about the authentication protocol specified by dwServerAuthenticationProtocol. See the dwAuthenticationData member for a list of possible values.
dwServerEapTypeId
Provides the type ID of the extensible authentication protocol (EAP) used to authenticate the remote computer. The value of this member is valid only if dwServerAuthenticationProtocol is RASLCPAP_EAP.
fMultilink
If this member is TRUE, the connection supports multi-link. Otherwise, this member is FALSE.
dwTerminateReason
This member always has a value of zero.
dwServerTerminateReason
This member always has a value of zero.
szReplyMessage[RAS_MaxReplyMessage]
Pointer to a string that contains the message, if any, from the authentication protocol success/failure packet.
dwOptions
Provides additional LCP options for the local computer. This member is a combination of the following flags.
Flag | Meaning
RASLCPO_PFC | Protocol Field Compression (see RFC 1172)
RASLCPO_ACFC | Address and Control Field Compression (see RFC 1172)
RASLCPO_SSHF | Short Sequence Number Header Format (see RFC 1990)
RASLCPO_DES_56 | DES 56-bit encryption
RASLCPO_3_DES | Triple DES Encryption

dwServerOptions
Provides addition LCP options for the remote computer. This member is a combination of the following flags.
Flag | Meaning
RASLCPO_PFC | Protocol Field Compression (see RFC 1172)
RASLCPO_ACFC | Address and Control Field Compression (see RFC 1172)
RASLCPO_SSHF | Short Sequence Number Header Format (see RFC 1990)
RASLCPO_DES_56 | DES 56-bit encryption
RASLCPO_3_DES | Triple DES Encryption

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, RasGetProjectionInfo, RASPROJECTION, RASPPPCCP


RASPPPIPX

The RASPPPIPX structure contains the result of a PPP IPX projection operation.

The RasGetProjectionInfo function returns a RASPPPIPX data structure when its rasprojection parameter has the value RASP_PppIpx.

typedef  struct  _RASPPPIPX {
  DWORD    dwSize;
  DWORD    dwError;
  TCHAR    szIpxAddress[ RAS_MaxIpxAddress + 1 ];
} RASPPPIPX;

Members

dwSize
Specifies the size of the structure, in bytes. Before calling the RasGetProjectionInfo function, set this member to sizeof(RASPPPIPX). The function can then determine the version of the RASPPPIPX data structure that the caller of RasGetProjectionInfo is expecting. This allows backwards compatibility for compiled applications if there are future enhancements to the data structure.
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, the error that prevented the projection from completing successfully.
szIpxAddress
Contains a zero-terminated string that is the client's IPX address on the RAS connection. This address string has the form net.node; for example, "1234ABCD.12AB34CD56EF".

Remarks

The RASPPPIPX structure can be used only on 32-bit Whistler or an earlier operating system. Windows 2000 64-bit Edition does not support the IPX protocol.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Ras.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, RasGetProjectionInfo, RASPROJECTION


RASPPPNBF

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

The RasGetProjectionInfo function returns a RASPPPNBF data structure when its rasprojection parameter has the value RASP_PppNbf.

typedef  struct  _RASPPPNBF {
  DWORD    dwSize;
  DWORD    dwError;
  DWORD    dwNetBiosError;
  TCHAR    szNetBiosError[ NETBIOS_NAME_LEN + 1 ];
  TCHAR    szWorkstationName[ NETBIOS_NAME_LEN + 1 ];
  BYTE     bLana;
} RASPPPNBF;

Members

dwSize
Specifies the size of the structure, in bytes. Before calling the RasGetProjectionInfo function, set this member to sizeof(RASPPPNBF). The function can then determine the version of the RASPPPNBF data structure that the caller of RasGetProjectionInfo is expecting. This allows backwards compatibility for compiled applications if there are future enhancements to the data structure.
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, the error that prevented the projection from completing successfully.
dwNetBiosError
If dwError has the value ERROR_SERVER_NOT_RESPONDING or ERROR_NETBIOS_ERROR, the dwNetBiosError field contains the NetBIOS error that occurred. For other values of dwError, this field contains zero.

Windows 95: This member is undefined.

szNetBiosError
If dwError has the value ERROR_NAME_EXISTS_ON_NET, the szNetBiosError field contains a zero-terminated string that is the NetBIOS name that caused the conflict. For other values of dwError, this field contains the null string.
szWorkstationName
Contains a zero-terminated 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.
bLana
Specifies the NetBIOS network adapter identifier, or LANA, on which the remote access connection was established. This member contains the value 0xFF if a connection was not established.

Remarks

Whistler or later: Whistler and later operating systems do not support the NetBEUI protocol.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Ras.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, RasGetProjectionInfo, RASPROJECTION


RASSLIP

The RASSLIP structure contains the results of a the Serial Line Internet Protocol (SLIP) projection operation.

RASSLIP {
  DWORD dwSize;
  DWORD dwError;
  TCHAR szIpAddress[ RAS_MaxIpAddress + 1 ];
};

Members

dwSize
Specifies the size, in bytes, of the RASSLIP structure. Before calling the RasGetProjectionInfo function, set dwSize to sizeof(RASSLIP) to identify the version of the structure.
dwError
Specifies whether SLIP is configured. If dwError is zero, SLIP framing is configured. Otherwise, dwError is ERROR_PROTOCOL_NOT_CONFIGURED.
szIpAddress
A null-terminated string that contains the client's IP address on the RAS connection. This address string has the form a.b.c.d.

Remarks

If the RASENTRY structure for the phone-book entry used in a RAS connection specifies SLIP framing, call RasGetProjectionInfo with a RASPROJECTION of RASP_Slip to determine whether SLIP framing was successfully configured.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, RASENTRY, RasGetProjectionInfo, RASPROJECTION


RASSUBENTRY

[This is preliminary documentation and subject to change.]

The RASSUBENTRY structure contains information about a subentry of a RAS phone-book entry. The RasSetSubEntryProperties and RasGetSubEntryProperties functions use this structure to set and retrieve the properties of a subentry.

typedef struct tagRASSUBENTRY {
  DWORD      dwSize;
  DWORD      dwfFlags;
  //
  // Device
  //
  TCHAR      szDeviceType[ RAS_MaxDeviceType + 1 ];
  TCHAR      szDeviceName[ RAS_MaxDeviceName + 1 ];
  //
  // Phone numbers
  //
  TCHAR      szLocalPhoneNumber[ RAS_MaxPhoneNumber + 1 ];
  DWORD      dwAlternateOffset;
} RASSUBENTRY;

Members

dwSize
Specifies the size, in bytes, of the RASSUBENTRY structure. Before calling RasSetSubEntryProperties or RasGetSubEntryProperties, set dwSize to sizeof(RASSUBENTRY) to identify the version of the structure.
dwfFlags
Currently unused. The RasSetSubEntryProperties function sets this member to zero. The RasGetSubEntryProperties function ignores this member.
szDeviceType
Specifies a null-terminated string indicating the RAS device type referenced by szDeviceName. See RASENTRY for a list of possible device types.
szDeviceName
Specifies a null-terminated string containing the name of the TAPI device to use with this phone-book entry. To enumerate all available RAS-capable devices, use the RasEnumDevices function.
szLocalPhoneNumber
Specifies a null-terminated string containing a telephone number. The way RAS uses this string depends on whether the RASEO_UseCountryAndAreaCodes flag is set in the dwfOptions member of the RASENTRY structure for this phone-book entry. If the flag is set, RAS combines szLocalPhoneNumber with the country and area codes specified in the RASENTRY structure. If the flag is not set, RAS uses the szLocalPhoneNumber string as the entire phone number.
dwAlternateOffset
Specifies the offset, in bytes, from the beginning of the structure to a list of consecutive null-terminated strings. The last string is terminated by two consecutive null characters. The strings are alternate phone numbers that RAS dials in the order listed if the primary number (see szLocalPhoneNumber) fails to connect. The alternate phone number strings are ANSI or Unicode, depending on whether you use the ANSI or Unicode version of the structure.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Structures, RasGetSubEntryProperties, RasSetSubEntryProperties


Remote Access Service Messages

Use the following message to implement RAS functionality:

WM_RASDIALEVENT


WM_RASDIALEVENT

The operating system sends a WM_RASDIALEVENT message to a window procedure when a change of state event occurs during a RAS connection process, and a window has been specified to handle notifications of such events by using the notifier parameter of RasDial.

The two message parameters are equivalent to the parameters of the same names that are used with RasDialFunc and RasDialFunc1 callback functions.

WM_RASDIALEVENT
rasconnstate = (RASCONNSTATE) wParam; // connection state about to be entered
dwError = (DWORD) lParam;             // error that may have occurred

Parameters

rasconnstate
Value of wParam. Equivalent to the rasconnstate parameter of the RasDialFunc and RasDialFunc1 callback functions. Specifies a RASCONNSTATE enumerator value that indicates the state the RasDial remote access connection process is about to enter.
dwError
Value of lParam. Equivalent to the dwError parameter of the RasDialFunc and RasDialFunc1 callback functions. A nonzero value indicates the error that has occurred, or zero if no error has occurred.

RasDial sends this message with dwError set to zero upon entry to each connection state. If an error occurs within a state, the message is sent again for the state, this time with a nonzero dwError value.

Return Values

If an application processes this message, it should return TRUE.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Ras.h.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Messages, RasDial, RasDialFunc, RasDialFunc1, RASCONNSTATE


Remote Access Service Enumeration Types

Use the following enumeration types to implement RAS functionality:

RASCONNSTATE

RASPROJECTION


RASCONNSTATE

The RASCONNSTATE enumeration type contains values that specify the states that may occur during a RAS connection operation. If the RasDial function is used to establish a RAS connection, specify a window, or a RasDialFunc, RasDialFunc1, or RasDialFunc2 callback function to receive notification messages that report the current connection state. Also, use the RasGetConnectStatus function to get the connection state for a specified connection.

typedef enum _RASCONNSTATE {
  RASCS_OpenPort = 0,
  RASCS_PortOpened,
  RASCS_ConnectDevice,
  RASCS_DeviceConnected,
  RASCS_AllDevicesConnected,
  RASCS_Authenticate,
  RASCS_AuthNotify,
  RASCS_AuthRetry,
  RASCS_AuthCallback,
  RASCS_AuthChangePassword,
  RASCS_AuthProject,
  RASCS_AuthLinkSpeed,
  RASCS_AuthAck,
  RASCS_ReAuthenticate,
  RASCS_Authenticated,
  RASCS_PrepareForCallback,
  RASCS_WaitForModemReset,
  RASCS_WaitForCallback,
  RASCS_Projected,

#if (WINVER >= 0x400)
  RASCS_StartAuthentication,    // Windows 95 only
  RASCS_CallbackComplete,       // Windows 95 only
  RASCS_LogonNetwork,           // Windows 95 only
#endif
  RASCS_SubEntryConnected,
  RASCS_SubEntryDisconnected,

  RASCS_Interactive = RASCS_PAUSED,
  RASCS_RetryAuthentication,
  RASCS_CallbackSetByCaller,
  RASCS_PasswordExpired,
#if (WINVER >= 0x500)
  RASCS_InvokeEapUI,
#endif

  RASCS_Connected = RASCS_DONE,
  RASCS_Disconnected
} RASCONNSTATE ;

The enumerator values are listed here in the general order in which the connection states occur. However, do not write code that depends on the order or occurrence of particular RASCONNSTATE connection states, because this may vary between platforms.

RASCS_OpenPort
The communication port is about to be opened.
RASCS_PortOpened
The communication port has been opened successfully.
RASCS_ConnectDevice
A device is about to be connected. RasGetConnectStatus can be called to determine the name and type of the device being connected.
RASCS_DeviceConnected
A device has connected successfully. RasGetConnectStatus can be called to determine the name and type of the device being connected.

For a simple modem connection, RASCS_ConnectDevice and RASCS_DeviceConnected will be called only once. For a dial-up X.25 PAD connection, the pair will be called first for the modem, then for the PAD. If a preconnect switch is configured, the pair will be called for the switch before any other devices connect. Likewise, the pair will be called for a postconnect switch after any other devices connect.

Windows 95: Note that Windows 95 does not currently support multistage connections such as the X.25 PAD connection described earlier.

RASCS_AllDevicesConnected
All devices in the device chain have successfully connected. At this point, the physical link is established.
RASCS_Authenticate
The authentication process is starting. Remote access does not allow the remote client to generate any traffic on the LAN until authentication has been successfully completed.

Remote access authentication on a Windows NT/Windows 2000 or Windows 95 server consists of:

  • Validating the user name/password on the specified domain.
  • Projecting the client onto the LAN. This means that the remote access server does what is necessary to send and receive data on the LAN on behalf of the client. For example, the remote access server might need to add a NetBIOS name that corresponds to the client's computer name.
  • Call-back processing in which the client hangs up and the server calls back. (The user needs special permissions on the remote access server for this.)
  • Calculating the link speed. This is necessary to correctly set transport time-outs to match the relatively slow speed of the remote link.
RASCS_AuthNotify
An authentication event has occurred. If dwError is zero, this event will be immediately followed by one of the more specific authentication states following. If dwError is nonzero, authentication has failed, and the error value indicates why.
RASCS_AuthRetry
The client has requested another validation attempt with a new user name/password/domain. This state does not occur in Windows NT version 3.1.
RASCS_AuthCallback
The remote access server has requested a callback number. This occurs only if the user has "Set By Caller" callback privilege on the server.
RASCS_AuthChangePassword
The client has requested to change the password on the account. This state does not occur in Windows NT version 3.1.
RASCS_AuthProject
The projection phase is starting.
RASCS_AuthLinkSpeed
The link-speed calculation phase is starting.
RASCS_AuthAck
An authentication request is being acknowledged.
RASCS_ReAuthenticate
Reauthentication (after callback) is starting.
RASCS_Authenticated
The client has successfully completed authentication.
RASCS_PrepareForCallback
The line is about to disconnect in preparation for callback.
RASCS_WaitForModemReset
The client is delaying in order to give the modem time to reset itself in preparation for callback.
RASCS_WaitForCallback
The client is waiting for an incoming call from the remote access server.
RASCS_Projected
This state occurs after the RASCS_AuthProject state. It indicates that projection result information is available. Access the projection result information by calling RasGetProjectionInfo.
RASCS_StartAuthentication
Windows 95 only: Indicates that user authentication is being initiated or retried.
RASCS_CallbackComplete
Windows 95 only: Indicates that the client has been called back and is about to resume authentication.
RASCS_LogonNetwork
Windows 95 only: Indicates that the client is logging on to the network.
RASCS_SubEntryConnected
When dialing a multilink phone-book entry, this state indicates that a subentry has been connected during the dialing process. The dwSubEntry parameter of a RasDialFunc2 callback function indicates the index of the subentry. When the final state of all subentries in the phone-book entry has been determined, the connection state is RASCS_Connected if one or more subentries have been connected successfully.
RASCS_SubEntryDisconnected
When dialing a multilink phone-book entry, this state indicates that a subentry has been disconnected during the dialing process. The dwSubEntry parameter of a RasDialFunc2 callback function indicates the index of the subentry.
RASCS_Interactive
This state corresponds to the terminal state supported by RASPHONE.EXE. This state does not occur in Windows NT version 3.1.
RASCS_RetryAuthentication
This state corresponds to the retry authentication state supported by RASPHONE.EXE. This state does not occur in Windows NT version 3.1.
RASCS_CallbackSetByCaller
This state corresponds to the callback state supported by RASPHONE.EXE. This state does not occur in Windows NT version 3.1.
RASCS_PasswordExpired
This state corresponds to the change password state supported by RASPHONE.EXE. This state does not occur in Windows NT version 3.1.
RASCS_InvokeEapUI
An application can use this paused state to bring up a custom authentication UI. The application should call the RasInvokeEapUI function to invoke the custom UI. RASCS_InvokeEapUI is a paused state.
RASCS_Connected
Successful connection.
RASCS_Disconnected
Disconnection or failed connection.

Remarks

The connection process states are divided into three classes: running states, paused states, and terminal states.

An application can easily determine the class of a specific state by performing Boolean bit operations with the RASCS_PAUSED and RASCS_DONE bitmasks. Here are some examples:

fDoneState = (state & RASCS_DONE);
fPausedState = (state & RASCS_PAUSED);
fRunState = !(fDoneState || fPausedState);

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Ras.h.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Enumeration Types, RasDial, RasInvokeEapUI, RasGetConnectStatus, RasGetProjectionInfo, RASCONNSTATUS


RASPROJECTION

The RASPROJECTION enumeration type defines values that specify a particular authentication protocol or Point-to-Point Protocol (PPP) control protocol. An application passes a value of this type to the RasGetProjectionInfo function to specify the protocol of interest.

typedef enum _RASPROJECTION {
  RASP_Amb = 0x10000,
  RASP_PppNbf = 0x803F,
  RASP_PppIpx = 0x802B,
  RASP_PppIp = 0x8021,
  RASP_PppCcp = 0x80FD,
  RASP_PppLcp = 0xC021,
  RASP_Slip = 0x20000
} RASPROJECTION ;

Each of the RASPROJECTION enumerators has a corresponding data structure; the RasGetProjectionInfo function returns the specified information in a structure of that type.

RASP_Amb
Windows 2000 and earlier: Specifies the Authentication Message Block (AMB) authentication protocol. AMB is a NetBIOS-based protocol used to authenticate with downlevel remote access servers ( all those prior to Windows NT 3.5). The corresponding data structure is a RASAMB.
RASP_PppNbf
Windows 2000 and earlier: Specifies the NetBEUI Framer (NBF) protocol. NBFCP is a PPP network control protocol used to negotiate the parameters necessary to ship NetBEUI packets on a WAN link. The corresponding data structure is a RASPPPNBF.
RASP_PppIpx
Specifies the Internetwork Packet Exchange (IPX) control protocol. IPXCP is a PPP network control protocol used to negotiate the parameters necessary to ship IPX packets on a WAN link. The corresponding data structure is a RASPPPIPX.

Windows 2000 64-bit Edition: The 64-bit edition of Windows 2000 does not support the IPX protocol.

RASP_PppIp
Specifies the Internet Protocol (IP) control protocol. IPCP is a PPP network control protocol used to negotiate the parameters necessary to ship IP packets on a WAN link. The corresponding data structure is a RASPPPIP.
RASP_PppCcp
Specifies the Compression Control Protocol (CCP). CCP enables computers using PPP to negotiate compression algorithms and parameters. The corresponding data structure is RASPPPCCP.
RASP_PppLcp
Specifies the Link Control Protocol (LCP). LCP is used by computers to establish, modify, and terminate PPP connections. The corresponding data structure is RASPPPLCP.
RASP_Slip
Specifies the Serial Line Internet Protocol (SLIP). SLIP is a framing protocol used primarily in UNIX environments.

Remarks

Whistler or later: Whistler and later operating systems do not support the NetBEUI protocol or authentication message blocks (AMB).

Windows 2000 64-bit Edition: The 64-bit edition of Windows 2000 does not support the IPX protocol.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Ras.h.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Enumeration Types, RasGetProjectionInfo, RASAMB, RASPPPIP, RASPPPIPX, RASPPPNBF


RAS Server Administration Reference

The following functions, structures, messages, and enumeration types are used to administer a server running Remote Access Service (RAS):

  • RAS Server Administration Functions
  • RAS Server Administration Structures
  • RAS Server Administration Union
  • RAS Server Administration Enumeration Types


RAS Server Administration Functions

For Microsoft® Windows NT® 4.0, use the following functions to implement RAS server administration functionality. Microsoft® Windows® 95 does not provide RAS server support.

RasAdminFreeBuffer

RasAdminGetErrorString

RasAdminGetUserAccountServer

RasAdminPortClearStatistics

RasAdminPortDisconnect

RasAdminPortEnum

RasAdminPortGetInfo

RasAdminServerGetInfo

RasAdminUserGetInfo

RasAdminUserSetInfo

RAS Administration DLL Functions

RAS Security DLL Functions


RasAdminFreeBuffer

The RasAdminFreeBuffer function frees memory that was allocated by RAS on behalf of the caller.

DWORD RasAdminFreeBuffer(
  PVOID Pointer  // pointer to the buffer to free
);

Parameters

Pointer
[in] Pointer to the buffer to be freed.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value can be the following error code.

Value | Meaning
ERROR_INVALID_PARAMETER | The Pointer parameter is invalid.

There is no extended error information for this function; do not call GetLastError.

Remarks

Use the RasAdminFreeBuffer function to free the buffers allocated by the RasAdminPortEnum and RasAdminPortGetInfo functions.

Windows 2000 and later: The RasAdminFreeBuffer function is replaced by the MprAdminBufferFree function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 only.
Windows 95/98/Me: Unsupported.
Header: Declared in Rassapi.h.
Library: Use Rassapi.lib.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Functions, RasAdminPortEnum, RasAdminPortGetInfo


RasAdminGetErrorString

The RasAdminGetErrorString function retrieves a message string that corresponds to a RAS error code returned by one of the RAS server administration (RasAdmin) functions. These message strings are retrieved from the Rasmsg.dll that is installed as part of RAS.

DWORD RasAdminGetErrorString (
  UINT ResourceId,    // error code to get message for
  WCHAR *lpszString,  // pointer to a buffer that receives
                      //  the error string
  DWORD InBufSize     // size, in characters, of the buffer
);

Parameters

ResourceId
[in] Specifies an error code returned by one of the RasAdmin functions. This value must be in the range of error codes from RASBASE to RASBASEEND. These are defined in Raserror.h.
lpszString
[out] Pointer to a buffer that receives the error message corresponding to the specified error code.
InBufSize
[in] Specifies the size, in characters, of the lpszString buffer. Error messages are typically 80 characters or less; a buffer size of 512 characters is always adequate.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error code. This value can be a last error value set by the LoadLibrary, GlobalAlloc, or LoadString functions; or it can be one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | The ResourceId or lpszString parameters are invalid.
ERROR_INSUFFICIENT_BUFFER | The size specified by the InBufSize parameter is too small.

There is no extended error information for this function; do not call GetLastError.

Remarks

The RasAdmin functions can return error codes that are not in the range supported by the RasAdminGetErrorString function. For example, the RasAdmin functions can return error codes that are defined in Lmerr.h and Winerror.h. Before calling RasAdminGetErrorString, verify that the error code is in the range RASBASE to RASBASEEND, as defined in Raserror.h.

Windows 2000 and later: The RasAdminGetErrorString function is replaced by the MprAdminGetErrorString function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 only.
Windows 95/98/Me: Unsupported.
Header: Declared in Rassapi.h.
Library: Use Rassapi.lib.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Functions, LoadLibrary, GlobalAlloc, LoadString


RasAdminGetUserAccountServer

The RasAdminGetUserAccountServer function retrieves the name of the server that has the user account database. Use the returned server name in the RasAdminUserGetInfo and RasAdminUserSetInfo functions to get or set information about a specified user.

DWORD RasAdminGetUserAccountServer(
  const WCHAR *lpszDomain,      // pointer to the name of
                                //  the Windows NT/2000 domain
  const WCHAR *lpszServer,      // pointer to the name of
                                //  the RAS server
  LPWSTR lpszUserAccountServer  // receives the name of
                                //  the user account server
);

Parameters

lpszDomain
[in] Pointer to a null-terminated Unicode string that specifies the name of the domain to which the RAS server belongs. This parameter is NULL for the RAS administration applications running on Microsoft® Windows NT®/Windows® 2000 workstations or servers that are not members of a Windows NT/Windows 2000 domain. If this parameter is NULL, the lpszServer parameter must be non-NULL.
lpszServer
[in] Pointer to a null-terminated Unicode string that specifies the name of the Windows NT/Windows 2000 RAS server. Specify the name with leading "\\" characters, in the form: \\servername. This parameter can be NULL if the lpszDomain parameter is not NULL.
lpszUserAccountServer
[out] Pointer to a buffer that receives a null-terminated Unicode string that specifies the name of a domain controller that has the user account database. The buffer should be big enough to hold the server name (UNCLEN +1). The function prefixes the returned server name with leading "\\" characters, in the form: \\servername.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value can be the following error code.

Value | Meaning
ERROR_INVALID_PARAMETER | Both lpszDomain and lpszServer are NULL.

There is no extended error information for this function; do not call GetLastError.

Remarks

The RasAdminGetUserAccountServer function can obtain the name of the server with the user accounts database given the name of the RAS server, or the name of the domain in which the RAS server resides.

The lpszDomain parameter should specify a valid Windows NT/Windows 2000 domain name. This parameter is NULL for RAS administration applications running on Windows NT/Windows 2000 servers that are not members of a Windows NT/Windows 2000 domain (for example, the server is in its own workgroup). In this case, the lpszServer parameter must specify the server name. To get the server name, call the GetComputerName function. Be sure to prefix the server name with the "\\" characters.

If the server name specified by lpszServer is a stand-alone Windows NT/Windows 2000 server (that is, the server or workstation is not a member of a Windows NT/Windows 2000 domain), then the server name itself is returned in the lpszUserAccountServer buffer.

Then use the name of the user account server in a call to the NetQueryDisplayInformation function to enumerate the users in the user account database.

Windows 2000 and later: The RasAdminGetUserAccountServer function is replaced by the MprAdminGetPDCServer function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 only.
Windows 95/98/Me: Unsupported.
Header: Declared in Rassapi.h.
Library: Use Rassapi.lib.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Functions, GetComputerName, RasAdminUserGetInfo, RasAdminUserSetInfo


RasAdminPortClearStatistics

The RasAdminPortClearStatistics function resets the counters representing the various statistics reported by the RasAdminPortGetInfo function in the RAS_PORT_STATISTICS structure. The counters are reset to zero and start accumulating.

DWORD RasAdminPortClearStatistics(
  const WCHAR *lpszServer,  // pointer to the server name
  const WCHAR *lpszPort     // pointer to the name of port on the server
);

Parameters

lpszServer
[in] Pointer to a null-terminated Unicode string that specifies the name of the Windows NT/Windows 2000 RAS server. Specify the name with leading "\\" characters, in the form: \\servername.
lpszPort
[in] Pointer to a null-terminated Unicode string that specifies the name of the port on the server.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value can be the following error code.

Value | Meaning
ERROR_DEV_NOT_EXIST | The specified port is invalid.

There is no extended error information for this function; do not call GetLastError.

Remarks

The RasAdminPortClearStatistics function clears the statistics on the server, not locally within the application that makes the call. This means that the statistics are also reset for any other application that is monitoring the specified port.

If the lpszPort port is part of a multilink connection, RasAdminPortClearStatistics resets the statistics for the specified port, The function also resets the cumulative statistics for the multilink connection. However, the function does not effect the individual statistics for other ports that are part of the multilink connection.

Windows 2000 and later: The RasAdminPortClearStatistics function is replaced by the MprAdminPortClearStats function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 only.
Windows 95/98/Me: Unsupported.
Header: Declared in Rassapi.h.
Library: Use Rassapi.lib.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Functions, RAS_PORT_STATISTICS, RasAdminPortGetInfo


RasAdminPortDisconnect

The RasAdminPortDisconnect function disconnects a port that is currently in use.

DWORD RasAdminPortDisconnect(
  const WCHAR *lpszServer,  // pointer to the server name
  const WCHAR *lpszPort     // pointer to the name of port on the server
);

Parameters

lpszServer
[in] Pointer to a null-terminated Unicode string that specifies the name of the Windows NT/Windows 2000 RAS server. Specify the name with leading "\\" characters, in the form: \\servername.
lpszPort
[in] Pointer to a null-terminated Unicode string that specifies the name of the port on the server.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_INVALID_PORT | The specified port is invalid.
NERR_UserNotFound | The port is not currently in use.

There is no extended error information for this function; do not call GetLastError.

Remarks

Windows 2000 and later: The RasAdminPortDisconnect function is replaced by the MprAdminPortDisconnect function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 only.
Windows 95/98/Me: Unsupported.
Header: Declared in Rassapi.h.
Library: Use Rassapi.lib.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Functions


RasAdminPortEnum

The RasAdminPortEnum function enumerates all ports on the specified RAS server. For each port on the server, the function returns the RAS_PORT_0 structure that contains information about the port.

DWORD RasAdminPortEnum(
  const WCHAR *lpszServer,  // pointer to the server name
  PRAS_PORT_0 *ppRasPort0,  // receives a pointer to an array of
                            //  port information
  WORD *pcEntriesRead       // receives the number of ports
                            //  enumerated
);

Parameters

lpszServer
[in] Pointer to a null-terminated Unicode string that specifies the name of the Windows NT/Windows 2000 RAS server. Specify the name with leading "\\" characters, in the form: \\servername.
ppRasPort0
[out] Pointer to a variable that receives a pointer to a buffer that contains an array of RAS_PORT_0 structures. When theapplication has finished with the memory, free it by calling the RasAdminFreeBuffer function.
pcEntriesRead
[out] Pointer to a 16-bit variable that receives the total number of RAS_PORT_0 structures returned in the ppRasPort0 array.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value can be the following error code.

Value | Meaning
NERR_ItemNotFound | No ports could be enumerated. This could be because all configured ports on the server are currently being used for dialing out.

There is no extended error information for this function; do not call GetLastError.

Remarks

Windows 2000 and later: The RasAdminPortEnum function is replaced by the MprAdminPortEnum function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 only.
Windows 95/98/Me: Unsupported.
Header: Declared in Rassapi.h.
Library: Use Rassapi.lib.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Functions, RAS_PORT_0, RasAdminFreeBuffer


RasAdminPortGetInfo

The RasAdminPortGetInfo function retrieves information about a specified port on a specified server.

DWORD RasAdminPortGetInfo(
  const WCHAR *lpszServer,         // pointer to the server name
  const WCHAR *lpszPort,           // pointer to the name of port
                                   //  on the server
  RAS_PORT_1 *pRasPort1,           // receives the state of the port
  RAS_PORT_STATISTICS *pRasStats,  // receives statistics about the port
  RAS_PARAMETERS **ppRasParams     // receives an array of
                                   //  media-specific parameters and values
);

Parameters

lpszServer
[in] Pointer to a null-terminated Unicode string that specifies the name of the Windows NT/Windows 2000 RAS server. Specify the name with leading "\\" characters, in the form: \\servername.
lpszPort
[in] Pointer to a null-terminated Unicode string that specifies the name of the port on the server.
pRasPort1
[out] Pointer to the RAS_PORT_1 structure that the function fills in with information about the state of the port.
pRasStats
[out] Pointer to the RAS_PORT_STATISTICS structure that the function fills in with statistics about the port.
ppRasParams
[out] Pointer to a pointer variable that receives the address of an array of RAS_PARAMETERS structures. Each structure contains the name of a media-specific key, such as MAXCONNECTBPS, and its associated value. When theapplication is finished with this memory, free it by calling the RasAdminFreeBuffer function.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_DEV_NOT_EXIST | The specified port is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory to allocate a buffer for the ppRasParams array.

There is no extended error information for this function; do not call GetLastError.

Remarks

Windows 2000 and later: The RasAdminPortGetInfo function is replaced by the MprAdminPortGetInfo function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 only.
Windows 95/98/Me: Unsupported.
Header: Declared in Rassapi.h.
Library: Use Rassapi.lib.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Functions, RAS_PARAMETERS, RAS_PORT_1, RAS_PORT_STATISTICS, RasAdminFreeBuffer


RasAdminServerGetInfo

The RasAdminServerGetInfo function gets the server configuration of a RAS server.

DWORD RasAdminServerGetInfo(
  const WCHAR *lpszServer,   // pointer to the name of the RAS server
  PRAS_SERVER_0 pRasServer0  // pointer to server information
);

Parameters

lpszServer
[in] Pointer to a null-terminated Unicode string that specifies the name of the Windows NT/Windows 2000 RAS server. If this parameter is NULL, the function returns information about the local computer. Specify the name with leading "\\" characters, in the form: \\servername.
pRasServer0
[out] Pointer to the RAS_SERVER_0 structure that receives the number of ports configured on the server, the number of ports currently in use, and the server version number.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error code. Possible error codes include those returned by GetLastError for the CallNamedPipe function. There is no extended error information for this function; do not call GetLastError.

Remarks

To enumerate all RAS servers in a Windows NT/Windows 2000 domain, call the NetServerEnum function and specify SV_TYPE_DIALIN for the servertype parameter.

Windows 2000 and later: The RasAdminServerGetInfo function is replaced by the MprAdminServerGetInfo function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 only.
Windows 95/98/Me: Unsupported.
Header: Declared in Rassapi.h.
Library: Use Rassapi.lib.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Functions, NetServerEnum, RAS_SERVER_0


RasAdminUserGetInfo

The RasAdminUserGetInfo function gets the RAS permissions and callback phone number information for a specified user.

DWORD RasAdminUserGetInfo(
  const WCHAR *lpszUserAccountServer,
                         // pointer to the name of the user
                         //  account server
  const WCHAR *lpszUser, // pointer to the name of the user
  PRAS_USER_0 pRasUser0  // receives the user's RAS information
);

Parameters

lpszUserAccountServer
[in] Pointer to a null-terminated Unicode string that specifies the name of the primary or backup domain controller that has the user account database. Use the RasAdminGetUserAccountServer function to get this server name.
lpszUser
[in] Pointer to a null-terminated Unicode string that specifies the name of the user for whom to get RAS information.
pRasUser0
Pointer to the RAS_USER_0 structure that receives the RAS data for the specified user.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value can be the following error code.

Value | Meaning
NERR_BufTooSmall | Insufficient memory to perform this function.

There is no extended error information for this function; do not call GetLastError.

Remarks

Windows 2000 and later: The RasAdminUserGetInfo function is replaced by the MprAdminUserGetInfo function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 only.
Windows 95/98/Me: Unsupported.
Header: Declared in Rassapi.h.
Library: Use Rassapi.lib.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Functions, RAS_USER_0, RasAdminGetUserAccountServer, RasAdminUserSetInfo


RasAdminUserSetInfo

The RasAdminUserSetInfo function sets the RAS permissions and call-back phone number for a specified user.

DWORD RasAdminUserSetInfo(
  const WCHAR *lpszUserAccountServer,
                               // pointer to the name of the
                               //  user account server
  const WCHAR *lpszUser,       // pointer to the name of the user
  const PRAS_USER_0 pRasUser0  // pointer to the new RAS
                               //  information for this user
);

Parameters

lpszUserAccountServer
[in] Pointer to a null-terminated Unicode string that specifies the name of the primary or backup domain controller that has the user account database. Use the RasAdminGetUserAccountServer function to get this server name.
lpszUser
[in] Pointer to a null-terminated Unicode string that specifies the name of the user for whom RAS information is to be set.
pRasUser0
[in] Pointer to the RAS_USER_0 structure that specifies the new RAS data for the specified user.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value can be one of the following error codes.

Value | Description
ERROR_INVALID_DATA | The pRasUser0 buffer contains invalid data.
ERROR_INVALID_CALLBACK_NUMBER | The callback number specified in the pRasUser0 buffer contains invalid characters.
NERR_BufTooSmall | Insufficient memory to perform this function.

There is no extended error information for this function; do not call GetLastError.

Remarks

When setting the RAS permissions for a user, the bfPrivilege member of the RAS_USER_0 structure must specify at least one of the call-back flags. For example, to set a user's privileges to allow dial-in privilege but no call-back privilege, set bfPrivilege to RASPRIV_DialinPrivilege | RASPRIV_NoCallback.

Windows 2000 and later: The RasAdminUserSetInfo function is replaced by the MprAdminUserSetInfo function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 only.
Windows 95/98/Me: Unsupported.
Header: Declared in Rassapi.h.
Library: Use Rassapi.lib.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Functions, RAS_USER_0, RasAdminGetUserAccountServer, RasAdminUserGetInfo


RAS Administration DLL Functions

Implement the following functions when developing a RAS administration DLL:

RasAdminAcceptNewConnection

RasAdminConnectionHangupNotification

RasAdminGetIpAddressForUser

RasAdminReleaseIpAddress


RasAdminAcceptNewConnection

The RasAdminAcceptNewConnection function is an application-defined function that is exported by a third-party RAS server administration DLL. RAS calls this function when a user tries to establish a remote connection to a RAS server. The function decides whether the user is allowed to connect.

The RAS server calls RasAdminAcceptNewConnection once for each port in a multilink connection.

BOOL RasAdminAcceptNewConnection(
  RAS_PORT_1 *pRasPort1,           // pointer to information
                                   //  about the connection
  RAS_PORT_STATISTICS *pRasStats,  // pointer to statistics about the port
  RAS_PARAMETERS *pRasParams       // pointer to an array of
                                   //  media-specific parameters and values
);

Parameters

pRasPort1
[in] Pointer to the RAS_PORT_1 structure that contains RAS data about the pending connection. Use the information in this structure to determine whether to accept the connection.
pRasStats
[in] Pointer to the RAS_PORT_STATISTICS structure that specifies statistics about the port.
pRasParams
[in] Pointer to an array of RAS_PARAMETERS structures. Each structure contains the name of a media-specific key, such as MAXCONNECTBPS, and its associated value.

Return Values

If the function returns TRUE, RAS accepts the new connection.

If the function returns FALSE, RAS does not accept the new connection. There is no extended error information for this function; do not call GetLastError.

Remarks

The RasAdminAcceptNewConnection function gives more control to a RAS server administration DLL to determine whether a specified remote user should be allowed to connect to a server.

An additional application of RasAdminAcceptNewConnection would be to send a popup message to newly connected clients. Use the NetMessageBufferSend function to send the message to the client computer.

The setup program for a third-party RAS administration DLL must register the DLL with RAS by providing information under the following key in the registry:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDll

To register the DLL, set the following values under this key.

Value name | Value data
DisplayName | A REG_SZ string that contains the user-friendly display name of the DLL.
DLLPath | A REG_SZ string that contains the full path of the DLL.

For example, the registry entry for a RAS administration DLL from a fictional company named ProElectron, Inc. might be:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDll
DisplayName : REG_SZ : ProElectron RAS Admin DLL
DLLPath : REG_SZ : C:\nt\system32\ntwkadm.dll

The setup program for a RAS administration DLL should also provide remove/uninstall functionality. If a user removes the DLL, the setup program should delete the DLL's registry entries.

Windows 2000 and later: This callout function is replaced by MprAdminAcceptNewConnection and MprAdminAcceptNewConnection2.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 only.
Windows 95/98/Me: Unsupported.
Header: Declared in Rassapi.h.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Functions, RAS_PARAMETERS, RAS_PORT_1, RAS_PORT_STATISTICS


RasAdminConnectionHangupNotification

The RasAdminConnectionHangupNotification function is an application-defined function that is exported by a third-party RAS server administration DLL. When RAS disconnects an existing connection, it calls this function to notify the DLL.

The RAS server calls RasAdminConnectionHangupNotification once for each port in a multilink connection.

VOID RasAdminConnectionHangupNotification(
  RAS_PORT_1 *pRasPort1,           // pointer to information
                                   //  about the connection
  RAS_PORT_STATISTICS *pRasStats,  // pointer to statistics
                                   //  about the port
  RAS_PARAMETERS *pRasParams       // pointer to an array of
                                   //  media-specific parameters and values
);

Parameters

pRasPort1
[in] Pointer to the RAS_PORT_1 structure that specifies RAS data about the connection that ended.
pRasStats
[in] Pointer to the RAS_PORT_STATISTICS structure that specifies statistics about the port. RAS began accumulating these statistics when the connection was first established.
pRasParams
[in] Pointer to an array of RAS_PARAMETERS structures. Each structure specifies the name of a media-specific key, such as MAXCONNECTBPS, and its associated value.

Return Values

The function does not return a value. There are no extended error information for this function; do not call GetLastError.

Remarks

The RAS call to the RasAdminConnectionHangupNotification function is just a notification; no action is required from the DLL. Use the information provided by this function for accounting purposes.

The setup program for a third-party RAS administration DLL must register the DLL with RAS by providing information under the following key in the registry:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDll

To register the DLL, set the following values under this key.

Value name | Value data
DisplayName | A REG_SZ string that contains the user-friendly display name of the DLL.
DLLPath | A REG_SZ string that contains the full path of the DLL.

For example, the registry entry for a RAS administration DLL from a fictional company named ProElectron, Inc. might be:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDll
 DisplayName : REG_SZ : ProElectron RAS Admin DLL
DLLPath : REG_SZ : C:\nt\system32\ntwkadm.dll

The setup program for a RAS administration DLL should also provide remove/uninstall functionality. If a user removes the DLL, the setup program should delete the DLL's registry entries.

Windows 2000 and later: This callout function is replaced by MprAdminConnectionHangupNotification and MprAdminConnectionHangupNotification2.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 only.
Windows 95/98/Me: Unsupported.
Header: Declared in Rassapi.h.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Functions, RAS_PARAMETERS, RAS_PORT_1, RAS_PORT_STATISTICS


RasAdminGetIpAddressForUser

The RasAdminGetIpAddressForUser function is an application-defined function that is exported by a third-party RAS server administration DLL. RAS calls this function to get an IP address for the dialed-in remote client.

DWORD RasAdminGetIpAddressForUser(
  WCHAR *lpszUserName,  // pointer to the name of the remote user
  WCHAR *lpszPortName,  // pointer to the name of the port
  IPADDR *pipAddress,   // pointer to the IP address
  BOOL *bNotifyRelease  // indicates whether RAS should call
                        //  RasAdminReleaseIpAddress
);

Parameters

lpszUserName
[in] Pointer to a null-terminated Unicode string that specifies the name of the remote user for whom an IP address is required.
lpszPortName
[in] Pointer to a null-terminated Unicode string that specifies the name of the port on which the user specified by lpszUserName is attempting to connect.
pipAddress
[in, out] Pointer to an IPADDR variable.

On input, *pipAddress contains either zero or the IP address that the RAS server proposes to use for the dialed-in remote client. The function can set *pipAddress to a different IP address, or accept the passed-in IP address. If *pipAddress is zero on input, the function must provide an IP address; otherwise, the client will be unable to connect to this server using IP.

bNotifyRelease
[out] Pointer to a BOOL variable. If TRUE, RAS calls the RasAdminReleaseIpAddress function when the user disconnects from this port.

Return Values

If pipAddress points to an IP address that the client can use to connect to this RAS server, the function should return NO_ERROR. This can occur if the function accepts the IP address that was passed by the RAS server, or if the function provides a different IP address.

If pipAddress does not point to an IP address, the function should return a nonzero error code. This can occur if no IP address is available, or if the passed IP address is unacceptable. In this case, the client will be unable to connect to this server using IP. There is no extended error information for this function; do not call GetLastError.

Remarks

The setup program for a third-party RAS administration DLL must register the DLL with RAS by providing information under the following key in the registry:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDll

To register the DLL, set the following values under this key.

Value name | Value data
DisplayName | A REG_SZ string that contains the user-friendly display name of the DLL.
DLLPath | A REG_SZ string that contains the full path of the DLL.

For example, the registry entry for a RAS administration DLL from a fictional company named ProElectron, Inc. Corporation might be:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDll
 DisplayName : REG_SZ : ProElectron RAS Admin DLL
DLLPath : REG_SZ : C:\nt\system32\ntwkadm.dll

The setup program for a RAS administration DLL should also provide remove/uninstall functionality. If a user removes the DLL, the setup program should delete the DLL's registry entries.

Windows 2000 and later: This callout function is replaced by MprAdminGetIpAddressForUser.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 only.
Windows 95/98/Me: Unsupported.
Header: Declared in Rassapi.h.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Functions, RasAdminReleaseIpAddress


RasAdminReleaseIpAddress

The RasAdminReleaseIpAddress function is an application-defined function that is exported by a third-party RAS server administration DLL. RAS calls this function to notify the DLL that the remote client was disconnected and that the IP address should be released.

VOID RasAdminReleaseIpAddress(
  WCHAR *lpszUserName,  // pointer to the name of the remote user
  WCHAR *lpszPortName,  // pointer to the name of the port
  IPADDR *pipAddress    // pointer to the IP address
);

Parameters

lpszUserName
[in] Specifies the pointer to a null-terminated Unicode string that specifies the name of a remote user for whom an IP address was previously obtained using the RasAdminGetIpAddressForUser function.
lpszPortName
[in] Pointer to a null-terminated Unicode string that specifies the name of the port on which the user specified by lpszUserName is connected.
pipAddress
[in] Pointer to an IPADDR variable that specifies the IP address returned for this user in a previous call to RasAdminGetIpAddressForUser.

Return Values

There is no extended error information for this function; do no call GetLastError.

Remarks

The RAS server calls the RasAdminReleaseIpAddress function only if the application returned TRUE in the bNotifyRelease parameter during the earlier call to RasAdminGetIpAddressForUser for the user specified by the lpszUserName parameter.

The setup program for a third-party RAS administration DLL must register the DLL with RAS by providing information under the following key in the registry:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDll

To register the DLL, set the following values under this key.

Value name | Value data
DisplayName | A REG_SZ string that contains the user-friendly display name of the DLL.
DLLPath | A REG_SZ string that contains the full path of the DLL.

For example, the registry entry for a RAS administration DLL from a fictional company named ProElectron, Inc. might be:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDll
 DisplayName : REG_SZ : ProElectron RAS Admin DLL
DLLPath : REG_SZ : C:\nt\system32\ntwkadm.dll

The setup program for a RAS administration DLL should also provide remove/uninstall functionality. If a user removes the DLL, the setup program should delete the DLL's registry entries.

Windows 2000 and later: This callout function is replaced by MprAdminReleaseIpAddress.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 only.
Windows 95/98/Me: Unsupported.
Header: Declared in Rassapi.h.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Functions, RasAdminGetIpAddressForUser


RAS Security DLL Functions

Implement the following functions when developering a RAS security DLL.

RasSecurityDialogBegin

RasSecurityDialogComplete

RasSecurityDialogEnd

RasSecurityDialogGetInfo

RasSecurityDialogReceive

RasSecurityDialogSend


RasSecurityDialogBegin

The RasSecurityDialogBegin function is a third-party RAS security DLL entry point that the Windows NT/Windows 2000 RAS server calls when a remote user tries to connect. This enables the security DLL to begin its authentication of the remote user.

Note that Windows NT/Windows 2000 currently provides RAS security host support only for serial devices; other types of connections, such as ISDN or a virtual private network (VPN) connection, are not supported.

DWORD WINAPI RasSecurityDialogBegin(
  HPORT hPort,        // RAS handle to the port
  PBYTE pSendBuf,     // pointer to buffer for sending data
  DWORD SendBufSize,  // size, in bytes, of the send buffer
  PBYTE pRecvBuf,     // pointer to buffer for receiving data
  DWORD RecvBufSize,  // size, in bytes, of the receive buffer
  VOID (WINAPI * RasSecurityDialogComplete)
                      // pointer to the completion function
);

Parameters

hPort
[in] Specifies a RAS port handle. The security DLL uses this handle in other RAS security functions, such as RasSecurityDialogSend and RasSecurityDialogReceive, to identify this authentication transaction.

Note that this handle is valid only in RAS security functions; do not use it in other Win32 I/O functions.

pSendBuf
[in] Pointer to a buffer allocated by the RAS server. The security DLL uses this buffer with the RasSecurityDialogSend function to send text that is displayed in the RAS terminal window on the remote computer.
SendBufSize
[in] Specifies the size, in bytes, of the pSendBuf buffer.
pRecvBuf
[in] Pointer to a buffer allocated by the RAS server. The security DLL uses this buffer with the RasSecurityDialogReceive function to receive the response from the remote user.
RecvBufSize
[in] Specifies the size, in bytes, of the pRecvBuf buffer.
RasSecurityDialogComplete
[in] Pointer to the RasSecurityDialogComplete function. When the security DLL has completed the authentication of the remote user, it calls this function to report the results to the RAS server.

Return Values

If the security DLL successfully starts the authentication operation, RasSecurityDialogBegin should return NO_ERROR. In this case, the security DLL must later terminate the authentication transaction by calling the function pointed to by the RasSecurityDialogComplete parameter.

If an error occurs, RasSecurityDialogBegin should return a nonzero error code. In this case, the RAS server hangs up the call and records the error in the Windows NT/Windows 2000 event log. Returning a nonzero error code terminates the authentication transaction, so the security DLL does not need to call the RasSecurityDialogComplete function.

Remarks

When a Windows NT/Windows 2000 RAS server receives a call from a remote computer, it calls the RasSecurityDialogBegin function exported by the registered RAS security DLL, if there is one. When the RAS server calls this function, it passes the following information to the security DLL:

  • A port handle to identify the connection
  • Pointers to buffers to use when communicating with the remote user
  • A pointer to the RasSecurityDialogComplete function to call when the authentication has been completed

The port handle and buffer pointers are valid until RasSecurityDialogComplete is called to terminate the authentication transaction.

The RasSecurityDialogBegin implementation must return as soon as possible, because the RAS server is blocked and cannot accept any other calls until RasSecurityDialogBegin returns. The RasSecurityDialogBegin function should copy the input parameters and create a thread to communicate with and authenticate the remote user.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Header: Declared in Rasshost.h.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Functions, RasSecurityDialogComplete, RasSecurityDialogReceive, RasSecurityDialogSend


RasSecurityDialogComplete

The RasSecurityDialogComplete function notifies the RAS server of the results of a third-party security authentication transaction. A third-party RAS security DLL calls RasSecurityDialogComplete when it has completed its authentication of the remote user.

The RAS server passes a pointer to the RasSecurityDialogComplete function when the server calls the RasSecurityDialogBegin entry point of the security DLL.

VOID RasSecurityDialogComplete(
  SECURITY_MESSAGE *pSecMsg  // pointer to the security message structure
);

Parameters

pSecMsg
[in] Pointer to the SECURITY_MESSAGE structure that specifies the results of the authentication transaction.

Return Values

None.

Remarks

When a security DLL has finished authenticating the remote user, it calls the RasSecurityDialogComplete function to report the results. The RAS server then performs a cleanup sequence. As part of this cleanup sequence, the RAS server calls the security DLL's RasSecurityDialogEnd function to give the DLL an opportunity to perform its own cleanup, if necessary.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Rasshost.h.
Library: Included as a resource in Rasman.dll.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Functions, RasSecurityDialogBegin, RasSecurityDialogComplete, RasSecurityDialogEnd, SECURITY_MESSAGE


RasSecurityDialogEnd

The RasSecurityDialogEnd function is a third-party RAS security DLL entry point that the Windows NT/Windows 2000 RAS server calls to terminate an authentication transaction.

DWORD WINAPI RasSecurityDialogEnd(
  HPORT hPort  // RAS handle to the port
);

Parameters

hPort
[in] Specifies the port handle that the RAS server passed to the security DLL in the RasSecurityDialogBegin call for this authentication transaction.

Return Values

If the security DLL returns NO_ERROR, the RAS server does not terminate the authentication transaction. In this case, the security DLL must later call the RasSecurityDialogComplete function when it is ready to terminate.

If the security DLL returns a nonzero error code, the RAS server terminates the authentication transaction. In this case, the security DLL does not need to make another RasSecurityDialogComplete call. Return an error code defined in Winerror.h or Raserror.h, such as ERROR_PORT_DISCONNECTED.

Remarks

When a security DLL has finished authenticating the remote user, it calls the RasSecurityDialogComplete function. The RAS server then performs a cleanup sequence that includes a call to the DLL's RasSecurityDialogEnd function. This gives the security DLL an opportunity to perform any necessary cleanup. To terminate the authentication transaction, RasSecurityDialogEnd must return a nonzero error code.

The RAS server may also call RasSecurityDialogEnd if it needs to abnormally terminate the authentication transaction before the security DLL calls RasSecurityDialogComplete. In this case, the security DLL should terminate the worker thread associated with the hPort port handle, and perform any other necessary cleanup. If RasSecurityDialogEnd returns a nonzero value, the security DLL does not need to call RasSecurityDialogComplete.

For both normal and abnormal termination, the RasSecurityDialogEnd function returns NO_ERROR to delay the termination. If it does so, it must later call RasSecurityDialogComplete when it is ready to terminate.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Header: Declared in Rasshost.h.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Functions, RasSecurityDialogBegin, RasSecurityDialogComplete


RasSecurityDialogGetInfo

The RasSecurityDialogGetInfo function is called by a RAS security DLL to get information about a port from the RAS server.

To call this function, first call the LoadLibrary function to load Rasman.dll. Then call the GetProcAddress function to get the DLL's RasSecurityDialogGetInfo entry point.

DWORD RasSecurityDialogGetInfo(
  HPORT hPort,                // RAS handle to port
  RAS_SECURITY_INFO *pBuffer  // pointer to structure that
                              //  gets port information
);

Parameters

hPort
[in] Specifies the port handle that the RAS server passed to the security DLL in the RasSecurityDialogBegin call for this authentication transaction.
pBuffer
[in] Pointer to the RAS_SECURITY_INFO structure that receives information about the specified RAS port.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the error codes defined in Raserror.h or Winerror.h. GetLastError does not provide extended error information.

Remarks

The RasSecurityDialogGetInfo function retrieves information about the port associated with a RAS security DLL authentication transaction.

The LastError member of the RAS_SECURITY_INFO structure indicates the state of the last RasSecurityDialogReceive call for the port. If the receive operation has been completed successfully, LastError is SUCCESS and the BytesReceived member indicates the number of bytes received. Otherwise, LastError is PENDING if the receive operation is still in progress, or a nonzero error code if the receive operation failed.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Rasshost.h.
Library: Included as a resource in Rasman.dll.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Functions, GetProcAddress, LoadLibrary, RAS_SECURITY_INFO, RasSecurityDialogReceive


RasSecurityDialogReceive

The RasSecurityDialogReceive function starts an asynchronous operation that receives a remote user's response to a security challenge. The response is the input that the user typed in a terminal window on the remote computer. A third-party RAS security DLL calls this function as part of its authentication of the remote user.

To call this function, first call the LoadLibrary function to load Rasman.dll. Then call the GetProcAddress function to get the DLL's RasSecurityDialogReceive entry point.

DWORD WINAPI RasSecurityDialogReceive(
  HPORT hPort,          // RAS handle to the port
  PBYTE pBuffer,        // pointer to buffer that receives
                        //  the user's response
  PWORD pBufferLength,  // returns size, in bytes, of the data received
  DWORD Timeout,        // time-out period, in seconds
  HANDLE hEvent         // event that is signaled when operation is finished
);

Parameters

hPort
[in] Specifies the port handle that the RAS server passed to the security DLL in the RasSecurityDialogBegin call for this authentication transaction.
pBuffer
[in] Pointer to the receive buffer that was passed to the security DLL in the RasSecurityDialogBegin call. When the asynchronous receive operation has been completed successfully, this buffer specifies the response from the remote user.
pBufferLength
[in] Pointer to a WORD variable. This variable must specify the size, in bytes, of the pBuffer buffer. When the receive operation has been completed, the variable indicates the number of bytes returned in the pBuffer buffer.
Timeout
[in] Specifies a time-out period, in seconds, after which the RAS server sets the hEvent event object to the signaled state.

If this value is zero, there is no time-out period; that is, the RAS server does not signal the event object until the receive operation has been completed.

hEvent
[in] Specifies the handle of an event object created by the CreateEvent function. The RAS server sets the event object to the signaled state when the receive operation has been completed or when the time-out period has elapsed.

Return Values

If the function is successful, the return value is PENDING (defined in Raserror.h). This indicates that the receive operation is in progress.

If an error occurs, the return value is one of the error codes defined in Raserror.h or Winerror.h. GetLastError does not provide extended error information.

Remarks

After calling the RasSecurityDialogSend function to send a security challenge to the remote user, the security DLL must call the RasSecurityDialogReceive function to get the user's response.

The RasSecurityDialogReceive function is asynchronous. When the function returns, the security DLL must use one of the wait functions, such as WaitForSingleObject, to wait for the hEvent event object to be signaled. The RAS server signals the event object when the receive operation has been completed or when the time-out interval has elapsed. If the receive operation is successful, the pBuffer buffer contains the response from the remote user, and the pBufferLength parameter indicates the number of bytes received. If the remote user sends more bytes than will fit in the buffer, the RAS server buffers the excess bytes and returns them in the next RasSecurityDialogReceive call.

Use the Timeout parameter to specify a time-out interval. If the time-out elapses, the RAS server signals the event object, and the pBufferLength parameter indicates that zero bytes were transferred. Alternatively, setTimeout to zero, and specify a time-out interval in the wait function used to wait for the event object.

When a security DLL is authenticating a remote user, the connection operation on the remote computer enters a RASCS_Interactive paused state. The message sent by RasSecurityDialogSend is displayed as output in a terminal window on the remote computer. The response received by RasSecurityDialogReceive is the input that the remote user types in the terminal window. The RASCS_Interactive value is defined in the RASCONNSTATE enumeration.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Rasshost.h.
Library: Included as a resource in Rasman.dll.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Functions, CreateEvent, GetProcAddress, LoadLibrary, RASCONNSTATE, RasSecurityDialogSend, WaitForSingleObject


RasSecurityDialogSend

The RasSecurityDialogSend function sends a message to be displayed in a terminal window on a remote computer. A third-party RAS security DLL sends this message as part of its authentication of a remote user.

To call this function, first call the LoadLibrary function to load Rasman.dll. Then call the GetProcAddress function to get the DLL's RasSecurityDialogSend entry point.

DWORD RasSecurityDialogSend(
  HPORT hPort,       // RAS handle to the port
  PBYTE pBuffer,     // pointer to buffer containing data to send
  WORD BufferLength  // size, in bytes, of the data being sent
);

Parameters

hPort
[in] Specifies the port handle that the RAS server passed to the security DLL in the RasSecurityDialogBegin call for this authentication transaction.
pBuffer
[in] Pointer to the send buffer that was passed to the security DLL in the call to RasSecurityDialogBegin. Before calling RasSecurityDialogSend, copy into this buffer the message to send to the remote user. The SendBufSize parameter of the RasSecurityDialogBegin function indicates the maximum number of bytes the buffer can store.
BufferLength
[in] Specifies the number of bytes to send in the pBuffer buffer.

Return Values

If the function is successful, the return value is PENDING (defined in Raserror.h). This indicates that the send operation is in progress.

If an error occurs, the return value is one of the error codes defined in Raserror.h or Winerror.h. GetLastError does not provide extended error information.

Remarks

The RasSecurityDialogSend function is asynchronous. After calling it to send a message to the remote user, call the RasSecurityDialogReceive function, and then wait for a response. The security DLL can make any number of RasSecurityDialogSend calls, with each call followed by a RasSecurityDialogReceive call.

When a security DLL is authenticating a remote user, the connection operation on the remote computer enters a RASCS_Interactive paused state. The message sent by RasSecurityDialogSend is displayed as output in a terminal window on the remote computer. The response received by RasSecurityDialogReceive is the input that the remote user types in the terminal window. The RASCS_Interactive value is defined in the RASCONNSTATE enumeration.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Rasshost.h.
Library: Included as a resource in Rasman.dll.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Functions, GetProcAddress, LoadLibrary, RASCONNSTATE, RasSecurityDialogBegin, RasSecurityDialogReceive


RAS Server Administration Structures

For Windows NT version 4.0, use the following structures to implement RAS server administration functionality. Windows 95 does not provide RAS server support.

RAS_PARAMETERS

RAS_PORT_0

RAS_PORT_1

RAS_PORT_STATISTICS

RAS_PPP_ATCP_RESULT

RAS_PPP_IPCP_RESULT

RAS_PPP_IPXCP_RESULT

RAS_PPP_NBFCP_RESULT

RAS_PPP_PROJECTION_RESULT

RAS_SECURITY_INFO

RAS_SERVER_0

RAS_STATS

RAS_USER_0

SECURITY_MESSAGE


RAS_PARAMETERS

The RAS_PARAMETERS structure is used by the RasAdminPortGetInfo function to return the name and value of a media-specific parameter associated with a port on a Windows NT/Windows 2000 RAS server.

struct RAS_PARAMETERS {
  CHAR  P_Key [RASSAPI_MAX_PARAM_KEY_SIZE];
  RAS_PARAMS_FORMAT  P_Type;
  BYTE  P_Attributes;
  RAS_PARAMS_VALUE  P_Value;
};

Members

P_Key
Specifies the name of the key that represents the media-specific parameter, such as MAXCONNECTBPS.
P_Type
Identifies the type of data associated with the parameter. This member can be one of the following values from the RAS_PARAMS_FORMAT enumeration.
Value | Meaning
ParamNumber | Indicates that the data associated with the key is a number.
ParamString | Indicates that the data associated with the key is a string.

P_Attributes
Reserved.
P_Value
Specifies the value associated with the parameter. This member is a RAS_PARAMS_VALUE union. If the P_Type member is ParamNumber, the Number member of the union contains the value. If P_Type is ParamString, the String member of the union contains the value.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Header: Declared in Rassapi.h.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Structures, RasAdminAcceptNewConnection, RasAdminConnectionHangupNotification, RasAdminPortGetInfo


RAS_PORT_0

The RAS_PORT_0 structure contains information that describes a RAS port.

typedef struct _RAS_PORT_0 {
  WCHAR wszPortName[RASSAPI_MAX_PORT_NAME];
  WCHAR wszDeviceType[RASSAPI_MAX_DEVICETYPE_NAME];
  WCHAR wszDeviceName[RASSAPI_MAX_DEVICE_NAME];
  WCHAR wszMediaName[RASSAPI_MAX_MEDIA_NAME];
  DWORD reserved;
  DWORD Flags;
  WCHAR wszUserName[UNLEN + 1];
  WCHAR wszComputer[NETBIOS_NAME_LEN];
  DWORD dwStartSessionTime;
  WCHAR wszLogonDomain[DNLEN + 1];
  BOOL fAdvancedServer;
} RAS_PORT_0, *PRAS_PORT_0;

Members

wszPortName
A null-terminated Unicode string that specifies the name of the port, such as "COM1".
wszDeviceType
A null-terminated Unicode string that specifies the type of the device on which the connection was made, such as "Modem" or "ISDN". The list of device types that might be specified in this member includes all the device types installed on the server, including third-party devices.
wszDeviceName
A null-terminated Unicode string that specifies the name of the device on which the connection was made, such as "Hayes 9600" or "PCIMACISDN1".
wszMediaName
Specifies a null-terminated Unicode string that specifies the name of the media used for the connection, such as "rasser" or "rastapi".
reserved
Reserved.
Flags
Specifies a set of bit flags that specify the nature of the connection made on this port. This member can be a combination of the following flags.
Value | Meaning
GATEWAY_ACTIVE | If this flag is set, the NetBIOS gateway is active on the server.
MESSENGER_PRESENT | If this flag is set, the Windows NT/Windows 2000 messenger service is running on the remote client.
PORT_MULTILINKED If this flag is set, the port is multilinked with other ports. Use this information to display the connection status as a multilinked port.

For a multilinked port, the RAS_PORT_STATISTICS structure contains two sets of statistics: one for the port alone, and another for the combined ports in the multilink connection.
PPP_CLIENT | If this flag is set, the remote client connected using PPP. If this flag is not set, the remote client connected using the AMB protocol.
REMOTE_LISTEN | If this flag is set, the RemoteListen parameter of the NetBIOS gateway is set to 1 on the server.
USER_AUTHENTICATED | If this flag is set, a remote client is connected to the server and the user has been authenticated. Check this flag to ensure that a client is actually connected to a port.

If the MESSENGER_PRESENT, GATEWAY_ACTIVE, and REMOTE_LISTEN flags are set, use the Windows NT/Windows 2000 messenger service to send an administrative message to the remote client. If MESSENGER_PRESENT and REMOTE_LISTEN are set, but GATEWAY_ACTIVE is not, send messages to the client only from the RAS server to which the client is connected.

wszUserName
A null-terminated Unicode string that specifies the name of the remote user connected to this port.
wszComputer
A null-terminated Unicode string that specifies the name of the remote client computer.
dwStartSessionTime
Specifies the time, in seconds from January 1, 1970, that the client connected to the RAS server on this port. Use the standard Win32 time routines to format this value for display.
wszLogonDomain
Specifies a null-terminated Unicode string that specifies the name of the Windows NT/Windows 2000 domain on which the remote user was authenticated. This string is the domain name only, with no "\\" prefix.
fAdvancedServer
Specifies a flag that is nonzero if the RAS server associated with this port is a Windows NT/Windows 2000 Advanced Server. Use this information to determine the name of the server that has the user account database. If the RAS server is an Advanced Server, get the name of the user account server by concatenating the prefix "\\" to the name returned in the wszLogonDomain member. This is because for an Advanced Server the local logon domain name is the same as the server name. If the RAS server is a Windows NT/Windows 2000 workstation, use the RasAdminGetUserAccountServer function to get the name of the user account server.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Header: Declared in Rassapi.h.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Structures, RAS_PORT_1, RAS_PORT_STATISTICS, RasAdminGetUserAccountServer, RasAdminPortEnum


RAS_PORT_1

The RAS_PORT_1 structure contains information about a RAS port.

typedef struct _RAS_PORT_1 {
  RAS_PORT_0  rasport0;
  DWORD       LineCondition;
  DWORD       HardwareCondition;
  DWORD       LineSpeed;
  WORD        NumStatistics;
  WORD        NumMediaParms;
  DWORD       SizeMediaParms;
  RAS_PPP_PROJECTION_RESULT  ProjResult;
} RAS_PORT_1, *PRAS_PORT_1;

Members

rasport0
Specifies a RAS_PORT_0 structure that contains information about the port, such as the name of the port, the name of the remote user connected to the port, and so on.
LineCondition
Specifies the state of the port. This member can be one of the following values.
Value | Meaning
RAS_PORT_NON_OPERATIONAL | The port is not operational. Check the event log for errors reported by the server.
RAS_PORT_DISCONNECTED | The port is currently disconnected.
RAS_PORT_CALLING_BACK | The RAS server is calling back the RAS client.
RAS_PORT_LISTENING | The port is waiting for a client to call in.
RAS_PORT_AUTHENTICATING | The server is in the process of authenticating the remote client.
RAS_PORT_AUTHENTICATED | The remote client is now authenticated.
RAS_PORT_INITIALIZING | The device attached to the port is being initialized. The state of the port will change to RAS_PORT_LISTENING when the initialization has been completed.

HardwareCondition
Specifies one of the following values to indicate the state of the device attached to the port.
Value | Meaning
RAS_MODEM_OPERATIONAL | The modem attached to this port is operational and is ready to receive client calls.
RAS_MODEM_HARDWARE_FAILURE | The modem attached to this port has a hardware problem.

LineSpeed
Specifies the speed, in bits per second, with which the computer can communicate with the port.
NumStatistics
This member is not used. The RAS administration functions, such as the RasAdminPortGetInfo function, use the RAS_PORT_STATISTICS structure to return port statistics.
NumMediaParms
Specifies the number of media-specific parameters for this port. For serial media this is typically the number of values that appear in the SERIAL.INI file.
SizeMediaParms
Specifies the size, in bytes, of the buffer required for all media-specific parameters. The RasAdminPortGetInfo function returns a buffer containing an array of RAS_PARAMETERS structures with the media parameters and values for the port.
ProjResult
A RAS_PPP_PROJECTION_RESULT structure that specifies the PPP projection information for this port. This structure provides information for each protocol that is negotiated when a RAS client connects to a server.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Header: Declared in Rassapi.h.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Structures, RAS_PARAMETERS, RAS_PORT_0, RAS_PORT_STATISTICS, RAS_PPP_PROJECTION_RESULT, RasAdminAcceptNewConnection, RasAdminConnectionHangupNotification, RasAdminPortGetInfo


RAS_PORT_STATISTICS

The RAS_PORT_STATISTICS structure reports the statistics that a RAS server collects for a connected port. The RAS server resets the various statistic counters each time the port is connected. Call the RasAdminPortClearStatistics function to force the RAS server to reset the statistic counters.

For a port that is part of a multilink connection, this structure provides two sets of statistics. The first set contains the cumulative statistics for all ports in the connection. These statistics are the same for all ports in the connection. The second set contains the statistics for just this port. If the port is not part of a multilink connection, both sets of statistics have the same information. To determine whether a port is part of a multilink connection, check the PORT_MULTILINKED bit in the Flags member of the port's RAS_PORT_0 structure.

typedef struct _RAS_PORT_STATISTICS
{
  // The connection statistics are followed by port statistics
  // A connection is across multiple ports.
  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;

  // the following are the port statistics
  DWORD   dwPortBytesXmited;
  DWORD   dwPortBytesRcved;
  DWORD   dwPortFramesXmited;
  DWORD   dwPortFramesRcved;
  DWORD   dwPortCrcErr;
  DWORD   dwPortTimeoutErr;
  DWORD   dwPortAlignmentErr;
  DWORD   dwPortHardwareOverrunErr;
  DWORD   dwPortFramingErr;
  DWORD   dwPortBufferOverrunErr;
  DWORD   dwPortBytesXmitedUncompressed;
  DWORD   dwPortBytesRcvedUncompressed;
  DWORD   dwPortBytesXmitedCompressed;
  DWORD   dwPortBytesRcvedCompressed;

} RAS_PORT_STATISTICS, *PRAS_PORT_STATISTICS;

Members

dwBytesXmited
Specifies the total number of bytes transmitted by the connection.
dwBytesRcved
Specifies the total number of bytes received by the connection.
dwFramesXmited
Specifies the total number of frames transmitted by the connection.
dwFramesRcved
Specifies the total number of frames received by the connection.
dwCrcErr
Specifies the total number of CRC errors on the connection. CRC errors are caused by the failure of a cyclic redundancy check. A CRC error indicates that one or more characters in the data packet received were found garbled on arrival.
dwTimeoutErr
Specifies the total number of time-out errors on the connection. Time-out errors occur when an expected character is not received in time. When this occurs, the software assumes that the data has been lost and requests that it be resent.
dwAlignmentErr
Specifies the total number of alignment errors on the connection. Alignment errors occur when a character received is not the one expected. This usually happens when a character is lost or when a time-out error occurs.
dwHardwareOverrunErr
Specifies the total number of hardware overrun errors on the connection. These errors indicate the number of times the sending computer has transmitted characters faster than the receiving computer hardware can process them. If this problem persists, reduce the BPS connection rate on the client.
dwFramingErr
Specifies the total number of framing errors on the connection. A framing error occurs when an asynchronous character is received with an invalid start or stop bit.
dwBufferOverrunErr
Specifies the total number of buffer overrun errors on the connection. A buffer overrun error occurs when the sending computer is transmitting characters faster than the receiving computer can accommodate them. If this problem persists, reduce the BPS connection rate on the client.
dwBytesXmitedUncompressed
Specifies the total number of bytes transmitted uncompressed by the connection.
dwBytesRcvedUncompressed
Specifies the total number of bytes received uncompressed by the connection.
dwBytesXmitedCompressed
Specifies the total number of bytes transmitted compressed by the connection.
dwBytesRcvedCompressed
Specifies the total number of bytes received compressed by the connection.
dwPortBytesXmited
Specifies the total number of bytes transmitted by the port.
dwPortBytesRcved
Specifies the total number of bytes received by the port.
dwPortFramesXmited
Specifies the total number of frames transmitted by the port.
dwPortFramesRcved
Specifies the total number of frames received by the port.
dwPortCrcErr
Specifies the total number of CRC errors on the port. CRC errors are caused by the failure of a cyclic redundancy check. A CRC error indicates that one or more characters in the data packet received were found garbled on arrival.
dwPortTimeoutErr
Specifies the total number of time-out errors on the port. Time-out errors occur when an expected character is not received in time. When this occurs, the software assumes that the data has been lost and requests that it be resent.
dwPortAlignmentErr
Specifies the total number of alignment errors on the port. Alignment errors occur when a character received is not the one expected. This usually happens when a character is lost or when a time-out error occurs.
dwPortHardwareOverrunErr
Specifies the total number of hardware overrun errors on the port. These errors indicate the number of times the sending computer has transmitted characters faster than the receiving computer hardware can process them. If this problem persists, reduce the BPS connection rate on the client.
dwPortFramingErr
Specifies the total number of framing errors on the port. A framing error occurs when an asynchronous character is received with an invalid start or stop bit.
dwPortBufferOverrunErr
Specifies the total number of buffer overrun errors on the port. A buffer overrun error occurs when the sending computer is transmitting characters faster than the receiving computer can accommodate them. If this problem persists, reduce the BPS connection rate on the client.
dwPortBytesXmitedUncompressed
Specifies the total number of bytes transmitted uncompressed by the port. If the port is part of a multilink connection, this member is not valid. Use the compression statistics for the connection instead.
dwPortBytesRcvedUncompressed
Specifies the total number of bytes received uncompressed by the port. If the port is part of a multilink connection, this member is not valid. Use the compression statistics for the connection instead.
dwPortBytesXmitedCompressed
Specifies the total number of bytes transmitted compressed by the port. If the port is part of a multilink connection, this member is not valid. Use the compression statistics for the connection instead.
dwPortBytesRcvedCompressed
Specifies the total number of bytes received compressed by the port. If the port is part of a multilink connection, this member is not valid. Use the compression statistics for the connection instead.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Header: Declared in Rassapi.h.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Structures, RAS_PORT_0, RasAdminAcceptNewConnection, RasAdminConnectionHangupNotification, RasAdminPortClearStatistics, RasAdminPortGetInfo


RAS_PPP_ATCP_RESULT

The RAS_PPP_ATCP_RESULT structure is used to report the result of an AppleTalk protocol projection operation for a port. Windows NT version 4.0 does not use this structure.

typedef struct _RAS_PPP_ATCP_RESULT {
  DWORD dwError;
  WCHAR wszAddress[ RAS_ATADDRESSLEN + 1 ];
} RAS_PPP_ATCP_RESULT;

Members

dwError
Specifies a value that indicates the results of the AppleTalk projection operation. A value of NO_ERROR indicates success, in which case, the wszAddress member is valid. If the projection operation is not successful, dwError is an error code from Winerror.h or Raserror.h.
wszAddress
Specifies a null-terminated Unicode string that specifies the IP address assigned to the remote client.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Header: Declared in Rassapi.h.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Structures, RAS_PPP_PROJECTION_RESULT


RAS_PPP_IPCP_RESULT

The RAS_PPP_IPCP_RESULT structure is used to report the result of a PPP Internet Protocol (IP) projection operation for a port.

typedef struct _RAS_PPP_IPCP_RESULT {
  DWORD dwError;
  WCHAR wszAddress[ RAS_IPADDRESSLEN + 1 ];
} RAS_PPP_IPCP_RESULT;

Members

dwError
Indicates the results of the IP projection operation. A value of NO_ERROR indicates success, in which case, the wszAddress member is valid. If the projection operation was not successful, dwError is an error code from Winerror.h or Raserror.h.
wszAddress
A null-terminated Unicode string that specifies the IP address assigned to the remote client. This string has the "a.b.c.d" form.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Header: Declared in Rassapi.h.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Structures, RAS_PORT_1, RAS_PPP_PROJECTION_RESULT, RasAdminPortGetInfo


RAS_PPP_IPXCP_RESULT

The RAS_PPP_IPXCP_RESULT structure is used to report the result of a PPP Internetwork Packet Exchange (IPX) projection operation for a port.

typedef struct _RAS_PPP_IPXCP_RESULT {
  DWORD dwError;
  WCHAR wszAddress[ RAS_IPXADDRESSLEN + 1 ];
} RAS_PPP_IPXCP_RESULT;

Members

dwError
Indicates the results of the IPX projection operation. A value of NO_ERROR indicates success, in which case, the wszAddress member is valid. If the projection operation was not successful, dwError is an error code from Winerror.h or Raserror.h.
wszAddress
A null-terminated Unicode string that specifies the IPX address assigned to the remote client. This string has the "net.node" form.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Header: Declared in Rassapi.h.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Structures, RAS_PORT_1, RAS_PPP_PROJECTION_RESULT, RasAdminPortGetInfo


RAS_PPP_NBFCP_RESULT

The RAS_PPP_NBFCP_RESULT structure is used to report the result of a PPP NetBEUI Framer (NBF) projection operation for a port.

typedef struct _RAS_PPP_NBFCP_RESULT {
  DWORD dwError;
  DWORD dwNetBiosError;
  CHAR  szName[ NETBIOS_NAME_LEN + 1 ];
  WCHAR wszWksta[ NETBIOS_NAME_LEN + 1 ];
} RAS_PPP_NBFCP_RESULT;

Members

dwError
Indicates the results of the NBF projection operation. A value of NO_ERROR indicates success, in which case, the wszWksta member contains the name of the remote computer. If the projection operation was not successful, dwError is an error code from Winerror.h or Raserror.h.
dwNetBiosError
Ignore this member on the server; it is relevant only on the client.
szName
Ignore this member on the server; it is relevant only on the client.
wszWksta
A null-terminated Unicode string that specifies the NetBIOS name of the RAS client workstation.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Header: Declared in Rassapi.h.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Structures, RAS_PORT_1, RAS_PPP_PROJECTION_RESULT, RasAdminPortGetInfo


RAS_PPP_PROJECTION_RESULT

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

typedef struct _RAS_PPP_PROJECTION_RESULT {
  RAS_PPP_NBFCP_RESULT nbf;
  RAS_PPP_IPCP_RESULT  ip;
  RAS_PPP_IPXCP_RESULT ipx;
  RAS_PPP_ATCP_RESULT  at;
} RAS_PPP_PROJECTION_RESULT;

Members

nbf
A RAS_PPP_NBFCP_RESULT structure that reports the result of a PPP NetBEUI Framer (NBF) projection operation.
ip
A RAS_PPP_IPCP_RESULT structure that reports the result of a PPP Internet Protocol (IP) projection operation.
ipx
A RAS_PPP_IPXCP_RESULT structure that reports the result of a PPP Internetwork Packet Exchange (IPX) projection operation.
at
A RAS_PPP_ATCP_RESULT structure. Windows NT version 4.0 does not use this member.

Remarks

This structure reports the projection results for NetBEUI, TCP/IP, and IPX protocols. Each PPP structure has a dwError member that indicates whether the other information in the structure is valid. If dwError is NO_ERROR, the other information is valid. If dwError is one of the error codes in Winerror.h or Raserror.h, the other information is not valid.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Header: Declared in Rassapi.h.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Structures, RAS_PORT_1, RAS_PPP_ATCP_RESULT, RAS_PPP_IPCP_RESULT, RAS_PPP_IPXCP_RESULT, RAS_PPP_NBFCP_RESULT, RasAdminPortGetInfo


RAS_SECURITY_INFO

The RAS_SECURITY_INFO structure is used with the RasSecurityDialogGetInfo function to return information about the RAS port associated with a RAS security DLL authentication transaction.

typedef struct _RAS_SECURITY_INFO {
  DWORD LastError;
  DWORD BytesReceived;
  CHAR DeviceName[RASSAPI_MAX_DEVICE_NAME+1];
}RAS_SECURITY_INFO,*PRAS_SECURITY_INFO;

Members

LastError
Specifies an error code that indicates the state of the last RasSecurityDialogReceive call for the port. If the receive operation failed, LastError is one of the error codes defined in Raserror.h or Winerror.h. Otherwise, LastError is one of the following values.
Value | Meaning
SUCCESS | The receive operation has been successfully completed. The BytesReceived member indicates the number of bytes received.
PENDING | The receive operation is pending completion.

BytesReceived
Specifies the number of bytes received in the most recent RasSecurityDialogReceive operation. This member is valid only if the value of the LastError member is SUCCESS.
DeviceName
Specifies a null-terminated string that contains the user-friendly display name of the device on the port, such as Hayes SmartModem 9600.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Rasshost.h.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Structures, RasSecurityDialogGetInfo, RasSecurityDialogReceive


RAS_SERVER_0

The RAS_SERVER_0 structure is used by the RasAdminServerGetInfo function to return information about the ports configured on a RAS server.

typedef struct _RAS_SERVER_0 {
  WORD  TotalPorts;   // total ports available for connection
  WORD  PortsInUse;   // ports currently in use by remote clients
  DWORD RasVersion;   // version of RAS server
} RAS_SERVER_0, *PRAS_SERVER_0;

Members

TotalPorts
Specifies the total number of ports configured on the RAS server that are available for remote clients to connect to. For example, if the total number of ports configured for dialing in to a server is four, but one of the ports is currently in use for dialing out, TotalPorts will be three.
PortsInUse
Specifies the number of ports currently in use by remote clients.
RasVersion
Specifies the version of the RAS server. Use this information to take version-specific action. This member is one of the following values.
Value | Description
RASDOWNLEVEL | Indicates a LAN Manager version 1.0 RAS server.
RASADMIN_35 | Indicates a Windows NT version 3.5 or 3.51 RAS server or client.
RASADMIN_CURRENT | Indicates a Windows NT version 4.0 RAS server or client.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Header: Declared in Rassapi.h.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Structures, RasAdminServerGetInfo


RAS_STATS

The RAS_STATS structure stores the statistics for a single-link RAS connection, or for one of the links in a multilink RAS connection.

typedef struct _RAS_STATS {
  DWORD   dwSize;
  DWORD   dwBytesXmited;
  DWORD   dwBytesRcved;
  DWORD   dwFramesXmited;
  DWORD   dwFramesRcved;
  DWORD   dwCrcErr;
  DWORD   dwTimeoutErr;
  DWORD   dwAlignmentErr;
  DWORD   dwHardwareOverrunErr;
  DWORD   dwFramingErr;
  DWORD   dwBufferOverrunErr;
  DWORD   dwCompressionRatioIn;
  DWORD   dwCompressionRatioOut;
  DWORD   dwBps;
  DWORD   dwConnectDuration;
} RAS_STATS, *PRAS_STATS;

Members

dwSize
Specifies the version of the structure. Set this member to sizeof(RAS_STATS) before using the structure in a function call.
dwBytesXmited
The number of bytes transmitted through this connection or link.
dwBytesRcved
The number of bytes received through this connection or link.
dwFramesXmited
The number frames transmitted through this connection or link.
dwFramesRcved
The number of frames received through this connection or link.
dwCrcErr
The number of cyclic redundancy check (CRC) errors on this connection or link.
dwTimeoutErr
The number of timeout errors on this connection or link.
dwAlignmentErr
The number of alignment errors on this connection or link.
dwHardwareOverrunErr
The number of hardware overrun errors on this connection or link.
dwFramingErr
The number of framing errors on this connection or link.
dwBufferOverrunErr
The number of buffer overrun errors on this connection or link.
dwCompressionRatioIn
The compression ratio for the data being received on this connection or link.
dwCompressionRatioOut
The compression ratio for the data being transmitted on this connection or link.
dwBps
The speed of the connection or link, in bits per second.

For a single-link connection and for individual links in a multilink connection, this speed is negotiated at the time the connection or link is established.

For multilink connections, this speed is equal to the sum of the speeds of the individual links. For multilink connections, this speed will vary as links are added or deleted.

This speed is not equal to the throughput of the connection or link. To calculate the average throughput, divide the number of bytes transmitted (dwBytesXmited) and received (dwBytesRcved) by the amount of time the connection or link has been up (dwConnectDuration).

dwConnectDuration
The amount of time, in milliseconds, that the connection or link has been connected.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Ras.h.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Structures, RasClearConnectionStatistics, RasClearLinkStatistics, RasGetConnectionStatistics, RasGetLinkStatistics


RAS_USER_0

The RAS_USER_0 structure is used in the RasAdminUserSetInfo and RasAdminUserGetInfo functions to specify information about a user.

typedef struct _RAS_USER_0 {
  BYTE  bfPrivilege;
  WCHAR szPhoneNumber[ RASSAPI_MAX_PHONENUMBER_SIZE + 1];
} RAS_USER_0, *PRAS_USER_0;

Members

bfPrivilege
A set of bit flags that specify the RAS privileges of the user. This member can be a combination of the RASPRIV_DialinPrivilege flag and one of the call-back flags. Use the RASPRIV_CallbackType mask to identify the type of call-back privilege provided to the user. The following flags are defined.
Value | Meaning
RASPRIV_NoCallback | The user has no call-back privilege.
RASPRIV_AdminSetCallback | The user account is configured to have the administrator set the call-back number.
RASPRIV_CallerSetCallback | The remote user can specify a call-back phone number when dialing in.
RASPRIV_DialinPrivilege | The user has permission to dial in to this server.

Specify one of the call-back flags in the call to the RasAdminUserSetInfo function.

szPhoneNumber
A null-terminated Unicode string that specifies the call-back phone number for the user.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Header: Declared in Rassapi.h.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Structures, RasAdminUserGetInfo, RasAdminUserSetInfo


SECURITY_MESSAGE

The SECURITY_MESSAGE structure is used with the RasSecurityDialogComplete function to indicate the results of a RAS security DLL authentication transaction.

typedef struct _SECURITY_MESSAGE {
  DWORD dwMsgId;
  HPORT hPort;
  DWORD dwError;
  CHAR  UserName[UNLEN+1];
  CHAR  Domain[DNLEN+1];
} SECURITY_MESSAGE, *PSECURITY_MESSAGE;

Members

dwMsgId
Indicates whether the RAS server should grant access to the remote user. This member can be one of the following values.
Value | Meaning
SECURITYMSG_SUCCESS | The security DLL successfully authenticated the remote user identified by the UserName member. The RAS server will proceed with its PPP authentication.
SECURITYMSG_FAILURE | The security DLL denied access to the remote user identified by the UserName member. The RAS server will hang up the call and record the failed authentication in the Windows NT/2000 event log.
SECURITYMSG_ERROR | An error occurred that prevented validation of the remote user. The RAS server will hang up the call and record the error in the Windows NT/2000 event log.

hPort
Specifies the port handle that the RAS server passed to the security DLL in the RasSecurityDialogBegin call for this authentication transaction.
dwError
Specifies an error code. If dwMsgId is SECURITYMSG_ERROR, set dwError to one of the nonzero error codes defined in Winerror.h or Raserror.h. The RAS server records this error code in the Windows NT/Windows 2000 event log. If the dwMsgId member indicates success or failure, set dwError to zero.
UserName
Specifies the name of the remote user if dwMsgId is SECURITYMSG_SUCCESS or SECURITYMSG_FAILURE. This string can be empty if dwMsgId is SECURITYMSG_ERROR.
Domain
Specifies the name of the logon domain for the remote user if dwMsgId is SECURITYMSG_SUCCESS or SECURITYMSG_FAILURE. This string can be empty if dwMsgId is SECURITYMSG_ERROR.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Rasshost.h.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Structures, RasSecurityDialogBegin, RasSecurityDialogComplete


RAS Server Administration Union

For Windows NT version 4.0, use the following union to implement RAS server administration functionality. Windows 95 does not provide RAS server support.

RAS_PARAMS_VALUE


RAS_PARAMS_VALUE

The RAS_PARAMS_VALUE union is used in the RAS_PARAMETERS structure to store the data associated with a media-specific parameter. The P_Type member of the RAS_PARAMETERS structure uses a value from the RAS_PARAMS_FORMAT enumeration to indicate the type of value currently stored in RAS_PARAMS_VALUE.

union RAS_PARAMS_VALUE {
  DWORD  Number;
  struct  {
      DWORD  Length ;
      PCHAR  Data ;
  } String;
};

Members

Number
If the P_Type member of the RAS_PARAMETERS structure is ParamNumber, the Number member contains the value of the media-specific parameter. For example, the MAXCONNECTBPS parameter is of type ParamNumber, and the value might be 19200.

If the P_Type member of the RAS_PARAMETERS structure is ParamNumber, the Number member contains the value of the media-specific parameter. For example, the MAXCONNECTBPS parameter is of type ParamNumber, and the value might be 19200.

String
If the P_Type member of the RAS_PARAMETERS structure is ParamString, the String member contains the value of the media-specific parameter.
Length
Specifies the length, in characters, of the string pointed to by the Data member.
Data
Pointer to a buffer that contains the string value of a media-specific parameter.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Header: Declared in Rassapi.h.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Union, RAS_PARAMETERS, RAS_PARAMS_FORMAT


RAS Server Administration Enumeration Types

For Windows NT version 4.0, use the following enumeration to implement RAS server administration functionality. Windows 95 does not provide RAS server support.

RAS_PARAMS_FORMAT


RAS_PARAMS_FORMAT

The RAS_PARAMS_FORMAT enumeration type is used in the RAS_PARAMETERS structure to indicate the type of data associated with a media-specific key.

enum RAS_PARAMS_FORMAT {
  ParamNumber        = 0,
  ParamString        = 1
} ;

Values

ParamNumber
Indicates that the data associated with the key is a number.
ParamString
Indicates that the data associated with the key is a string.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Header: Declared in Rassapi.h.

See Also

Remote Access Service (RAS) Overview, RAS Server Administration Enumeration Types, RAS_PARAMETERS


Routing and Remote Access Service

Purpose

The Routing and Remote Access Service (RRAS) API makes it possible to create applications to administer the routing and remote access service capabilities of Microsoft® Windows® 2000 Server. Developers can use RRAS to implement routing protocols.

Where Applicable

RRAS makes it possible for a computer running Windows 2000 Server to function as a network router. RRAS also provides the next generation of server functionality for the Remote Access Service (RAS) for Windows. The new RRAS server functionality follows and builds upon the Remote Access Service (RAS) that was included in Windows NT Server 4.0. The RRAS API can be used in any environment that uses these features of the operating system.

Developer Audience

The RRAS API is designed for use by C/C++ programmers. Programmers should also be familiar with networking concepts.

Run-Time Requirements

RRAS is a server-based technology. The enhanced RAS functionality of RRAS is available for Windows NT Server 4.0 by installing the RRAS redistributable. All the functionality of RRAS is incorporated into Windows 2000 Server. RRAS applications cannot run on Windows NT Workstation 4.0, Windows 2000 Professional, Windows 95 or Windows 98. For more specific information about which operating systems support a particular function, refer to the Requirements sections in the documentation.

See Also

IP Helper Functions

Remote Access Service

Overview

General information about Routing and Remote Access Service.

Reference

Documentation of Routing and Remote Access Services component functions, structures, and other elements of code is in the following sections.

  • RAS Adminstration

  • Router Management

  • Management Information Base

  • Packet Filtering

  • Routing Protocol Interface

  • Routing Table Manager Version 2

  • Routing Table Manager Version 1

  • Multicast Group Manager

  • Extensible Authentication Protocol

  • Tracing Reference

Feedback

Make error reports and feature requests directly to Microsoft.


About Routing and Remote Access Service

The following documentation describes the Routing and Remote Access Service (RRAS). The RRAS API is a feature of Microsoft® Windows® 2000.

This documentation includes the following sections:

  • Remote Access Service Administration
  • Router Management
  • Management Information Base
  • Packet Filtering
  • Routing Protocol Interface
  • Routing Table Manager Version 1
  • Routing Table Manager Version 2
  • Extensible Authentication Protocol
  • Multicast Group Manager
  • Tracing
  • Glossary


Windows 2000 Routing and Remote Access Services Architecture

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


Windows 2000 Registry Layout

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

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\RasMan
    \PPP
        \ControlProtocols
            \Builtin
                Path: REG_EXPAND_SZ: %SystemRoot%\System32\rasppp.dll
            \Chap
                Path: REG_EXPAND_SZ: %SystemRoot%\System32\raschap.dll
        \EAP
            \<typeID>
                ConfigCLSID: REG_SZ: <guid>
                ConfigUiPath: REG_EXPAND_SZ: %SystemRoot%\System32\rastls.dll
                FriendlyName: REG_SZ: Public Key Based Authentication (EAP-TLS)
                IdentityUIPath: REG_EXPAND_SZ: %SystemRoot%\System32\rastls.dll
                InvokePasswordDialog: REG_DWORD: 0
                InvokeUsernameDialog: REG_DWORD: 0
                Path: REG_EXPAND_SZ: %SystemRoot%\System32\rastls.dll
            \<typeID>
                FriendlyName: REG_SZ: MD5 CHAP
                InvokePasswordDialog: REG_DWORD: 0x1
                InvokeUsernameDialog: REG_DWORD: 0x1
                Path: REG_EXPAND_SZ: %SystemRoot%\System32\raschap.dll
                StandaloneSupported: REG_DWORD: 0

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\RemoteAccess
    \Accounting
        \Providers
            ActiveProvider: REG_SZ: . . .
            \<guid>
                ConfigCLSID: REG_SZ: <guid>
                DisplayName: REG_SZ: Radius Accounting
                Path: REG_EXPAND_SZ: %SystemRoot%\System32\rasrad.dll
                Vendor: REG_SZ: Microsoft
             . . .
    \Authentication
        \Providers
            ActiveProvider: REG_SZ: . . .
            \<guid>
                ConfigCLSID: REG_SZ: <guid>
                DisplayName: REG_SZ: Radius Authentication
                Path: REG_EXPAND_SZ: %SystemRoot%\System32\rasrad.dll
                Vendor: REG_SZ: Microsoft
            \<guid>
                ConfigCLSID: REG_SZ: <guid>
                DisplayName: REG_SZ: NT Authentication
                Path: REG_EXPAND_SZ: %SystemRoot%\System32\rasauth.dll
                Vendor: REG_SZ: Microsoft
             . . .
    \DemandDialManager
        DLLPath: REG_EXPAND_SZ: . . .
        < RAS parameters and DDM parameters >
    \Interfaces
        \0
            Enabled: REG_DWORD: (0/1)
            InterfaceName: REG_SZ: Redmond
            Type: REG_DWORD: (Internal/Dedicated/Loopback)
                \IP
                    InterfaceInfo: REG_BINARY: . . .
                    ProtocolID: REG_DWORD: 0x0021
                \IPX
                    InterfaceInfo: REG_BINARY: . . .
                    ProtocolID: REG_DWORD: 0x002B
                . . .
        \N
            InterfaceName: REG_SZ: IntelEtherExpressPro2
            . . .
    \Parameters
        LANOnlyMode: REG_DWORD: (0/1)
        ServerFlags: REG_DWORD: . . .
        ServiceDLL: REG_EXPAND_SZ: %SystemRoot%\System32\mprdim.dll
    \RouterManagers
        \IP
            DLLPath: REG_SZ: . . .
            GlobalInFilter: REG_BSZ: < filter set name > . . .
            GlobalInfo: REG_BINARY: . . .
            GlobalInterfaceInfo: REG_BINARY: . . .
            ProtocolID: REG_DWORD: 0x0021
            . . .
            \IPX
            DLLPath: REG_SZ: . . .
            GlobalInFilter: REG_BSZ: < filter set name > . . .
            GlobalInfo: REG_BINARY: . . .
            GlobalInterfaceInfo: REG_BINARY: . . .
            ProtocolID: REG_DWORD: 0x002B
            . . .
        . . .

HKEY_LOCAL_MACHINE\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
                    \IPBOOTP
                        . . .
                    \IPRIP
                        . . .
                \IPX
                    \IpxRip
                        ConfigDll: REG_SZ: ipxadmin.dll
                        DllName: REG_SZ: IPXRIP.DLL
                        ProtocolID: REG_DWORD: 0x20000
                        Title: REG_SZ: RIP for Ipx
                    \IpxSap
                        . . .
                    . . .
            \UIConfigDlls
                <guid1>: REG_SZ: ifadmin.dll
                <guid2>: REG_SZ: ipadmin.dll
                <guid3>: REG_SZ: ipxadmin.dll
                <guid4>: REG_SZ: ddmadmin.dll

Every router manager installed in the system has a registry key created under the Router key. The DLLPath variable specifies the location of the DLL that corresponds 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, for example).


About Remote Access Service Administration

Microsoft® Windows® 2000 provides a set of functions for administering user permissions and ports on Windows 2000 RAS servers. Using these functions, you can develop a RAS server administration application to perform the following tasks:

  • Enumerate those users who have a specified set of RAS permissions
  • Assign or revoke RAS permissions for a specified user
  • Enumerate the configured ports on a RAS server
  • Get information and statistics about a specified port on a RAS server
  • Reset the statistics counters for a specified port
  • Disconnect a specified port

You can also install a RAS server administration DLL for auditing user connections and assigning IP addresses to dial-in users. The DLL exports a set of functions that the RAS server calls whenever a user tries to connect or disconnect.

This documentation describes the following topics:

  • Function Comparison: Windows 2000 vs RRAS Redistributable
  • RAS User Administration
  • RAS Server and Port Administration
  • RAS Administration DLL
  • RAS Administration DLL Registry Setup


Function Comparison: Windows 2000 vs RRAS Redistributable

The RAS API is distributed as a feature of Microsoft Windows 2000. RAS is also available as a redistributable for Windows NT 4.0. RAS in either of these forms provides the same functionality. The only difference is the naming convention that is used for the reference elements in each version of the RAS API.

The RAS functions for Windows NT 4.0 typically begin with the "RasAdmin" prefix. The analogous functions for Routing and Remote Access Service (RRAS) begin with the "MprAdmin" prefix. For example, Windows NT 4.0 RAS provides a function called RasAdminPortGetInfo. The analogous function in RRAS is called MprAdminPortGetInfo. Another example: Windows NT 4.0 RAS provides the callback function RasAdminGetIpAddressForUser. RRAS provides a similar callback function called MprAdminGetIpAddressForUser. Exceptions to this rule are RasAdminPortClearStatistics, which, under RRAS is MprAdminPortClearStats, and RasAdminFreeBuffer, which under RRAS is MprAdminBufferFree.

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

Windows NT 4.0 RAS | RRAS
RasAdminAcceptNewConnection | MprAdminAcceptNewConnection
RasAdminConnectionHangupNotification | MprAdminConnectionHangupNotification
RasAdminFreeBuffer | MprAdminBufferFree
RasAdminGetErrorString | MprAdminGetErrorString
RasAdminGetIpAddressForUser | MprAdminGetIpAddressForUser
RasAdminPortClearStatistics | MprAdminPortClearStats
RasAdminPortDisconnect | MprAdminPortDisconnect
RasAdminPortEnum | MprAdminPortEnum
RasAdminPortGetInfo | MprAdminPortGetInfo
RasAdminReleaseIpAddress | MprAdminReleaseIpAddress
RasAdminUserGetInfo | MprAdminUserGetInfo
RasAdminUserSetInfo | MprAdminUserSetInfo

Although the RRAS functions are similar to their Windows NT 4.0 RAS counterparts in functionality, RRAS 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.

The RRAS redistributable for Windows NT 4.0 adds the following functions, which have no counterparts in Windows NT 4.0 RAS:

MprAdminAcceptNewLink

MprAdminConnectionClearStats

MprAdminConnectionEnum

MprAdminConnectionGetInfo

MprAdminGetPDCServer

MprAdminIsServiceRunning

MprAdminLinkHangupNotification

MprAdminPortReset

MprAdminServerConnect

MprAdminServerDisconnect

In addition to the preceding functions, Windows 2000 adds the following functions:

MprAdminSendUserMessage

MprAdminAcceptNewConnection2

MprAdminConnectionHangupNotification2


RAS User Administration

A Windows® 2000 RAS server uses a user account database that contains information about a set of user accounts. The information includes a user's RAS privileges, which are a set of bit flags that determine how the RAS server responds when the user calls to connect. The RAS server administration functions locate the user account database, and get and set the RAS privileges for user accounts.

A Windows 2000 RAS server can be part of a Windows 2000 domain, or it can be a stand-alone Windows 2000 Server or Windows 2000 Professional workstation that is not part of a domain. For a server that is part of a domain, the user account database is stored on the Windows NT/Windows 2000 server that is the primary domain controller (PDC). A stand-alone server stores its own local user account database. To get the name of the server that stores the user account database used by a specified RAS server, you can call the MprAdminGetPDCServer function. You can then use the name of the user account server in a call to the NetQueryDisplayInformation function to enumerate the users in a user account database. You can also use the server name in calls to the MprAdminUserGetInfo and MprAdminUserSetInfo functions to get and set the RAS privileges for a specified user account.

The MprAdminUserGetInfo and MprAdminUserSetInfo functions use the RAS_USER_0 structure to specify a user's RAS privileges and call-back phone number. The RAS privileges indicate the following information:

  • Whether the user can make a remote connection to the server or the domain to which the server belongs.
  • Whether the user establishes a connection through a call back, in which the RAS server hangs up and then calls back to the user to establish the connection.

Each user account specifies one of the following flags to indicate the user's call-back privileges.

Value | Meaning
RASPRIV_NoCallback | The RAS server will not call back the user to establish a connection.
RASPRIV_AdminSetCallback | When the user calls, the RAS server hangs up and calls a preset call-back phone number stored in the user account database. The szPhoneNumber member of the RAS_USER_0 structure contains the user's call-back phone number.
RASPRIV_CallerSetCallback | When the user calls, the RAS server provides the option of specifying a phone number to call back. The user can also choose to connect immediately without a call back. The szPhoneNumber member contains a default number that the user can override.


RAS Server and Port Administration

The RAS server administration functions get information about a specified RAS server and its ports. These functions are also used to terminate a connection on a specified RAS server port.

The MprAdminServerGetInfo function returns a MPR_SERVER_0 structure that contains information about the configuration of a RAS server. The returned information includes the number of ports currently available for connection, the number of ports currently in use, and the server version number.

The MprAdminPortEnum function retrieves an array of RAS_PORT_0 structures that contains information for each of the ports configured on a RAS server. The information for each port includes:

  • The name of the port
  • Information about the device attached to the port
  • Whether the RAS server associated with the port is a Windows NT/Windows 2000 Server
  • Whether the port is currently in use, and, if it is, information about the connection

You can call the MprAdminPortGetInfo function to get additional information about a specified port on a RAS server. This function returns a RAS_PORT_1 structure that contains a RAS_PORT_0 structure and additional information about the current state of the port. The RasAdminPortGetInfo function also returns an array of RAS_PARAMETERS structures that describe the values of any media-specific keys associated with the port. A RAS_PARAMETERS structure uses a value from the RAS_PARAMS_FORMAT enumeration to indicate the format of the value for each media-specific key.

The MprAdminPortGetInfo function also returns a RAS_PORT_STATISTICS structure that contains various statistic counters for the current connection, if any, on the port. For a port that is part of a multilink connection, MprAdminPortGetInfo returns statistics for the individual port and cumulative statistics for all ports involved in the connection. You can use the MprAdminPortClearStats function to reset the statistic counters for the port. The MprAdminPortDisconnect function disconnects a port that is in use.

Use the MprAdminBufferFree function to free memory allocated by the MprAdminPortEnum and MprAdminPortGetInfo functions. Use the MprAdminGetErrorString function to get a string that describes a RAS error code returned by one of the RAS server administration (RasAdmin) functions.


RAS Administration DLL

Microsoft® Windows NT® 4.0 makes it possible to install a RAS administration DLL on a Windows NT 4.0 RAS server. The DLL exports functions that the RAS server calls whenever a user tries to connect or disconnect. You can use the DLL to perform the following administrative functions:

  • Decide whether to allow a user to connect to the server. This can provide a security check in addition to the standard RAS user authentication.
  • Record the time that each user connects to and disconnects from the server. This can be useful for billing or auditing purposes.
  • Assign an IP address to each user. This is useful for security, because this feature is used to map a user's connection to a specific computer.

Implement the following functions when developing a RAS server administration DLL:

  • MprAdminAcceptNewConnection
  • MprAdminConnectionHangupNotification
  • MprAdminGetIpAddressForUser
  • MprAdminReleaseIpAddress

A RAS administration DLL must implement and export all of the above functions. If any of the functions are not implemented, the remote access service does not start.

The MprAdminAcceptNewConnection and MprAdminConnectionHangupNotification functions enable the DLL to audit user connections to the server. A Windows NT/Windows 2000 RAS server calls the MprAdminAcceptNewConnection function whenever a user tries to connect. This function prevents the user from connecting. The MprAdminAcceptNewConnection function is also used to generate an entry in a log for billing or auditing. When the user disconnects, the RAS server calls the MprAdminConnectionHangupNotification function, which can log the time at which the user disconnected.

After the RAS server has authenticated a caller, it calls the MprAdminGetIpAddressForUser function to get an IP address for the remote client. The DLL uses this function to provide an alternate scheme to map an IP address to a dial-in user. If MprAdminGetIpAddressForUser is not implemented, a RAS server connects a remote user to an IP address that is selected from a static pool of IP addresses, or one selected by a Dynamic Host Configuration Protocol (DHCP) server. The MprAdminGetIpAddressForUser function allows the DLL to override this default IP address and specify a particular IP address for each user. The MprAdminGetIpAddressForUser function can set a flag that causes RAS to call the MprAdminReleaseIPAddress function when the user disconnects. The DLL can use MprAdminReleaseIPAddress to update its user-to-IP-address map.

RAS serializes calls into the administration DLL. A call into one of the DLL's functions for a given RAS client does not preempt a call to that function for a different RAS client; RAS does not call the function for the other client until the initial call is complete. Furthermore, serialization extends to certain groups of functions. The IP address functions are serialized as a group; a call into either MprAdminGetIpAddressForUser or MprAdminReleaseIpAddress blocks calls into both functions until the initial call is complete. MprAdminAcceptNewConnection and MprAdminConnectionHangupNotification are also serialized as a group.

RAS executes the functions that assign IP addresses in one process; the functions for connection and disconnection notifications are executed in another process. Consequently, the DLL doesnot depend on shared data between these two sets of functions.

The RAS server logs an error in the system event log if an error occurs when it tries to load a RAS administration DLL or when calling one of the DLL's functions. This can happen, for example, if the DLL specified the wrong name for an exported function, or if it did not include the function name in the DEF file. The entry in the event log indicates the reason for the failure.

Windows 2000 and later: RAS administration DLLs that implement this function interface do not work on Windows 2000 and later versions. For Windows 2000 and later versions, use the MprAdmin function interface provided with the more recent versions of Windows. For more information, see the RAS Administration Reference in the Routing and RAS documentation.


RAS Administration DLL Registry Setup

The setup program for a third-party RAS administration DLL must register the DLL with RAS by providing information under the following key in the registry:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDll

To register the DLL, set the following values under this key.

Value name | Value data
DisplayName | A REG_SZ string that contains the user-friendly display name of the DLL.
DLLPath | A REG_SZ string that contains the full path of the DLL.

For example, the registry entry for a RAS administration DLL from a fictional company named ProElectron, Inc. might be:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDll

DisplayName : REG_SZ : ProElectron RAS Admin DLL

DLLPath : REG_SZ : C:\nt\system32\ntwkadm.dll

The setup program for a RAS administration DLL also provides remove and uninstall functionality. If a user removes the DLL, the setup program deletes the registry entries for the DLL.


Remote Access Service Administration Reference

Use the following functions, structures, and enumerated types when developing administration applications for the Remote Access Service.

  • RAS Administration Functions
  • RAS Administration Structures
  • RAS Administration Enumerated Types


RAS Administration Functions

This documentation describes RRAS functions that are used to develop software to administer RAS dial-up connections. These functions include:

MprAdminConnectionClearStats

MprAdminConnectionEnum

MprAdminConnectionGetInfo

MprAdminPortClearStats

MprAdminPortDisconnect

MprAdminPortEnum

MprAdminPortGetInfo

MprAdminPortReset

Additional functions are used for both RAS administration and router administration. The following functions documented in the Router Administration Functions reference:

MprAdminBufferFree

MprAdminGetErrorString

MprAdminIsServiceRunning

MprAdminServerConnect

MprAdminServerDisconnect

To implement a RAS administration DLL, use the functions described in the following topic:

RAS Admin DLL Functions

To manage users of a RAS server, use the functions described in the following topic:

RAS User Administration Functions


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
[in] Handle to the Remote Access Server on which to execute MprAdminConnectionClearStats. Obtain this handle by calling MprAdminServerConnect.
hRasConnection
[in] 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 is NO_ERROR.

If the function fails, the return value is ERROR_INVALID_PARAMETER.

Remarks

This function is available on Windows NT 4.0 if the RRAS redistributable is installed. However, the version of Mprapi.dll that ships with the RRAS redistributable exports the function as RasAdminConnectionClearStats rather than MprAdminConnectionClearStats. Therefore, when using the RRAS redistributable, use LoadLibrary and GetProcAddress to access this function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Remote Access Service Administration Reference, RAS Administration Functions, 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, one, or two
  LPBYTE *lplpbBuffer,           // pointer to array of connection structs
  DWORD dwPrefMaxLen,            // maximum preferred length of returned data
  LPDWORD lpdwEntriesRead,       // number of connections enumerated
  LPDWORD lpdwTotalEntries,      // number of connections that could've been enumerated
  LPDWORD lpdwResumeHandle       // handle with which to resume enumeration
);

Parameters

hRasServer
[in] Handle to the RAS server on which connections are enumerated. Obtain this handle by calling MprAdminServerConnect.
dwLevel
[in] Specifies the format of the information returned through the lplpbBuffer parameter.

Windows NT 4.0: This parameter must be zero.

Windows 2000 and later: This parameter should be zero, one, or two, corresponding to RAS_CONNECTION_0, RAS_CONNECTION_1, or RAS_CONNECTION_2.

lplpbBuffer
[out] Upon successful execution, lplpbBuffer points to an array of structures that describe the enumerated connections. These structures are of type RAS_CONNECTION_0, RAS_CONNECTION_1, or RAS_CONNECTION_2 depending on the value of the dwLevel parameter. Free this memory by calling MprAdminBufferFree.
dwPrefMaxLen
[in] Specifies the preferred maximum length of returned data in 8-bit bytes. If dwPrefMaxLen is -1, the buffer returned is large enough to hold all available information.
lpdwEntriesRead
[out] Pointer to a DWORD variable. This variable receives the total number of connections enumerated from the current resume position.
lpdwTotalEntries
[out] Pointer to a DWORD variable. This variable receives the total number of connections that could have been enumerated from the current resume position.
lpdwResumeHandle
[in] Pointer to a DWORD variable. This variable specifies a resume handle used to continue the enumeration. The lpdwResumeHandle parameter is zero on the first call, and left unchanged on subsequent calls. If the return code is ERROR_MORE_DATA, another call may be made using this handle to retrieve more data. If the handle is NULL upon return, the enumeration is complete. This handle is invalid for other types of error returns.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_LEVEL | The value passed for dwLevel is not zero, one, or two. Levels one and two are supported only on Windows 2000 and later operating systems.
ERROR_INVALID_PARAMETER | At least one of the following parameters is NULL or does not point to valid memory: lplpBuffer, lpdwEntriesRead, or lpdwTotalEntries..
ERROR_MORE_DATA | Not all of the data was returned with this call. To obtain additional data, call the function again using the resume handle.
RPC_S_INVALID_BINDING | The handle passed in the hRasServer parameter is NULL or invalid..

Remarks

This function is available on Windows NT 4.0 if the RRAS redistributable is installed. However, the version of Mprapi.dll that ships with the RRAS redistributable exports the function as RasAdminConnectionEnum rather than MprAdminConnectionEnum. Therefore, when using the RRAS redistributable, use LoadLibrary and GetProcAddress to access this function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Remote Access Service Administration Reference, RAS Administration Functions, 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
[in] Handle to the computer on which connection information is gathered. This computer should be running RRAS for Windows NT/Windows 2000. Obtain this handle by calling MprAdminServerConnect.
dwLevel
[in] Specifies the format and content of the returned information. Acceptable values for dwLevel are zero or one. A value of zero returns a RAS_CONNECTION_0 structure; a value of one returns a RAS_CONNECTION_1 structure.
hConnection
[in] Handle to the connection for which to obtain information. Obtain this handle by calling MprAdminConnectionEnum.
lplpbBuffer
[out] Pointer to a pointer variable that points 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 is NO_ERROR.

If the function fails, the return value is ERROR_INVALID_PARAMETER.

Remarks

This function is available on Windows NT 4.0 if the RRAS redistributable is installed. However, the version of Mprapi.dll that ships with the RRAS redistributable exports the function as RasAdminConnectionGetInfo rather than MprAdminConnectionGetInfo. Therefore, when using the RRAS redistributable, use LoadLibrary and GetProcAddress to access this function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Remote Access Service Administration Reference, RAS Administration Functions, 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
[in] Handle to the RAS server on which to clear the statistics for the specified port. Obtain this handle by calling MprAdminServerConnect.
hPort
[in] Handle to the port for which statistics are reset. Obtain this handle by calling MprAdminPortEnum.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is ERROR_INVALID_PARAMETER.

Remarks

This function is available on Windows NT 4.0 if the RRAS redistributable is installed. However, the version of Mprapi.dll that ships with the RRAS redistributable exports the function as RasAdminPortClearStats rather than MprAdminPortClearStats. Therefore, when using the RRAS redistributable, use LoadLibrary and GetProcAddress to access this function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Remote Access Service Administration Reference, RAS Administration Functions, 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
[in] Handle to the RAS server on which to disconnect the port. Obtain this handle by calling MprAdminServerConnect.
hPort
[in] Handle to the port to disconnect. Obtain this handle by calling MprAdminPortEnum.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is ERROR_INVALID_PARAMETER.

Remarks

This function is available on Windows NT 4.0 if the RRAS redistributable is installed. However, the version of Mprapi.dll that ships with the RRAS redistributable exports the function as RasAdminPortDisconnect rather than MprAdminPortDisconnect. Therefore, when using the RRAS redistributable, use LoadLibrary and GetProcAddress to access this function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Remote Access Service Administration Reference, RAS Administration Functions, 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
  LPDWORD lpdwEntriesRead,       // number of ports enumerated
  LPDWORD lpdwTotalEntries,      // number of ports that could have been enumerated
  LPDWORD lpdwResumeHandle       // handle with which to resume enumeration
);

Parameters

hRasServer
[in] Handle to the RAS server on which to enumerate ports. Obtain this handle by calling MprAdminServerConnect.
dwLevel
[in] Specifies the level of information returned in the enumeration. This parameter must be zero.
hConnection
[in] Handle to a connection for which the active ports are enumerated. If hConnection is INVALID_HANDLE_VALUE, all the ports in use or available for use by RRAS are enumerated. Obtain the hConnection handle by calling MprAdminConnectionEnum.
lplpbBuffer
[out] 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
[in] Specifies the preferred maximum length of returned data in 8-bit bytes. If dwPrefMaxLen is -1, the buffer returned is large enough to hold all available information.
lpdwEntriesRead
[out] Pointer to a DWORD variable. This variable receives the total number of ports enumerated from the current resume position.
lpdwTotalEntries
[out] Pointer to a DWORD variable. This variable receives the total number of ports that could have been enumerated from the current resume position.
lpdwResumeHandle
[in] Pointer to a DWORD variable. Upon successful execution, lpdwResumeHandle specifies a handle that can be used to resume 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 reissued 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 is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
ERROR_DDM_NOT_RUNNING | The Demand Dial Manager (DDM) is not running, possibly because the Dynamic Interface Manager (DIM) is configured to run only on a LAN.
ERROR_INVALID_PARAMETER | At least one of the following parameters is NULL or does not point to valid memory: lplpBuffer, lpdwEntriesRead, or lpdwTotalEntries.
ERROR_MORE_DATA | Not all of the data was returned with this call. To obtain additional data, call the function again using the handle that was returned in the IpdwResumeHandle parameter.
ERROR_NOT_SUPPORTED | The dwLevel parameter is not zero.

Remarks

This function is available on Windows NT 4.0 if the RRAS redistributable is installed. However, the version of Mprapi.dll that ships with the RRAS redistributable exports the function as RasAdminPortEnum rather than MprAdminPortEnum. Therefore, when using the RRAS redistributable, use LoadLibrary and GetProcAddress to access this function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Remote Access Service Administration Reference, RAS Administration Functions, 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
[in] Handle to the RAS server computer on which to collect port information. Obtain this handle by calling MprAdminServerConnect.
dwLevel
[in] 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_PORT_0 structure; a value of one will return a RAS_PORT_1 structure.
hPort
[in] Handle to the port for which to collect information. Obtain this handle by calling MprAdminPortEnum.
lplpbBuffer
[out] 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 is NO_ERROR.

If the function fails, the return value is ERROR_INVALID_PARAMETER.

Remarks

This function is available on Windows NT 4.0 if the RRAS redistributable is installed. However, the version of Mprapi.dll that ships with the RRAS redistributable exports the function as RasAdminPortGetInfo rather than MprAdminPortGetInfo. Therefore, when using the RRAS redistributable, use LoadLibrary and GetProcAddress to access this function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Remote Access Service Administration Reference, RAS Administration Functions, 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
[in] Handle to the RAS server on which to reset the specified port. Obtain this handle by calling MprAdminServerConnect.
hPort
[in] Handle to the port to be reset. Obtain this handle by calling MprAdminPortEnum.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is ERROR_INVALID_PARAMETER.

Remarks

This function is available on Windows NT 4.0 if the RRAS redistributable is installed. However, the version of Mprapi.dll that ships with the RRAS redistributable exports the function as RasAdminPortReset rather than MprAdminPortReset. Therefore, when using the RRAS redistributable, use LoadLibrary and GetProcAddress to access this function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Remote Access Service Administration Reference, RAS Administration Functions, MprAdminServerConnect, MprAdminPortEnum


RAS Admin DLL Functions

A RAS server administration DLL allows you to customize the following aspects of RAS:

  • Access control for remote access clients
  • Remote access client connection and disconnection event logging
  • Logging and control of IP address allocation to remote access clients.

A RAS administration DLL must implement and export all of the following functions:

MprAdminAcceptNewLink

MprAdminConnectionHangupNotification

MprAdminConnectionHangupNotification2

MprAdminInitializeDll

MprAdminGetIpAddressForUser

MprAdminLinkHangupNotification

MprAdminReleaseIpAddress

MprAdminTerminateDll

In addition, the RAS administration DLL must implement and export either

MprAdminAcceptNewConnection, and

MprAdminConnectionHangupNotification

or

MprAdminAcceptNewConnection2, and

MprAdminConnectionHangupNotification2

If not all of the required functions are implemented, the remote access service will fail to start.

RAS serializes calls into the administration DLL. A call into one of the DLL's functions for a given RAS client will never be preempted by a call to that function for a different RAS client; the initial call is guaranteed to complete before RAS calls the function for the other client. Furthermore, serialization extends to certain groups of functions. The IP address functions are serialized as a group; a call into either MprAdminGetIpAddressForUser or MprAdminReleaseIpAddress will block calls into both until the initial call completes. Together, the new connection/link and connection/link-hang-up notification functions are also serialized as a group.

Do not call any of the RAS Administration Functions or Ras User Administration Functions from inside a callout function. Calls to these functions will not return when made from within a callout function.


MprAdminAcceptNewConnection

Remote Access Service calls the MprAdminAcceptNewConnection function each time a new user dials in and successfully completes RAS authentication. MprAdminAcceptNewConnection determines whether the user is allowed to connect.

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

Parameters

pRasConnection0
[in] Pointer to a RAS_CONNECTION_0 structure that describes this connection.
pRasConnection1
[in] Pointer to a RAS_CONNECTION_1 structure that describes this connection.

Return Values

If MprAdminAcceptNewConnection accepts the connection, the return value should be TRUE.

If MprAdminAcceptNewConnection rejects the connection, the return value should be FALSE.

Remarks

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

Do not call any of the RAS Administration Functions or Ras User Administration Functions from inside MprAdminAcceptNewConnection. Calls to these functions will not return when made from within a callout function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.

See Also

Remote Access Service Administration Reference, RAS Administration Functions, MprAdminAcceptNewConnection2, MprAdminConnectionHangupNotification, MprAdminConnectionHangupNotification2, RAS_CONNECTION_0, RAS_CONNECTION_1


MprAdminAcceptNewConnection2

Remote Access Service calls the MprAdminAcceptNewConnection2 function each time a new user dials in and successfully completes RAS authentication. MprAdminAcceptNewConnection2 determines whether the user is allowed to connect.

BOOL MprAdminAcceptNewConnection2(
  RAS_CONNECTION_0 *pRasConnection0,
  RAS_CONNECTION_1 *pRasConnection1,
  RAS_CONNECTION_2 *pRasConnection2
);

Parameters

pRasConnection0
[in] Pointer to a RAS_CONNECTION_0 structure that describes this connection.
pRasConnection1
[in] Pointer to a RAS_CONNECTION_1 structure that describes this connection.
pRasConnection2
[in] Pointer to a RAS_CONNECTION_2 structure that describes this connection.

Return Values

If MprAdminAcceptNewConnection2 accepts the connection, the return value should be TRUE.

If MprAdminAcceptNewConnection2 rejects the connection, the return value should be FALSE.

Remarks

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

Do not call any of the RAS Administration Functions or Ras User Administration Functions from inside MprAdminAcceptNewConnection2. Calls to these functions will not return when made from within a callout function.

Requirements

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

See Also

Remote Access Service Administration Reference, RAS Administration Functions, MprAdminConnectionHangupNotification2, RAS_CONNECTION_0, RAS_CONNECTION_1, RAS_CONNECTION_2


MprAdminAcceptNewLink

RAS calls the MprAdminAcceptNewLink function each time a link is created for a particular connection. RAS calls this function once immediately after MprAdminAcceptNewConnection returns, 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
[in] Pointer to a RAS_PORT_0 structure that describes the port being used by the link.
pRasPort1
[in] 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.

Do not call any of the RAS Administration Functions or RAS User Administration Functions from inside MprAdminAcceptNewLink. Calls to these functions will not return when made from within a callout function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.

See Also

Remote Access Service Administration Reference, RAS Administration Functions, MprAdminAcceptNewConnection, MprAdminConnectionHangupNotification, MprAdminLinkHangupNotification, RAS_PORT_0, RAS_PORT_1


MprAdminConnectionHangupNotification

Remote Access Service calls the MprAdminConnectionHangupNotification function 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
[in] Pointer to a RAS_CONNECTION_0 structure that describes this connection.
pRasConnection1
[in] Pointer to a RAS_CONNECTION_1 structure that describes this connection.

Return Values

This function does not have a return value.

Remarks

Do not call any of the RAS Administration Functions or Ras User Administration Functions from inside MprAdminConnectionHangupNotification. Calls to these functions will not return when made from within a callout function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.

See Also

Remote Access Service Administration Reference, RAS Administration Functions, MprAdminAcceptNewConnection, MprAdminAcceptNewLink, MprAdminConnectionHangupNotification2, RAS_CONNECTION_0, RAS_CONNECTION_1


MprAdminConnectionHangupNotification2

Remote Access Service calls the MprAdminConnectionHangupNotification2 function after the last link for the specified connection has been dismantled.

VOID MprAdminConnectionHangupNotification2(
  RAS_CONNECTION_0 *pRasConnection0,
  RAS_CONNECTION_1 *pRasConnection1,
  RAS_CONNECTION_2 *pRasConnection2
  );

Parameters

pRasConnection0
[in] Pointer to a RAS_CONNECTION_0 structure that describes this connection.
pRasConnection1
[in] Pointer to the RAS_CONNECTION_1 structure that describes this connection.
pRasConnection2
[in] Pointer to a RAS_CONNECTION_2 structure that describes this connection.

Return Values

This function does not have a return value.

Remarks

Do not call any of the RAS Administration Functions or Ras User Administration Functions from inside MprAdminConnectionHangupNotification2. Calls to these functions will not return when made from within a callout function.

Requirements

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

See Also

Remote Access Service Administration Reference, RAS Administration Functions, MprAdminAcceptNewConnection2, MprAdminAcceptNewLink, RAS_CONNECTION_0, RAS_CONNECTION_1, RAS_CONNECTION_2


MprAdminInitializeDll

When the Routing and Remote Access Service (RRAS) starts, it calls the MprAdminInitializeDll function exported by the administration DLL. Use this function to perform any needed initialization for the DLL.

DWORD APIENTRY MprAdminInitializeDll(
    VOID
);

Parameters

This function takes no parameters.

Requirements

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

See Also

MprAdminTerminateDll


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
[in] Pointer to a Unicode string that specifies the name of the user requiring an IP address.
lpwszPortName
[in] Pointer to a Unicode string that specifies the name of the port on which the user is attempting to connect.
lpdwIpAddress
[in, out] On input, pointer to a DWORD variable that contains zero or the IP address RAS allocated for the user

On output, if RAS specified zero, the DLL allocates an IP address for the user. In this case, if the DLL does not allocate an IP address, the user is not able to connect. If RAS specified an IP address, the DLL either accepts the address or substitutes a different one.

bNotifyRelease
[out] 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.

Remarks

Do not call any of the RAS Administration Functions or Ras User Administration Functions from inside MprAdminGetIpAddressForUser. Calls to these functions will not return when made from within a callout function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.

See Also

Remote Access Service Administration Reference, RAS Administration Functions, 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
[in] Pointer to a RAS_PORT_0 structure that describes the port being used by the link.
pRasPort1
[in] 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.

Remarks

Do not call any of the RAS Administration Functions or Ras User Administration Functions from inside MprAdminLinkHangupNotification. Calls to these functions will not return when made from within a callout function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.

See Also

Remote Access Service Administration Reference, RAS Administration Functions, MprAdminConnectionHangupNotification, MprAdminConnectionHangupNotification2, MprAdminAcceptNewConnection, MprAdminAcceptNewConnection2, MprAdminAcceptNewLink, RAS_PORT_0, RAS_PORT_1


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
[in] Pointer to a Unicode string that specifies the name of the user requiring an IP address.
lpwszPortName
[in] Pointer to a Unicode string that specifies the name of the port on which the user is attempting to connect.
lpdwIpAddress
[in] Pointer to a DWORD variable. This variable specifies the IP address to be released.

Return Values

This function does not have a return value.

Remarks

Do not call any of the RAS Administration Functions or Ras User Administration Functions from inside MprAdminReleaseIpAddress. Calls to these functions will not return when made from within a callout function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.

See Also

Remote Access Service Administration Reference, RAS Administration Functions, MprAdminConnectionHangupNotification, MprAdminGetIpAddressForUser


MprAdminTerminateDll

When the Routing and Remote Access Service shuts down, it calls the MprAdminTerminateDll function exported by the administration DLL. Use this function to perform any needed clean-up for the DLL.

DWORD APIENTRY MprAdminTerminateDll(
    VOID
);

Parameters

This function takes no parameters.

Requirements

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

See Also

MprAdminInitializeDll


RAS User Administration Functions

Use the following functions to manage dial-up users:

MprAdminGetPDCServer

MprAdminSendUserMessage

MprAdminUserGetInfo

MprAdminUserSetInfo

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. 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 lpwsPDCName               // pointer to buffer to receive
                                   // name of server with UAS
);

Parameters

lpwsDomainName
[in] Pointer to a null-terminated Unicode string that specifies the name of the domain to which the RAS server belongs. This parameter can be NULL if you are running your RAS administration application on a Windows NT/Windows 2000 server that is not participating in a domain. If this parameter is NULL, the lpwsServerName parameter must not be NULL.
lpwsServerName
[in] Pointer to a null-terminated Unicode string that specifies the name of the Windows NT/Windows 2000 RAS server. Specify the name with leading "\\" characters, in the form: \\servername. This parameter can be NULL if the lpwsDomain parameter is not NULL.
lpwsPDCName
[out] Pointer to a buffer that receives a null-terminated Unicode string that contains the name of a domain controller that has the user account database. The buffer should be big enough to hold the server name (UNCLEN +1). The function prefixes the returned server name with leading "\\" characters, in the form: \\servername.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails the return value is one of the following values.

Value | Meaning
ERROR_NO_SUCH_DOMAIN | The domain specified is not valid.
NERR_InvalidComputer | The lpwsDomainName is NULL, and lpwsServerName parameter is not valid.

Remarks

The MprAdminGetPDCServer function can obtain the name of the server with the user accounts database given the name of the RAS server, or the name of the domain in which the RAS server resides. To get the server name, call the GetComputerName function

If the server name specified by lpszServer is part of a domain, The server returned by MprAdminGetPDCServer will be either the primary domain controller or a backup domain controller.

If the server name specified by lpszServer is a stand-alone Windows NT/Windows 2000 server (that is, the server or workstation does not participate in a Windows NT/Windows 2000 domain), then the server name itself is returned in the lpszUserAccountServer buffer.

You can then use the name of the user account server in a call to the NetQueryDisplayInformation function to enumerate the users in the user account database. You can also use the server name in calls to the MprAdminUserGetInfo and MprAdminUserSetInfo functions to get and set RAS privileges for a specified user account.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Remote Access Service Administration Reference, RAS Administration Functions, GetComputerName, MprAdminUserGetInfo, MprAdminUserSetInfo, NetQueryDisplayInformation


MprAdminSendUserMessage

The MprAdminSendUserMessage function sends a message to the user connected on the specified connection.

DWORD MprAdminSendUserMessage(
  HANDLE hConnection,    // handle to connection
  LPWSTR lpwszMessage    // pointer to message
);

Parameters

hConnection
[in] Handle to the connection on which the user is connected. Use MprAdminConnectionEnum to obtain this handle.
lpwszMessage
[in] Pointer to a Unicode string that specifies the message to the user.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The caller does not have sufficient privileges.
ERROR_DDM_NOT_RUNNING | The Demand Dial Manager (DDM) is not running, possibly because the Dynamic Interface Manager (DIM) is configured to run only on a LAN.
ERROR_INTERFACE_NOT_CONNECTED | The hConnection parameter is not valid.
ERROR_INVALID_PARAMETER | The lpwszMessage parameter is NULL.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Remote Access Service Administration Reference, RAS Administration Functions, MprAdminConnectionEnum


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
[in] Pointer to a Unicode string that specifies the name of the server computer with the master User Accounts Subsystem (UAS). If the remote access server is part of a domain, the computer with the UAS will be either the primary domain controller or the backup domain controller. If the remote access server is not part of a domain, then the server itself will store the UAS. In either case, call the MprAdminGetPDCServer function to obtain the value for this parameter.

If the server itself stores the UAS, this parameter may be NULL.

lpwsUserName
[in] Pointer to a Unicode string that specifies the name of the user for which to get RAS information.
dwLevel
[in] This parameter must be zero.

Windows 2000 and later: This parameter may be zero or one.

lpbBuffer
[out] 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.

Windows 2000 and later: If the dwLevel parameter specifies one, lpbBuffer should point to a RAS_USER_1 structure.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails the return value is one of the following values.

Value | Meaning
ERROR_ACCESS_DENIED | The caller does not have sufficient privileges.
ERROR_INVALID_LEVEL | The value of dwLevel is invalid.
ERROR_INVALID_PARAMETER | lpbBuffer is NULL
ERROR_NO_SUCH_USER | The user specified by lpwsUserName does not exist on the server specified by lpwsServerName.

Remarks

This function is available on Windows NT 4.0 if the RRAS redistributable is installed. However, the version of Mprapi.dll that ships with the RRAS redistributable exports the function as RasAdminUserGetInfo rather than MprAdminUserGetInfo. Therefore, when using the RRAS redistributable, use LoadLibrary and GetProcAddress to access this function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Remote Access Service Administration Reference, RAS Administration Functions, 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
[in] Pointer to a Unicode string that specifies the name of the server computer with the master User Accounts Subsystem (UAS). If the remote access server is part of a domain, the computer with the UAS will be either the primary domain controller or the backup domain controller. If the remote access server is not part of a domain, then the server itself will store the UAS. In either case, call the MprAdminGetPDCServer function to obtain the value for this parameter.

If the server itself stores the UAS, this parameter may be NULL.

lpwsUserName
[in] Pointer to a Unicode string that specifies the name of the user for which to set RAS information.
dwLevel
[in] This parameter must be zero.

Windows 2000 and later: This parameter may be zero or one.

lpbBuffer
[in] Pointer to a RAS_USER_0 structure that specifies the new RAS information for the user.

Windows 2000 and later: If the dwLevel parameter specifies one, lpbBuffer should point to a RAS_USER_1 structure.

Return Values

If the function succeeds, the return value is NO_ERROR.

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

Value | Meaning
ERROR_ACCESS_DENIED | The caller does not have sufficient privileges.
ERROR _INVALID_LEVEL | The value of dwLevel is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient resources to complete the operation.
ERROR_NO_SUCH_USER | The user specified by lpwsUserName does not exist on the server specified by lpwsServerName.

Remarks

This function is available on Windows NT 4.0 if the RRAS redistributable is installed. However, the version of Mprapi.dll that ships with the RRAS redistributable exports the function as RasAdminUserSetInfo rather than MprAdminUserSetInfo. Therefore, when using the RRAS redistributable, use LoadLibrary and GetProcAddress to access this function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Remote Access Service Administration Reference, RAS Administration Functions, MprAdminGetPDCServer, MprAdminUserGetInfo, RAS_USER_0


RAS Administration Structures

The RAS Administration Functions use the following structures:

PPP_ATCP_INFO

PPP_CCP_INFO

PPP_INFO

PPP_INFO_2

PPP_IPCP_INFO

PPP_IPCP_INFO2

PPP_IPXCP_INFO

PPP_LCP_INFO

PPP_NBFCP_INFO

RAS_CONNECTION_0

RAS_CONNECTION_1

RAS_CONNECTION_2

RAS_PORT_0

RAS_PORT_1

RAS_USER_0

RAS_USER_1


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
Specifies 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
Specifies a Unicode string that holds the client's AppleTalk address on the RAS connection.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.

See Also

Remote Access Service Administration Reference, RAS Administration Structures, PPP_INFO


PPP_CCP_INFO

The PPP_CCP_INFO structure contains information that describes the results of a Compression Control Protocol (CCP) negotiation.

typedef struct _PPP_CCP_INFO {
  OUT DWORD           dwError;
  OUT DWORD           dwCompressionAlgorithm;
  OUT DWORD           dwOptions;
  OUT DWORD           dwRemoteCompressionAlgorithm;
  OUT DWORD           dwRemoteOptions;
} PPP_CCP_INFO;

Members

dwError
Specifies an error if the negotiation is unsuccessful.
dwCompressionAlgorithm
Specifies the compression algorithm used by the local computer. The following table shows the possible values for this member.
Value | Meaning
RASCCPCA_MPPC | Microsoft Point-to-Point Compression (MPPC) Protocol
RASCCPCA_STAC | STAC option 4

dwOptions
Specifies the compression options on the local computer. The following options are supported.
Option | Meaning
PPP_CCP_COMPRESSION | Compression without encryption.
PPP_CCP_HISTORYLESS | Microsoft Point to Point Encryption (MPPE) in stateless mode. The session key is changed after every packet. This mode improves performance on high latency networks, or networks that experience significant packet loss.
PPP_CCP_ENCRYPTION40BITOLD | MPPE using 40-bit keys.
PPP_CCP_ENCRYPTION40BIT | MPPE using 40-bit keys.
PPP_CCP_ENCRYPTION56BIT | MPPE using 56-bit keys.
PPP_CCP_ENCRYPTION128BIT | MPPE using 128-bit keys.

dwRemoteCompressionAlgorithm
Specifies the compression algorithm used by the remote computer. The following table shows the possible values for this member.
Value | Meaning
RASCCPCA_MPPC | Microsoft Point-to-Point Compression (MPPC) Protocol
RASCCPCA_STAC | STAC option 4

dwRemoteOptions
Specifies the compression options on the remote computer. The following options are supported.
Option | Meaning
PPP_CCP_COMPRESSION | Compression without encryption.
PPP_CCP_HISTORYLESS | Microsoft Point to Point Encryption (MPPE) in stateless mode. The session key is changed after every packet. This mode improves performance on high latency networks, or networks that experience significant packet loss.
PPP_CCP_ENCRYPTION40BITOLD | MPPE using 40-bit keys.
PPP_CCP_ENCRYPTION40BIT | MPPE using 40-bit keys.
PPP_CCP_ENCRYPTION56BIT | MPPE using 56-bit keys.
PPP_CCP_ENCRYPTION128BIT | MPPE using 128-bit keys.

Requirements

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

See Also

PPP_LCP_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
Specifies a PPP_NBFCP_INFO structure.
ip
Specifies a PPP_IPCP_INFO structure.
ipx
Specifies a PPP_IPXCP_INFO structure.
at
Specifies a PPP_ATCP_INFO structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.

See Also

Remote Access Service Administration Reference, RAS Administration Structures, PPP_ATCP_INFO, PPP_IPCP_INFO, PPP_IPXCP_INFO, PPP_NBFCP_INFO, RAS_CONNECTION_1


PPP_INFO_2

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

typedef struct _PPP_INFO_2 {
  PPP_NBFCP_INFO  nbf;
  PPP_IPCP_INFO   ip;
  PPP_IPXCP_INFO  ipx;
  PPP_ATCP_INFO   at;
  PPP_CCP_INFO    ccp;
  PPP_LCP_INFO    lcp;
} PPP_INFO_2;

Members

nbf
Specifies a PPP_NBFCP_INFO structure.
ip
Specifies a PPP_IPCP_INFO structure.
ipx
Specifies a PPP_IPXCP_INFO structure.
at
Specifies a PPP_ATCP_INFO structure.
ccp
Specifies a PPP_CCP_INFO structure.
lcp
Specifies a PPP_LCP_INFO structure.

Requirements

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

See Also

Remote Access Service Administration Reference, RAS Administration Structures, PPP_ATCP_INFO, PPP_IPCP_INFO, PPP_IPXCP_INFO, PPP_NBFCP_INFO, PPP_CCP_INFO, PPP_LCP_INFO, RAS_CONNECTION_2


PPP_IPCP_INFO

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

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

Members

dwError
Specifies 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
Specifies a Unicode string that holds the local computer's IP address for the connection. This string has the form a.b.c.d; for example, "11.101.237.71".

The PPP_IPCP_INFO structures provides address information from the perspective of the server. For example, if a remote access client is connecting to a RAS server, this member holds the IP address of the server.

wszRemoteAddress
Specifies a Unicode string that holds the IP address of the remote computer. This string has the form "a.b.c.d". If the address is not available, this member is an empty string, "".

The PPP_IPCP_INFO structures provides address information from the perspective of the server. For example, if a remote access client is connecting to a RAS server, this member holds the IP address of the client.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.

See Also

Remote Access Service Administration Reference, RAS Administration Structures, PPP_INFO, PPP_IPCP_INFO2


PPP_IPCP_INFO2

The PPP_IPCP_INFO2 structure contains the result of a PPP Internet Protocol (IP) negotiation.

typedef struct _PPP_IPCP_INFO2 {
  DWORD    dwError;
  WCHAR    wszAddress[ IPADDRESSLEN + 1 ];
  WCHAR    wszRemoteAddress[ IPADDRESSLEN + 1 ];
  DWORD    dwOptions;
  DWORD    dwRemoteOptons;
} PPP_IPCP_INFO2;

Members

dwError
Specifies 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
Specifies a Unicode string that holds the local computer's IP address for the connection. This string has the form a.b.c.d; for example, "11.101.237.71".

The PPP_IPCP_INFO2 structures provides address information from the perspective of the server. For example, if a remote access client is connecting to a RAS server, this member holds the IP address of the server.

wszRemoteAddress
Specifies a Unicode string that holds the IP address of the remote computer. This string has the form "a.b.c.d". If the address is not available, this member specifies an empty string, "".

The PPP_IPCP_INFO2 structures provides address information from the perspective of the server. For example, if a remote access client is connecting to a RAS server, this member holds the IP address of the client.

dwOptions
Specifies IPCP options for the local computer. Currently, the only option is PPP_IPCP_VJ. This option indicates that IP datagrams sent by the local computer are compressed using Van Jacobson compression.
dwRemoteOptons
Specifies IPCP options for the remote peer. Currently, the only option is PPP_IPCP_VJ. This option indicates that IP datagrams sent by the remote peer (that is, received by the local computer) are compressed using Van Jacobson compression.

Requirements

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

See Also

Remote Access Service Administration Reference, RAS Administration Structures, PPP_INFO, PPP_IPCP_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
Specifies 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
Specifies a Unicode string that holds the client's IPX address on the RAS connection.

Remarks

The PPP_IPXCP_INFO structure can be used only when administrating computers that are running 32-bit Whistler or an earlier operating system. Windows 2000 64-bit Edition does not support the IPX protocol.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.

See Also

Remote Access Service Administration Reference, RAS Administration Structures, PPP_INFO


PPP_LCP_INFO

The PPP_LCP_INFO structure contains information that describes the results of an PPP Link Control Protocol (LCP) negotiation.

typedef struct _PPP_LCP_INFO {
  OUT DWORD dwError;
  OUT DWORD dwAuthenticationProtocol;
  OUT DWORD dwAuthenticationData;
  OUT DWORD dwRemoteAuthenticationProtocol;
  OUT DWORD dwRemoteAuthenticationData;
  OUT DWORD dwTerminateReason;
  OUT DWORD dwRemoteTerminateReason;
  OUT DWORD dwOptions;
  OUT DWORD dwRemoteOptions;
  OUT DWORD dwEapTypeId;
  OUT DWORD dwRemoteEapTypeId;
} PPP_LCP_INFO;

Members

dwError
Specifies the error that occurred if the negotiation was unsuccessful.
dwAuthenticationProtocol
Specifies the authentication protocol used to authenticate the local computer. This member can be one of the following values.
Value | Meaning
PPP_LCP_PAP | Password Authentication Protocol
PPP_LCP_SPAP | Shiva Password Authentication Protocol
PPP_LCP_CHAP | Challenge Handshake Authentication Protocol
PPP_LCP_EAP | Extensible Authentication Protocol

dwAuthenticationData
Specifies additional information about the authentication protocol specified by the dwAuthenticationProtocol member. This member can be one of the following values.
Value | Meaning
PPP_LCP_CHAP_MD5 | MD5 CHAP
PPP_LCP_CHAP_MS | Microsoft CHAP
PPP_LCP_CHAP_MSV2 | Microsoft CHAP version 2

dwRemoteAuthenticationProtocol
Specifies the authentication protocol used to authenticate the remote computer. See the dwAuthenticationProtocol member for a list of possible values.
dwRemoteAuthenticationData
Specifies additional information about the authentication protocol specified by dwRemoteAuthenticationProtocol. See the dwAuthenticationData member for a list of possible values.
dwTerminateReason
Specifies the reason the connection was terminated by the local computer. This member always has a value of zero.
dwRemoteTerminateReason
Specifies the reason the connection was terminated by the remote computer. This member always has a value of zero.
dwOptions
Specifies information about LCP options in use by the local computer. This member is a combination of the following flags.
Flag | Meaning
PPP_LCP_MULTILINK_FRAMING | The connection is using multilink
RASLCPO_PFC | Protocol Field Compression (see RFC 1172)
RASLCPO_ACFC | Address and Control Field Compression (see RFC 1172)
RASLCPO_SSHF | Short Sequence Number Header Format (see RFC 1990)
RASLCPO_DES_56 | DES 56-bit encryption
RASLCPO_3_DES | Triple DES Encryption

dwRemoteOptions
Specifies information about LCP options in use by the remote computer. This member is a combination of the following flags.
Flag | Meaning
PPP_LCP_MULTILINK_FRAMING | The connection is using multilink.
RASLCPO_PFC | Protocol Field Compression (see RFC 1172)
RASLCPO_ACFC | Address and Control Field Compression (see RFC 1172)
RASLCPO_SSHF | Short Sequence Number Header Format (see RFC 1990)
RASLCPO_DES_56 | DES 56-bit encryption
RASLCPO_3_DES | Triple DES Encryption

dwEapTypeId
Specifies the type identifier of the Extensible Authentication Protocol (EAP) used to authenticate the local computer. The value of this member is valid only if dwAuthenticationProtocol is PPP_LCP_EAP.
dwRemoteEapTypeId
Specifies the type identifier of the Extensible Authentication Protocol (EAP) used to authenticate the remote computer. The value of this member is valid only if dwRemoteAuthenticationProtocol is PPP_LCP_EAP.

Requirements

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

See Also

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

Remarks

The PPP_NBFCP_INFO structure can be used only when administrating computers that are running an operating system prior to Whistler. Whistler and later operating systems do not support the NetBEUI protocol.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.

See Also

Remote Access Service Administration Reference, RAS Administration Structures, PPP_INFO


RAS_CONNECTION_0

The RAS_CONNECTION_0 structure contains general information regarding a specific connection, such as user name 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
Specifies the duration of the current connection, in seconds.
dwInterfaceType
Specifies the interface type of the current connection.
dwConnectionFlags
Specifies one of a set of flags that describe this connection. This member can contain the following flags.
Flag | Meaning
RAS_FLAGS_PPP_CONNECTION | The connection is using Point-to-Point Protocol (PPP).
RAS_FLAGS_MESSENGER_PRESENT | The messenger service is active on the client, and that messages can be sent to the client using MprAdminSendUserMessage.
RAS_FLAGS_RAS_CONNECTION | The connection is a NetBIOS connection from a Windows 3.11 or Windows for Workgroups client.
RAS_FLAGS_ARAP_CONNECTION | The connection is using AppleTalk Remote Access Protocol (ARAP).

wszInterfaceName
Specifies a Unicode string that contains the name of the interface for this connection.
wszUserName
Specifies a Unicode string that contains the name of the user logged on to the connection.
wszLogonDomain
Specifies a Unicode string that contains the domain on which the connected user is authenticated.
wszRemoteComputer
Specifies a Unicode string that contains the name of the remote computer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.

See Also

Remote Access Service Administration Reference, RAS Administration Structures, RAS_CONNECTION_1, RAS_CONNECTION_2


RAS_CONNECTION_1

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

typedef struct RAS_CONNECTION_1 {
  HANDLE      hConnection;
  HANDLE      hInterface;
  PPP_INFO    PppInfo;
  DWORD       dwBytesXmited;
  DWORD       dwBytesRcved;
  DWORD       dwFramesXmited;
  DWORD       dwFramesRcved;
  DWORD       dwCrcErr;
  DWORD       dwTimeoutErr;
  DWORD       dwAlignmentErr;
  DWORD       dwHardwareOverrunErr;
  DWORD       dwFramingErr;
  DWORD       dwBufferOverrunErr;
  DWORD       dwCompressionRatioIn;
  DWORD       dwCompressionRatioOut;

} RAS_CONNECTION_1; *PRAS_CONNECTION_1;

Members

hConnection
Handle to the connection.
hInterface
Handle to the interface.
PppInfo
Specifies a PPP_INFO structure.
dwBytesXmited
Specifies the bytes transmitted on the current connection.
dwBytesRcved
Specifies the bytes received on the current connection.
dwFramesXmited
Specifies the frames transmitted on the current connection.
dwFramesRcved
Specifies the frames received on the current connection.
dwCrcErr
Specifies the CRC (Cyclic Redundancy Check) errors on the current connection.
dwTimeoutErr
Specifies the time-out errors on the current connection.
dwAlignmentErr
Specifies the alignment errors on the current connection.
dwHardwareOverrunErr
Specifies the number of hardware overrun errors on the current connection.
dwFramingErr
Specifies the number of framing errors for the current connection.
dwBufferOverrunErr
Specifies the number of buffer overrun errors.
dwCompressionRatioIn
Specifies a percentage that indicates the degree to which data received on this connection is compressed. The ratio is the size of the compressed data divided by the size of the same data in an uncompressed state.
dwCompressionRatioOut
Specifies a percentage that indicates the degree to which data transmitted on this connection is compressed. The ratio is the size of the compressed data divided by the size of the same data in an uncompressed state.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.

See Also

Remote Access Service Administration Reference, RAS Administration Structures, RAS_CONNECTION_0, RAS_CONNECTION_2, PPP_INFO


RAS_CONNECTION_2

The RAS_CONNECTION_2 structure contains information for a connection, including the GUID that identifies the connection.

typedef struct _RAS_CONNECTION_2 {
  HANDLE      hConnection;                  // handle to the connection
  WCHAR       wszUserName[ UNLEN + 1 ];     // name of the user
                                            // on this connection
  ROUTER_INTERFACE_TYPE   dwInterfaceType;  // interface type
                                            // for the connection
  GUID        guid;                         // guid that identifies the connection
  PPP_INFO_2  PppInfo2;
} RAS_CONNECTION_2, *PRAS_CONNECTION_2;

Members

hConnection
Handle to the connection.
wszUserName[ UNLEN + 1 ]
Specifies a Unicode string that contains the name of the user on this connection.
dwInterfaceType
Specifies the type of interface.
guid
Specifies a GUID (Globally Unique Identifier) that identifies the connection. For incoming connection, this GUID is valid only as long as the connection is active.
PppInfo2
Specifies a PPP_INFO_2 structure that contains information about the PPP negotiation for this connection.

Requirements

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

See Also

Remote Access Service Administration Reference, RAS Administration Structures, MprAdminConnectionEnum, RAS_CONNECTION_0, RAS_CONNECTION_1


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               wszDeviceType[ 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
Specifies the cumulative number of calls this port has serviced.
dwConnectDuration
Specifies the duration of the current connection, in seconds.
wszPortName
Specifies the port name.
wszMediaName
Specifies the media name.
wszDeviceName
Specifies the device name.
wszDeviceType
Specifies the device type.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.

See Also

Remote Access Service Administration Reference, RAS Administration Structures, 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                   dwCompressionRatioIn;
  DWORD                   dwCompressionRatioOut;
} RAS_PORT_1, *PRAS_PORT_1;

Members

hPort
Handle to the port.
hConnection
Handle to the connection.
dwHardwareCondition
Specifies a RAS_HARDWARE_CONDITION structure.
dwLineSpeed
Specifies the line speed of the port, represented in bits per second.
dwBytesXmited
Specifies the bytes transmitted on the port.
dwBytesRcved
Specifies the bytes received on the port.
dwFramesXmited
Specifies the frames transmitted on the port.
dwFramesRcved
Specifies the frames received on the port.
dwCrcErr
Specifies the CRC errors on the port.
dwTimeoutErr
Specifies the time-out errors on the port.
dwAlignmentErr
Specifies the alignment errors on the port.
dwHardwareOverrunErr
Specifies the hardware overrun errors on the port.
dwFramingErr
Specifies the framing errors on the port.
dwBufferOverrunErr
Specifies the buffer overrun errors on the port.
dwCompressionRatioIn
Specifies a percentage that indicates the degree to which data received on this connection is compressed. The ratio is the size of the compressed data divided by the size of the same data in an uncompressed state.
dwCompressionRatioOut
Specifies a percentage indicating the degree to which data transmitted on this connection is compressed. The ratio is the size of the compressed data divided by the size of the same data in an uncompressed state.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.

See Also

Remote Access Service Administration Reference, RAS Administration Structures, RAS_PORT_0, RAS_HARDWARE_CONDITION


RAS_USER_0

The RAS_USER_0 structure contains information for a 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
Specifies the types of remote access privilege available to the RAS user.

The following remote access privilege constants are defined in Mprapi.h.
Value | Meaning
RASPRIV_DialinPrivilege | The user has permission to dial in to the RAS server.
RASPRIV_NoCallback | The RAS server will not call back the user to establish a connection.
RASPRIV_AdminSetCallback | When the user calls, the RAS server hangs up and calls a preset call-back phone number stored in the user account database. The wszPhoneNumber member of the RAS_USER_0 structure contains the user's call-back phone number.
RASPRIV_CallerSetCallback | When the user calls, the RAS server provides the option of specifying a call-back phone number. The user can also choose to connect immediately without a call back. The wszPhoneNumber member contains a default number that the user can override.

Use the following constant as a mask to isolate the call-back privilege. (This constant is also defined in Mprapi.h.)

RASPRIV_CallbackType

wszPhoneNumber
Pointer to a Unicode string containing the phone number at which the RAS user should be called back.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Header: Declared in Rassapi.h.

See Also

Remote Access Service Administration Reference, RAS Administration Structures, MprAdminUserGetInfo, MprAdminUserSetInfo, RAS_USER_1


RAS_USER_1

The RAS_USER_1 structure contains information for a particular Remote Access Service user. The RAS_USER_1 structure is similar to the RAS_USER_0 structure, except that RAS_USER_1 supports an additional member, bfPrivilege2.

typedef struct _RAS_USER_1 {
  OUT BYTE        bfPrivilege;
  OUT WCHAR       wszPhoneNumber[ MAX_PHONE_NUMBER_LEN + 1];
  OUT BYTE        bfPrivilege2;
} RAS_USER_1, *PRAS_USER_1;

Members

bfPrivilege
Specifies the types of remote access privilege available to the RAS user.

The following remote access privilege constants are defined in Mprapi.h.
Value | Meaning
RASPRIV_DialinPrivilege | The user has permission to dial in to the RAS server.
RASPRIV_NoCallback | The RAS server will not call back the user to establish a connection.
RASPRIV_AdminSetCallback | When the user calls, the RAS server hangs up and calls a preset call-back phone number stored in the user account database. The wszPhoneNumber member of the RAS_USER_0 structure contains the user's call-back phone number.
RASPRIV_CallerSetCallback | When the user calls, the RAS server provides the option of specifying a call-back phone number. The user can also choose to connect immediately without a call back. The wszPhoneNumber member contains a default number that the user can override.

Use the following constant as a mask to isolate the call back privilege. (This constant is also defined in Mprapi.h.)

RASPRIV_CallbackType

wszPhoneNumber
Pointer to a Unicode string containing the phone number at which the RAS user should be called back.
bfPrivilege2
Specifies flags that grant additional remote access privileges to the RAS user.

The following remote access privilege constants are defined in Mprapi.h.
Value | Meaning
RASPRIV2_DialinPolicy | Remote access policies determine whether the user is allowed dial-in access.

Requirements

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

See Also

Remote Access Service Administration Reference, RAS Administration Structures, MprAdminUserGetInfo, MprAdminUserSetInfo, RAS_USER_0


RAS Administration Enumerated Types

The RAS Administration Functions use the following enumerated types:

RAS_HARDWARE_CONDITION

RAS_PORT_CONDITION


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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.

See Also

Remote Access Service Administration Reference, RAS Administration Enumerated Types


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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.

See Also

Remote Access Service Administration Reference, RAS Administration Enumerated Types


About Router Management

The router administration API allows developers to create applications to manage the router service on a computer running Microsoft® Windows® 2000. The following topics provide detailed information about router administration:

  • Components of the Router Architecture
  • Router Initialization
  • Router Management Functions
  • Router Interface Functions
  • Router Manager (Transport) Functions
  • Router Manager Client (InterfaceTransport) Functions
  • MprInfo Functions and Information Headers
  • Managing Router Clients and Interfaces


Components of the Router Architecture

The router administration documentation makes frequent reference to the following components of the router.

Dynamic Interface Manager (DIM)

All router administration functions pass through DIM. Depending on the nature of the function, DIM may pass the call on to one of the router managers. Functions that deal only with interfaces are handled by DIM. If the function affects routing protocols, DIM will call into the router manager for the transport corresponding to that protocol. For example, if the function affects the Open Shortest Path First (OSPF) protocol, DIM will call into the IP Router Manager, since OSPF is an IP routing protocol.

Router Managers

Each routable transport has its own router manager. Currently router managers exist for the IP and IPX transports. The router managers manage router protocols and other types of routing clients that run on interfaces on the local computer.

Routing Protocols and other Clients

Clients are service providers that function within the framework of the router architecture. Routing protocols are one type of client that is supported by the router.

Clients are specific to a particular routable transport: either IP or IPX. Routing protocols for the IP transport include Open Shortest Path First (OSPF) and Routing Information Protocol (RIP). Examples of IPX routing protocols are Service Advertising Protocol (SAP) and RIP for IPX. An example of a client that is not a routing protocol is Network Address Translation (NAT) for IP.

The interface between the router manager and a client is described in the section Routing Protocol Interface. All clients conform to this interface. Using this interface, vendors can implement their own clients that are compatible with the router.

Interfaces

An interface is a connection to an external network. Each interface is identified by a unique interface index. Interfaces are logical entities; router clients such at NAT or OSPF deal with all types of interfaces similarly. In terms of implementation however, an interface can represent a dedicated connection (such as to a Local Area Network (LAN)) or a non-dedicated, dial up connection (such as a PPP connection to a Wide Area Network (WAN)).

In the case of a LAN interface, the interface corresponds to an actual physical device in the computer, a LAN adapter. In the case of a WAN interface, the interface is mapped to a port at the time a connection is established. The port could be a COM port, a parallel port or a virtual port (for tunnels such as PPTP and L2TP).

WAN interfaces have the additional quality that they typically receive a network address only at the time that a connection is established. For example, a WAN interface using PPP receives its network layer address from the remote peer during the connection process. Receiving a network address as part of the connection process is sometimes referred to as "late-binding."


Router Initialization

Configuration information for the router, the router managers and the routing protocols/clients is divided into global information and per interface information and is stored in the registry and the router's phone-book file, router.pbk.

When the router process starts, DIM (Dynamic Interface Manager) reads the router configuration from the registry. DIM creates the interfaces that are specified by the interface information.

DIM also retrieves the global router manager information. DIM starts the router managers corresponding to this information, and passes them the information. For example, if DIM finds global information for the IP router manager in the registry, DIM will start the IP router manager and pass it the global information. If no global information is present in the registry for a particular router manager, DIM will not start that router manager.

The router managers examine the global information received from DIM. If the router manager finds information specific to a particular client within the global information, the router manager will load the DLL for the client (for example ipNAT.dll) and initialize the client by calling the client's RegisterProtocol and StartProtocol functions. The router manager passes the client-specific global information to the client in the call to StartProtocol.

At each stage, the information being passed to the next entity is opaque to the entity above it. That is, DIM does not interpret the global information for the IP Router Manager, beyond the fact that the information is meant for the IP Router Manager. Similarly, the IP Router Manager does not interpret the OSPF specific information beyond the fact that it is OSPF information.


Router Management Functions

The following sections discuss the different types of router management functions and what you should know to use them effectively.

All router management functions require administrator privileges. A user in the Power User group does not have sufficient privileges to use the router management functions.

The Different Classes of Router Management Functions

The router management functions can be divided up into the administration functions and the configuration functions. The administration functions have a prefix of MprAdmin and the configuration functions have a prefix of MprConfig. Despite the naming, both sets of functions are used for router management. The MprAdmin functions operate directly on the running router. The MprConfig functions have similar functionality, but operate on the router configuration stored in the registry. Both types of functions pass information blocks.

The router management functions can also be divided up based on what components of the router they manage: interfaces, router managers, or router manager clients.

The router interface functions have a prefix of either MprAdminInterface or MprConfigInterface. Use these functions to access interfaces. The router manager functions have a prefix of MprAdminTransport or MprConfigTransport. Use these functions to access the router managers. Lastly, the router manager client functions have a prefix of MprAdminInterfaceTransport or MprConfigInterfaceTransport. Use these functions to access the clients running on the router.

A subset of MprAdmin functions are the MprAdminMib functions. These also operate on the running route alone. However, these functions do not pass information blocks. These functions provide additional flexibility to the protocol designer, especially for retrieving non-configuration information, such as statistics

Ensuring that Changes Occur Immediately and are Persistent

A developer can make changes to the router configuration directly using the router configuration functions. However, any changes made to the configuration will not take effect until the router is restarted, since this is the only time that DIM reads the configuration from the registry.

A developer can make changes to the running router by using the router administration functions. However, these changes are not persistent: since they haven't been written to the registry, they will be lost if the router is restarted.

In order to make changes that are both immediate and persistent, a developer will need to use both the router administration and the router configuration functions. If the router is not running, the developer need only call the appropriate router configuration functions.

For querying information from the running router, use the router administration functions. If the router is not running, query information using the router configuration functions.

Windows 2000 and later: The MprAdminInterfaceCreate and MprAdminInterfaceSetInfo functions support the MPR_INTERFACE_2 structure. However, MprConfigInterfaceCreate and MprConfigInterfaceSetInfo do not. In order to create a demand-dial interface that is persistent after a reboot, call MprAdminInterfaceCreate with MPR_INTERFACE_2, then call MprConfigInterfaceCreate with MPR_INTERFACE_0 or MPR_INTERFACE_1. Similarly, to make persistent changes to a demand-dial interface, call MprAdminInterfaceSetInfo with MPR_INTERFACE_2, then call MprConfigInterfaceSetInfo with MPR_INTERFACE_0 or MPR_INTERFACE_1.

Using Router Administration and Configuration Functions Remotely

Most of the router administration and configuration functions can be called on a computer other than the one being administered. These functions take as a parameter, a handle to the router service or configuration to administer. The administration functions use RPC (Remote Procedure Call) to communicate with the routing service specified by the handle. The configuration functions write to and read from the registry of the computer specified by the handle.

To administer the routing service on a remote machine first call MprAdminIsServiceRunning to verify that the service is running. Then call MprdminServerConnect to obtain the handle. If the router service is not running on the remote machine, all router administration ("MprAdmin") calls will fail.

To make changes to the router configuration on a remote machine obtain a handle by calling the MprConfigServerConnect function.


Router Interface Functions

Use the following functions to administer interfaces on the router.

Administration Function | Configuration Function
MprAdminInterfaceCreate | MprConfigInterfaceCreate
MprAdminInterfaceDelete | MprConfigInterfaceDelete
MprAdminInterfaceEnum | MprConfigInterfaceEnum
MprAdminInterfaceGetHandle | MprConfigInterfaceGetHandle
MprAdminInterfaceGetInfo | MprConfigInterfaceGetInfo
MprAdminInterfaceSetInfo | MprConfigInterfaceSetInfo

These functions affect the interfaces themselves, not clients running on the interfaces. For this reason, none of the functions require the caller to specify a particular transport (IP or IPX); although clients (such as routing protocols) are associated with particular transports, the interfaces themselves are not.

These functions are handled directly by DIM. They do not utilize the router managers.

The MprAdminInterfaceCreate and MprAdminInterfaceDelete functions cannot create or delete LAN interfaces. They can only create or delete demand-dial interfaces. See ROUTER_INTERFACE_TYPE for a list of interface types.


Router Manager (Transport) Functions

Use the following functions to administer the router managers. These functions also allow a developer to read and write the global information for the router managers, and the global information for router clients (such as routing protocols).

Administration function | Configuration function
MprAdminTransportCreate | MprConfigTransportCreate
No administration function | MprConfigTransportDelete
MprAdminTransportGetInfo | MprConfigTransportGetInfo
MprAdminTransportSetInfo | MprConfigTransportSetInfo
No administration function | MprConfigTransportEnum
No administration function | MprConfigTransportGetHandle


Router Manager Client (InterfaceTransport) Functions

Use the following functions to administer clients (such as routing protocols) on particular interfaces. These functions also allow a developer to read and write interface-specific information for router clients (such as routing protocols).

Administration function | Configuration function
MprAdminInterfaceTransportAdd | MprConfigInterfaceTransportAdd
MprAdminInterfaceTransportRemove | MprConfigInterfaceTransportRemove
MprAdminInterfaceTransportGetInfo | MprConfigInterfaceTransportGetInfo
MprAdminInterfaceTransportSetInfo | MprConfigInterfaceTransportSetInfo
No administration function | MprConfigInterfaceTransportEnum
No administration function | MprConfigInterfaceTransportGetHandle


MprInfo Functions and Information Headers

The following functions require that the caller pass an information structure or header as one of the parameters.

Administration function | Configuration function
No administration function | MprConfigTransportCreate
MprAdminTransportSetInfo | MprConfigTransportSetInfo
MprAdminInterfaceTransportSetInfo | MprConfigInterfaceTransportSetInfo
MprAdminInterfaceTransportAdd | MprConfigInterfaceTransportAdd

Similarly, the following functions return information headers.

Administration function | Configuration function
MprAdminTransportGetInfo | MprConfigTransportGetInfo
MprAdminInterfaceTransportGetInfo | MprConfigInterfaceTransportGetInfo

For the transport functions, the information header contains global information for the transport. For the client ("InterfaceTransport") functions, the header contains information specific to the client (for example, OSPF) being administered.

The information headers and their contents should be manipulated only by using the MprInfo functions. Developers should not attempt to manipulate the contents of the information headers directly.

The "interface-only" functions such as MprAdminInterfaceSetInfo do not require the use of MprInfo functions. The information that is passed and returned with these functions is always in the form of an MPR_INTERFACE structure.


Managing Router Clients and Interfaces

The following topics describe how to perform typical management tasks using the MprAdmin and MprConfig and MprInfo functions:

  • Changing Interface-Specific and Global Information for Clients
  • Deleting a Client from an Interface


Changing Interface-Specific and Global Information for Clients

To change the interface information for a specific client, for example NAT, first use the appropriate "GetInfo" function to retreive the current information. If the router is running, use MprAdminInterfaceTransportGetInfo. If the router is not running, use the MprConfigInterfaceTransportGetInfo. This call will retrieve the information for all the clients running on the specified interface. For example, if both OSPF and RIP are running on a particular interface, this call will retrieve the interface information for both. Use the MprInfoBlockFind function to locate the information block corresponding to the client you want to modify. Then use the MprInfoBlockSet functions to perform the modifications. Lastly, use either MprAdminInterfaceTransportSetInfo or MprConfigInterfaceSetInfo to make the changes to either the running router or the router configuration in the registry.

Global client information is information that is not specific to any particular interface on which the client is running. Use a similar procedure to modify global information for a specific client. First retrieve the global information for all the clients using MprAdminTransportGetInfo or MprConfigTransportGetInfo. Then use the MprInfo functions to modify the information. Lastly, use the MprAdminTransportSetInfo or MprConfigTransportSetInfo functions to "save" the modified information back to either the running router or the registry.

Calls to the above administration functions go through the Dynamic Interface Manager (DIM), and eventually translate into calls from the router manager to the clients themselves. All clients, whether or not they are routing protocols, must conform to the interface described in the section Router Protocol Interface. As part of this interface, the routing protocol must support the following functions (among others):

  • GetGlobalInfo
  • SetGlobalInfo
  • GetInterfaceInfo
  • SetInterfaceInfo

The router manager calls the GetInterfaceInfo functions for each of the clients to gather the information that is returned from a call to MprAdminInterfaceTransportGetInfo. Similarly, when the router manager receives updated information via MprAdminInterfaceTransportSetInfo call, it uses the SetInterfaceInfo functions to update the interface information for each of the clients.


Deleting a Client from an Interface

To delete a client, such as a routing protocol, from a particular interface, use either MprAdminInterfaceTransportGetInfo or MprConfigInterfaceTransportGetInfo to retrieve all the client information for the interface. Use MprInfoBlockRemove to remove the information block for the client to be deleted. Then use MprInfoBlockAdd to add a zero-length block for the client to be deleted. Finally, use MprAdminInterfaceTransportSetInfo or MprConfigInterfaceTransportSetInfo to "save" the information back to either the running router or the registry.

If the router manager receives a zero-length interface information block for a client, it knows to delete that client from the interface. The router manager will delete the client by calling the client's implementation of DeleteInterface. Note the important distinction between passing an information header that doesn't contain an information block for a client, and passing an information header that contains a zero-length information block for the client. In the first case, the router manager will take no action with respect to the client. In the second case, the router manager will delete the client from the interface.


Router Management Reference

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

  • Router Administration Functions
  • Router Configuration Functions
  • Router Management Structures
  • Router Management Enumerated Types
  • Information Header Functions
  • Router Information Structures
  • Router Information Enumeration Types
  • Microsoft Challenge Handshake Authentication Protocol


Router Administration Functions

Use the following functions when developing software to administer Microsoft® Windows® 2000 routers:

MprAdminBufferFree

MprAdminDeregisterConnectionNotification

MprAdminGetErrorString

MprAdminInterfaceConnect

MprAdminInterfaceCreate

MprAdminInterfaceDelete

MprAdminInterfaceDeviceGetInfo

MprAdminInterfaceDeviceSetInfo

MprAdminInterfaceDisconnect

MprAdminInterfaceEnum

MprAdminInterfaceGetCredentials

MprAdminInterfaceGetCredentialsEx

MprAdminInterfaceGetHandle

MprAdminInterfaceGetInfo

MprAdminInterfaceQueryUpdateResult

MprAdminInterfaceSetCredentials

MprAdminInterfaceSetCredentialsEx

MprAdminInterfaceSetInfo

MprAdminInterfaceTransportAdd

MprAdminInterfaceTransportGetInfo

MprAdminInterfaceTransportRemove

MprAdminInterfaceTransportSetInfo

MprAdminInterfaceUpdatePhonebookInfo

MprAdminInterfaceUpdateRoutes

MprAdminIsServiceRunning

MprAdminRegisterConnectionNotification

MprAdminServerConnect

MprAdminServerDisconnect

MprAdminServerGetCredentials

MprAdminServerGetInfo

MprAdminServerSetCredentials

MprAdminTransportCreate

MprAdminTransportGetInfo

MprAdminTransportSetInfo


MprAdminBufferFree

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

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

Parameters

pBuffer
[in] Pointer to the memory buffer to free.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | The pBuffer parameter is NULL.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, MprAdminInterfaceGetInfo, MprAdminInterfaceEnum, MprAdminServerGetInfo, MprAdminInterfaceTransportGetInfo, MprAdminTransportGetInfo


MprAdminDeregisterConnectionNotification

The MprAdminDeregisterConnectionNotification function deregisters an event object that was previously registered using MprAdminRegisterConnectionNotification. Once deregistered, this event is no longer signaled when an interface connects or disconnects.

DWORD MprAdminDeregisterConnectionNotification(
  MPR_SERVER_HANDLE hMprServer,    // handle to server
  HANDLE hEventNotification        // handle to event
);

Parameters

hMprServer
[in] Handle to the Windows 2000 router on which to execute this call. Obtain this handle by calling MprAdminServerConnect.
hEventNotification
[in] Handle to an event object to deregister. This event will no longer be signaled when an interface connects or disconnects.

Return Values

If the function is successful, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
ERROR_DDM_NOT_RUNNING | The Demand Dial Manager (DDM) is not running.
ERROR_INVALID_PARAMETER | The hEventNotification parameter is NULL or is an invalid handle.
Other | Use FormatMessage to retrieve the system error message that corresponds to the error code returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, FormatMessage, MprAdminRegisterConnectionNotification


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
[in] Specifies the error code for a Windows 2000 router error.
lplpwsErrorString
[out] Pointer to an LPWSTR variable that points to the text associated with the dwError code on successful return. Free this memory by calling LocalFree.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
ERROR_INVALID_PARAMETER | The error code in dwError is unknown.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, 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 fSynchronous              // flag to control synchronous
                                 // versus asychronous operation
);

Parameters

hMprServer
[in] Handle to the Windows 2000 router on which to execute this call. Obtain this handle by calling MprAdminServerConnect.
hInterface
[in] Handle to the interface. This handle is obtained from a previous call to MprAdminInterfaceCreate.
hEvent
[in] Handle to an event that is 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 calling application must specify NULL for this parameter, if hMprserver specifies a remote router.

fSynchronous
[in] 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

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
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 calling application 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 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 signaled, use MprAdminInterfaceGetInfo to determine the success or failure of the connection attempt.
NULL | TRUE | The call does not return until the connection attempt has completed.
NULL | FALSE | The call returns immediately. A return value of PENDING indicates that the attempt was initiated successfully.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, MprAdminInterfaceCreate, MprAdminInterfaceDisconnect, MprAdminInterfaceGetInfo, MprAdminServerConnect


MprAdminInterfaceCreate

[This is preliminary documentation and subject to change.]

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,               // info that describes interface
  HANDLE *phInterface            // handle to the interface
);

Parameters

hMprServer
[in] Handle to the Windows 2000 router on which to execute this call. Obtain this handle by calling MprAdminServerConnect.
dwLevel
[in] Specifies the level of information passed in lpBuffer. Must be zero, indicating that the lpBuffer parameter points to the MPR_INTERFACE_0 structure.

Windows 2000 and later: The dwLevel parameter may have a value of zero, one, or two. A value of one indicates that lpBuffer points to an MPR_INTERFACE_1 structure. A value of two indicates that lpBuffer points to an MPR_INTERFACE_2 structure.

lpBuffer
[in] Pointer to an MPR_INTERFACE_0 structure that contains the information to create the interface. The hInterface member of this structure is ignored.

Windows 2000 and later: The lpBuffer parameter points to either an MPR_INTERFACE_0, MPR_INTERFACE_1, or MPR_INTERFACE_2 structure. The dwLevel parameter indicates the type of structure.

phInterface
[out] Pointer to a HANDLE variable. The variable receives a handle to use in all subsequent calls to manage this interface.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
ERROR_DDM_NOT_RUNNING | The router interface type specified in the MPR_INTERFACE_0 or MPR_INTERFACE_1 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.

Remarks

Windows 2000 and later: The MprAdminInterfaceCreate function supports the MPR_INTERFACE_2 structure. However, MprConfigInterfaceCreate does not. In order to create a demand-dial interface that is persistent after a reboot, call MprAdminInterfaceCreate with MPR_INTERFACE_2, then call MprConfigInterfaceCreate with MPR_INTERFACE_0 or MPR_INTERFACE_1.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, MPR_INTERFACE_0, MPR_INTERFACE_1, MPR_INTERFACE_2, 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
[in] Handle to the Windows 2000 router on which to execute this call. Obtain this handle by calling MprAdminServerConnect.
hInterface
[in] Handle to the interface to delete. Obtain this handle by calling MprAdminInterfaceCreate.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
ERROR_INTERFACE_CONNECTED | The interface specified is a demand-dial interface and is currently connected.
ERROR_INVALID_HANDLE | The hInterface value is invalid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, MprAdminInterfaceCreate, MprAdminServerConnect


MprAdminInterfaceDeviceGetInfo

[This is preliminary documentation and subject to change.]

The MprAdminInterfaceDeviceGetInfo retrieves information about a device that is used in a router demand-dial interface.

DWORD MprAdminInterfaceDeviceGetInfo(
  MPR_SERVER_HANDLE hMprServer,
  HANDLE hInterface,
  DWORD dwIndex,
  DWORD dwLevel,
  LPBYTE *lplpBuffer
);

Parameters

hMprServer
[in] Handle to the Windows 2000 router on which to execute this call. Obtain this handle by calling MprAdminServerConnect.
hInterface
[in] Handle to the interface. Obtain this handle from a previous call to MprAdminInterfaceCreate, or by calling MprAdminInterfaceEnum
dwIndex
[in] Specifies the one-based index of the device. A multi-linked demand-dial interface uses multiple devices.
dwLevel
[in] Specifies the level of the information retrieved.
lplpBuffer
[out] Pointer to a pointer to an MPR_DEVICE_0 or MPR_DEVICE_1 structure that receives the information about the device. The dwLevel parameter specifies the type of structure.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
ERROR_INVALID_HANDLE | The hInterface value is invalid.
ERROR_INVALID_PARAMETER | The lplpbBuffer parameter is NULL.
ERROR_NOT_ENOUGH_MEMORY | Insufficient resources to complete the operation.
ERROR_NOT_SUPPORTED | The dwLevel value is invalid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

MPR_DEVICE_0, MPR_DEVICE_1, MprAdminInterfaceCreate, MprAdminInterfaceDeviceGetInfo


MprAdminInterfaceDeviceSetInfo

[This is preliminary documentation and subject to change.]

The MprAdminInterfaceDeviceSetInfo creates or modifies a device that is used in a router demand-dial interface.

DWORD MprAdminInterfaceDeviceSetInfo(
  MPR_SERVER_HANDLE hMprServer,
  HANDLE hInterface,
  DWORD dwIndex,
  DWORD dwLevel,
  LPBYTE lplpBuffer
);

Parameters

hMprServer
[in] Handle to the Windows 2000 router on which to execute this call. Obtain this handle by calling MprAdminServerConnect.
hInterface
[in] Handle to the interface. Obtain this handle from a previous call to MprAdminInterfaceCreate, or by calling MprAdminInterfaceEnum.
dwIndex
[in] Specifies the one-based index of the device. A multi-linked demand-dial interface uses multiple devices.
dwLevel
[in] Specifies the level of the information pointed to by the lplpBuffer parameter.
lplpBuffer
[in] Pointer to an MPR_DEVICE_0 or MPR_DEVICE_1 structure that receives the information about the device. The dwLevel parameter specifies the type of structure.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
ERROR_INVALID_HANDLE | The hInterface value is invalid.
ERROR_INVALID_PARAMETER | The lplpbBuffer parameter is NULL.
ERROR_NOT_ENOUGH_MEMORY | Insufficient resources to complete the operation.
ERROR_NOT_SUPPORTED | The dwLevel value is invalid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

MPR_DEVICE_0, MPR_DEVICE_1, MprAdminInterfaceCreate, MprAdminInterfaceDeviceGetInfo


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
[in] Handle to the Windows 2000 router on which to execute this call. Obtain this handle by calling MprAdminServerConnect.
hInterface
[in] Handle to the interface. This handle is obtained from a previous call to MprAdminInterfaceCreate.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
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.

Router Management Reference, Router Administration Functions, MprAdminInterfaceCreate, MprAdminInterfaceConnect, MprAdminServerConnect

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.


MprAdminInterfaceEnum

[This is preliminary documentation and subject to change.]

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 information structures
  DWORD dwPrefMaxLen,            // maximum length of data to return
  LPDWORD lpdwEntriesRead,        // number of interfaces enumerated
  LPDWORD lpdwTotalEntries,       // number of interfaces that could
                                 // have been enumerated
  LPDWORD lpdwResumeHandle       // handle for continuing
                                 // the enumeration
);

Parameters

hMprServer
[in] Handle to the Windows 2000 router on which to execute this call. Obtain this handle by calling MprAdminServerConnect.
dwLevel
[in]Specifies the level of information passed in lpBuffer. Must be zero.
lplpbBuffer
[out] Pointer to a pointer variable that points to an array of MPR_INTERFACE_0 structures on successful return. This memory should be freed by the MprAdminBufferFree call.
dwPrefMaxLen
[in] Specifies the preferred maximum length of returned data (in 8-bit bytes). If this parameter is -1, the buffer returned is large enough to hold all available information.
lpdwEntriesRead
[out] Pointer to a DWORD variable. This variable receives the total number of interfaces that were enumerated from the current position in the enumeration.
lpdwTotalEntries
[out] Pointer to a DWORD variable. This variable receives the total number of interfaces that could have been enumerated from the current resume position.
lpdwResumeHandle
[in] Pointer to a DWORD variable. This variable specifies 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 using 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 calling application specifies NULL for this parameter, the function will not return a resume handle.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
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 invalid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, MPR_INTERFACE_1, MprAdminBufferFree, MprAdminServerConnect


MprAdminInterfaceGetCredentials

Use the MprAdminInterfaceGetCredentials function to retrieve the domain, user name, 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 user name
  LPWSTR lpwsPassword,         // string to receive password
  LPWSTR lpwsDomainName        // string to receive domain name
);

Parameters

lpwsServer
[in] Pointer to a Unicode string that specifies the name of the Windows 2000 router on which to execute this call.

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

lpwsInterfaceName
[in] Pointer to a Unicode string that specifies the name of the demand-dial interface. Use MprAdminInterfaceGetInfo to obtain the interface name.
lpwsUserName
[out] Pointer to a Unicode string that receives the name of the user. This string should be UNLEN+1 long.

This parameter is optional. If the calling application specifies NULL for this parameter, the function does not return the user name.

lpwsPassword
[out] Pointer to a Unicode string that receives the password. This string should be PWLEN+1 long.

This parameter is optional. If the calling application specifies NULL for this parameter, the function does not return the password.

lpwsDomainName
[out] Pointer to a Unicode string that receives the domain name. This string should be DNLEN+1 long.

This parameter is optional. If the calling application specifies NULL for this parameter, the function does not return the domain name.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY | The specified interface does not have any demand-dial parameters associated with it.
ERROR_INVALID_PARAMETER At least one of the following is true:
  • The lpwsInterfaceName parameter is NULL.
  • The lpwsUserName, lpwsPassword, and lpwsDomainName parameters are all NULL.
Other | Use FormatMessage to retrieve the system error message that corresponds to the error code returned.

Remarks

The lpwsUserName, lpwsPassword, and lpwsDomainName parameters are optional. However, if the calling application specifies NULL for all three parameters, MprAdminInterfaceGetCredentials returns ERROR_INVALID_PARAMETER.

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

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, FormatMessage, MprAdminInterfaceSetCredentials


MprAdminInterfaceGetCredentialsEx

Use the MprAdminInterfaceGetCredentialsEx function to retrieve extended credentials information for the specified interface. Use this function to retrieve credentials information used for Extensible Authentication Protocols (EAPs).

DWORD MprAdminInterfaceGetCredentialsEx(
  MPR_SERVER_HANDLE hMprServer,  // handle to router
  HANDLE hInterface,             // handle to interface
  DWORD dwLevel,                 // format of credentials
  LPBYTE *lplpbBuffer            // retrieved credentials
);

Parameters

hMprServer
[in] Handle to a Windows 2000 router. This handle is obtained from a previous call to MprAdminServerConnect.
hInterface
[in] Handle to the interface. This handle is obtained from a previous call to MprAdminInterfaceCreate.
dwLevel
[in] Specifies the format of credentials information retrieved. This parameter must be zero, which indicates that the information is formatted as an MPR_CREDENTIALSEX_0 structure.

Whistler or later: This parameter is zero or one. A value of one indicates that the information is a pre-shared key, and is formatted as an MPR_CREDENTIALSEX_1 structure.

lplpbBuffer
[in] Pointer to a pointer to an MPR_CREDENTIALSEX_0 structure that contains the extended credentials information. Free the memory occupied by this structure with MprAdminBufferFree.

Whistler or later: If the dwLevel parameter specifies one, this parameter is a pointer to a pointer to MPR_CREDENTIALSEX_1 structure that contains the pre-shared key for the interface.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
ERROR_INVALID_HANDLE | The hInterface value is invalid.
ERROR_INVALID_PARAMETER | The lplpbBuffer parameter is NULL.
ERROR_NOT_ENOUGH_MEMORY | Insufficient resources to complete the operation.
ERROR_NOT_SUPPORTED | The dwLevel value is invalid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

MprAdminInterfaceCreate, MprAdminInterfaceGetCredentials, MprAdminInterfaceSetCredentialsEx, MprAdminServerConnect


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
[in] Handle to the Windows 2000 router on which to execute this call. Obtain this handle by calling MprAdminServerConnect.
lpwsInterfaceName
[in] Pointer to a Unicode string that specifies the name of the interface to be retrieved.
phInterface
[out] Pointer to a HANDLE variable that receives a handle to the interface specified by lpwsInterfaceName.
fIncludeClientInterfaces
[in] Specifies whether the function returns a client interface. If this parameter is FALSE, interfaces of type ROUTER_IF_TYPE_CLIENT are ignored in the search for the interface with the name specified by lpwsInterfaceName. If this parameter is TRUE and an interface with the specified name exists, MprAdminInterfaceGetHandle returns a handle to an interface of type ROUTER_IF_TYPE_CLIENT. Since it is possible that there are several interfaces of type ROUTER_IF_TYPE_CLIENT, the handle returned references the first interface found with the name specified by lpwsInterfaceName.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
ERROR_INVALID_PARAMETER | lpwsInterfaceName is NULL.
ERROR_NO_SUCH_INTERFACE | No interface exists with the name specified by lpwsInterfaceName.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, 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
[in] Handle to the Windows 2000 router to query. This handle is obtained from a previous call to MprAdminServerConnect.
hInterface
[in] Handle to the interface obtained by a previous call to MprAdminInterfaceCreate.
dwLevel
[in] Specifies the type of structure returned through the lplpbBuffer parameter. Must be zero, indicating that the lpBuffer parameter points to an MPR_INTERFACE_0 structure.

Windows 2000 and later: Must have a value of zero, one or two. A value of one indicates that the lpBuffer parameter points to an MPR_INTERFACE_1 structure. A value of two indicates that the lpBuffer parameter points to an MPR_INTERFACE_2 structure.

lplpbBuffer
[in] Pointer to a pointer variable. This variable will point to an MPR_INTERFACE_0 structure. Free this memory by calling MprAdminBufferFree.

Windows 2000 and later: The pointer variable may point to an MPR_INTERFACE_0, MPR_INTERFACE_1, or MPR_INTERFACE_2 structure. The type of the structure should be indicated by the value of the dwLevel parameter.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
ERROR_INVALID_HANDLE | The hInterface value is invalid.
ERROR_INVALID_PARAMETER | The lplpbBuffer parameter is NULL.
ERROR_NOT_ENOUGH_MEMORY | Insufficient resources to complete the operation.
ERROR_NOT_SUPPORTED | The dwLevel value is invalid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, MPR_INTERFACE_0, MPR_INTERFACE_1, MPR_INTERFACE_2, 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
[in] Handle to the Windows 2000 router on which to execute this call. Obtain this handle by calling MprAdminServerConnect.
hInterface
[in] Handle to the interface. This handle is obtained from a previous call to MprAdminInterfaceCreate.
dwTransportId
[in] Specifies the DWORD variable that contains the transport identifier. This parameter identifies the router manager that updated its routing information.
lpdwUpdateResult
[out] Pointer to a DWORD variable. This variable receives the result of the last call to MprAdminInterfaceUpdateRoutes.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
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 2000 router maintains a router manager for each transport.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, MprAdminInterfaceCreate, MprAdminInterfaceUpdateRoutes, MprAdminServerConnect


MprAdminInterfaceSetCredentials

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

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

Parameters

lpwsServer
[in] Pointer to a Unicode string that specifies the name of the Windows 2000 router on which to execute this call.

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

lpwsInterfaceName
[in] Pointer to a Unicode string that specifies the name of the demand-dial interface. Use MprAdminInterfaceGetInfo to obtain the interface name.
lpwsUserName
[in] Pointer to a Unicode string that specifies the user name.

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

lpwsDomainName
[in] Pointer to a Unicode string that specifies the domain name.

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

lpwsPassword
[in] Pointer to a Unicode string that specifies the password.

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

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
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 is too long, and therefore invalid. See the 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 that corresponds to the error code returned.

Remarks

The lpwsUserName, lpwsPassword, and lpwsDomainName parameters are optional. If the calling application specifies NULL for all three parameters, MprAdminInterfaceSetCredentials removes all credential information for this interface.

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

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, FormatMessage, MprAdminInterfaceGetCredentials, MprAdminInterfaceGetInfo


MprAdminInterfaceSetCredentialsEx

Use the MprAdminInterfaceSetCredentialsEx function to set extended credentials information for an interface. Use this function to set credentials information used for Extensible Authentication Protocols (EAPs).

DWORD MprAdminInterfaceSetCredentialsEx(
  MPR_SERVER_HANDLE hMprServer,  // handle to router
  HANDLE hInterface,             // handle to interface
  DWORD dwLevel,                 // format of credentials
  LPBYTE lpbBuffer               // new credentials
);

Parameters

hMprServer
[in] Handle to a Windows 2000 router. This handle is obtained from a previous call to MprAdminServerConnect.
hInterface
[in] Handle to the interface. This handle is obtained from a previous call to MprAdminInterfaceCreate.
dwLevel
[in] Specifies the format of the credentials information. This parameter must be zero, which indicates that the information is formatted as an MPR_CREDENTIALSEX_0 structure.

Whistler or later: This parameter is zero or one. A value of one indicates that the credentials information is a pre-shared key, and is formatted as an MPR_CREDENTIALSEX_1 structure.

lpbBuffer
[in] Pointer to an MPR_CREDENTIALSEX_0 structure that specifies the new extended credentials information for the interface.

Whistler or later: If the dwLevel parameter is one, pointer to an MPR_CREDENTIALSEX_1 structure that contains the pre-shared key to set for the interface.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
ERROR_INVALID_HANDLE | The hInterface value is invalid.
ERROR_INVALID_PARAMETER | The lplpbBuffer parameter is NULL.
ERROR_NOT_ENOUGH_MEMORY | Insufficient resources to complete the operation.
ERROR_NOT_SUPPORTED | The dwLevel value is invalid.

Remarks

To a delete a pre-shared key, call MprAdminInterfaceSetCredentials with the MPR_CREDENTIALSEX_1.dwSize member set to zero.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

MprAdminInterfaceCreate, MprAdminInterfaceSetCredentials, MprAdminInterfaceSetCredentialsEx, MprAdminServerConnect


MprAdminInterfaceSetInfo

The MprAdminInterfaceSetInfo function sets information for a specified interface on a specified server.

DWORD MprAdminInterfaceSetInfo(
  MPR_SERVER_HANDLE hMprServer,  // handle to router
  HANDLE hInterface,             // handle to interface
  DWORD dwLevel,                 // level of information
  LPBYTE lpbBuffer               // buffer of information
);

Parameters

hMprServer
[in] Handle to the Windows 2000 router to query. This handle is obtained from a previous call to MprAdminServerConnect.
hInterface
[in] Handle to the interface obtained by a previous call to MprAdminInterfaceCreate.
dwLevel
[in] Specifies the type of structure returned through the lplpbBuffer parameter. Must be zero, one, or two.
lpbBuffer
[in] Pointer to an MPR_INTERFACE_0, MPR_INTERFACE_1, or MPR_INTERFACE_2 structure. The dwLevel parameter indicates the type of structure.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
ERROR_INVALID_HANDLE | The hInterface value is invalid.
ERROR_INVALID_PARAMETER | The lplpbBuffer parameter is NULL.
ERROR_NOT_ENOUGH_MEMORY | Insufficient resources to complete the operation.
ERROR_NOT_SUPPORTED | The dwLevel value is invalid.

Remarks

Windows 2000 and later: The MprAdminInterfaceSetInfo function supports the MPR_INTERFACE_2 structure. However, MprConfigInterfaceSetInfo does not. In order to make persistent changes to a demand-dial interface, call MprAdminInterfaceSetInfo with MPR_INTERFACE_2, then call MprConfigInterfaceSetInfo with MPR_INTERFACE_0 or MPR_INTERFACE_1.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, MPR_INTERFACE_0, MPR_INTERFACE_1, MPR_INTERFACE_2, MprAdminBufferFree, MprAdminInterfaceCreate, MprAdminInterfaceGetInfo, MprAdminServerConnect


MprAdminInterfaceTransportAdd

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

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

Parameters

hMprServer
[in] Handle to the Windows 2000 router on which to execute this call. Obtain this handle by calling MprAdminServerConnect.
hInterface
[in] Handle to the interface on which to add the transport. This handle is obtained by a previous call to MprAdminInterfaceCreate.
dwTransportId
[in] Specifies the transport to add to the interface.
pInterfaceInfo
[in] Pointer to an information header that specifies interface information for this transport. Use the Information Header Functions to manipulate information headers.
dwInterfaceInfoSize
[in] Specifies the size, in bytes, of the information pointed to by pInterfaceInfo.

Remarks

The dwTransportId parameter also specifies the router manager because a Windows 2000 router uses a different router manager for each transport.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, MprAdminInterfaceCreate, MprAdminInterfaceTransportRemove, MprAdminServerConnect


MprAdminInterfaceTransportGetInfo

The MprAdminInterfaceTransportGetInfo function retrieves information about a transport running on a 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
[in] Handle to the Windows 2000 router on which to execute this call. Obtain this handle by calling MprAdminServerConnect.
hInterface
[in] Handle to the interface. This handle is obtained from a previous call to MprAdminInterfaceCreate.
dwTransportId
[in] Specifies the transport/router manager for which information is requested.
ppInterfaceInfo
[out] Pointer to a pointer variable. The pointer variable points to an information header that receives information for the specified interface and transport. Use the Information Header Functions to manipulate information headers.
lpdwInterfaceInfoSize
[out] Pointer to a DWORD variable. This variable receives the size in bytes of the interface information returned through the ppInterfaceInfo parameter.

This parameter is optional. If the calling application specifies NULL for this parameter, the function does not return the size of the interface information.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
ERROR_INVALID_HANDLE | The hInterface value is invalid, or if the interface specified is administratively disabled.
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 or router manager.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, MprAdminInterfaceCreate, MprAdminInterfaceTransportSetInfo, MprAdminServerConnect


MprAdminInterfaceTransportRemove

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

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

Parameters

hMprServer
[in] Handle to the Windows 2000 router on which to execute this call. Obtain this handle by calling MprAdminServerConnect.
hInterface
[in] Handle to the interface from which to remove the transport. Obtain this handle by calling MprAdminInterfaceCreate.
dwTransportId
[in] Specifies the transport to remove from the interface.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
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

The dwTransportId parameter specifies a router manager because a Windows 2000 router uses a different router manager for each routable transport.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, MprAdminInterfaceCreate, MprAdminInterfaceTransportAdd, MprAdminServerConnect


MprAdminInterfaceTransportSetInfo

The MprAdminInterfaceTransportSetInfo function sets information for a transport running on a 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
[in] Handle to the Windows 2000 router on which to execute this call. Obtain the handle by calling MprAdminServerConnect.
hInterface
[in] Handle to the interface. Obtain this handle by calling MprAdminInterfaceCreate.
dwTransportId
[in] Specifies the transport for which information is set.
pInterfaceInfo
[in] Pointer to an information header that contains information for the specified interface and transport. Use the Information Header Functions to manipulate information headers.
dwInterfaceInfoSize
[in] Specifies the size, in bytes, of the information pointed to by pInterfaceInfo.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, MprAdminInterfaceCreate, MprAdminInterfaceTransportGetInfo, MprAdminServerConnect


MprAdminInterfaceUpdatePhonebookInfo

The MprAdminInterfaceUpdatePhonebookInfo function forces the router to pick up changes made on a specified demand-dial interface. Call this function after making changes to a phone-book entry for a demand-dial interface.

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

Parameters

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

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
ERROR_CANNOT_LOAD_PHONEBOOK | The function could not load the phone book into memory.
ERROR_CANNOT_OPEN_PHONEBOOK | The function could not find the phone-book 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 complete the operation.
Other | Use FormatMessage to retrieve the system error message that corresponds to the error code returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, FormatMessage, MprAdminInterfaceCreate, MprAdminServerConnect


MprAdminInterfaceUpdateRoutes

The MprAdminInterfaceUpdateRoutes function requests a specified router manager to 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
[in] Handle to the Windows 2000 router on which to execute this call. Obtain this handle by calling MprAdminServerConnect.
hInterface
[in] Handle to the interface. Obtain this handle by calling MprAdminInterfaceCreate.
dwTransportId
[in] Specifies the router manager that is to update its routing information. Windows 2000 router uses a different router manager for each transport.
hEvent
[in] Handle to an event that is signaled when the attempt to update routing information for the specified interface has completed. If NULL, then the function is synchronous. The calling application must specify NULL for this parameter, if hMprServer specifies a remote router.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
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 calling application 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 because Windows 2000 router uses a different router manager for each transport.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, MprAdminInterfaceCreate, MprAdminInterfaceQueryUpdateResult, MprAdminServerConnect


MprAdminIsServiceRunning

The MprAdminIsServiceRunning function checks whetherRRAS is running on a specified machine. If not, none of the router administration function calls will succeed.

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

Parameters

lpwsServerName
[in] Pointer to a Unicode string that specifies the name of the server to query.

Return Values

The return value is one of the following boolean values.

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions


MprAdminRegisterConnectionNotification

The MprAdminRegisterConnectionNotification function registers an event object with the Demand Dial Manager (DDM) so that, if an interface connects or disconnects, the event is signaled.

DWORD MprAdminRegisterConnectionNotification(
  MPR_SERVER_HANDLE hMprServer,  // handle to server
  HANDLE hEventNotification      // handle to event
);

Parameters

hMprServer
[in] Handle to the Windows 2000 router on which to execute this call. Obtain this handle by calling MprAdminServerConnect.
hEventNotification
[in] Handle to an event object. This event is signaled whenever an interface connects or disconnects.

Return Values

If the function is successful, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
ERROR_DDM_NOT_RUNNING | The Demand Dial Manager (DDM) is not running.
ERROR_INVALID_PARAMETER | The hEventNotification parameter is NULL or is an invalid handle.
Other | Use FormatMessage to retrieve the system error message that corresponds to the error code returned.

Remarks

The event is signaled when an interface connects or disconnects. When an event is signaled, the calling application can determine which interface is affected by using a function such as MprAdminConnectionEnum or MprAdminInterfaceEnum.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, FormatMessage, MprAdminConnectionEnum, MprAdminDeregisterConnectionNotification, MprAdminInterfaceEnum


MprAdminServerConnect

The MprAdminServerConnect function establishes a connection to a Windows 2000 router for the purpose of administering that router. 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
[in] Pointer to a Unicode string that specifies the name of the remote server.
phMprServer
[out] Pointer to a HANDLE variable that receives a handle to the server. Use this handle in subsequent calls to administer the server.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privilege.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, 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
[in] Handle to the Windows 2000 router from which to disconnect. Obtain this handle by calling MprAdminServerConnect.

Return Values

None.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, MprAdminServerConnect


MprAdminServerGetCredentials

[This is preliminary documentation and subject to change.]

The MprAdminServerGetCredentials function retrieves the pre-shared key for the specified server.

DWORD MprAdminServerGetCredentials(
    MPR_SERVER_HANDLE    hMprServer,
    DWORD                dwLevel,
    LPBYTE *             lplpbBuffer
);

Parameters

hMprServer
[in] Handle to a Windows server. Obtain this handle by calling MprAdminMIBServerConnect.
dwLeve
[in] This parameter must be zero.
lplpbBuffer
[out] Pointer to a pointer that, on successful return, points to a MPR_CREDENTIALSEX_1 structure that contains the pre-shared key for the server. Free the memory occupied by this structure with MprAdminBufferFree.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
ERROR_INVALID_PARAMETER | The lplpbBuffer parameter is NULL, or the dwLevel parameter is not zero..
Other |  | Use FormatMessage to retrieve the system error message that corresponds to the error code returned.

Remarks

The server maintains a single pre-shared key for all users.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, MprAdminServerSetCredentials, MPR_CREDENTIALSEX_1


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
[in] Handle to the Windows 2000 router to query. Obtain this handle by calling MprAdminMIBServerConnect.
dwLevel
[in] Specifies the level of the information returned in lplpbBuffer. Must be zero.
lplpbBuffer
[out] Pointer to a pointer variable. On successful return, this pointer variable points to an MPR_SERVER_0 structure. Free this memory by calling MprAdminBufferFree.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
ERROR_INVALID_PARAMETER | The lplpbBuffer parameter is NULL.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, MprAdminBufferFree, MPR_SERVER_0, MprAdminServerConnect


MprAdminServerSetCredentials

[This is preliminary documentation and subject to change.]

The MprAdminServerSetCredentials functions sets the pre-shared key for the specified server.

DWORD MprAdminServerSetCredentials(
  MPR_SERVER_HANDLE hMprServer,
  DWORD dwLevel,
  LPBYTE lpbBuffer
);

Parameters

hMprServer
[in] Handle to a Windows server. Obtain this handle by calling MprAdminMIBServerConnect.
dwLevel
[in] This parameter must be zero.
lpbBuffer
[out] Pointer to a MPR_CREDENTIALSEX_1 structure that contains the pre-shared key for the server.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
ERROR_INVALID_PARAMETER | The lpbBuffer parameter is NULL, or the dwLevel parameter is not zero.
Other | Use FormatMessage to retrieve the system error message that corresponds to the error code returned.

Remarks

The server maintains a single pre-shared key for all users.

To delete the pre-shared key, call MprAdminServerSetCredentials with the MPR_CREDENTIALSEX_1.dwSize member set to zero.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, MprAdminServerGetCredentials, MPR_CREDENTIALSEX_1


MprAdminTransportCreate

The MprAdminTransportCreate function loads a new transport, and starts the router manager for the transport.

DWORD MprAdminTransportCreate(
  MPR_SERVER_HANDLE hMprServer,
  DWORD dwTransportId,
  LPWSTR lpwsTransportName,
  LPBYTE pGlobalInfo,
  DWORD dwGlobalInfoSize,
  LPBYTE pClientInterfaceInfo,
  DWORD dwClientInterfaceInfoSize,
  LPWSTR lpwsDLLPath
);

Parameters

hMprServer
[in] Handle to the Windows 2000 router on which to set the information. Obtain this handle by calling MprAdminServerConnect.
dwTransportId
[in] Specifies the transport for which to set information.
lpwsTransportName
[in] Pointer to a null-terminated Unicode string that specifies the name of the transport.
pGlobalInfo
[in] Pointer to a buffer that specifies global information for the transport. Use the Information Header Functions to manipulate information headers.

This parameter is optional. If the calling application specifies NULL for this parameter, the function does not set the global information.

dwGlobalInfoSize
[in] Specifies the size, in bytes, of the buffer pointed to by the pGlobalInfo parameter.
pClientInterfaceInfo
[in] Pointer to a buffer that specifies default client interface information for the transport.

This parameter is optional. If the calling application specifies NULL for this parameter, the function does not set the default client interface information.

dwClientInterfaceInfoSize
[in] Specifies the size, in bytes, of the buffer pointed to by the pClientInterfaceInfo parameter.
lpwsDLLPath
[in] Pointer to a null-terminated Unicode string that specifies the path to the DLL for the transport.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
ERROR_INVALID_PARAMETER | The pGlobalInfo parameter and the pClientInterfaceInfo parameter are both NULL.
ERROR_NOT_ENOUGH_MEMORY | Insufficient resources to complete the operation.
ERROR_PROTOCOL_ALREADY_INSTALLED | The specified transport is already running on the specified router.
ERROR_UNKNOWN_PROTOCOL_ID | The dwTransportId value does not match any installed transport.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

MprAdminTransportGetInfo, MprAdminTransportSetInfo


MprAdminTransportGetInfo

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

DWORD 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
[in] Handle to the Windows 2000 router to query. This handle is obtained from a previous call to MprAdminServerConnect.
dwTransportId
[in] Specifies the transport about which to retrieve information.
ppGlobalInfo
[out] Pointer to a pointer variable. This variable points to an information header that receives global information for this transport. Use the Information Header Functions to manipulate information headers.

Free this memory by calling MprAdminBufferFree.

This parameter is optional. If the calling application specifies NULL for this parameter, the function does not retrieve the global information.

lpdwGlobalInfoSize
[out] Pointer to a DWORD variable. This variable receives the size, in bytes, of the global information for the transport.
ppClientInterfaceInfo
[out] Pointer to a pointer variable. This variable points to default client interface information for this transport. Free this memory by calling MprAdminBufferFree.

This parameter is optional. If the calling application specifies NULL for this parameter, the function does not retrieve the client interface information.

lpdwClientInterfaceInfoSize
[out] Pointer to a DWORD variable. This variable receives the size, in bytes, of the client interface information.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
ERROR_INVALID_PARAMETER One of the following is true:
  • The ppGlobalInfo parameter and the ppClientInterfaceInfo parameter are both NULL.
  • The ppGlobalInfo parameter does not point to valid memory.
  • The ppClientInterfaceInfo parameter does not point to valid memory.
ERROR_NOT_ENOUGH_MEMORY | Insufficient resources to complete 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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, MprAdminBufferFree, MprAdminServerConnect, MprAdminTransportSetInfo


MprAdminTransportSetInfo

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

DWORD 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
);

Parameters

hMprServer
[in] Handle to the Windows 2000 router on which to set the information. Obtain this handle by calling MprAdminServerConnect.
dwTransportId
[in] Specifies the transport for which to set information.
pGlobalInfo
{in] Pointer to a buffer that specifies global information for the transport. Use the Information Header Functions to manipulate information headers.

This parameter is optional. If the calling application specifies NULL for this parameter, the function does not set the global information.

dwGlobalInfoSize
[in]Specifies the size, in bytes, of the buffer pointed to by the pGlobalInfo parameter.
pClientInterfaceInfo
[in] Pointer to a buffer that specifies default client interface information for the transport.

This parameter is optional. If the calling application specifies NULL for this parameter, the function does not set the default client interface information.

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

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling application does not have sufficient privileges.
ERROR_INVALID_PARAMETER | The pGlobalInfo parameter and the pClientInterfaceInfo parameter are both NULL.
ERROR_NOT_ENOUGH_MEMORY | Insufficient resources to complete the operation.
ERROR_UNKNOWN_PROTOCOL_ID | The dwTransportId value does not match any installed transport.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Administration Functions, MprAdminServerConnect, MprAdminTransportGetInfo


Router Configuration Functions

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

MprConfigBufferFree

MprConfigGetFriendlyName

MprConfigGetGuidName

MprConfigInterfaceCreate

MprConfigInterfaceDelete

MprConfigInterfaceEnum

MprConfigInterfaceGetHandle

MprConfigInterfaceGetInfo

MprConfigInterfaceSetInfo

MprConfigInterfaceTransportAdd

MprConfigInterfaceTransportEnum

MprConfigInterfaceTransportGetHandle

MprConfigInterfaceTransportGetInfo

MprConfigInterfaceTransportRemove

MprConfigInterfaceTransportSetInfo

MprConfigServerBackup

MprConfigServerConnect

MprConfigServerDisconnect

MprConfigServerGetInfo

MprConfigServerInstall

MprConfigServerRestore

MprConfigTransportCreate

MprConfigTransportDelete

MprConfigTransportEnum

MprConfigTransportGetHandle

MprConfigTransportGetInfo

MprConfigTransportSetInfo


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
[in] Pointer to a memory buffer allocated by a previous call to:

MprConfigXEnum

MprConfigXGetInfo

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

Return Values

If the function succeeds, the return value is NO_ERROR.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, MprConfigInterfaceEnum, MprConfigInterfaceTransportEnum, MprConfigTransportEnum, MprConfigInterfaceGetInfo, MprConfigInterfaceTransportGetInfo, MprConfigServerGetInfo, MprConfigTransportGetInfo


MprConfigGetFriendlyName

The MprConfigGetFriendlyName function returns the friendly name for an interface that corresponds to the specified GUID name.

DWORD MprConfigGetFriendlyName(
  HANDLE hMprConfig,   // handle to router configuration
  PWCHAR pszGuidName,  // GUID name for the interface
  PWCHAR pszBuffer,    // buffer to receive friendly name
  DWORD dwBufferSize   // size of buffer passed in
);

Parameters

hMprConfig
[in] Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
pszGuidName
[in] Pointer to a Unicode string that specifies the GUID name for the interface.
pszBuffer
[out] Pointer to a buffer that receives the friendly name for the interface.
dwBufferSize
[in] Specifies the size, in bytes, of the buffer pointed to by pszBuffer.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_BUFFER_OVERFLOW | The buffer pointed to by pszBuffer is not large enough to hold the returned GUID name.
ERROR_INVALID_PARAMETER | One of the following parameters hMprConfig, pszGuidName, or pszBuffer is NULL.
ERROR_NOT_FOUND | No GUID name was found that corresponds to the specified friendly name.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, MprConfigGetGuidName, MprConfigServerConnect


MprConfigGetGuidName

The MprConfigGetGuidName function returns the GUID name for an interface that corresponds to the specified friendly name.

DWORD MprConfigGetGuidName(
  HANDLE hMprConfig,       // handle to router configuration
  PWCHAR pszFriendlyName,  // friendly name for the interface
  PWCHAR pszBuffer,        // buffer to receive GUID name
  DWORD dwBufferSize       // size of buffer passed in
);

Parameters

hMprConfig
[in] Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
pszFriendlyName
[in] Pointer to a Unicode string that specifies the friendly name for the interface.
pszBuffer
[out] Pointer to a buffer that receives the GUID name for the interface.
dwBufferSize
[in] Specifies the size, in bytes, of the buffer pointed to by pszBuffer.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_BUFFER_OVERFLOW | The buffer pointed to by pszBuffer is not large enough to hold the returned GUID name.
ERROR_INVALID_PARAMETER | At least one of the parameters hMprConfig, pszFriendlyName, or pszBuffer is NULL.
ERROR_NOT_FOUND | No GUID name was found that corresponds to the specified friendly name.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, MprConfigGetFriendlyName, MprConfigServerConnect


MprConfigServerInstall

The MprConfigServerInstall function configures Routing and Remote Access Service with a default configuration.

DWORD MprConfigServerInstall(
  DWORD dwLevel,
  PVOID pBuffer
);

Parameters

dwLevel
[in] This parameter is reserved for future use, and should be zero.
pBuffer
[in] This parameter is reserved for future use, and should be NULL.

Return Values

If the functions succeeds, the return value is ERROR_SUCCESS.

Remarks

The MprConfigServerInstall function performs the following tasks:

  • Resets the current RouterManager and Interface keys.
  • Initializes RAS structures for IP.
  • Sets the router type to include:

    ROUTER_TYPE_RAS

    ROUTER_TYPE_WAN

    ROUTER_TYPE_LAN

  • Sets the error logging level and authorization settings to defaults.
  • Sets the devices for Routing and RAS.
  • Adds the RRAS snapin to the computer management console.
  • Deletes the router phone book.
  • Registers the router in the domain.
  • Writes out the "router is configured" registry key.

The MprConfigServerInstall function does not start Routing and RAS. Nor does it set the service start type for Routing and RAS.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Windows 2000 Registry Layout


MprConfigInterfaceCreate

[This is preliminary documentation and subject to change.]

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
[in] Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
dwLevel
[in] Specifies the level of information requested. This parameter must be zero.

Windows 2000 and later: This parameter may have a value of one. A value of one indicates that the lpbBuffer parameter points to an MPR_INTERFACE_1 structure.

lpbBuffer
[in] Pointer to an MPR_INTERFACE_0 structure.

Windows 2000 and later: This parameter may point to either an MPR_INTERFACE_0 or MPR_INTERFACE_1 structure. The type of structures is indicated by the value of the dwLevel parameter.

phRouterInterface
[out] Pointer to a handle variable. This variable receives a handle to the interface configuration.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER At least one of the following is true:
  • hMprConfig is NULL
  • dwLevel is not zero or one.
  • 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 that corresponds to the error code returned.

Remarks

Windows 2000 and later: The MprAdminInterfaceCreate function supports the MPR_INTERFACE_2 structure. However, MprConfigInterfaceCreate does not. In order to create a demand-dial interface that is persistent after a reboot, call MprAdminInterfaceCreate with MPR_INTERFACE_2, then call MprConfigInterfaceCreate with MPR_INTERFACE_0 or MPR_INTERFACE_1.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, 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
[in] Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
hRouterInterface
[in] Handle to the interface configuration. Obtain this handle by calling MprConfigInterfaceCreate, MprConfigInterfaceGetHandle, or MprConfigInterfaceEnum.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
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 that corresponds to the error code returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, FormatMessage, MprConfigInterfaceCreate, MprConfigInterfaceEnum, MprConfigInterfaceGetHandle, MprConfigServerConnect


MprConfigInterfaceEnum

[This is preliminary documentation and subject to change.]

The MprConfigInterfaceEnum function enumerates the interfaces that are 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
[in] Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
dwLevel
[in] Specifies the level of the information returned through the lplpBuffer parameter. This parameter must be zero.
lplpBuffer
[in, out] On input, Pointer to a pointer variable.

On output, the variable points to an array of MPR_INTERFACE_0 structures. Free this memory by calling MprConfigBufferFree.

dwPrefMaxLen
[in] 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
[out] Pointer to a DWORD variable. This variable receives the total number of entries that were enumerated from the current resume position.
lpdwTotalEntries
[out] Pointer to a DWORD variable. This variable receives the total number of entries that could have been enumerated from the current resume position.
lpdwResumeHandle
[in, out] Pointer to a DWORD variable.

On input, the handle should be zero on the first call, and left unchanged on subsequent calls to continue the enumeration.

On output, contains a resume handle that can be used to continue the enumeration. If the handle is NULL, the enumeration is complete.

If an error occurs in the enumeration, this handle is invalid.

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

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
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 that corresponds to the error code returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, 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
[in] Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
lpwsInterfaceName
[in] Pointer to a Unicode string that specifies the name of the interface for which the configuration handle is requested.
phRouterInterface
[out] Pointer to a handle variable. This variable receives a handle to the interface configuration.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
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 that corresponds to the error code returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, FormatMessage, MprConfigServerConnect


MprConfigInterfaceGetInfo

[This is preliminary documentation and subject to change.]

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
[in] Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
hRouterInterface
[in] Handle to the interface configuration for which to retrieve information. Obtain this handle by calling MprConfigInterfaceCreate, MprConfigInterfaceGetHandle, or MprConfigInterfaceEnum.
dwLevel
[in] Specifies the level of the information returned in the lplpBuffer parameter. This parameter must be zero.

Windows 2000 and later: This parameter may have a value of one. A value of one indicates that the lplpBuffer parameter points to a MPR_INTERFACE_1 structure.

lplpBuffer
[in, out] On input, pointer to a pointer variable.

On output, points to an MPR_INTERFACE_0 structure. Free this buffer by calling MprConfigBufferFree.

Windows 2000 and later: The pointer variable may point to either an MPR_INTERFACE_0 or MPR_INTERFACE_1 structures. The type of structure is indicated by the value of the dwLevel parameter.

lpdwBufferSize
[out] Pointer to a DWORD variable. This variable receives the size, in bytes, of the data returned through lplpBuffer.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER At least one of the following is true:
  • hMprConfig is NULL
  • hRouterInterface is NULL
  • dwLevel is not zero or one.
  • lplpBuffer is NULL
  • lpdwBufferSize is NULL
ERROR_NOT_ENOUGH_MEMORY | Insufficient resources to complete the operation.
ERROR_NO_SUCH_INTERFACE | The interface that corresponds to hRouterInterface is not present in the router configuration.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, MprConfigBufferFree, MprConfigInterfaceCreate, MprConfigInterfaceEnum, MprConfigInterfaceGetHandle, MprConfigServerConnect


MprConfigInterfaceSetInfo

[This is preliminary documentation and subject to change.]

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
[in] Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
hRouterInterface
[in] Handle to the interface configuration being updated. Obtain this handle by calling MprConfigInterfaceCreate, MprConfigInterfaceGetHandle, or MprConfigInterfaceEnum.
dwLevel
[in] Specifies the level of the information in the lpBuffer parameter. This parameter must be zero.

Windows 2000 and later: This parameter may have a value of one. A value of one indicates that the lpBuffer parameter points to an MPR_INTERFACE_1 structure.

lpBuffer
[in] Pointer to a buffer that contains an MPR_INTERFACE_0 structure. The information in this structure is used to update the interface configuration.

Windows 2000 and later: The buffer contains either an MPR_INTERFACE_0 or MPR_INTERFACE_1 structure. The type of the structures is indicated by the value of the dwLevel parameter.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER At least one of the following is true:
  • hMprConfig is NULL.
  • hRouterInterface is NULL.
  • dwLevel is not zero or one.
  • lpBuffer is NULL.
ERROR_NO_SUCH_INTERFACE | The interface that corresponds to hRouterInterface is not present in the router configuration.
Other | Use FormatMessage to retrieve the system error message that corresponds to the error code returned.

Remarks

Windows 2000 and later: The MprAdminInterfaceSetInfo function supports the MPR_INTERFACE_2 structure. However, MprConfigInterfaceSetInfo does not. In order to make persistent changes to a demand-dial interface, call MprAdminInterfaceSetInfo with MPR_INTERFACE_2, then call MprConfigInterfaceSetInfo with MPR_INTERFACE_0 or MPR_INTERFACE_1.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, FormatMessage, MprConfigInterfaceCreate, MprConfigInterfaceEnum, MprConfigInterfaceGetHandle, 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
[in] Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
hRouterInterface
[in] Handle to the interface configuration to which to add the specified transport. Obtain this handle by calling MprConfigInterfaceCreate, MprConfigInterfaceGetHandle, or MprConfigInterfaceEnum.
dwTransportId
Specifies the value that identifies the transport. This parameter also identifies the router manager for the transport.
lpwsTransportName
[in] Pointer to a Unicode string that specifies the name for the transport being added. If this parameter is not specified and the transport is IP or IPX, MprConfigInterfaceTransportAdd uses "IP" or "IPX". If this parameter is not specified and the transport is other than IP or IPX, MprConfigInterfaceTransportAdd converts the dwTransportId parameter into a string and uses that as the transport name.
pInterfaceInfo
[in] Pointer to an information header that contains information for the specified interface and transport. The router manager for the specified transport interprets this information. Use the Information Header Functions to manipulate information headers.
dwInterfaceInfoSize
[in] Specifies the size, in bytes, of the data pointed to by pInterfaceInfo.
phRouterIfTransport
[out] Pointer to a handle variable. This variable receives a handle to the transport configuration for this interface.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
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 that corresponds to the error code returned.

Remarks

In addition to specifying a transport, the dwTransportId parameter also specifies a router manager, because a Windows 2000 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 specified parameter values.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, 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
[in] Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
hRouterInterface
[in] Handle to the interface configuration from which to enumerate the transports. Obtain this handle by calling MprConfigInterfaceCreate, or MprConfigInterfaceEnum.
dwLevel
[in] Specifies the level of the information returned in the lplpBuffer parameter. This parameter must be zero.
lplpBuffer
[in, out] On input, pointer to pointer variable.

On output, points to an array of MPR_IFTRANSPORT_0 structures. This memory should be freed by calling MprConfigBufferFree.

dwPrefMaxLen
[in] 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
[out] Pointer to a DWORD variable. This variable receives the total number of entries that were enumerated from the current resume position.
lpdwTotalEntries
[out] Pointer to a DWORD variable. This variable receives the total number of entries that could have been enumerated from the current resume position.
lpdwResumeHandle
[in, out] Pointer to a DWORD variable.

On input, the handle should be zero on the first call and left unchanged on subsequent calls.

On output, this variable contains a resume handle used to continue the enumeration. If the handle is NULL, the enumeration is complete.

If an error occurs in the enumeration, this handle is invalid.

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

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
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 that corresponds to the error code returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, 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
[in] Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
hRouterInterface
[in] Handle to the interface configuration. Obtain this handle by calling MprConfigInterfaceCreate, MprConfigInterfaceGetHandle, or MprConfigInterfaceEnum.
dwTransportId
[in] Specifies the transport configuration.
phRouterIfTransport
[out] Pointer to a handle variable. This variable receives a handle to the transport configuration for this interface.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
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 that corresponds to the error code returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, FormatMessage, MprConfigInterfaceCreate, MprConfigInterfaceEnum, MprConfigInterfaceGetHandle, MprConfigServerConnect


MprConfigInterfaceTransportGetInfo

The MprConfigInterfaceTransportGetInfo function retrieves the configuration information for the specified client on the specified 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,       // configuration information for interface
                                 // and interface
  LPDWORD lpdwInterfaceInfoSize  // size of interface transport information
);

Parameters

hMprConfig
[in] Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
hRouterInterface
[in] Handle to the interface configuration from which to retrieve the specified client information. Obtain this handle by calling MprConfigInterfaceCreate, MprConfigInterfaceGetHandle, or MprConfigInterfaceEnum.
hRouterIfTransport
[in] Handle to the transport configuration from which to retrieve the specified client information. Obtain this handle by calling MprConfigInterfaceTransportGetHandle or MprConfigInterfaceTransportEnum.
ppInterfaceInfo
[in, out] On input, pointer to a pointer variable.

On output, this pointer variable points to an information header that contains configuration information for the client. Use the Information Header Functions to manipulate information headers. Free this memory by calling MprConfigBufferFree.

This parameter is optional. If the calling application specifies NULL for this parameter, the function does not return the configuration information.

lpdwInterfaceInfoSize
[out] Pointer to a DWORD variable. This variable receives the size, in bytes, of the data pointed to by ppInterfaceInfo.

This parameter is optional; the calling application may specify NULL for this parameter. However, if ppInterfaceInfo is not NULL, this parameter cannot be NULL. For more information, see the Remarks section later in this topic.

Return Values

If the function succeeds, the return value is NO_ERROR. For more information, see the Remarks section later in this topic.

If the function fails, the return value is one of the following error codes.

Value | Meaning
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_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.
ERROR_NOT_ENOUGH_MEMORY | Insufficient resources to complete the operation.
Other | Use FormatMessage to retrieve the system error message that corresponds to the error code returned.

Remarks

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, FormatMessage, MPR_IFTRANSPORT_0, MprConfigBufferFree, MprConfigInterfaceCreate, MprConfigInterfaceEnum, MprConfigInterfaceGetHandle, MprConfigInterfaceTransportEnum, MprConfigInterfaceTransportGetHandle, MprConfigServerConnect


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
[in] Handle to the router configuration. The handle is obtained from a previous call to MprConfigServerConnect.
hRouterInterface
[in] Handle to the interface configuration from which to delete the specified transport. Obtain this handle by calling MprConfigInterfaceCreate, MprConfigInterfaceGetHandle, or MprConfigInterfaceEnum.
hRouterIfTransport
[in] Handle to the interface transport configuration to be deleted. Obtain this handle by calling MprConfigInterfaceTransportAdd, MprConfigInterfaceTransportGetHandle, or MprConfigInterfaceTransportEnum.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
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 that corresponds to the error code returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, FormatMessage, MprConfigInterfaceCreate, MprConfigInterfaceEnum, MprConfigInterfaceGetHandle, MprConfigInterfaceTransportAdd, MprConfigInterfaceTransportEnum, MprConfigInterfaceTransportGetHandle, MprConfigServerConnect


MprConfigInterfaceTransportSetInfo

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

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,      // configuration information for transport
                              // and interface
  DWORD dwInterfaceInfoSize   // size of configuration information
);

Parameters

hMprConfig
[in] Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
hRouterInterface
[in] Handle to the interface configuration in which to update the information. Obtain this handle by calling MprConfigInterfaceCreate or MprConfigInterfaceEnum.
hRouterIfTransport
[in] Handle to the transport configuration in which to update the information for the client. Obtain this handle by calling MprConfigInterfaceTransportGetHandle or MprConfigInterfaceTransportEnum.
pInterfaceInfo
[in] Pointer to an information header that contains configuration information for the client on the specified interface and transport. The router manager for the specified transport interprets this information. Use the Information Header Functions to manipulate information headers.

This parameter is optional. If the calling application specifies NULL for this parameter, the function does not update the configuration information for the client.

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

This parameter is optional; the calling application may specify zero for this parameter. However, if pInterfaceInfo is not NULL, this parameter cannot be zero. For more information, see the Remarks section later in this topic.

Return Values

If the function succeeds, the return value is NO_ERROR. For more information, see the Remarks section later in this topic.

If the function fails, the return value is one of the following error codes.

Value | Meaning
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 that corresponds to the error code returned.

Remarks

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, FormatMessage, MprConfigInterfaceCreate, MprConfigInterfaceEnum, MprConfigInterfaceGetHandle, MprConfigInterfaceTransportEnum, MprConfigInterfaceTransportGetHandle, MprConfigServerConnect


MprConfigServerBackup

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

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

Parameters

hMprConfig
[in] Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
lpwsPath
[in] Pointer to a Unicode string that specifies the path to the directory in which to write the backup files. This path should end with a trailing backslash.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
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 that corresponds to the error code returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, FormatMessage, MprConfigServerConnect, MprConfigServerRestore


MprConfigServerConnect

The MprConfigServerConnect function connects to the Windows 2000 router 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
[in] Pointer to a Unicode string that specifies 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
[out] Pointer to a handle variable. This variable receives a handle to the router configuration.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
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 that corresponds to the error code returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, 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
[in] Handle to a router configuration obtained from a previous call to MprConfigServerConnect.

Return Values

None.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, 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
[in] Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
dwLevel
[in] Specifies the level of the information requested. This parameter must be zero.
lplpBuffer
[out] Pointer to a pointer variable. This variable points to a buffer that receives the retrieved information. Free the memory for this buffer using MprConfigBufferFree.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
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 that corresponds to the error code returned.

Remarks

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, FormatMessage, MPR_SERVER_0, MprConfigBufferFree, MprConfigServerConnect


MprConfigServerRestore

The MprConfigServerRestore function restores the router-manager, interface, and phone-book 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,
[in] Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
lpwsPath
[in] Pointer to a Unicode string that specifies the path to the directory in which to write the backup files. This path should end with a trailing backslash.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
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 that corresponds to the error code returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, FormatMessage, MprConfigServerBackup, MprConfigServerConnect


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
[in] Handle to the router configuration to which to add the transport. Obtain this handle by calling MprConfigServerConnect.
dwTransportId
[in] Specifies the transport to add to the configuration. This parameter also identifies the router manager for the transport.
lpwsTransportName
[in] Pointer to a Unicode string that specifies the name of the transport being added. If this parameter is not specified, the dwTransportId parameter is converted into a string and used as the transport name.
pGlobalInfo
[in] Pointer to an information header that specifies global information for the transport. The router manager for the transport interprets this information. Use the Information Header Functions to manipulate information headers.
dwGlobalInfoSize
[in] Specifies the size, in bytes, of the data pointed to by the pGlobalInfo parameter.
pClientInterfaceInfo
[in] Pointer to an information header that specifies default interface information for client routers. This information is used to configure dynamic interfaces for client routers for this transport. Use the Information Header Functions to manipulate information headers.

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

dwClientInterfaceInfoSize
[in] Specifies the size, in bytes, of the data pointed to by the pClientInterfaceInfo parameter. If the calling application specifies NULL for pClientInterfaceInfo, the calling application should specify zero for this parameter.
lpwsDLLPath
[in] Pointer to a Unicode string that specifies the name of the router manager DLL for the specified transport. If this name is specified, the function sets the DLL path for this transport to this name.

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

phRouterTransport
[out] Pointer to a handle variable. This variable receives a handle to the transport configuration.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
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 that corresponds 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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, 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
[in] Handle to the router configuration from which to remove the transport. Obtain this handle by calling MprConfigServerConnect.
hRouterTransport
[in] Handle to the configuration for the transport being deleted. Obtain this handle by calling MprConfigTransportCreate or MprConfigTransportGetHandle.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
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 that corresponds to the error code returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, 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
[in] Handle to the router configuration for the transports. Obtain this handle by calling MprConfigServerConnect.
dwLevel
[in] Specifies the level of information returned through the lplpBuffer parameter. This parameter must be zero.
lplpBuffer
[in, out] On input, pointer to a pointer variable.

On output, the pointer variable points to an array of MPR_TRANSPORT_0 structures. Free this memory buffer by calling MprConfigBufferFree.

dwPrefMaxLen
[in] 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
[out] Pointer to a DWORD variable. This variable receives the total number of entries that were enumerated from the current resume position.
lpdwTotalEntries
[out] Pointer to a DWORD variable. This variable receives the total number of entries that could have been enumerated from the current resume position.
lpdwResumeHandle
[in, out] Pointer to a DWORD variable.

On input, the handle should be zero on the first call and left unchanged on subsequent calls.

On output, this variable contains a resume handle used to continue the enumeration. If the handle is NULL, the enumeration is complete.

If an error occurs in the enumeration, this handle is invalid.

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

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
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 that corresponds to the error code returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, 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
[in] Handle to the router configuration. The handle is obtained from a previous call to MprConfigServerConnect.
dwTransportId
[in] Specifies the transport for which to retrieve the configuration.
phRouterTransport
[out] Pointer to a handle variable. This variable receives a handle to the specified transport's configuration.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
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 that corresponds to the error code returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, 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
[in] Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
hRouterTransport
[in] Handle to the transport configuration being retrieved. Obtain this handle by calling MprConfigTransportCreate, MprConfigTransportGetHandle, or MprConfigTransportEnum.
ppGlobalInfo
[in, out] On input, pointer to a pointer variable.

On output, this pointer variable points to an information header that contains global information for the transport. Use the Information Header Functions to manipulate information headers. Free this buffer by calling MprConfigBufferFree.

This parameter is optional. If the calling application specifies NULL for this parameter, the function does not retrieve the global information.

lpdwGlobalInfoSize
[out] Pointer to a DWORD variable. This variable receives the size, in bytes, of the buffer returned through the ppGlobalInfo parameter.

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

ppClientInterfaceInfo
[in, out] On input, pointer to a pointer variable.

On output, this pointer points to an information header that contains default interface information for client routers for this transport. Use the Information Header Functions to manipulate information headers. Free the buffer by calling MprConfigBufferFree.

This parameter is optional. If the calling application specifies NULL for this parameter, the function does not retrieve the interface information.

lpdwClientInterfaceInfoSize
[out] Pointer to a DWORD variable. This variable receives the size, in bytes, of the buffer returned through the ppClientInterfaceInfo parameter.

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

lplpwsDLLPath
[in, out] On input, pointer to a pointer to a Unicode string.

On output, the Unicode string receives the name of the router manager DLL for the specified transport.

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

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
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 that corresponds 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 that corresponds to the error code returned.

Remarks

If the pGlobalInfo, pClientInterfaceInfo, and lpwsDLLPath parameters are all NULL, the function does nothing and returns a value of NO_ERROR.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, FormatMessage, Information Header Functions, MprConfigBufferFree, MprConfigServerConnect, MprConfigTransportCreate, MprConfigTransportEnum, MprConfigTransportGetHandle


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
[in] Handle to the router configuration. Obtain this handle by calling MprConfigServerConnect.
hRouterTransport
[in] Handle to the transport configuration being updated. Obtain this handle by calling MprConfigTransportCreate, MprConfigTransportGetHandle, or MprConfigTransportEnum.
pGlobalInfo
[in] Pointer to an information header that specifies global information for the transport. The router manager for the transport interprets this information. Use the Information Header Functions to manipulate information headers.

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

dwGlobalInfoSize
[in] Specifies the size, in bytes, of the data pointed to by pGlobalInfo. If the calling application specifies NULL for pGlobalInfo, the calling application should specify zero for this parameter.
pClientInterfaceInfo
[in] Pointer to an information header that specifies default interface information for client routers. The information is used to configure dynamic interfaces for client routers for this transport. Use the Information Header Functions to manipulate information headers.

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

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

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

Return Values

If the function succeeds, the return value is NO_ERROR. For more information, see the Remarks section later in this topic.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | The hMprConfig parameter is NULL, the hRouterTransport parameter is NULL, or both are NULL.
ERROR_UNKNOWN_PROTOCOL_ID | The transport configuration that corresponds to hRouterTransport was not found in the router configuration.
Other | Use FormatMessage to retrieve the system error message that corresponds to the error code returned.

Remarks

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

MprConfigTransportSetInfo 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 MprConfigTransportSetInfo is unable to set any one of the items, it returns immediately without attempting to set the remaining items.

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

Router Management Reference, Router Configuration Functions, FormatMessage, MprConfigServerConnect, MprConfigTransportCreate, MprConfigTransportEnum, MprConfigTransportGetHandle


Router Management Structures

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

IP_ADAPTER_BINDING_INFO

IP_LOCAL_BINDING

IPX_ADAPTER_BINDING_INFO

MPR_CREDENTIALSEX_0

MPR_CREDENTIALSEX_1

MPR_DEVICE_0

MPR_DEVICE_1

MPR_IFTRANSPORT_0

MPR_INTERFACE_0

MPR_INTERFACE_1

MPR_INTERFACE_2

MPR_SERVER_0

MPR_TRANSPORT_0


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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Router Management Reference, Router Management Structures, 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
Specifies an IP address for the adapter.
Mask
Specifies 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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Router Management Reference, Router Management Structures, IP_ADAPTER_BINDING_INFO


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]
Specifies the network number to which the adapter is bound.
LocalNode[6]
Specifies the node number to which the adapter is bound.
RemoteNode[6]
Specifies the node number of a peer router or client for demand-dial point-to-point connections (for LAN connections this field is set to the broadcast node address, for example, 0xFFFFFFFFFFFF).
MaxPacketSize
Specifies the maximum packet size that can be transmitted over a connection established on the adapter.
LinkSpeed
Specifies the speed of the connection in 100 baud, for example, for 9600 baud connection this value is 96.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Router Management Reference, Router Management Structures, IP_ADAPTER_BINDING_INFO


MPR_CREDENTIALSEX_0

The MPR_CREDENTIALSEX_0 structure contains extended credentials information such as the information used by Extensible Authentication Protocols (EAPs).

typedef struct _MPR_CREDENTIALSEX_0 {
  DWORD    dwSize;                // size of info
  LPBYTE   lpbCredentialsInfo;    // extended credentials info
} MPR_CREDENTIALSEX_0, *PMPR_CREDENTIALSEX_0;

Members

dwSize
Specifies the size of the data pointed to by the lpbCredentialsInfo member.
lpbCredentialsInfo
Pointer to the extended credentials information.

Requirements

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

See Also

MprAdminInterfaceGetCredentialsEx, MprAdminInterfaceSetCredentialsEx


MPR_CREDENTIALSEX_1

[This is preliminary documentation and subject to change.]

The MPR_CREDENTIALSEX_1 structure contains a pre-shared key used by a demand-dial interface.

typedef struct _MPR_CREDENTIALSEX_0 {
  DWORD    dwSize;                // size of info
  LPBYTE   lpbCredentialsInfo;    // extended credentials info
} MPR_CREDENTIALSEX_0, *PMPR_CREDENTIALSEX_0;

Members

dwSize
Specifies the size of the data pointed to by the lpbCredentialsInfo member.
lpbCredentialsInfo
Pointer to the pre-shared key.

Remarks

To a delete a pre-shared key, call MprAdminInterfaceSetCredentials with the MPR_CREDENTIALSEX_1.dwSize member set to zero.

Requirements

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

See Also

MprAdminInterfaceGetCredentialsEx, MprAdminInterfaceSetCredentialsEx


MPR_DEVICE_0

[This is preliminary documentation and subject to change.]

The MPR_DEVICE_0 structure stores information about a device used for a link in a multi-linked demand dial interface.

typedef struct _MPR_DEVICE_0 {
  WCHAR    szDeviceType[ MPR_MaxDeviceType + 1 ];
  WCHAR    szDeviceName[ MPR_MaxDeviceName + 1 ];
} MPR_DEVICE_0, *PMPR_DEVICE_0;

Members

szDeviceType
Specifies a null-terminated string that indicates the RAS device type referenced by szDeviceName. See MPR_INTERFACE_2 for a list of possible device types.
szDeviceName
Specifies a null-terminated string that contains the name of the TAPI device to use with this phone-book entry.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Mprapi.h.

See Also

MPR_DEVICE_1, MprAdminInterfaceDeviceGetInfo, MprAdminInterfaceDeviceSetInfo


MPR_DEVICE_1

[This is preliminary documentation and subject to change.]

The MPR_DEVICE_1 structure stores information about a device used for a link in a multi-linked demand dial interface. In addition to the information in MPR_DEVICE_0, MPR_DEVICE_1 contains phone-number information.

typedef struct _MPR_DEVICE_1 {
  WCHAR    szDeviceType[ MPR_MaxDeviceType + 1 ];
  WCHAR    szDeviceName[ MPR_MaxDeviceName + 1 ];
  WCHAR    szLocalPhoneNumber[ MPR_MaxPhoneNumber + 1 ];
  PWCHAR   szAlternates;
} MPR_DEVICE_1, *PMPR_DEVICE_1;

Members

szDeviceType
Specifies a null-terminated string that indicates the device type referenced by szDeviceName. See MPR_INTERFACE_2 for a list of possible device types.
szDeviceName
Specifies a null-terminated string that contains the name of the TAPI device to use with this phone-book entry.
szLocalPhoneNumber
Specifies a null-terminated Unicode string that contains a telephone number. The router uses the szLocalPhoneNumber string as the entire phone number.
szAlternates
Pointer to a list of consecutive null-terminated Unicode strings. The last string is terminated by two consecutive null characters. The strings are alternate phone numbers that the router dials in the order listed if the primary number (see szLocalPhoneNumber) fails to connect.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Mprapi.h.

See Also

MPR_DEVICE_0, MprAdminInterfaceDeviceGetInfo, MprAdminInterfaceDeviceSetInfo


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
Identifies the transport.
hIfTransport
Handle to the interface transport.
wszIfTransportName
Specifies a Unicode string that contains the name of the interface transport.

Requirements

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

See Also

Router Management Reference, Router Management Structures, MPR_TRANSPORT_0, MprConfigInterfaceTransportEnum


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
Specifies whether the interface is enabled. This member is TRUE if the interface is enabled, FALSE if the interface is administratively disabled.
IfType
Specifies the type of interface.
dwConnectionState
Specifies the current state of the interface, for example connected, disconnected, or unreachable. For a list of possible states, see ROUTER_CONNECTION_STATE.
fUnReachabilityReasons
Specifies a value that represents a reason why the interface cannot be reached. See Unreachability Reasons for a list of possible values.
dwLastError
Specifies a nonzero value if the interface fails to connect.

Requirements

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

See Also

Router Management Reference, Router Management Structures, MprAdminInterfaceEnum, MprAdminInterfaceGetInfo, ROUTER_CONNECTION_STATE, ROUTER_INTERFACE_TYPE, Unreachability Reasons


MPR_INTERFACE_1

The MPR_INTERFACE_1 structure contains information for a particular router interface.

typedef struct _MPR_INTERFACE_1 {
  WCHAR                  wszInterfaceName[MAX_INTERFACE_NAME_LEN+1];
  HANDLE                     hInterface;
  BOOL                       fEnabled;
  ROUTER_INTERFACE_TYPE      IfType;
  ROUTER_CONNECTION_STATE    dwConnectionState;
  DWORD                      fUnReachabilityReasons;
  DWORD                      dwLastError;
  LPWSTR                     lpwsDialoutHoursRestriction;
} MPR_INTERFACE_1, * PMPR_INTERFACE_1;

Members

wszInterfaceName
Pointer to a Unicode string that contains the name of the interface.
hInterface
Handle to the interface.
fEnabled
Specifies whether the interface is enabled. This value is TRUE if the interface is enabled, FALSE if the interface is administratively disabled.
IfType
Specifies the type of interface.
dwConnectionState
Specifies the current state of the interface, for example connected, disconnected, or unreachable. For a list of possible states, see ROUTER_CONNECTION_STATE.
fUnReachabilityReasons
Specifies a value that represents a reason why the interface was unreachable. See Unreachability Reasons for a list of possible values.
dwLastError
Specifies a nonzero value if the interface fails to connect.
lpwsDialoutHoursRestriction
Pointer to a Unicode string that specifies the times during which dial-out is restricted. The format for this string is:
<day><space><time range><space><time range> . . . <NULL><day>. . . <NULL><NULL>

Where day is a numeral that corresponds to a day of the week.
Numeral | Day
0 | Sunday
1 | Monday
2 | Tuesday
3 | Wednesday
4 | Thursday
5 | Friday
6 | Saturday

Time range is of the form HH:MM-HH:MM, using 24-hour notation.

The string <space> in the preceding syntax denotes a space character. The string <NULL> denotes a null character.

The restriction string is terminated by two consecutive null characters.

Example:

2 09:00-12:00 13:00-17:30<NULL>4 09:00-12:00 13:00-17:30<NULL><NULL>

The preceding string restricts dial-out to Tuesdays and Thursdays from 9:00 AM to 12:00 PM and from 1:00 PM to 5:30 PM.

Requirements

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

See Also

Router Management Reference, Router Management Structures, MprAdminInterfaceCreate, MprAdminInterfaceEnum, MprAdminInterfaceGetInfo, ROUTER_CONNECTION_STATE, ROUTER_INTERFACE_TYPE, Unreachability Reasons


MPR_INTERFACE_2

[This is preliminary documentation and subject to change.]

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

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

Members

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

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

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

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

Setting the MPRIO_SpecificNameServers flag corresponds to selecting the Specify Name Server Addresses setting in the TCP/IP Settings dialog box. Clearing the MPRIO_SpecificNameServers flag corresponds to selecting the Server Assigned Name Server Addresses setting in the TCP/IP Settings dialog box.
MPRIO_IpHeaderCompression If this flag is set, RRAS negotiates to use IP header compression on PPP connections.

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

This flag corresponds to the Use IP Header Compression check box in the TCP/IP settings dialog box. It is generally advisable to set this flag because IP header compression significantly improves performance. The flag should be cleared only when connecting to a server that does not correctly negotiate IP header compression.
MPRIO_RemoteDefaultGateway If this flag is set, the default route for IP packets is through the dial-up adapter when the connection is active. If this flag is clear, the default route is not modified.

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

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

This flag corresponds to the Require Microsoft Encrypted Password check box in the Security dialog box. See also MPRIO_RequireDataEncryption.
MPRIO_RequireDataEncryption If this flag is set, data encryption must be negotiated successfully or the connection should be dropped. This flag is ignored unless MPRIO_RequireMsEncryptedPw is also set.

This flag corresponds to the Require Data Encryption checkbox in the Security dialog box.
MPRIO_NetworkLogon If this flag is set, RRAS logs on to the network after the point-to-point connection is established.

Windows NT/2000 or later: This flag currently has no effect under Windows NT.
MPRIO_UseLogonCredentials If this flag is set, RRAS uses the user name, password, and domain of the currently logged-on user when dialing this entry. This flag is ignored unless MPRIO_RequireMsEncryptedPw is also set.

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

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

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

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

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

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

Windows 2000 64-bit Edition: The MPRNP_Ipx flag is not supported

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Remarks

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

dwCountryID
dwCountryCode
szAreaCode
dwFramingProtocol

Windows 2000 64-bit Edition: The 64-bit edition of Windows does not support the IPX protocol.

Requirements

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

See Also

MPR_INTERFACE_0, MPR_INTERFACE_1, MprAdminInterfaceGetInfo, MprAdminInterfaceSetInfo


MPR_SERVER_0

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

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

Members

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

Requirements

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

See Also

Router Management Reference, Router Management Structures, MprAdminServerGetInfo, MprConfigServerGetInfo


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
Identifies the transport.
hTransport
Handle to the transport.
wszTransportName
Specifies a Unicode string that contains the name of the transport.

Requirements

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

See Also

Router Management Reference, Router Management Structures, MPR_IFTRANSPORT_0


Router Management Enumerated Types

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

ROUTER_CONNECTION_STATE

ROUTER_INTERFACE_TYPE


ROUTER_CONNECTION_STATE

The ROUTER_CONNECTION_STATE type enumerates the possible states of an interface on a Windows 2000 router.

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. See Unreachability Reasons for a list of possible reasons.
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.

Remarks

These states are sometimes referred to as "operational states."

Requirements

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

See Also

Router Management Reference, Router Management Enumerated Types, MPR_INTERFACE_0, MPR_INTERFACE_1, Unreachability Reasons


ROUTER_INTERFACE_TYPE

The ROUTER_INTERFACE_TYPE type enumerates the different kinds of interfaces on a Windows 2000 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_IF_TYPE_TUNNEL1,
  ROUTER_IF_TYPE_DIALOUT
} 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.
ROUTER_IF_TYPE_TUNNEL1
The interface is a connected over a virtual private network (VPN).
ROUTER_IF_TYPE_DIALOUT
The interface is a dial-on-demand (DOD) interface.

Requirements

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

See Also

Router Management Reference, Router Management Enumerated Types, MPR_INTERFACE_0, MPR_INTERFACE_1, RAS_CONNECTION_2


Unreachability Reasons

The following table lists constant values that indicate why an interface is unreachable.

Value | Meaning
MPR_INTERFACE_ADMIN_DISABLED | The administrator has disabled the interface.
MPR_INTERFACE_CONNECTION_FAILURE | The previous connection attempt failed. Look at the dwLastError member for the error code.
MPR_INTERFACE_DIALOUT_HOURS_RESTRICTION | Dial-out is not allowed at the current time.
MPR_INTERFACE_OUT_OF_RESOURCES | No ports or devices are available for use.
MPR_INTERFACE_SERVICE_PAUSED | The service is paused.
MPR_INTERFACE_NO_MEDIA_SENSE | The network cable is disconnected from the network card.
MPR_INTERFACE_NO_DEVICE | The netword card has been removed from the machine.

See Also

MPR_INTERFACE_0, MPR_INTERFACE_1, MIB_IFROW, MIB_IFSTATUS


Microsoft Challenge Handshake Authentication Protocol

[This is preliminary documentation and subject to change.]

Use the following functions to change user passwords using the Microsoft Challenge-Handshake Authentication Protocol (MS-CHAP).

Function | Description
MSChapSrvChangePassword | Change user password.
MSChapSrvChangePassword2 | Change user password with mutual encryption.


MSChapSrvChangePassword

[This is preliminary documentation and subject to change.]

The MSChapSrvChangePassword function changes the password of a user account.

extern WINADVAPI DWORD WINAPI
MSChapSrvChangePassword(
  LPWSTR ServerName,
  LPWSTR UserName,
  BOOLEAN LmOldPresent,
  PLM_OWF_PASSWORD LmOldOwfPassword,
  PLM_OWF_PASSWORD LmNewOwfPassword,
  PNT_OWF_PASSWORD NtOldOwfPassword,
  PNT_OWF_PASSWORD NtNewOwfPassword
);

Parameters

ServerName
[in] Pointer to a Unicode string that specifies the name of the server on which to operate. If this parameter is NULL, the function operates on the local computer.
UserName
[in] Pointer to a Unicode string that specifies the name of the user whose password to change.
LmOldPresent
[in] Specifies whether the password designated by LmOldOwfPassword is valid. This parameter is FALSE only if the LmOldOwfPassword password is too long to be represented by a LAN Manager (LM) password.
LmOldOwfPassword
[in] Specifies the one-way function (OWF) of the current LAN Manager (LM) password for the user. This parameter is ignored if the LmOldPresent parameter is FALSE.
LmNewOwfPassword
[in] Specifies the one-way function (OWF) of the new LAN Manager (LM) password for the user.
NtOldOwfPassword
[in] Specifies the one-way function (OWF) of the current password for the user.
NtNewOwfPassword
[in] Specifies the one-way function (OWF) of the new password for the user.

Return Values

If the function succeeds, the return value is STATUS_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
STATUS_ACCESS_DENIED | Calling application does not have the appropriate privilege to complete the operation.
STATUS_INVALID_HANDLE | Specified server or user name was not valid.
STATUS_ILL_FORMED_PASSWORD | New password is poorly formed, for example, it contains characters that cannot be entered from the keyboard.
STATUS_PASSWORD_RESTRICTION | A restriction prevents the password from being changed. Possible restrictions include time restrictions on how often a password is allowed to be changed or length restrictions on the provided password. This error is also returned if the new password matched a password in the recent history log for the account. Security administrators specify how many of the most recently used passwords are not available for re-use. These are kept in the password recent history log.
STATUS_WRONG_PASSWORD | The OldPassword parameter does not specify the user's current password.
STATUS_INVALID_DOMAIN_STATE | Domain server is not in an enabled state. The domain server must be enabled for this operation.
STATUS_INVALID_DOMAIN_ROLE | Domain server is serving the incorrect role (primary or backup) to perform the requested operation.
STATUS_INVALID_PARAMETER_MIX | Either the LmOldPresent parameter or NtPresent parameter or both must be TRUE.

Remarks

The value specified by LMNewOwfPassword must always be valid. If the new password is too long to be represented by a LAN Manager (LM) password, then LMNewOwfPassword should be the LM one-way function (OWF) of a NULL password.

This function allows users to change their own passwords if they have the access: USER_CHANGE_PASSWORD.

This function fails with STATUS_PASSWORD_RESTRICTION if the attempt to change the password conflicts with an administrative password restriction.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in MsChapp.h.
Library: Use MsChapp.lib.

See Also

Router Management Reference, Microsoft Challenge Handshake Authentication Protocol, MSChapSrvChangePassword2


MSChapSrvChangePassword2

[This is preliminary documentation and subject to change.]

The MSChapSrvChangePassword function changes the password of a user account while supporting mutual encryption.

extern WINADVAPI DWORD WINAPI
MSChapSrvChangePassword2(
  LPWSTR ServerName,
  LPWSTR UserName,
  PSAMPR_ENCRYPTED_USER_PASSWORD NewPasswordEncryptedWithOldNt,
  PENCRYPTED_NT_OWF_PASSWORD OldNtOwfPasswordEncryptedWithNewNt,
  BOOLEAN LmPresent,
  PSAMPR_ENCRYPTED_USER_PASSWORD NewPasswordEncryptedWithOldLm,
  PENCRYPTED_LM_OWF_PASSWORD OldLmOwfPasswordEncryptedWithNewLmOrNt
);

Parameters

ServerName
[in] Pointer to a Unicode string that specifies the name of the server on which to operate. If this parameter is NULL, the function operates on the local computer.
UserName
[in] Pointer to a Unicode string that specifies the name of the user whose password to change.
NewPasswordEncryptedWithOldNt
[in] Specifies the new cleartext password encrypted with the old NT one-way-function (OWF) password.
OldNtOwfPasswordEncryptedWithNewNt
[in] Specifies the old NT one-way function (OWF) password encrypted with the new NT OWF password.
LmPresent
[in] If TRUE, specifies that the values of the NewPasswordEncryptedWithOldNt and OldNtOwfPasswordEncryptedWithNewNt parameters are encrypted using the LAN Manager (LM) one-way function (OWF) password rather than the NT OWF password.
NewPasswordEncryptedWithOldLm
[in] Specifies the new cleartext password encrypted with the old LAN Manager (LM) one-way-function (OWF) password.
OldLmOwfPasswordEncryptedWithNewLmOrNt
[in] Specifies the old LAN Manager (LM) one-way function (OWF) password encrypted with the new LM OWF password.

Return Values

If the function succeeds, the return value is STATUS_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value | Meaning
STATUS_ACCESS_DENIED | Calling application does not have the appropriate privilege to complete the operation.
STATUS_INVALID_HANDLE | Specified server or user name was not valid.
STATUS_ILL_FORMED_PASSWORD | New password is poorly formed, for example, it contains characters that cannot be entered from the keyboard.
STATUS_PASSWORD_RESTRICTION | A restriction prevents the password from being changed. Possible restrictions include time restrictions on how often a password is allowed to be changed or length restrictions on the provided password. This error is also returned if the new password matched a password in the recent history log for the account. Security administrators specify how many of the most recently used passwords are not available for re-use. These are kept in the password recent history log.
STATUS_WRONG_PASSWORD | The OldPassword parameter does not specify the user's current password.
STATUS_INVALID_DOMAIN_STATE | Domain server is not in an enabled state. The domain server must be enabled for this operation.
STATUS_INVALID_DOMAIN_ROLE | Domain server is serving the incorrect role (primary or backup) to perform the requested operation.

Remarks

This function allows users to change their own passwords if they have the access: USER_CHANGE_PASSWORD.

This function fails with STATUS_PASSWORD_RESTRICTION if the attempt to change the password conflicts with an administrative password restriction.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in MsChapp.h.
Library: Use MsChapp.lib.

See Also

Router Management Reference, Microsoft Challenge Handshake Authentication Protocol, MSChapSrvChangePassword


Information Header Functions

Use the following functions to manipulate router information headers and blocks. An information header is composed of private meta-data and information blocks. Information blocks are arrays of information structures of various types.

The following functions manipulate information headers:

MprInfoCreate

MprInfoDelete

MprInfoDuplicate

MprInfoRemoveAll

The following functions manipulate information blocks within an information header:

MprInfoBlockAdd

MprInfoBlockFind

MprInfoBlockQuerySize

MprInfoBlockRemove

MprInfoBlockSet

Many of the router administration and configuration functions use information headers.


MprInfoBlockAdd

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

DWORD MprInfoBlockAdd(
  LPVOID lpHeader,          // 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 *lplpNewHeader    // new header (incl. new block)
);

Parameters

lpHeader
[in] Pointer to the header in which to add the new block.
dwInfoType
[in] Specifies the type of block to add. The types available depend on the transport: IP or IPX.
dwItemSize
[in] Specifies the size of each item in the block to be added.
dwItemCount
[in] Specifies the number of items of size dwItemSize to be copied as data for the new block.
lpItemData
[in] 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.
lplpNewHeader
[out] 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 is one of the following values.

Value | Description
ERROR_INVALID_PARAMETER | The lpHeader, lplpNewHeader, or lpItemData parameter is NULL, or a block of type dwInfoType already exists in the header.
Other | The call failed. Use FormatMessage to retrieve the error message that corresponds to the returned error code.

Remarks

After adding an information block, obtain the new size of the information header by call MprInfoBlockQuerySize.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

MprInfo Functions and Information Headers, FormatMessage, MprInfoBlockRemove, MprInfoDuplicate, MprInfoBlockQuerySize


MprInfoBlockFind

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

DWORD MprInfoBlockFind(
  LPVOID lpHeader,          // 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

lpHeader
[in] Specifies the header in which to locate the block.
dwInfoType
[in] Specifies the type of block to locate. The types available depend on the transport: IP or IPX.
lpdwItemSize
[out] Pointer to a DWORD variable that receives 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
[out] Pointer to a DWORD variable that receives 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
[out] 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 is one of the following values.

Value | Description
ERROR_INVALID_PARAMETER | The lpInfoHeader parameter 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 that corresponds to the returned error code.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

MprInfo Functions and Information Headers, FormatMessage


MprInfoBlockQuerySize

The MprInfoBlockQuerySize function returns the returns the size of the information header.

DWORD APIENTRY
MprInfoBlockQuerySize(
  LPVOID lpHeader
);

Parameters

lpHeader
[in] Pointer to the information header for which to return the size.

Return Values

MprInfoBlockQuerySize returns the size of the information header.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

MprInfo Functions and Information Headers, MprInfoBlockAdd, MprInfoBlockRemove


MprInfoBlockRemove

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

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

Parameters

lpHeader
[in] Pointer to the header from which the block should be removed.
dwInfoType
[in] Specifies the type of block to be removed. The types available depend on the transport: IP or IPX.
lplpNewHeader
[out] Pointer to a pointer variable that receives the new header.

Return Values

If the function succeeds, the return value is NO_ERROR.

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

Value | Description
ERROR_INVALID_PARAMETER | The lpHeader parameter 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 that corresponds to the returned error code.

Remarks

After removing an information block, obtain the new size of the information header by call MprInfoBlockQuerySize.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

MprInfo Functions and Information Headers, FormatMessage, MprInfoBlockAdd, MprInfoBlockQuerySize


MprInfoBlockSet

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

DWORD MprInfoBlockSet(
  LPVOID lpHeader,          // 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 *lplpNewHeader    // new header (incl. modified block)
);

Parameters

lpHeader
[in] Pointer to the header in which to modify the specified block.
dwInfoType
[in] Specifies the type of block to change. The types available depend on the transport: IP or IPX.
dwItemSize
[in] Specifies the size of each item in the block's new data.
dwItemCount
[in] Specifies the number of items of size dwItemSize to be copied as the new data for the block.
lpItemData
[in] 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.
lplpNewHeader
[out] 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 is 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 that corresponds to the returned error code.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

MprInfo Functions and Information Headers, FormatMessage, MprInfoBlockAdd, MprInfoBlockRemove, MprInfoBlockSet


MprInfoCreate

The MprInfoCreate function creates a new information header.

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

Parameters

dwVersion
[in] Specifies the version of the information header structure to be created. The only value currently supported is RTR_INFO_BLOCK_VERSION, as declared in Mprapi.h.
lplpNewHeader
[out] 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 is one of the following values.

Value | Description
ERROR_INVALID_PARAMETER | The lplpNewHeader parameter 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 that corresponds to the returned error code.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

MprInfo Functions and Information Headers, FormatMessage


MprInfoDelete

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

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

Parameters

lpHeader
[in] 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 is one of the following values.

Value | Description
ERROR_INVALID_PARAMETER | The lpHeader parameter is NULL.
Other | The call failed. Use FormatMessage to retrieve the error message that corresponds to the returned error code.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

MprInfoBlockAdd, MprInfoBlockRemove, MprInfoBlockSet, FormatMessage


MprInfoDuplicate

The MprInfoDuplicate function duplicates an existing information header.

DWORD MprInfoDuplicate(
  LPVOID lpHeader,        // pointer to existing info header
  LPVOID *lplpNewHeader   // pointer to pointer to duplicate
);

Parameters

lpHeader
[in] Pointer to the information header to duplicate.
lplpNewHeader
[out] Pointer to a pointer variable. On successful return, this variable points 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 is one of the following values.

Value | Description
ERROR_INVALID_PARAMETER | The lplpNewHeader parameter 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 that corresponds to the returned error code.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

MprInfo Functions and Information Headers, FormatMessage, MprInfoCreate


MprInfoRemoveAll

The MprInfoRemoveAll function removes all information blocks from the specified header.

DWORD APIENTRY
MprInfoRemoveAll(
  LPVOID lpHeader,
  LPVOID *lplpNewHeader
);

Parameters

lpHeader
[in] Pointer to the information header from which to remove all information blocks.
lplpNewHeader
[out] Pointer to a pointer variable. On successful return, this variable points to the information header with all information blocks removed.

Return Values

If the function succeeds, the return value is NO_ERROR.

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

Value | Description
ERROR_INVALID_PARAMETER | Either the lpHeader parameter is NULL or the lplpNewHeader parameter is NULL.
Other | Use FormatMessage to retrieve the error message that corresponds to the returned error code.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

MprInfo Functions and Information Headers, MprInfoBlockRemove


Router Information Structures

The following reference pages describe the router information structures for the IP and IPX transports:

  • IP Information Structures
  • IPX Information Structures


IP Information Structures

The MIB_IPFORWARDROW is used for the IP transport. This structure is defined in Iprtrmib.h.

MIB_IPFORWARDROW


IPX Information Structures

The following information structures are for the IPX transport. The structures IPX_TRAFFIC_FILTER_INFO and IPX_TRAFFIC_FILTER_GLOBAL_INFO are defined in Ipxtfflt.h. The remaining structures are defined in Ipxrtdef.h.

IPX_ADAPTER_INFO

IPX_GLOBAL_INFO

IPX_IF_INFO

IPX_SERVER_ENTRY

IPX_STATIC_NETBIOS_NAME_INFO

IPX_STATIC_ROUTE_INFO

IPX_STATIC_SERVICE_INFO

IPX_TRAFFIC_FILTER_GLOBAL_INFO

IPX_TRAFFIC_FILTER_INFO

IPXWAN_IF_INFO


IPX_IF_INFO

The IPX_IF_INFO structure stores information for an IPX interface.

typedef struct _IPX_IF_INFO {
  ULONG    AdminState;        // admin state of the interface
  ULONG    NetbiosAccept;     // accept Netbios broadcast packets
  ULONG    NetbiosDeliver;    // deliver Netbios broadcast packets
} IPX_IF_INFO, *PIPX_IF_INFO;

Members

AdminState
Specifies the administrative state of the interface.
NetbiosAccept
Specifies whether to accept NetBIOS broadcast packets.
NetbiosDeliver
Specifies whether to deliver NetBIOS broadcast packets

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ipxrtdef.h.

See Also

IPXWAN_IF_INFO


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
Specifies the service type as defined by the SAP specification.
Name[48]
Specifies the service name as defined by SAP specifications.
Network[4]
Specifies the network number portion of the service address.
Node[6]
Specifies the node number portion of the service address.
Socket[2]
Specifies the socket number portion of service address.
HopCount
Specifies 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. The declaration for IPX_SERVER_ENTRY is in stm.h.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ipxrtdef.h.

See Also

IPX_SERVER_ENTRY


IPXWAN_IF_INFO

The IPXWAN_IF_INFO structure stores the administrative state for an IPX WAN interface.

typedef struct _IPXWAN_IF_INFO {
  ULONG    AdminState;    // enable/disable IPXWAN negotiation
} IPXWAN_IF_INFO, *PIPXWAN_IF_INFO;

Members

AdminState
Specifies the administrative state of the interface. This member can be one of the following values. These value are defined in Ipxconst.h.

ADMIN_STATE_DISABLED

ADMIN_STATE_ENABLED

ADMIN_STATE_ENABLED_ONLY_FOR_NETBIOS_STATIC_ROUTING

ADMIN_STATE_ENABLED_ONLY_FOR_OPER_STATE_UP

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ipxrtdef.h.

See Also

MprInfo Functions and Information Headers, IPX_IF_INFO


Router Information Enumeration Types

Use the following information 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 listed in Ipinfoid.h. Use these information types with the Information Header functions when running the IP transport:

  • IP_DEMAND_DIAL_FILTER_INFO
  • IP_IN_FILTER_INFO
  • IP_OUT_FILTER_INFO
  • IP_GLOBAL_INFO
  • IP_IFFILTER_INFO
  • IP_INTERFACE_STATUS_INFO
  • IP_MCAST_HEARBEAT_INFO
  • IP_MCAST_BOUNDARY_INFO
  • IP_PROT_PRIORITY_INFO
  • IP_ROUTE_INFO
  • IP_ROUTER_DISC_INFO


IPX Info Types for Router Information Blocks

The following information types are listed in Ipxrtdef.h. Use these information types with the router information block functions when running the IPX transport.

Info type | Info structure
IPX_ADAPTER_INFO_TYPE | IPX_ADAPTER_INFO
IPX_GLOBAL_INFO_TYPE | IPX_GLOBAL_INFO
IPX_INTERFACE_INFO_TYPE | IPX_IF_INFO
IPX_IN_TRAFFIC_FILTER_GLOBAL_INFO_TYPE | IPX_TRAFFIC_FILTER_GLOBAL_INFO
IPX_OUT_TRAFFIC_FILTER_GLOBAL_INFO_TYPE | IPX_TRAFFIC_FILTER_GLOBAL_INFO
IPX_IN_TRAFFIC_FILTER_INFO_TYPE | IPX_TRAFFIC_FILTER_INFO
IPX_OUT_TRAFFIC_FILTER_INFO_TYPE | IPX_TRAFFIC_FILTER_INFO
IPX_STATIC_NETBIOS_NAME_INFO_TYPE | IPX_STATIC_NETBIOS_NAME_INFO
IPX_STATIC_ROUTE_INFO_TYPE | IPX_STATIC_ROUTE_INFO
IPX_STATIC_SERVICE_INFO_TYPE | IPX_STATIC_SERVICE_INFO
IPXWAN_INTERFACE_INFO_TYPE | IPXWAN_IF_INFO


About Management Information Base

The Management Information Base (MIB) API makes it possible 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 managers service. By using this API, the router supports the Simple Network Management Protocol (SNMP).

In the SNMP framework, each of the manageable objects in the router is represented by a variable that has a unique Object Identifier (OID). Corresponding to each OID is a value which represents the current state of the object. The collection of OIDs and values is referred to as a Management Information Base (MIB). The MprAdminMib calls allow a developer to specify an object by its OID and either query or write ("Set") the object's value.

To query and set MIB 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 values 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.

The module servicing the MIB call will be a router manager or one of the routing protocols. The caller 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.

The MprAdminMib functions can be called on a computer other than the one being administered. The MprAdminMIB functions that query or write values, take as a parameter a handle to the computer to administer. Use the MprAdminMIBServerConnect function to establish the connection to the remote computer and obtain this handle. After calling the necessary MprAdminMIB functions to accomplish a particular administrative task, call the MprAdminMIBServerDisconnect function to sever the connection to the remote computer.

The MprAdminMIBEntryCreate and MprAdminMIBEntrySet functions take as parameters an OID and a buffer which contains the new value for the object.

The MprAdminMIBEntryGet, MprAdminMIBEntryGetFirst and MprAdminMIBEntryGetNext functions take as parameters an OID and the address of a pointer variable. On successful return, the pointer variable points to a buffer that contains the value for the object. The caller should free the memory for this buffer by calling the MprAdminMIBBufferFree function.

The MprAdminMIBEntryGetFirst and MprAdminMIBEntryGetNext functions enable a developer to perform an "SNMP walk". Because the OIDs are ordered, each OID and therefore each manageable object has a "next" OID. An SNMP-Walk refers to traversing a portion of the MIB by reading or writing a sequence of OIDs.

All MprAdminMib calls pass through the Dynamic Interface Manager (DIM). Depending on the OID, DIM passes the call to one of the router managers. (Both IP and IPX support SNMP). Again, depending on the OID, the router manager may handle the call itself, or pass the call to one of its clients. All router clients are required to implement and export the following functions which correspond to the similarly named MprAdminMIB functions:

  • MibCreate
  • MibDelete
  • MibSet
  • MibGet
  • MibGetFirst
  • MibGetNext
  • MibGetTrapInfo
  • MibSetTrapInfo


Using the MIB API

This section contains examples that show how to use the MIB API to query and set variables:

  • 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;

See Also

MIB_OPAQUE_INFO, MIB_OPAQUE_QUERY, MprAdminMIBEntryGet


Management Information Base Reference

This documentation describes the reference elements used in the Management Information Base (MIB) API. Use these reference elements to query and set the values of the MIB variables. The router managers and the routing protocols that the router manager services export the MIB variables:

  • MIB Functions
  • MIB Structures
  • Transport and Protocol Constants


MIB Functions

Use the following functions to query and set MIB variables:

  • MprAdminMIBBufferFree
  • MprAdminMIBEntryCreate
  • MprAdminMIBEntryDelete
  • MprAdminMIBEntryGet
  • MprAdminMIBEntryGetFirst
  • MprAdminMIBEntryGetNext
  • MprAdminMIBEntrySet
  • MprAdminMIBGetTrapInfo
  • MprAdminMIBServerConnect
  • MprAdminMIBServerDisconnect
  • MprAdminMIBSetTrapInfo


MprAdminMIBBufferFree

The MprAdminMIBBufferFree function frees buffers returned by the following functions:

  • MprAdminMIBEntryGet
  • MprAdminMIBEntryGetFirst
  • MprAdminMIBEntryGetNext
DWORD MprAdminMIBBufferFree(
  LPVOID pBuffer    // address of memory to free
);

Parameters

pBuffer
[in] Pointer to a memory buffer to free.

Return Values

If the function succeeds, the return value is NO_ERROR.

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

Value | Description
ERROR_INVALID_PARAMETER | The pBuffer parameter is NULL.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

MIB Reference, MIB Functions, 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
[in] Handle to the Windows 2000 router on which to execute this call. Obtain this handle by calling MprAdminMIBServerConnect.
dwTransportId
[out] Receives the router manager that exported the variable.
dwRoutingPid
[in] Specifies the routing protocol that exported the variable.
lpEntry
[in] Pointer to an opaque data structure. The data structure's format is determined by the router manager or router manager client servicing the call. The data structure should contain information that specifies the variable being created and the value to assign to the variable.
dwEntrySize
[in] Specifies the size, in bytes, of the data pointed to by the lpEntry parameter.

Return Values

If the function succeeds, the return value is NO_ERROR.

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

Value | Description
ERROR_ACCESS_DENIED | The caller does not have sufficient privileges.
ERROR_CANNOT_COMPLETE | The dwRoutingPid variable does not 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 because the resulting behavior is undefined.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

MIB Reference, MIB Functions, MIB Structures, 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
[in] Handle to the Windows 2000 router on which to execute this call. Obtain this handle by calling MprAdminMIBServerConnect.
dwTransportId
[in]Specifies the router manager that exported the variable.
dwRoutingPid
[in] Specifies the routing protocol that exported the variable.
lpEntry
[in] 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 that specifies the variable to be deleted.
dwEntrySize
[in] Specifies the size, in bytes, of the data pointed to by lpEntry parameter.

Return Values

If the function succeeds, the return value is NO_ERROR.

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

Value | Description
ERROR_ACCESS_DENIED | The caller does not have sufficient privileges.
ERROR_CANNOT_COMPLETE | The dwRoutingPid variable does not 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 because the resulting behavior is undefined.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

MIB Reference, MIB Functions, MIB Structures, 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
[in] Handle to the Windows 2000 router on which to execute this call. Obtain this handle by calling MprAdminMIBServerConnect.
dwTransportId
[in] Specifies the router manager that exported the variable.
dwRoutingPid
[in] Specifies the routing protocol that exported the variable.
lpInEntry
[in] 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 that specifies the variable being queried.
dwInEntrySize
[in] Specifies the size, in bytes, of the data structure pointed to by lpInEntry.
lplpOutEntry
[out] 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 receives the value of the variable that was queried. Free this memory by calling MprAdminMIBBufferFree.
lpdwOutEntrySize
[out] Pointer to a DWORD variable that, on successful return, receives the size in bytes of the data structure returned through the lplpOutEntry parameter.

Return Values

If the function succeeds, the return value is NO_ERROR.

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

Value | Description
ERROR_ACCESS_DENIED | The caller does not have sufficient privileges.
ERROR_CANNOT_COMPLETE | The dwRoutingPid variable does not 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 because the resulting behavior is undefined.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

MIB Reference, MIB Functions, MIB Structures, 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 "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
[in] Handle to the Windows 2000 router on which to execute this call. Obtain this handle by calling MprAdminMIBServerConnect.
dwTransportId
[in] Specifies the router manager that exported the variable.
dwRoutingPid
[in] Specifies the routing protocol that exported the variable.
lpInEntry
[in] 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 that specifies the variable being queried.
dwInEntrySize
[in] Specifies the size, in bytes, of the data pointed to by lpInEntry.
lplpOutEntry
[out] 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 receives the value of the first variable from the set of variables exported. Free this memory by calling MprAdminMIBBufferFree.
lpdwOutEntrySize
[out] Pointer to a DWORD variable. On successful return, this variable receives the size, in bytes, of the data structure that was returned through the lplpOutEntry parameter.

Return Values

If the function succeeds, the return value is NO_ERROR.

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

Value | Description
ERROR_ACCESS_DENIED | The caller does not have sufficient privileges.
ERROR_CANNOT_COMPLETE | The dwRoutingPid variable does not 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 because the resulting behavior is undefined.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

MIB Reference, MIB Functions, MIB Structures, 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. The module servicing the call defines "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
[in] Handle to the Windows 2000 router on which to execute this call. This handle is obtained from a previous call to MprAdminMIBServerConnect.
dwTransportId
[in] Specifies the router manager that exported the variable.
dwRoutingPid
[in] Specifies the routing protocol that exported the variable.
lpInEntry
[in] 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 that specifies the variable being queried.
dwInEntrySize
[in] Specifies the size, in bytes, of the data structure pointed to by lpInEntry.
lplpOutEntry
[out] 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 receives the value of the next variable from the set of variables exported. Free this memory by calling MprAdminMIBBufferFree.
lpdwOutEntrySize
[out] Pointer to a DWORD variable. This variable receives the size in bytes of the data structure returned through the lplpOutEntry parameter.

Return Values

If the function succeeds, the return value is NO_ERROR.

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

Value | Description
ERROR_ACCESS_DENIED | The caller does not have sufficient privileges.
ERROR_CANNOT_COMPLETE | The dwRoutingPid variable does not 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 because the resulting behavior is undefined.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

MIB Reference, MIB Functions, MIB Structures, 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
[in] Handle to the Windows 2000 router on which to execute this call. Obtain this handle by calling MprAdminMIBServerConnect.
dwTransportId
[in] Specifies the router manager that exported the variable.
dwRoutingPid
[in] Specifies the routing protocol that exported the variable.
lpEntry
[in] 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 that specifies the variable being set and the value to be assigned to the variable.
dwEntrySize
[in] Specifies the size, in bytes, of the data pointed to by the lpEntry parameter.

Return Values

If the function succeeds, the return value is NO_ERROR.

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

Value | Description
ERROR_ACCESS_DENIED | The caller does not have sufficient privileges.
ERROR_CANNOT_COMPLETE | The dwRoutingPid variable does not 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 because the resulting behavior is undefined.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

MIB Reference, MIB Functions, MIB Structures, MprAdminMIBServerConnect, MprAdminMIBEntryGet, Protocol Identifiers, Transport Identifiers


MprAdminMIBGetTrapInfo

The MprAdminMIBGetTrapInfo function queries the module that set a trap event for more information about the trap.

DWORD MprAdminMIBGetTrapInfo(
  MIB_SERVER_HANDLE hMibServer,
  DWORD dwTransportId,
  DWORD dwRoutingPid,
  LPVOID lpInData,
  DWORD dwInDataSize,
  LPVOID *lplpOutData,
  LPDWORD lpdwOutDataSize
);

Parameters

hMibServer
[in] Handle to the Windows 2000 router on which to execute this call. Obtain this handle by calling MprAdminMIBServerConnect.
dwTransportId
[in] Specifies a DWORD variable that contains the protocol family identifier.
dwRoutingPid
[in] Specifies a DWORD variable that contains the identifier of the routing protocol.
lpInData
[in] Specifies the address of the input data.
dwInDataSize
[in] Specifies a DWORD variable that contains the size, in, bytes of the data pointed to by lpInData.
lplpOutData
[out] Receives, the address of a pointer to the output data.
lpdwOutDataSize
[in, out] On input, pointer to a DWORD variable.

On output, receives the size, in bytes, of the data pointed to by *lplpOutData.

Return Values

If the functions succeeds, the return value is NO_ERROR

If the function fails, the return value is one of the following error codes.

Value | Description
ERROR_ACCESS_DENIED | The caller does not have sufficient privileges.
ERROR_UNKNOWN_PROTOCOL_ID | The dwTransportId value does not match any installed router manager.
ERROR_NOT_ENOUGH_MEMORY | Insufficient resources to complete the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

MIB Reference, MIB Functions, MprAdminMIBSetTrapInfo


MprAdminMIBServerConnect

The MprAdminMIBServerConnect function establishes a connection to the Windows 2000 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

lpwsServerName
[in] Pointer to a Unicode string that specifies the name of the remote server. If the caller specifies NULL for this parameter, the function returns a handle to the local server.
phMibServer
[out] Pointer to a handle variable. This variable receives a handle to the server.

Return Values

If the function succeeds, the return value is NO_ERROR.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

MIB Reference, MIB Functions, MprAdminMIBServerDisconnect


MprAdminMIBServerDisconnect

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

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

Parameters

hMibServer
[in] Handle to the Windows 2000 router from which to disconnect. Obtain this handle by calling MprAdminMIBServerConnect.

Return Values

This function has no return value.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

MIB Reference, MIB Functions, MprAdminMIBServerConnect


MprAdminMIBSetTrapInfo

The MprAdminMIBSetTrapInfo function specifies a handle to an event that is signaled whenever a TRAP needs to be issued.

DWORD MprAdminMIBSetTrapInfo(
  DWORD dwTransportId,
  DWORD dwRoutingPid,
  HANDLE hEvent,
  LPVOID lpInData,
  DWORD dwInDataSize,
  LPVOID *lplpOutData,
  LPDWORD lpdwOutDataSize
);

Parameters

dwTransportId
[in] Specifies a DWORD variable that contains the protocol family identifier.
dwRoutingPid
[in] Specifies a DWORD variable that contains the identifier of the routing protocol.
hEvent
[in] Handle to an event that is signaled when a TRAP needs to be issued.
lpInData
[in] Pointer to the input data.
dwInDataSize
[in] Specifies a DWORD variable that contains the size in bytes of the data pointed to by lpInData.
lplpOutData
[out] Receives the address of a pointer to the output data.
lpdwOutDataSize
[in, out]On input, pointer to a DWORD variable.

On output, receives the size, in bytes, of the data pointed to by *lplpOutData.

Return Values

If the functions succeeds, the return value is NO_ERROR

If the function fails, the return value is one of the following error codes.

Value | Description
ERROR_ACCESS_DENIED | The caller does not have sufficient privileges.
ERROR_UNKNOWN_PROTOCOL_ID | The dwTransportId value does not match any installed router manager.
ERROR_NOT_ENOUGH_MEMORY | Insufficient resources to complete the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mprapi.h.
Library: Use Mprapi.lib.

See Also

MIB Reference, Transport and Protocol Constants, MprAdminMIBGetTrapInfo


MIB Structures

Use the following structures with the MIB functions to get and set MIB variables. These structures are defined in Iprtrmib.h:

  • MIB_BEST_IF
  • MIB_ICMP
  • MIB_IFNUMBER
  • MIB_IFROW
  • MIB_IFSTATUS
  • MIB_IFTABLE
  • MIB_IPADDRROW
  • MIB_IPADDRTABLE
  • MIB_IPFORWARDNUMBER
  • MIB_IPFORWARDROW
  • MIB_IPFORWARDTABLE
  • MIB_IPMCAST_GLOBAL
  • MIB_IPMCAST_IF_ENTRY
  • MIB_IPMCAST_IF_TABLE
  • MIB_IPMCAST_MFE
  • MIB_IPMCAST_MFE_STATS
  • MIB_IPMCAST_OIF
  • MIB_IPMCAST_OIF_STATS
  • MIB_IPNETROW
  • MIB_IPNETTABLE
  • MIB_IPSTATS
  • MIB_MFE_STATS_TABLE
  • MIB_MFE_TABLE
  • MIB_OPAQUE_INFO
  • MIB_OPAQUE_QUERY
  • MIB_PROXYARP
  • MIB_TCPROW
  • MIB_TCPSTATS
  • MIB_TCPTABLE
  • MIB_UDPROW
  • MIB_UDPSTATS
  • MIB_UDPTABLE
  • MIBICMPINFO
  • MIBICMPSTATS


MIB_BEST_IF

The MIB_BEST_IF structure stores the index of the interface that has the best route to a particular destination address.

typedef struct _MIB_BEST_IF {
  DWORD   dwDestAddr;    // destination address
  DWORD   dwIfIndex;     // best interface for that dest addr
} MIB_BEST_IF, *PMIB_BEST_IF;

Members

dwDestAddr
Specifies the IP address of the destination.
dwIfIndex
Specifies the index of the interface that has the best route to the destination address specified by the dwDestAddr member.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

GetBestInterface, GetBestRoute


MIB_ICMP

The MIB_ICMP structure contains the Internet Control Message Protocol (ICMP) statistics for a particular computer.

typedef struct _MIB_ICMP {
  MIBICMPINFO   stats;    // contains ICMP stats
} MIB_ICMP,*PMIB_ICMP;

Members

stats
Specifies a MIBICMPINFO structure that contains the ICMP statistics for the computer.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iprtrmib.h.

See Also

GetIcmpStatistics, MIBICMPINFO


MIB_IFNUMBER

The MIB_IFNUMBER structure stores the number of interfaces on a particular computer.

typedef struct _MIB_IFNUMBER {
  DWORD   dwValue;    // number of interfaces
} MIB_IFNUMBER, *PMIB_IFNUMBER;

Members

dwValue
Specifies the number of interfaces on the computer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Iprtrmib.h.

See Also

MIB_IFTABLE


MIB_IFROW

The MIB_IFROW structure stores information about a particular interface.

typedef struct _MIB_IFROW {
  WCHAR   wszName[MAX_INTERFACE_NAME_LEN];
  DWORD   dwIndex;    // index of the interface
  DWORD   dwType;     // type of interface
  DWORD   dwMtu;      // max transmission unit
  DWORD   dwSpeed;    // speed of the interface
  DWORD   dwPhysAddrLen;    // length of physical address
  BYTE    bPhysAddr[MAXLEN_PHYSADDR]; // physical address of adapter
  DWORD   dwAdminStatus;    // administrative status
  DWORD   dwOperStatus;     // operational status
  DWORD   dwLastChange;     // last time operational status changed
  DWORD   dwInOctets;       // octets received
  DWORD   dwInUcastPkts;    // unicast packets received
  DWORD   dwInNUcastPkts;   // non-unicast packets received
  DWORD   dwInDiscards;     // received packets discarded
  DWORD   dwInErrors;       // erroneous packets received
  DWORD   dwInUnknownProtos;  // unknown protocol packets received
  DWORD   dwOutOctets;      // octets sent
  DWORD   dwOutUcastPkts;   // unicast packets sent
  DWORD   dwOutNUcastPkts;  // non-unicast packets sent
  DWORD   dwOutDiscards;    // outgoing packets discarded
  DWORD   dwOutErrors;      // erroneous packets sent
  DWORD   dwOutQLen;        // output queue length
  DWORD   dwDescrLen;       // length of bDescr member
  BYTE    bDescr[MAXLEN_IFDESCR];  // interface description
} MIB_IFROW,*PMIB_IFROW;

Members

wszName[MAX_INTERFACE_NAME_LEN]
Pointer to a Unicode string that contains the name of the interface.
dwIndex
Specifies the index that identifies the interface.
dwType
Specifies the type of interface.
dwMtu
Specifies the Maximum Transmission Unit (MTU).
dwSpeed
Specifies the speed of the interface in bits per second.
dwPhysAddrLen
Specifies the length of the physical address specified by the bPhysAddr member.
bPhysAddr[MAXLEN_PHYSADDR]
Specifies the physical address of the adapter for this interface.
dwAdminStatus
Specifies the interface is administratively enabled or disabled.
dwOperStatus
Specifies the operational status of the interface. This member can be one of the following values.

MIB_IF_OPER_STATUS_NON_OPERATIONAL
MIB_IF_OPER_STATUS_UNREACHABLE
MIB_IF_OPER_STATUS_DISCONNECTED
MIB_IF_OPER_STATUS_CONNECTING
MIB_IF_OPER_STATUS_CONNECTED
MIB_IF_OPER_STATUS_OPERATIONAL

dwLastChange
Specifies the last time the operational status changed.
dwInOctets
Specifies the number of octets of data received through this interface.
dwInUcastPkts
Specifies the number of unicast packets received through this interface.
dwInNUcastPkts
Specifies the number of non-unicast packets received through this interface. Broadcast and multicast packets are included.
dwInDiscards
Specifies the number of incoming packets that were discarded even though they did not have errors.
dwInErrors
Specifies the number of incoming packets that were discarded because of errors.
dwInUnknownProtos
Specifies the number of incoming packets that were discarded because the protocol was unknown.
dwOutOctets
Specifies the number of octets of data sent through this interface.
dwOutUcastPkts
Specifies the number of unicast packets sent through this interface.
dwOutNUcastPkts
Specifies the number of non-unicast packets sent through this interface. Broadcast and multicast packets are included.
dwOutDiscards
Specifies the number of outgoing packets that were discarded even though they did not have errors.
dwOutErrors
Specifies the number of outgoing packets that were discarded because of errors.
dwOutQLen
Specifies the output queue length.
dwDescrLen
Specifies the length of the bDescr member.
bDescr[MAXLEN_IFDESCR]
Contains a description of the interface.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iprtrmib.h.

See Also

GetIfEntry, MIB_IFSTATUS, MIB_IFTABLE, MPR_INTERFACE_0


MIB_IFSTATUS

The MIB_IFSTATUS structure stores status information for a particular interface.

typedef struct _MIB_IFSTATUS {
  DWORD   dwIfIndex;
  DWORD   dwAdminStatus;
  DWORD   dwOperationalStatus;
  BOOL    bMHbeatActive;
  BOOL    bMHbeatAlive;
} MIB_IFSTATUS, *PMIB_IFSTATUS;

Members

dwIfIndex
Specifies the index that identifies the interface.
dwAdminStatus
Specifies the administrative status of the interface, that is, whether the interface is administratively enabled or disabled.
dwOperationalStatus
Specifies the operational status of the interface. See ROUTER_CONNECTION_STATE for a list of the possible operational states.
bMHbeatActive
Specifies whether multicast heartbeat detection is enabled. A value of TRUE indicates that heartbeat detection is enabled. A value of FALSE indicates that heartbeat detection is disabled.
bMHbeatAlive
Specifies whether the multicast heartbeat dead interval has been exceeded. A value of TRUE indicates that the interval has been exceeded. A value of FALSE indicates that the interval has not been exceeded.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Iprtrmib.h.

See Also

MIB_IFROW, MPR_INTERFACE_0, MPR_INTERFACE_1


MIB_IFTABLE

The MIB_IFTABLE structure contains a table of interface entries.

typedef struct _MIB_IFTABLE {
  DWORD     dwNumEntries;       // number of entries in table
  MIB_IFROW table[ANY_SIZE];    // array of interface entries
} MIB_IFTABLE, *PMIB_IFTABLE;

Members

dwNumEntries
Specifies the number of interface entries in the array.
table[ANY_SIZE]
Pointer to a table of interface entries implemented as an array of MIB_IFROW structures.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iprtrmib.h.

See Also

GetIfTable, MIB_IFNUMBER, MIB_IFROW


MIB_IPADDRROW

The MIB_IPADDRROW specifies information for a particular IP address.

typedef struct _MIB_IPADDRROW {
  DWORD   dwAddr;              // IP address
  DWORD   dwIndex;             // interface index
  DWORD   dwMask;              // subnet mask
  DWORD   dwBCastAddr;         // broadcast address
  DWORD   dwReasmSize;         // rassembly size
  unsigned short   unused1;    // not currently used
  unsigned short   unused2;    // not currently used
} MIB_IPADDRROW, *PMIB_IPADDRROW;

Members

dwAddr
Specifies the IP address.
dwIndex
Specifies the index of the interface associated with this IP address.
dwMask
Specifies the subnet mask for the IP address.
dwBCastAddr
Specifies the broadcast address. A broadcast address is typically the IP address with the host portion set to either all zeros or all ones.
dwReasmSize
Specifies the maximum reassembly size for received datagrams
unused1
This member is reserved.
unused2
This member is reserved.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iprtrmib.h.

See Also

MIB_IPADDRTABLE


MIB_IPADDRTABLE

The MIB_IPADDRTABLE structure contains a table of IP address entries.

typedef struct _MIB_IPADDRTABLE {
  DWORD         dwNumEntries;    // number of entries in the table
  MIB_IPADDRROW table[ANY_SIZE]; // array of IP address entries
} MIB_IPADDRTABLE, *PMIB_IPADDRTABLE;

Members

dwNumEntries
Specifies the number of IP address entries in the table.
table[ANY_SIZE]
Pointer to a table of IP address entries implemented as an array of MIB_IPADDRROW structures.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iprtrmib.h.

See Also

GetIpAddrTable, MIB_IPADDRROW


MIB_IPFORWARDNUMBER

The MIB_IPFORWARDNUMBER stores the number of routes in a particular IP routing table.

typedef struct _MIB_IPFORWARDNUMBER {
  DWORD   dwValue;
} MIB_IPFORWARDNUMBER, *PMIB_IPFORWARDNUMBER;

Members

dwValue
Specifies the number of routes in the IP routing table.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iprtrmib.h.

See Also

GetIpForwardTable, MIB_IPFORWARDROW, MIB_IPFORWARDTABLE


MIB_IPFORWARDROW

The MIB_IPFORWARDROW structure contains information that describes an IP network route.

typedef struct _MIB_IPFORWARDROW {
  DWORD   dwForwardDest;       // IP addr of destination
  DWORD   dwForwardMask;       // subnetwork mask of destination
  DWORD   dwForwardPolicy;     // conditions for multi-path route
  DWORD   dwForwardNextHop;    // IP address of next hop
  DWORD   dwForwardIfIndex;    // index of interface
  DWORD   dwForwardType;       // route type
  DWORD   dwForwardProto;      // protocol that generated route
  DWORD   dwForwardAge;        // age of route
  DWORD   dwForwardNextHopAS;  // autonomous system number
                               // of next hop
  DWORD   dwForwardMetric1;    // protocol-specific metric
  DWORD   dwForwardMetric2;    // protocol-specific metric
  DWORD   dwForwardMetric3;    // protocol-specific metric
  DWORD   dwForwardMetric4;    // protocol-specific metric
  DWORD   dwForwardMetric5;    // protocol-specific metric
} MIB_IPFORWARDROW, *PMIB_IPFORWARDROW;

Members

dwForwardDest
Specifies the IP address of the destination host.
dwForwardMask
Specifies the subnet mask of the destination host.
dwForwardPolicy
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.
dwForwardNextHop
Specifies the IP address of the next hop in the route.
dwForwardIfIndex
Specifies the index of the interface for this route.
dwForwardType
Specifies the route type as defined in RFC 1354. The following list shows the possible values for this member.
Value | Meaning
4 | The next hop is not the final destination (remote route).
3 | The next hop is the final destination (local route).
2 | The route is invalid.
1 | Other.

dwForwardProto
Specifies the protocol that generated the route. See Protocol Identifiers for a list of possible protocols.
dwForwardAge
Specifies the age of the route in seconds.
dwForwardNextHopAS
Specifies the autonomous system number of the next hop.
dwForwardMetric1
Specifies a routing-protocol-specific metric value. This metric value is documented in RFC 1354.
dwForwardMetric2
Specifies a routing-protocol-specific metric value. This metric value is documented in RFC 1354.
dwForwardMetric3
Specifies a routing-protocol-specific metric value. This metric value is documented in RFC 1354.
dwForwardMetric4
Specifies a routing-protocol-specific metric value. This metric value is documented in RFC 1354.
dwForwardMetric5
Specifies a routing-protocol-specific metric value. This metric value is documented in RFC 1354.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iprtrmib.h.

See Also

CreateIpForwardEntry, DeleteIpForwardEntry, MIB_IPFORWARDTABLE, SetIpForwardEntry


MIB_IPFORWARDTABLE

The MIB_IPFORWARDTABLE structure contains a table of IP route entries.

typedef struct _MIB_IPFORWARDTABLE {
  DWORD               dwNumEntries;    // number of entries in the table
  MIB_IPFORWARDROW    table[ANY_SIZE]; // array of route entries
} MIB_IPFORWARDTABLE, *PMIB_IPFORWARDTABLE;

Members

dwNumEntries
Specifies the number of route entries in the table.
table[ANY_SIZE]
Pointer to a table of route entries implemented as an array of MIB_IPFORWARDROW structures.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iprtrmib.h.

See Also

GetIpForwardTable, MIB_IPFORWARDNUMBER, MIB_IPFORWARDROW


MIB_IPMCAST_GLOBAL

The MIB_IPMCAST_GLOBAL structure stores global information for IP multicast on a particular computer.

typedef struct _MIB_IPMCAST_GLOBAL {
  DWORD   dwEnable;
} MIB_IPMCAST_GLOBAL, *PMIB_IPMCAST_GLOBAL;

Members

dwEnable
Specifies whether IP multicast is enabled on the computer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Iprtrmib.h.

See Also

MIB_IPMCAST_IF_ENTRY, MIB_IPMCAST_MFE, MIB_IPMCAST_OIF


MIB_IPMCAST_IF_ENTRY

The MIB_IPMCAST_IF_ENTRY stores information about an IP multicast interface.

typedef struct _MIB_IPMCAST_IF_ENTRY {
  DWORD   dwIfIndex;
  DWORD   dwTtl;
  DWORD   dwProtocol;
  DWORD   dwRateLimit;
  ULONG   ulInMcastOctets;
  ULONG   ulOutMcastOctets;
} MIB_IPMCAST_IF_ENTRY, *PMIB_IPMCAST_IF_ENTRY;

Members

dwIfIndex
Specifies the index of this interface.
dwTtl
Specifies the time-to-live value for this interface.
dwProtocol
Specifies the multicast routing protocol that owns this interface.
dwRateLimit
Specifies the rate limit of this interface.
ulInMcastOctets
Specifies the number of octets of multicast data received through this interface.
ulOutMcastOctets
Specifies the number of octets of multicast data sent through this interface.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Iprtrmib.h.

See Also

MIB_IPMCAST_IF_TABLE


MIB_IPMCAST_IF_TABLE

The MIB_IPMCAST_IF_TABLE structure contains a table of IP multicast interface entries.

typedef struct _MIB_IPMCAST_IF_TABLE {
  DWORD                  dwNumEntries;      // number of entries
  MIB_IPMCAST_IF_ENTRY   table[ANY_SIZE];   // table of interfaces
} MIB_IPMCAST_IF_TABLE, *PMIB_IPMCAST_IF_TABLE;

Members

dwNumEntries
Specifies the number of interface entries in the table.
table[ANY_SIZE]
Pointer to a table of interface entries implemented as an array of MIB_IPMCAST_IF_TABLE structures.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Iprtrmib.h.

See Also

MIB_IPMCAST_IF_ENTRY


MIB_IPMCAST_MFE

The MIB_IPMCAST_MFE structure stores the information for an IP MFE.

typedef struct _MIB_IPMCAST_MFE {
  DWORD   dwGroup;
  DWORD   dwSource;
  DWORD   dwSrcMask;
  DWORD   dwUpStrmNgbr;
  DWORD   dwInIfIndex;
  DWORD   dwInIfProtocol;
  DWORD   dwRouteProtocol;
  DWORD   dwRouteNetwork;
  DWORD   dwRouteMask;
  ULONG   ulUpTime;
  ULONG   ulExpiryTime;
  ULONG   ulTimeOut;
  ULONG   ulNumOutIf;
  DWORD   fFlags;
  DWORD   dwReserved;
  MIB_IPMCAST_OIF rgmioOutInfo[ANY_SIZE];
} MIB_IPMCAST_MFE, *PMIB_IPMCAST_MFE;

Members

dwGroup
Specifies the range of multicast groups for this MFE. Zero indicates a wildcard group.
dwSource
Specifies the range of source addresses for this MFE. Zero indicates a wildcard source.
dwSrcMask
Specifies the subnet mask that corresponds to dwSourceAddr. The dwSourceAddr and dwSourceMask members are used together to define a range of sources.
dwUpStrmNgbr
Specifies the upstream neighbor that is related to this MFE.
dwInIfIndex
Specifies the index of the interface to which this MFE is related.
dwInIfProtocol
Specifies the routing protocol that owns the incoming interface to which this MFE is related.
dwRouteProtocol
Specifies the client that created the route.
dwRouteNetwork
Specifies the address associated with the route referred to by dwRouteProtocol.
dwRouteMask
Specifies the mask associated with the route referred to by dwRouteProtocol.
ulUpTime
Specifies how long, in seconds, this MFE has been valid. This value starts from zero and is incremented until it reaches the ulTimeOut value, at which time the MFE is deleted.
ulExpiryTime
Specifies the time, in seconds, that remains before the MFE expires and is deleted. This value starts from ulTimeOut and is decremented until it reaches zero, at which time the MFE is deleted.
ulTimeOut
Specifies the total length of time that this MFE should remain valid. After the time-out value is exceeded, the MFE is deleted. This value is static.
ulNumOutIf
Specifies the number of outgoing interfaces that are associated with this MFE.
fFlags
Reserved. This member should be NULL.
dwReserved
Reserved. This member should be NULL.
rgmioOutInfo[ANY_SIZE]
Pointer to a table of outgoing interface statistics that are implemented as an array of MIB_IPMCAST_OIF structures.

Remarks

The MIB_IPMCAST_MFE structure does not have a fixed size. Use the SIZEOF_MIB_MFE(X) macro to determine the size of this structure. This macro is defined in the Iprtrmib.h header file.

The dwRouteProtocol, dwRouteNetwork, and dwRouteMask members uniquely identify the route to which this MFE is related.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Iprtrmib.h.

See Also

MIB_MFE_TABLE, MIB_IPMCAST_OIF


MIB_IPMCAST_MFE_STATS

The MIB_IPMCAST_MFE_STATS structure stores the statistics associated with an MFE.

typedef struct _MIB_IPMCAST_MFE_STATS {
  DWORD   dwGroup;
  DWORD   dwSource;
  DWORD   dwSrcMask;
  DWORD   dwUpStrmNgbr;
  DWORD   dwInIfIndex;
  DWORD   dwInIfProtocol;
  DWORD   dwRouteProtocol;
  DWORD   dwRouteNetwork;
  DWORD   dwRouteMask;
  ULONG   ulUpTime;
  ULONG   ulExpiryTime;
  ULONG   ulNumOutIf;
  ULONG   ulInPkts;
  ULONG   ulInOctets;
  ULONG   ulPktsDifferentIf;
  ULONG   ulQueueOverflow;
  MIB_IPMCAST_OIF_STATS   rgmiosOutStats[ANY_SIZE];
} MIB_IPMCAST_MFE_STATS, *PMIB_IPMCAST_MFE_STATS;

Members

dwGroup
Specifies the multicast group for this MFE. Zero indicates a wildcard group.
dwSource
Specifies the range of source addresses for this MFE. Zero indicates a wildcard source.
dwSrcMask
Specifies the subnet mask that corresponds to dwSourceAddr. The dwSourceAddr and dwSourceMask members are used together to define a range of sources.
dwUpStrmNgbr
Specifies the upstream neighbor that is related to this MFE.
dwInIfIndex
Specifies the index of the incoming interface to which this MFE is related.
dwInIfProtocol
Specifies the routing protocol that owns the incoming interface to which this MFE is related.
dwRouteProtocol
Specifies the client that created the route.
dwRouteNetwork
Specifies the address associated with the route referred to by dwRouteProtocol.
dwRouteMask
Specifies the mask associated with the route referred to by dwRouteProtocol.
ulUpTime
Specifies the time, in 100ths of a seconds, since the MFE was created.
ulExpiryTime
Specifies the time, in 100ths of a seconds, until the MFE will be deleted. Zero is specified if the MFE is not subject to aging requirements.
ulNumOutIf
Specifies the number of interfaces in the outgoing interface list for this MFE.
ulInPkts
Specifies the number of packets that have been forwarded that matched this MFE.
ulInOctets
Specifies the number of octets of data forwarded that match this MFE.
ulPktsDifferentIf
Specifies the number of packets matching this MFE that were dropped due to an incoming interface check.
ulQueueOverflow
Specifies the number of packets matching this MFE that were dropped due to a queue overflow. There is one queue per MFE.
rgmiosOutStats[ANY_SIZE]
Pointer to a table of outgoing interface statistics that are implemented as an array of MIB_IPMCAST_OIF_STATS structures. The number of entries in the table is specified by the value of the ulNumOutIf parameter.

Remarks

The MIB_IPMCAST_MFE_STATS structure does not have a fixed size. Use the macro SIZEOF_MIB_MFE_STATS(X) to determine the size of this structure. This macro is defined in the Iprtrmib.h header file.

The dwRouteProtocol, dwRouteNetwork, and dwRouteMask members uniquely identify the route to which this MFE is related.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Iprtrmib.h.

See Also

MIB_IPMCAST_OIF_STATS


MIB_IPMCAST_OIF

The MIB_IPMCAST_OIF structure stores the information required to send an outgoing IP multcast packet.

typedef struct _MIB_IPMCAST_OIF {
  DWORD   dwOutIfIndex;     // index of outgoing interface
  DWORD   dwNextHopAddr;    // dest addr for packet
  PVOID   pvReserved;       // reserved
  DWORD   dwReserved;       // reserved
} MIB_IPMCAST_OIF, *PMIB_IPMCAST_OIF;

Members

dwOutIfIndex
Specifies the index of the interface on which to send the outgoing IP multicast packet.
dwNextHopAddr
Specifies the destination address for the outgoing IP multicast packet.
pvReserved
Reserved. This member should be NULL.
dwReserved
Reserved. This member should be zero.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Iprtrmib.h.

See Also

MIB_IPMCAST_MFE, MIB_IPMCAST_OIF_STATS


MIB_IPMCAST_OIF_STATS

The MIB_IPMCAST_OIF_STATS structure stores the statistics that are associated with an outgoing multicast interface.

typedef struct _MIB_IPMCAST_OIF_STATS {
  DWORD   dwOutIfIndex;
  DWORD   dwNextHopAddr;
  PVOID   pvDialContext;
  ULONG   ulTtlTooLow;
  ULONG   ulFragNeeded;
  ULONG   ulOutPackets;
  ULONG   ulOutDiscards;
} MIB_IPMCAST_OIF_STATS, *PMIB_IPMCAST_OIF_STATS;

Members

dwOutIfIndex
Specifies the outgoing interface to which these statistics are related.
dwNextHopAddr
Specifies the address of the next hop that corresponds to dwOutIfIndex. The dwOutIfIndex and dwIfNextHopIPAddr parameters uniquely identify a next hop on point-to-multipoint interfaces, where one interface connects to multiple networks. Examples of point-to-multipoint interfaces include non-broadcast multiple-access (NBMA) interfaces, and the internal interface on which all dial-up clients connect.

For Ethernet and other broadcast interfaces, specify zero. Also specify zero for point-to-point interfaces, which are identified by only dwOutIfIndex.

pvDialContext
Reserved. This member should be NULL.
ulTtlTooLow
Specifies the number of packets on this outgoing interface that were discarded because the packet's time-to-live value was too low.
ulFragNeeded
Specifies the number of packets that required fragmentation when they were forwarded on this interface.
ulOutPackets
Specifies the number of packets that were forwarded out this interface.
ulOutDiscards
Specifies the number of packets that were discarded on this interface.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Iprtrmib.h.

See Also

MIB_IPMCAST_OIF


MIB_IPNETROW

The MIB_IPNETROW structure contains information for an Address Resolution Protocol (ARP) table entry.

typedef struct _MIB_IPNETROW {
  DWORD   dwIndex;        // adapter index
  DWORD   dwPhysAddrLen;  // physical address length
  BYTE    bPhysAddr[MAXLEN_PHYSADDR];  // physical address
  DWORD   dwAddr;         // IP address
  DWORD   dwType;         // ARP entry type
} MIB_IPNETROW, *PMIB_IPNETROW;

Members

dwIndex
Specifies the index of the adapter.
dwPhysAddrLen
Specifies the length of the physical address.
bPhysAddr[MAXLEN_PHYSADDR]
Specifies the physical address.
dwAddr
Specifies the IP address.
dwType
Specifies the type of ARP entry. This type can be one of the following values.
Value | Meaning
4 | Static
3 | Dynamic
2 | Invalid
1 | Other

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iprtrmib.h.

See Also

CreateIpNetEntry, DeleteIpNetEntry, MIB_IPNETTABLE, SetIpNetEntry


MIB_IPNETTABLE

The MIB_IPNETTABLE contains a table of Address Resolution Protocol (ARP) entries.

typedef struct _MIB_IPNETTABLE {
  DWORD           dwNumEntries;    // number of entries in table
  MIB_IPNETROW    table[ANY_SIZE]; // array of ARP entries
} MIB_IPNETTABLE, *PMIB_IPNETTABLE;

Members

dwNumEntries
Specifies the number of ARP entries in the table.
table[ANY_SIZE]
Pointer to a table of ARP entries implemented as an array of MIB_IPNETROW structures.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iprtrmib.h.

See Also

GetIpNetTable, MIB_IPNETROW


MIB_IPSTATS

The MIB_IPSTATS structure stores information about the IP protocol running on a particular computer.

typedef struct _MIB_IPSTATS {
  DWORD   dwForwarding;       // IP forwarding enabled or disabled
  DWORD   dwDefaultTTL;       // default time-to-live
  DWORD   dwInReceives;       // datagrams received
  DWORD   dwInHdrErrors;      // received header errors
  DWORD   dwInAddrErrors;     // received address errors
  DWORD   dwForwDatagrams;    // datagrams forwarded
  DWORD   dwInUnknownProtos;  // datagrams with unknown protocol
  DWORD   dwInDiscards;       // received datagrams discarded
  DWORD   dwInDelivers;       // received datagrams delivered
  DWORD   dwOutRequests;      //
  DWORD   dwRoutingDiscards;  //
  DWORD   dwOutDiscards;      // sent datagrams discarded
  DWORD   dwOutNoRoutes;      // datagrams for which no route exists
  DWORD   dwReasmTimeout;     // datagrams for which all
                              // frags did not arrive
  DWORD   dwReasmReqds;       // datagrams requiring reassembly
  DWORD   dwReasmOks;         // successful reassemblies
  DWORD   dwReasmFails;       // failed reassemblies
  DWORD   dwFragOks;          // successful fragmentations
  DWORD   dwFragFails;        // failed fragmentations
  DWORD   dwFragCreates;      // datagrams fragmented
  DWORD   dwNumIf;            // number of interfaces on computer
  DWORD   dwNumAddr;          // number of IP address on computer
  DWORD   dwNumRoutes;        // number of routes in routing table
} MIB_IPSTATS, *PMIB_IPSTATS;

Members

dwForwarding
Specifies whether IP forwarding is enabled or disabled.
dwDefaultTTL
Specifies the default initial time to live (TTL) for datagrams originating on a particular computer.
dwInReceives
Specifies the number of datagrams received.
dwInHdrErrors
Specifies the number of datagrams received that have header errors.
dwInAddrErrors
Specifies the number of datagrams received that have address errors.
dwForwDatagrams
Specifies the number of datagrams forwarded.
dwInUnknownProtos
Specifies the number of datagrams received that have an unknown protocol.
dwInDiscards
Specifies the number of received datagrams discarded.
dwInDelivers
Specifies the number of received datagrams delivered.
dwOutRequests
Specifies the number of outgoing datagrams that IP is requested to transmit. This number does not include forwarded datagrams.
dwRoutingDiscards
Specifies the number of outgoing datagrams discarded.
dwOutDiscards
Specifies the number of transmitted datagrams discarded.
dwOutNoRoutes
Specifies the number of datagrams for which this computer did not have a route to the destination IP address. These datagrams were discarded.
dwReasmTimeout
Specifies the amount of time allowed for all pieces of a fragmented datagram to arrive. If all pieces do not arrive within this time, the datagram is discarded.
dwReasmReqds
Specifies the number of datagrams that require reassembly.
dwReasmOks
Specifies the number of datagrams that were successfully reassembled.
dwReasmFails
Specifies the number of datagrams that cannot be reassembled.
dwFragOks
Specifies the number of datagrams that were fragmented successfully.
dwFragFails
Specifies the number of datagrams that have not been fragmented because the IP header specifies no fragmentation. These datagrams are discarded.
dwFragCreates
Specifies the number of fragments created.
dwNumIf
Specifies the number of interfaces.
dwNumAddr
Specifies the number of IP addresses associated with this computer.
dwNumRoutes
Specifies the number of routes in the IP routing table.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iprtrmib.h.


MIB_MFE_TABLE

The MIB_MFE_TABLE structure contains a table of Multicast Forwarding Entries (MFEs).

typedef struct _MIB_MFE_TABLE {
  DWORD           dwNumEntries;      // number of entries
  MIB_IPMCAST_MFE table[ANY_SIZE];   // table of MFEs
} MIB_MFE_TABLE, *PMIB_MFE_TABLE;

Members

dwNumEntries
Specifies the number of multicast forwarding entries in the table.
table[ANY_SIZE]
Pointer to a table of multicast forwarding entries implemented as an array of MIB_IPMCAST_MFE structures.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Iprtrmib.h.

See Also

MIB_IPMCAST_MFE


MIB_MFE_STATS_TABLE

The MIB_MFE_STATS_TABLE structure stores statistics for a group of Multicast Forwarding Entries (MFE).

typedef struct _MIB_MFE_STATS_TABLE {
  DWORD   dwNumEntries;
  MIB_IPMCAST_MFE_STATS table[ANY_SIZE];
} MIB_MFE_STATS_TABLE, *PMIB_MFE_STATS_TABLE;

Members

dwNumEntries
Specifies the number of MFE entries in the array.
table[ANY_SIZE]
Pointer to a table of MFEs that are implemented as an array of MIB_IPMCAST_MFE_STATS structures.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Iprtrmib.h.

See Also

MIB_IPMCAST_MFE_STATS


MIB_OPAQUE_INFO

The MIB_OPAQUE_INFO structure contains information returned from a MIB opaque query.

typedef struct _MIB_OPAQUE_INFO {
  DWORD  dwId;

  union
  {
    ULONGLONG   ullAlign;
    BYTE        rgbyData[1];
  };

} MIB_OPAQUE_INFO, *PMIB_OPAQUE_INFO;

Members

dwId
Specifies the type of information returned.
ullAlign
Speficies bytes that align the information returned.
rgbyData
Pointer to the information returned from the opaque query.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Iprtrmib.h.

See Also

MIB_OPAQUE_QUERY


MIB_OPAQUE_QUERY

The MIB_OPAQUE_QUERY structure contains information for a MIB opaque query.

typedef struct _MIB_OPAQUE_QUERY {
  DWORD   dwVarId;
  DWORD   rgdwVarIndex[ANY_SIZE];
} MIB_OPAQUE_QUERY, *PMIB_OPAQUE_QUERY;

Members

dwVarId
Specifies the identifier of the MIB object to query.
rgdwVarIndex[ANY_SIZE]
Specifies the index of the MIB object to query.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Iprtrmib.h.

See Also

MIB_OPAQUE_INFO


MIB_PROXYARP

The MIB_PROXYARP structure stores information for a Proxy Address Resolution Protocol (PARP) entry.

typedef struct _MIB_PROXYARP {
  DWORD   dwAddress;    // address for which to proxy
  DWORD   dwMask;       // subnet mask for the address
  DWORD   dwIfIndex;    // interface on which to proxy
} MIB_PROXYARP, *PMIB_PROXYARP;

Members

dwAddress
Specifies the IP address for which to act as a proxy.
dwMask
Specifies the subnet mask for the IP address specified by the dwAddress member.
dwIfIndex
Specifies the index of the interface on which to act as a proxy for the address specified by the dwAddress member.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iprtrmib.h.

See Also

CreateProxyArpEntry, DeleteProxyArpEntry


MIB_TCPROW

The MIB_TCPROW structure contains information for a TCP connection.

typedef struct _MIB_TCPROW {
  DWORD   dwState;        // state of the connection
  DWORD   dwLocalAddr;    // address on local computer
  DWORD   dwLocalPort;    // port number on local computer
  DWORD   dwRemoteAddr;   // address on remote computer
  DWORD   dwRemotePort;   // port number on remote computer
} MIB_TCPROW, *PMIB_TCPROW;

Members

dwState
Specifies the state of the TCP connection. This member can have one of the following values.
Value | Description
MIB_TCP_STATE_CLOSED | To be determined.
MIB_TCP_STATE_LISTEN | To be determined.
MIB_TCP_STATE_SYN_SENT | To be determined.
MIB_TCP_STATE_SYN_RCVD | To be determined.
MIB_TCP_STATE_ESTAB | To be determined.
MIB_TCP_STATE_FIN_WAIT1 | To be determined.
MIB_TCP_STATE_FIN_WAIT2 | To be determined.
MIB_TCP_STATE_CLOSE_WAIT | To be determined.
MIB_TCP_STATE_CLOSING | To be determined.
MIB_TCP_STATE_LAST_ACK | To be determined.
MIB_TCP_STATE_TIME_WAIT | To be determined.
MIB_TCP_STATE_DELETE_TCB | Transmission Control Block (TCB) deleted.

dwLocalAddr
Specifies the address for the connection on the local computer.
dwLocalPort
Specifies the port number for the connection on the local computer.
dwRemoteAddr
Specifies the address for the connection on the remote computer.
dwRemotePort
Specifies the port number the connection on the remote computer.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iprtrmib.h.

See Also

MIB_TCPTABLE, SetTcpEntry


MIB_TCPSTATS

The MIB_TCPSTATS structure contains statistics for the TCP protocol running on the local computer.

typedef struct _MIB_TCPSTATS {
  DWORD   dwRtoAlgorithm;    // time-out algorithm
  DWORD   dwRtoMin;          // minimum time-out
  DWORD   dwRtoMax;          // maximum time-out
  DWORD   dwMaxConn;         // maximum connections
  DWORD   dwActiveOpens;     // active opens
  DWORD   dwPassiveOpens;    // passive opens
  DWORD   dwAttemptFails;    // failed attempts
  DWORD   dwEstabResets;     // established connections reset
  DWORD   dwCurrEstab;       // established connections
  DWORD   dwInSegs;          // segments received
  DWORD   dwOutSegs;         // segment sent
  DWORD   dwRetransSegs;     // segments retransmitted
  DWORD   dwInErrs;          // incoming errors
  DWORD   dwOutRsts;         // outgoing resets
  DWORD   dwNumConns;        // cumulative connections
} MIB_TCPSTATS, *PMIB_TCPSTATS;

Members

dwRtoAlgorithm
Specifies the retransmission time-out (RTO) algorithm in use. This member can be one of the following values.
Value | Description
MIB_TCP_RTO_CONSTANT | Constant Time-out
MIB_TCP_RTO_RSRE | MIL-STD-1778 Appendix B
MIB_TCP_RTO_VANJ | Van Jacobson's Algorithm
MIB_TCP_RTO_OTHER | Other

dwRtoMin
Specifies the minimum retransmission time-out value in milliseconds.
dwRtoMax
Specifies the maximum retransmission time-out value in milliseconds.
dwMaxConn
Specifies the maximum number of connections. If this member is -1, the maximum number of connections is dynamic.
dwActiveOpens
Specifies the number of active opens. In an active open, the client is initiating a connection with the server.
dwPassiveOpens
Specifies the number of passive opens. In a passive open, the server is listening for a connection request from a client.
dwAttemptFails
Specifies the number of failed connection attempts.
dwEstabResets
Specifies the number of established connections that have been reset.
dwCurrEstab
Specifies the number of currently established connections.
dwInSegs
Specifies the number of segments received.
dwOutSegs
Specifies the number of segments transmitted. This number does not include retransmitted segments.
dwRetransSegs
Specifies the number of segments retransmitted.
dwInErrs
Specifies the number of errors received.
dwOutRsts
Specifies the number of segments transmitted with the reset flag set.
dwNumConns
Specifies the cumulative number of connections.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iprtrmib.h.

See Also

GetTcpStatistics


MIB_TCPTABLE

The MIB_TCPTABLE structure contains a table of TCP connections.

typedef struct _MIB_TCPTABLE {
  DWORD      dwNumEntries;    // number of entries in the table
  MIB_TCPROW table[ANY_SIZE]; // array of TCP connections
} MIB_TCPTABLE, *PMIB_TCPTABLE;

Members

dwNumEntries
Specifies the number of entries in the table.
table[ANY_SIZE]
Pointer to a table of TCP connections implemented as an array of MIB_TCPROW structures.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iprtrmib.h.

See Also

GetTcpTable, MIB_TCPROW


MIB_UDPROW

The MIB_UDPROW structure contains address information for sending and receiving User Datagram Protocol (UDP) datagrams.

typedef struct _MIB_UDPROW {
  DWORD   dwLocalAddr;    // IP address on local computer
  DWORD   dwLocalPort;    // port number on local computer
} MIB_UDPROW, *PMIB_UDPROW;

Members

dwLocalAddr
Specifies the IP address on the local computer.
dwLocalPort
Specifies the port number on the local computer.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iprtrmib.h.

See Also

MIB_UDPSTATS, MIB_UDPTABLE


MIB_UDPSTATS

The MIB_UDPSTATS structure contains statistics for the User Datagram Protocol (UDP) running on the local computer.

typedef struct _MIB_UDPSTATS {
  DWORD   dwInDatagrams;    // received datagrams
  DWORD   dwNoPorts;        // datagrams for which no port exists
  DWORD   dwInErrors;       // errors on received datagrams
  DWORD   dwOutDatagrams;   // sent datagrams
  DWORD   dwNumAddrs;       // number of entries in
                            // UDP listener table
} MIB_UDPSTATS,*PMIB_UDPSTATS;

Members

dwInDatagrams
Specifies the number of datagrams received.
dwNoPorts
Specifies the number of received datagrams that were discarded because the port specified was invalid.
dwInErrors
Specifies the number of erroneous datagrams that were received. This number does not include the value contained by the dwNoPorts member.
dwOutDatagrams
Specifies the number of datagrams transmitted.
dwNumAddrs
Specifies the number of entries in the UDP listener table.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iprtrmib.h.

See Also

GetUdpStatistics, MIB_UDPROW


MIB_UDPTABLE

The MIB_UDPTABLE structure contains a table of MIB_UDPROW structures.

typedef struct _MIB_UDPTABLE {
  DWORD       dwNumEntries;    // number of entries in the table
  MIB_UDPROW  table[ANY_SIZE]; // table of MIB_UDPROW structs
} MIB_UDPTABLE, *PMIB_UDPTABLE;

Members

dwNumEntries
Specifies the number of entries in the table.
table[ANY_SIZE]
Pointer to an array of MIB_UDPROW structures.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iprtrmib.h.

See Also

GetUdpTable, MIB_UDPROW


MIBICMPINFO

The MIBICMPINFO structure contains Internet Control Message Protocol (ICMP) statistics for a particular computer.

typedef    struct _MIBICMPINFO {
  MIBICMPSTATS   icmpInStats;    // stats for incoming messages
  MIBICMPSTATS   icmpOutStats;   // stats for outgoing messages
} MIBICMPINFO;

Members

icmpInStats
Specifies an MIBICMPSTATS structure that contains the statistics for incoming ICMP messages.
icmpOutStats
Specifies an MIBICMPSTATS structure that contains the statistics for outgoing ICMP messages.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iprtrmib.h.

See Also

MIB_ICMP, MIBICMPSTATS


MIBICMPSTATS

The MIBICMPSTATS structure contains statistics for either incoming or outgoing Internet Control Message Protocol (ICMP) messages on a particular computer.

typedef struct _MIBICMPSTATS {
  DWORD   dwMsgs;            // number of messages
  DWORD   dwErrors;          // number of errors
  DWORD   dwDestUnreachs;    // destination unreachable messages
  DWORD   dwTimeExcds;       // time-to-live exceeded messages
  DWORD   dwParmProbs;       // parameter problem messages
  DWORD   dwSrcQuenchs;      // source quench messages
  DWORD   dwRedirects;       // redirection messages
  DWORD   dwEchos;           // echo requests
  DWORD   dwEchoReps;        // echo replies
  DWORD   dwTimestamps;      // time-stamp requests
  DWORD   dwTimestampReps;   // time-stamp replies
  DWORD   dwAddrMasks;       // address mask requests
  DWORD   dwAddrMaskReps;    // address mask replies
} MIBICMPSTATS;

Members

dwMsgs
Specifies the number of messages received or sent.
dwErrors
Specifies the number of errors received or sent.
dwDestUnreachs
Specifies the number of destination-unreachable messages received or sent. A destination-unreachable message is sent to the originating computer when a datagram fails to reach its intended destination.
dwTimeExcds
Specifies the number of time-to-live (TTL) exceeded messages received or sent. A time-to-live exceeded message is sent to the originating computer when a datagram is discarded because the number of routers it has passed through exceeds its time-to-live value.
dwParmProbs
Specifies the number of parameter-problem messages received or sent. A parameter-problem message is sent to the originating computer when a router or host detects an error in a datagram's IP header.
dwSrcQuenchs
Specifies the number of source quench messages received or sent. A source quench request is sent to a computer to request that it reduce its rate of packet transmission.
dwRedirects
Specifies the number of redirect messages received or sent. A redirect message is sent to the originating computer when a better route is discovered for a datagram sent by that computer.
dwEchos
Specifies the number of echo requests received or sent. An echo request causes the receiving computer to send an echo reply message back to the originating computer.
dwEchoReps
Specifies the number of echo replies received or sent. A computer sends an echo reply in response to receiving an echo request message.
dwTimestamps
Specifies the number of time-stamp requests received or sent. A time-stamp request causes the receiving computer to send a time-stamp reply back to the originating computer.
dwTimestampReps
Specifies the number of time-stamp replies received or sent. A computer sends a time-stamp reply in response to receiving a time-stamp request. Routers can use time-stamp requests and replies to measure the transmission speed of datagrams on a network.
dwAddrMasks
Specifies the number of address mask requests received or sent. A computer sends an address mask request to determine the number of bits in the subnet mask for its local subnet.
dwAddrMaskReps
Specifies the number of address mask responses received or sent. A computer sends an address mask response in response to an address mask request.

Remarks

Two MIBICMPSTATS structures are required to hold all the ICMP statistics for a given computer. One MIBICMPSTATS structure contains the statistics for incoming ICMP messages. The other contains the statistics for outgoing ICMP messages. For this reason, the MIBICMPINFO structure contains two MIBICMPSTATS structures.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iprtrmib.h.

See Also

MIB_ICMP, MIBICMPINFO


Transport and Protocol Constants

Use the following constants with router administration and configuration functions, and with the MIB API:

  • Transport Identifiers
  • Protocol Identifiers


Transport Identifiers

The following transport identifiers are also listed in Mprapi.h:

PID_IPX

PID_IP

PID_NBF

See Also

MIB Reference, Transport and Protocol Constants


Protocol Identifiers

The following protocol identifiers are also listed in Routprot.h.

IP Protocols

The following routing protocols are associated with the IP transport.

Protocol | Description
PROTO_IP_OTHER | Protocol not listed here.
PROTO_IP_LOCAL | Routes generated by the stack.
PROTO_IP_NETMGMT | Routes added by "route add" or through SNMP.
PROTO_IP_ICMP | Routes from ICMP redirects.
PROTO_IP_EGP | Exterior Gateway Protocol.
PROTO_IP_GGP | To be determined.
PROTO_IP_HELLO | HELLO routing protocol.
PROTO_IP_RIP | Routing Informaton Protocol.
PROTO_IP_IS_IS | To be determined.
PROTO_IP_ES_IS | To be determined.
PROTO_IP_CISCO | To be determined.
PROTO_IP_BBN | To be determined.
PROTO_IP_OSPF | Open Shortest Path First routing protocol.
PROTO_IP_BGP | Border Gateway Protocol.
PROTO_IP_BOOTP | Bootstrap Protocol.
PROTO_IP_NT_AUTOSTATIC | Routes that were originally generated by a routing protocol, but which are now static.
PROTO_IP_NT_STATIC | Routes that were added from the routing user interface, or by "routemon ip add".
PROTO_IP_NT_STATIC_NON_DOD | Identical to PROTO_IP_NET_STATIC, except these routes do not cause Dial On Demand (DOD).

Routes with a protocol identifier of PROTO_IP_LOCAL include:

  • The loopback route
  • The subnet route
  • All networks broadcast route for subnetted interfaces
  • All "1"s broadcast route
  • Local multicast route
  • Route to remote end of a PPP link

The identifier for the IP router manager is:

IPRTRMGR_PID

This identifier can be used instead of a routing protocol identifier for MIB calls with the IP router manager. This identifier is used for MIB-II, Forwarding MIB, and some enterprise specific information. This identifier is also listed in Iprtrmib.h.

IPX Protocols

The following routing protocols are associated with the IPX transport.

Protocol | Description
IPX_PROTOCOL_RIP | Routing Information Protocol for IPX
IPX_PROTOCOL_SAP | Service Advertisement Protocol
IPX_PROTOCOL_NLSP | Netware Link Services Protocol

The identifier for the IPX router manager is:

IPX_PROTOCOL_BASE

Use this identifier instead of a routing protocol identifier for MIB calls with the IPX router manager.


Packet Filtering Reference

Packet filtering enables the developer to create and manage input and output filters for IP packets. Each IP adapter interface can be associated with one or more filters. Filters can include source and destination addresses, address mask and port; and protocol identifiers.

With the exception of the PfGetInterfaceStatistics function, all of the functions described in this section require administrative permissions.

The following reference elements are found in the Fltdefs.h header file:

  • Packet Filtering Functions
  • Packet Filtering Structures
  • Packet Filtering Enumerated Types


Packet Filtering Functions

Use the following functions to manage IP packet filters:

PfAddFiltersToInterface

PfAddGlobalFilterToInterface

PfBindInterfaceToIndex

PfBindInterfaceToIPAddress

PfCreateInterface

PfDeleteInterface

PfDeleteLog

PfGetInterfaceStatistics

PfMakeLog

PfRebindFilters

PfRemoveFilterHandles

PfRemoveFiltersFromInterface

PfRemoveGlobalFilterFromInterface

PfSetLogBuffer

PfTestPacket

PfUnBindInterface


PfAddFiltersToInterface

The PfAddFiltersToInterface function adds the specified filters to the specified interface.

PfAddFiltersToInterface(
  INTERFACE_HANDLE ih,
  DWORD cInFilters,
  PPF_FILTER_DESCRIPTOR pfiltIn,
  DWORD cOutFilters,
  PPF_FILTER_DESCRIPTOR pfiltOut,
  PFILTER_HANDLE pfHandle
);

Parameters

ih
[in] Specifies a handle to the interface.
cInFilters
[in] Specifies the number of input filter descriptions pointed to by the pfiltIn parameter.
pfiltIn
[in] Pointer to an array of filter descriptions to use as input filters.
cOutFilters
[in] Specifies the number of output filter descriptions pointed to by the pfiltOut parameter.
pfiltOut
[in] Pointer to an array of filter descriptions to use as output filters.
pfHandle
[out] Pointer to a buffer that receives an array of filter handles. If the caller does not require the filter handles, the caller may set this parameter to NULL.

Remarks

A filter reverses the default processing rule for the interface, that is, the rule that was specified during the call to PfCreateInterface.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
PFERROR_NO_FILTERS_GIVEN | No filter descriptions were supplied
Other | Use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Fltdefs.h.
Library: Use Iphlpapi.lib.

See Also

PfRemoveFiltersFromInterface, PfRemoveFilterHandles


PfAddGlobalFilterToInterface

The PfAddGlobalFilterToInterface function adds a global filter on the specified interface.

DWORD PfAddGlobalFilterToInterface(
  INTERFACE_HANDLE pInterface,
  GLOBAL_FILTER gfFilter
);

Parameters

pInterface
[in] Handle to the interface.
gfFilter
[in] Specifies the global filter to add to the interface.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Remarks

The global filter acts across all filters on the interface.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Fltdefs.h.
Library: Use Iphlpapi.lib.

See Also

GLOBAL_FILTER, PfRemoveGlobalFilterFromInterface


PfBindInterfaceToIndex

The PfBindInterfaceToIndex function associates an interface with the specified IP stack index.

DWORD PfBindInterfaceToIndex(
  INTERFACE_HANDLE pInterface,
  DWORD dwIndex,
  PFADDRESSTYPE pfatLinkType,
  PBYTE LinkIPAddress
);

Parameters

pInterface
[in] Specifies a handle to the interface to associate with the IP stack index.
dwIndex
[in] Specifies the IP stack index to which to associate the interface.
pfatLinkType
[in] Specifies the address type for the interface. This parameter is of type PFADDRESSTYPE.
LinkIPAddress
[in] Pointer to an array of bytes that specifies the IP address for the interface.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_IPV6_NOT_IMPLEMENTED | The IPV6 address type is not yet implemented.
Other | Use FormatMessage to obtain the message string for the returned error.

Remarks

Use the IP Helper functions to obtain a stack index.

An application should support the possibility of interface indexes changing due to Plug and Play.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Fltdefs.h.
Library: Use Iphlpapi.lib.

See Also

PFADDRESSTYPE, PfBindInterfaceToIPAddress, PfUnbindInterface


PfBindInterfaceToIPAddress

The PfBindInterfaceToIPAddress function associates an interface with the IP stack index having the specified address.

DWORD PfBindInterfaceToIPAddress(
  INTERFACE_HANDLE pInterface,
  PFADDRESSTYPE pfatType,
  PBYTE IPAddress
);

Parameters

pInterface
[in] Specifies a handle to the interface to associate with the IP stack index.
pfatType
[in] Specifies the address type for the interface. This parameter is of type PFADDRESSTYPE.
IPAddress
[in] Pointer to an array of bytes that specifies the IP address for the interface.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_IPV6_NOT_IMPLEMENTED | The IPV6 address type is not yet implemented.
Other | Use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Fltdefs.h.
Library: Use Iphlpapi.lib.

See Also

PFADDRESSTYPE, PfBindInterfaceToIndex


PfCreateInterface

The PfCreateInterface function creates a new filter interface. Use this interface to control the adding and deleting of filters to and from adapters.

PfCreateInterface(
  DWORD dwName,
  PFFORWARD_ACTION inAction,
  PFFORWARD_ACTION outAction,
  BOOL bUseLog,
  BOOL bMustBeUnique,
  INTERFACE_HANDLE *ppInterface
);

Parameters

dwName
[in] Specifies the interface name. A zero value specifies a new, unique interface. Any other value is a potentially shared interface.

The bMustBeUnique parameter can turn a shared interface into a unique one. However, using bMustBeUnique in this way can cause the function to fail.

inAction
[in] Specifes a default action for an input packet. This member can be one of the following values.
Value | Meaning
PF_ACTION_FORWARD | Forward the packet.
PF_ACTION_DROP | Discard the packet.

outAction
[in] Specifies a default action for an output packet. This member can be one of the following values.
Value | Meaning
PF_ACTION_FORWARD | Forward the packet.
PF_ACTION_DROP | Discard the packet.

bUseLog
[in] Specifies whether to bind the log to this interface. If this member is TRUE, the log will be bound to this interface.
bMustBeUnique
[in] Specifies whether the interface is unique or shared. If this member is TRUE, this interface is unique, that is, it cannot be shared.
ppInterface
[out] Pointer to a pointer that, on successful return, points to an interface handle to use with subsequent function calls.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Remarks

An interface can either be unique to a process or shared. If an interface is shared, other processes may add or remove filters.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Fltdefs.h.
Library: Use Iphlpapi.lib.

See Also

PfAddFiltersToInterface, PfRemoveFiltersFromInterface, PfDeleteInterface


PfDeleteInterface

The PfDeleteInteface function deletes an interface that was previously created using PfCreateInterface.

PfDeleteInterface(
  INTERFACE_HANDLE pInterface
);

Parameters

pInterface
[in] Specifies an interface handle obtained from a previous call to PfCreateInterface.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Fltdefs.h.
Library: Use Iphlpapi.lib.

See Also

PfCreateInterface


PfDeleteLog

The PfDeleteLog function immediately disables the log on all interfaces with which it is associated. The log is deleted when all interfaces associated with the log are deleted.

DWORD PfDeleteLog(VOID);

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Fltdefs.h.
Library: Use Iphlpapi.lib.

See Also

PfMakeLog, PfSetLogBuffer


PfGetInterfaceStatistics

The PfGetInterfaceStatistics function retrieves statistics for the specified interface. This function can also, optionally, retrieve statistics for the filters associated with this interface.

DWORD PfGetInterfaceStatistics(
  INTERFACE_HANDLE pInterface,
  PPF_INTERFACE_STATS ppfStats,
  PDWORD pdwBufferSize,
  BOOL fResetCounters
);

Parameters

pInterface
[in] Handle to the interface.
ppfStats
Pointer to a buffer that receives the statistics for the interface.

If the caller requires only the statistics for the interface, this buffer should be of a size equal to a PF_INTERFACE_STATS structure. If the caller supplies a buffer that is smaller than this size, PfGetInterfaceStatistics returns PFERROR_BUFFER_TOO_SMALL, and the pdwBufferSize parameter contains a size equal to a PF_INTERFACE_STATS structure.

If the caller requires the statistics for both the interface and the associated filters, the buffer should be of a size greater than PF_INTERFACE_STATS. If the buffer is still not large enough, PfGetInterfaceStatistics returns ERROR_INSUFFICIENT_BUFFER, and the pdwBufferSize parameter points to a DWORD variable that contains a buffer size large enough to hold both the interface and filter statistics.

pdwBufferSize
[in] Pointer to a DWORD variable that specifies the size of the buffer pointed to by the ppfStats parameter.
fResetCounters
[in] Specifies whether the statistics counters for the interface should be reset. If this parameter is TRUE, the statistics counters are reset.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INSUFFICIENT_BUFFER | This error is specific to PfGetInterfaceStatistics and means that the supplied user buffer is too small for the filters. The correct size is returned as the interface statistics that contain the filter counts.
PFERROR_BUFFER_TOO_SMALL | This error is specific to PfGetInterfaceStatistics and means the user buffer is too small even for the interface statistics. The returned size is the size of the interface statistics, but does not include space for filters. If the function is called using this size, the return value should be ERROR_INSUFFICIENT_BUFFER.
Other | Use FormatMessage to obtain the message string for the returned error.

Remarks

The caller may call PfGetInterfaceStatistics twice. Initially, to obtain the correct buffer size, then a second time to retrieve the statistics. If the caller calls PfGetInterfaceStatistics twice for a shared interface, the second call may fail with ERROR_INSUFFICIENT_BUFFER. This error can occur because the other sharers may add filters to the interface in the interval between the two calls. This type of error should not occur for a UNIQUE interface.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Fltdefs.h.
Library: Use Iphlpapi.lib.

See Also

PF_INTERFACE_STATS


PfMakeLog

The PfMakeLog function creates a log to use with an interface or set of interfaces.

WORD PfMakeLog(
  HANDLE hEvent
);

Parameters

hEvent
[in] Handle to a Win32 event object. The caller can use this event object to obtain notification when a specified number of bytes have been used in the log's buffer, or when a certain number of entries have been created in the log. For more information, see PfSetLogBuffer.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Remarks

Only one log exists. The log can be used with multiple interfaces.

The interface log must be created before the interfaces with which it will be used. It is not possible to associate a log with an already existing interface.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Fltdefs.h.
Library: Use Iphlpapi.lib.

See Also

PfDeleteLog, PfSetLogBuffer


PfRebindFilters

The PfRebindFilters function rebinds the filters on the specified interface.

DWORD PfRebindFilters(
  INTERFACE_HANDLE pInterface,
  PPF_LATEBIND_INFO pLateBindInfo
);

Parameters

pInterface
[in] Handle to the interface.
pLateBindInfo
[in] Pointer to the late-binding information for the interface.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Remarks

The fLateBound member of PF_FILTER_DESCRIPTOR for each filter determines how the information pointed to by the pLateBindInfo parameter affects the filter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Fltdefs.h.
Library: Use Iphlpapi.lib.

See Also

PF_FILTER_DESCRIPTOR


PfRemoveFilterHandles

The PfRemoveFilterHandles function removes the filter associated with the specified handles.

DWORD PfRemoveFilterHandles(
  INTERFACE_HANDLE pInterface,
  DWORD cFilters,
  PFILTER_HANDLE pvHandles
);

Parameters

pInterface
[in] Specifies a handle to the interface.
cFilters
[in] Specifies the number of filter handles pointed to by the pvHandles parameter. Obtain these handles from the PfAddFiltersToInterface function.
pvHandles
[in] Pointer to an array of filter handles that specify the filters to remove.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Fltdefs.h.
Library: Use Iphlpapi.lib.

See Also

PfAddFiltersToInterface, PfRemoveFiltersFromInterface


PfRemoveFiltersFromInterface

The PfRemoveFiltersFromInterface function removes the specified filters from the interface.

DWORD PfRemoveFiltersFromInterface(
  INTERFACE_HANDLE ih,
  DWORD cInFilters,
  PPF_FILTER_DESCRIPTOR pfiltIn,
  DWORD cOutFilters,
  PPF_FILTER_DESCRIPTOR pfiltOut
);

Parameters

ih
[in] Handle to the interface.
cInFilters
[in] Specifies the number of input filter descriptions pointed to by the pfiltIn parameter.
pfiltIn
[in] Pointer to an array of filter descriptions to use as input filters.
cOutFilters
[in] Specifies the number of output filters descriptions pointed to by the pfiltOut parameter.
pfiltOut
[in] Pointer to an array of filter descriptions to use as output filters.

Return Values

If the function succeeds, the return value is NO_ERROR.

Value | Meaning
PFERROR_NO_FILTERS_GIVEN | No filter descriptions were supplied
Other | Use FormatMessage to obtain the message string for the returned error.

Remarks

The filter description passed in through the pfiltIn and pfiltOut parameters must be an exact match to a filter that was added previously.

No error is returned if a matching filter is not found.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Fltdefs.h.
Library: Use Iphlpapi.lib.

See Also

PfAddFiltersToInterface


PfRemoveGlobalFilterFromInterface

The PfRemoveGlobalFilterFromInterface function removes the specified global filter from the interface.

DWORD PfRemoveGlobalFilterFromInterface(
  INTERFACE_HANDLE pInterface,
  GLOBAL_FILTER gfFilter
);

Parameters

pInterface
[in] Handle to the interface.
gfFilter
[in] Specifies the global filter to remove from the interface.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Fltdefs.h.
Library: Use Iphlpapi.lib.

See Also

GLOBAL_FILTER, PfAddGlobalFilterToInterface


PfSetLogBuffer

The PfSetLogBuffer function exchanges the log current buffer for a new one.

DWORD PfSetLogBuffer(
  PBYTE pbBuffer,
  DWORD dwSize,
  DWORD dwThreshold,
  DWORD dwEntries,
  PDWORD pdwLoggedEntries,
  PDWORD pdwLostEntries,
  PDWORD pdwSizeUsed
);

Parameters

pbBuffer
[in] Pointer to the new log buffer. This buffer must be quad-word aligned.
dwSize
[in] Specifies the size, in bytes, of the new buffer.
dwThreshold
[in] Specifies the number of bytes used before signaling the event object associated with the log.
dwEntries
[in] Specifies the number of entries in the log that will cause the event object to be signaled.
pdwLoggedEntries
[out] Pointer to a DWORD variable that receives the number of entries in the old buffer.
pdwLostEntries
[out] Pointer to a DWORD variable that receives the number of entries that could not be put into the old buffer.
pdwSizeUsed
[out] Pointer to a DWORD variable that receives the number of bytes used in the old buffer.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Fltdefs.h.
Library: Use Iphlpapi.lib.

See Also

PfMakeLog, PfDeleteLog


PfTestPacket

The PfTestPacket function tests the specified packet and returns the action that would be performed given the specified interface.

DWORD PfTestPacket(
  INTERFACE_HANDLE pInInterface  OPTIONAL,
  INTERFACE_HANDLE pOutInterface OPTIONAL,
  DWORD cBytes,
  PBYTE pbPacket,
  PPFFORWARD_ACTION ppAction
);

Parameters

pInInterface
[in] Handle to an interface to use as an input interface for the packet. This parameter is optional and may be NULL.
pOutInterface
[in] Handle to an interface to use as an output interface for the packet. This parameter is optional and may be NULL.
cBytes
pbPacket
[in] Pointer to a network packet to test with the specified interface (or interfaces).
ppAction
[out] Pointer to a variable of type PFFORWARD_ACTION. This variable receives the action that would have been taken given the specified interface(s) and packet.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Remarks

Specifying only an input interface simulates a packet destined for the local computer. Specifying only an output interface simulates sending a packet from the local computer. Specifying both an input and an output interface simulates routing a network packet.

If the caller does not specify any interfaces, the PfTestPacket returns PF_ACTION_FORWARD in the ppAction parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Fltdefs.h.
Library: Use Iphlpapi.lib.

See Also

PFFORWARD_ACTION


PfUnBindInterface

The PfUnBindInterface function unbinds the interface from the stack.

DWORD PfUnBindInterface(
  INTERFACE_HANDLE pInterface
);

Parameters

pInterface
[in] Specifies the interface to unbind from the stack.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, use FormatMessage to obtain the message string for the returned error.

Remarks

Unbinding the interface does not destroy the interface or any of its filters.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Fltdefs.h.
Library: Use Iphlpapi.lib.

See Also

PfBindInterfaceToIndex


Packet Filtering Structures

Use the following structures when managing IP packet filters:

PF_FILTER_DESCRIPTOR

PF_FILTER_STATS

PF_INTERFACE_STATS

PF_LATEBIND_INFO

PFLOGFRAME


PF_FILTER_DESCRIPTOR

The PF_FILTER_DESCRIPTOR structure contains the information that defines a packet filter.

typedef struct _PF_FILTER_DESCRIPTOR {
  DWORD          dwFilterFlags;    // see below
  DWORD          dwRule;           // copied into the log when appropriate
  PFADDRESSTYPE  pfatType;
  PBYTE          SrcAddr;
  PBYTE          SrcMask;
  PBYTE          DstAddr;
  PBYTE          DstMask;
  DWORD          dwProtocol;
  DWORD          fLateBound;
  WORD           wSrcPort;
  WORD           wDstPort;
  WORD           wSrcPortHighRange;
  WORD           wDstPortHighRange;
} PF_FILTER_DESCRIPTOR, *PPF_FILTER_DESCRIPTOR;

Members

dwFilterFlags
Currently only a single flag is supported for this member:

FD_FLAGS_NOSYN

dwRule
Specifies the rule for the filter.
pfatType
Specifies the address type for the filter. This member is of type PFADDRESSTYPE.
SrcAddr
Specifies the source address of the packets to filter.
SrcMask
Specifies the subnet mask for the source address.
DstAddr
Specifies the destination address of the packets to filter.
DstMask
Specifies the subnet mask for the destination address.
dwProtocol
Specifies the protocols to filter. This member can be one of the following values.
Value | Meaning
FILTER_PROTO_ANY | All protocols
FILTER_PROTO_ICMP | Internet Control Message Protocol
FILTER_PROTO_TCP | Transmission Control Protocol
FILTER_PROTO_UDP | User Datagram Protocol

fLateBound
Specifies the address information that should be updated when the filter is rebound. This member can be any combination of the following flags:

LB_SRC_ADDR_USE_SRCADDR_FLAG
LB_SRC_ADDR_USE_DSTADDR_FLAG
LB_DST_ADDR_USE_SRCADDR_FLAG
LB_DST_ADDR_USE_DSTADDR_FLAG

wSrcPort
Specifies the source port of the packets to filter.
wDstPort
Specifies the destination port of the packets to filter.
wSrcPortHighRange
Specifies the high range of the source port of packets to filter.
wDstPortHighRange
Specifies the high range of the destination port of packets to filter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Fltdefs.h.

See Also

PF_LATEBIND_INFO, PfAddFiltersToInterface, PfRebindFilters


PF_FILTER_STATS

The PF_FILTER_STATS structure contains a description of a particular filter and the number of packets filtered by the filter.

typedef struct _PF_FILTER_STATS {
  DWORD       dwNumPacketsFiltered;
  PF_FILTER_DESCRIPTOR info;
} PF_FILTER_STATS, *PPF_FILTER_STATS;

Members

dwNumPacketsFiltered
Specifies the number of packets filtered by the filter specified by the info member.
info
Specifies a PF_FILTER_DESCRIPTOR that describes a particular filter.

Remarks

The PF_INTERFACE_STATS structure contains an array of PF_FILTER_STATS structures. Each element of the PF_FILTER_STATS array corresponds to a filter associated with the PF_INTERFACE_STATS interface.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Fltdefs.h.

See Also

PF_FILTER_DESCRIPTOR, PF_INTERFACE_STATS, PfGetInterfaceStatistics


PF_INTERFACE_STATS

The PF_INTERFACE_STATS structure contains statistics for an interface.

typedef struct _PF_INTERFACE_STATS {
  PVOID             pvDriverContext;
  DWORD             dwFlags;
  DWORD             dwInDrops;
  DWORD             dwOutDrops;
  PFFORWARD_ACTION  eaInAction;
  PFFORWARD_ACTION  eaOutAction;
  DWORD             dwNumInFilters;
  DWORD             dwNumOutFilters;
  DWORD             dwFrag;
  DWORD             dwSpoof;
  DWORD             dwReserved1;
  DWORD             dwReserved2;
  LARGE_INTEGER     liSYN;
  LARGE_INTEGER     liTotalLogged;
  DWORD             dwLostLogEntries;
  PF_FILTER_STATS   FilterInfo[1];
} PF_INTERFACE_STATS, *PPF_INTERFACE_STATS;

Members

pvDriverContext
This member is not currently used.
dwFlags
No flags are currently defined for this member.
dwInDrops
Specifies the number of incoming packets that were dropped.
dwOutDrops
Specifies the number of outgoing packets that were dropped.
eaInAction
Specifies the default incoming action.
eaOutAction
Specifies the default outgoing action.
dwNumInFilters
Specifies the number of filters for incoming packets.
dwNumOutFilters
Specifies the number of filters for outgoing packets.
dwFrag
Specifies the state of global fragment checking. See GLOBAL_FILTER for more information.
dwSpoof
Specifies the state of global checking of destination addresses. See GLOBAL_FILTER for more information.
dwReserved1
Reserved. This member should be zero.
dwReserved2
Reserved. This member should be zero.
liSYN
Specifies the number of SYN packets discarded.
liTotalLogged
Specifies the number of packets logged.
dwLostLogEntries
Specifies the number of logged packets lost because of buffering problems.
FilterInfo[1]
Specifies an array of PF_FILTER_STATS structures. The array contains an element for each filter associated with the interface. Each element contains a description of the filter and the number of packets filtered by that filter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Fltdefs.h.

See Also

GLOBAL_FILTER, PfGetInterfaceStatistics, PF_FILTER_STATS, PFFORWARD_ACTION


PF_LATEBIND_INFO

The PF_LATEBIND_INFO structure contains address information for late-binding interface.

typedef struct _PF_LATEBIND_INFO {
  PBYTE  SrcAddr;
  PBYTE  DstAddr;
  PBYTE  Mask;
} PF_LATEBIND_INFO, *PPF_LATEBIND_INFO;

Members

SrcAddr
Specifies a new source address.
DstAddr
Specifies a new destination address.
Mask
Specifies a subnet mask.

Remarks

Late-binding information is typically used with Wide Area Network (WAN) interfaces. The address information for such interfaces usually changes at the time they establish a connection.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Fltdefs.h.

See Also

PF_FILTER_DESCRIPTOR, PfRebindFilters


PFLOGFRAME

The PFLOGFRAME structure stores the information for a log entry.

typedef struct _pfLogFrame {
  LARGE_INTEGER  Timestamp;
  PFFRAMETYPE    pfeTypeOfFrame;
  DWORD          dwTotalSizeUsed;
  DWORD          dwFilterRule;
  WORD           wSizeOfAdditionalData;
  WORD           wSizeOfIpHeader;
  DWORD          dwInterfaceName;
  DWORD          dwIPIndex;
  BYTE           bPacketData[1];wsizeOfIpHeader
} PFLOGFRAME, *PPFLOGFRAME;

Members

Timestamp
pfeTypeOfFrame
Variable of type PFFRAMETYPE that specifies the reason the packet was filtered.
dwTotalSizeUsed
The total size, in bytes, of this entry. Use this value to find the next log entry in a sequence of entries.
dwFilterRule
Specifies the rule for the filter.
wSizeOfAdditionalData
Specifies additional data for the rule.
wSizeOfIpHeader
Size of the IP header for the packet.
dwInterfaceName
The name of the interface.
dwIPIndex
The index of the interface on which the packet was sent or received.
bPacketData[1]

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Fltdefs.h.

See Also

PFFRAMETYPE, PfMakeLog, PfSetLogBuffer, PfDeleteLog


Packet Filtering Enumerated Types

Use the following enumerated types when managing IP packet filters:

GLOBAL_FILTER

PFADDRESSTYPE

PFFORWARD_ACTION

PFFRAMETYPE


GLOBAL_FILTER

The GLOBAL_FILTER type enumerates the kinds of global filters that can be applied to an interface.

typedef enum _GlobalFilter {
  GF_FRAGMENTS = 2,
  GF_STRONGHOST = 8,
  GF_FRAGCACHE = 9
} GLOBAL_FILTER, *PGLOBAL_FILTER;

Values

GF_FRAGMENTS
Causes a consistency check of packet fragments.
GF_STRONGHOST
Causes a check of the destination address of incoming packets.
GF_FRAGCACHE
Causes a check of the fragments from the cache.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Fltdefs.h.

See Also

PF_INTERFACE_STATS, PfAddGlobalFilterToInterface, PfRemoveGlobalFilterFromInterface


PFADDRESSTYPE

The PFADDRESSTYPE type enumerates the address formats supported by filter interface.

typedef enum _PfAddresType {
  PF_IPV4,
  PF_IPV6
} PFADDRESSTYPE, *PPFADDRESSTYPE;

Values

PF_IPV4
The address format used with Internet Protocol v4.
PF_IPV6
The address format used with Internet Protocol v6.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Fltdefs.h.

See Also

PfBindInterfaceToIndex, PfBindInterfaceToIPAddress


PFFORWARD_ACTION

The PFFORWARD_ACTION type enumerates the possible ways in which a filter interface can process a network packet.

typedef enum _PfForwardAction {
  PF_ACTION_FORWARD = 0,
  PF_ACTION_DROP
} PFFORWARD_ACTION, *PPFFORWARD_ACTION;

Values

PF_ACTION_FORWARD
The interface forwards the network packet.
PF_ACTION_DROP
The interface discards the network packet.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Fltdefs.h.

See Also

PF_INTERFACE_STATS, PfTestPacket


PFFRAMETYPE

The PFFRAMETYPE type enumerates the reasons why a packet was filtered.

typedef enum _PfFrameType {
  PFFT_FILTER  = 1,
  PFFT_FRAG    = 2,
  PFFT_SPOOF   = 3
} PFFRAMETYPE, *PPFFRAMETYPE;

Values

PFFT_FILTER
The packet violated a filter rule.
PFFT_FRAG
A bad fragment was detected.
PFFT_SPOOF
A check of the destination address resulted in a "strong host" failure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Fltdefs.h.

See Also

PFLOGFRAME, GLOBAL_FILTER


About Routing Protocol Interface

The following documentation describes the integration of third-party routing protocols into the Routing and Remote Access Service (RRAS). RRAS is a feature of Microsoft® Windows® 2000 that acts as a multiprotocol router. RRAS defines the interface between the router manager and the routing protocol. The routing protocol is implemented in a dynamic link library (DLL).

Use this interface to implement routing protocols, such as IGRP, NLSP, and BGP, as user-mode DLLs that work with RRAS.

This documentation describes the following topics:

  • Adapters
  • Interfaces
  • Static and Autostatic Routes


Adapters

An adapter represents the hardware that connects to a particular network segment. A bound LAN card is one example of an adapter. Similarly, a computer 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.


Routing Protocol Interface Reference

This documentation describes the functions and structures that are used to implement a routing protocol as a user-mode DLL. These reference elements are described in the following topics:

  • Routing Protocol Interface Functions
  • Routing Protocol Interface Structures


Routing Protocol Interface Functions

Implement the following functions for a routing protocol DLL:

AddInterface

ConnectClient

DeleteInterface

DisconnectClient

DoUpdateRoutes

GetEventMessage

GetGlobalInfo

GetInterfaceInfo

GetMfeStatus

GetNeighbors

InterfaceStatus

MibCreate

MibDelete

MibGet

MibGetFirst

MibGetNext

MibSet

MibSetTrapInfo

QueryPower

RegisterProtocol

SetGlobalInfo

SetInterfaceInfo

SetPower

StartComplete

StartProtocol

StopProtocol

UnbindInterface

If the routing protocol supports service handling, implement the following function in addition to those listed preceding:

DoUpdateServices


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 router manager enables the interface by calling InterfaceStatus with the RIS_INTERFACE_ENABLED flag.

DWORD AddInterface(
  LPWSTR InterfaceName,  // name of the interface
  ULONG InterfaceIndex,  // index for the interface
  NET_INTERFACE_TYPE InterfaceType,
                         // type of the interface
  DWORD MediaType,
  WORD AccessType,
  WORD ConnectionType,
  PVOID InterfaceInfo,   // interface information block
  ULONG StructureVersion,
  ULONG StructureSize,
  ULONG StructureCount
);

Parameters

InterfaceName
[in] 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
[in] Specifies the interface in the set of interfaces configured on the router.
InterfaceType
[in] Specifies 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.

MediaType
[in] Specifies the media type.
AccessType
[in] Specifies the type of network access.
ConnectionType
[in] Specifies the type of network connection.
InterfaceInfo
[in] Pointer to a buffer that specifies protocol-defined configuration information associated with the interface. This information is private to the routing protocol.
StructureVersion
[in] Specifies the version of the information structures pointed to by the InterfaceInfo parameter. In some cases, this is equal to the version of the routing protocol.
StructureSize
[in] Specifies the size of each of the information structures pointed to by the InterfaceInfo parameter. Since some information structures contain variable length members, the routing protocol isn't necessarily able to determine the size of the information from the version.
StructureCount
[in] Specifies a count of the number of information structures pointed to by the InterfaceInfo parameter. This parameter is always one.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Routing Protocol Interface Reference, Routing Protocol Interface Functions, DeleteInterface


ConnectClient

The router manager calls the ConnectClient function when a client connects to an interface on which the routing protocol is running.

typedef DWORD (WINAPI *PCONNECT_CLIENT) (
  ULONG InterfaceIndex,
  PVOID ClientAddress
);

Parameters

InterfaceIndex
[in] Specifies the index of the interface on which the client is connecting.
ClientAddress
[in] Pointer to the address (e.g. the IP address) of the connecting client.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value should be one of the following error codes.

Value | Description
ERROR_INVALID_PARAMETER | At least one of the following is true: The InterfaceIndex parameter is invalid, for example, no interface exists with that index.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

DisconnectClient


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
[in] Specifies the interface in the set of interfaces configured on the router.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Description
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).

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Routing Protocol Interface Reference, Routing Protocol Interface Functions, AddInterface


DisconnectClient

The router manager calls the DisconnectClient function when a client disconnects from an interface on which the routing protocol is running.

typedef DWORD (WINAPI *PDISCONNECT_CLIENT) (
  ULONG InterfaceIndex,
  PVOID ClientAddress
);

Parameters

InterfaceIndex
[in] Specifies the index of the interface on which the client is connecting.
ClientAddress
[in] Pointer to the address (for example, the IP address) of the connecting client.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value should be one of the following error codes.

Value | Description
ERROR_INVALID_PARAMETER | At least one of the following is true: The InterfaceIndex parameter is invalid, for example, no interface exists with that index.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

ConnectClient


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
[in] Specifies the interface in the set of interfaces configured on the router.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Description
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).

Remarks

If the function returns NO_ERROR, the update operation started successfully on the interface. Check the routing protocol event queue for a completion event (see GetEventMessage).

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Routing Protocol Interface Reference, Routing Protocol Interface Functions, 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
[in] Specifies the interface in the set of interfaces configured on the router.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Description
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).

Remarks

If the function returns NO_ERROR, the update operation started successfully on the interface. Check the routing protocol event queue for a completion event (see GetEventMessage).

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Routing Protocol Interface Reference, Routing Protocol Interface Functions, DoUpdateRoutes, GetEventMessage


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
[out] 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 shut down 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 SetInterfaceInfo. 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 converts 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
[out]ointer 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

If the entry is retrieved successfully, the return value is NO_ERROR.

If the routing protocol's message queue does not contain any entries, the return value is ERROR_NO_MORE_ITEMS.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Routing Protocol Interface Reference, Routing Protocol Interface Functions, DoUpdateRoutes, DoUpdateServices, MESSAGE, SetGlobalInfo, SetInterfaceInfo, 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
[in] Pointer to a buffer to receive the protocol-defined global configuration information. The format of this information is specific to the routing protocol.
GlobalInfoSize
[in, out] Pointer to a DWORD variable.

On input this variable specifies the size, in bytes, of the buffer pointed to by the GlobalInfo parameter.

On output this variable receives 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

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Routing Protocol Interface Reference, Routing Protocol Interface Functions, SetInterfaceInfo, SetGlobalInfo


GetInterfaceInfo

The GetInterfaceInfo function gets the configuration information kept by the routing protocol for a specific interface.

DWORD GetInterfaceInfo(
  ULONG InterfaceIndex,     // the index of the interface
  PVOID InterfaceInfo,      // buffer for interface information
  PULONG BufferSize,        // size of the buffer for
                            // interface information
  ULONG StructureVersion,
  ULONG StructureSize,
  ULONG StructureCount
);

Parameters

InterfaceIndex
[in] Specifies the interface in the set of interfaces configured on the router.
InterfaceInfo
[in] Pointer to a buffer that receives the protocol-defined configuration information associated with the interface. This information is private to the routing protocol.
BufferSize
[in, out] Pointer to a DWORD variable.

On input: This variable specifies the size, in bytes, of the buffer provided to receive the configuration information.

On output: This variable receives 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.

StructureVersion
[in] Specifies the version of the information structures pointed to by the InterfaceInfo parameter. In some cases, this is equal to the version of the routing protocol.
StructureSize
[in] Specifies the size of each of the information structures pointed to by the InterfaceInfo parameter. Since some information structures contain variable length members, the routing protocol isn't necessarily able to determine the size of the information from the version.
StructureCount
[in] Specifies a count of the number of information structures pointed to by the InterfaceInfo parameter. This parameter is always one.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Iphlpapi.h.

See Also

Routing Protocol Interface Reference, Routing Protocol Interface Functions, SetInterfaceInfo


GetMfeStatus

The router manager calls the GetMfeStatus function to obtain the status of the multicast forwarding entry (MFE) for the specified interface, group address, and source address.

typedef DWORD (WINAPI *PGET_MFE_STATUS) (
  DWORD InterfaceIndex,
  DWORD GroupAddress,
  DWORD SourceAddress,
  PBYTE StatusCode
);

Parameters

InterfaceIndex
[in] Specifies the index of the interface for this MFE.
GroupAddress
[in] Specifies the multicast group address for this MFE.
SourceAddress
[in] Specifies the multicast source address for this MFE.
StatusCode
[out] Pointer to a BYTE variable. The routing protocol should fill in this variable with one of the following values. The routing protocol should select the highest-valued code that applies.
Value | Meaning
MFE_NO_ERROR | None of the following values apply.
MFE_REACHED_CORE | The local computer on this router is an rendezvous point (RP)/core router for the multicast group.
MFE_OIF_PRUNED | This value should be set only by the owner of the outgoing interface. The value indicates that no downstream receivers exist on the outgoing interface.
MFE_PRUNED_UPSTREAM | This value should be set only by the owner of the incoming interface. The value indicates that a prune message was sent upstream.
MFE_OLD_ROUTER | This value should be set only by the owner of the incoming interface. The value indicates that the upstream neighbor doesn't support mtrace.

Return Values

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

If the function fails, the return value should be one of the following error codes.

Value | Description
ERROR_CAN_NOT_COMPLETE | The routing protocol could not complete the request.
ERROR_INVALID_PARAMETER | The InterfaceIndex parameter is invalid (for example, no interface exists with that index), or the group or source address is invalid.

Remarks

Only multicast routing protocols need implement this function. Non-multicast routing protocols should pass NULL as the pointer value for this function in MPR_ROUTING_CHARACTERISTICS

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

GetNeighbors


GetNeighbors

The router manager calls the GetNeighbors function to obtain the querier for the network attached through the specified interface.

typedef DWORD (WINAPI *PGET_NEIGHBORS) (
  DWORD InterfaceIndex,
  PDWORD NeighborList,
  PDWORD NeighborListSize,
  PBYTE InterfaceFlags
);

Parameters

InterfaceIndex
[in] Specifies the index of the interface on which the routing protocol should provide the querier.
NeighborList
[in] Pointer to an array DWORD variables. The routing protocol should fill in this array with the address of the querier.

If the local computer is the querier for the network attached through the specified interface, the routing protocol need not fill in this variable. Instead, the routing protocol should set the value pointed to by NeighborListSize to zero. Also, the routing protocol should add MRINFO_QUERIER_FLAG to the flags returned in the InterfaceFlags parameter.

NeighborListSize
[in, out] On input, pointer to a DWORD variable.

On output, the routing protocol fills this variable with the length, in bytes, of the address returned in the NeighborList parameter.

InterfaceFlags
[out] Receives one or more of the following flags. The flags describe the relationship of the local computer to other computers on the network attached through the specified interface.

MRINFO_TUNNEL_FLAG

MRINFO_PIM_FLAG

MRINFO_DOWN_FLAG

MRINFO_DISABLED_FLAG

MRINFO_QUERIER_FLAG

MRINFO_LEAF_FLAG

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Description
ERROR_CAN_NOT_COMPLETE | The routing protocol could not complete the request.
ERROR_INSUFFICIENT_BUFFER | The size of the buffer pointed to by NeighborList is not large enough to hold the address. The required size is returned in the DWORD variable pointed to by the NeigbhorListSize parameter.
ERROR_INVALID_PARAMETER | The InterfaceIndex parameter is invalid (for example, no interface exists with that index).

Remarks

Only multicast routing protocols need implement this function. Non-multicast routing protocols should pass NULL as the pointer value for this function in MPR_ROUTING_CHARACTERISTICS

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

GetMfeStatus


InterfaceStatus

Router manager calls the InterfaceStatus function to change the status of an interface.

typedef DWORD (WINAPI * PINTERFACE_STATUS) (
  ULONG InterfaceIndex,
  BOOL InterfaceActive,
  DWORD StatusType,
  PVOID StatusInfo
);

Parameters

InterfaceIndex
[in] Specifies the index of the interface to change.
InterfaceActive
[in] Specifies whether the interface is active.
StatusType
[in] Specifies the new interface status. This parameter is one of the following values.

RIS_INTERFACE_ADDRESS_CHANGE

RIS_INTERFACE_ENABLED

RIS_INTERFACE_DISABLED

RIS_INTERFACE_MEDIA_PRESENT

RIS_INTERFACE_MEDIA_ABSENT

StatusInfo
[in] Pointer to a structure that specifies information appropriate to the type of interface status type. For example, if the StatusType parameter specifies an address change, the StatusInfo parameter will point to a structure that contains the new address information, such as IP_ADAPTER_BINDING_INFO or IPX_ADAPTER_BINDING_INFO. This parameter may be NULL.

Return Values

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

If the function fails, the return value should be one of the following error codes.

Value | Description
ERROR_CAN_NOT_COMPLETE | Unspecified failure.
ERROR_INVALID_PARAMETER | The InterfaceIndex parameter is invalid (for example, no interface exists with that index).

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

AddInterface, DeleteInterface


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
[in] Specifies the size of the data for the Create Request.
InputData
[in] Pointer to a buffer that specifies the data for the Create Request.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Routing Protocol Interface Reference, Routing Protocol Interface Functions, 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
[in] Specifies the size of the data for the Delete Request.
InputData
[in] Pointer to a buffer that specifies the data for the Delete Request.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Routing Protocol Interface Reference, Routing Protocol Interface Functions, MibCreate


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
[in] Specifies the size of the data for the Get Request.
InputData
[in] Pointer to a buffer that specifies the data for the Get Request.
OutputDataSize
[out] 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
[out] Pointer to a buffer that receives the data from the MIB entry.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Routing Protocol Interface Reference, Routing Protocol Interface Functions, MibGetFirst, MibGetNext, MibSet


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
[in] Specifies the size of the data for the Get First Request.
InputData
[in] Pointer to the data to be passed with the Get First Request.
OutputDataSize
[out] 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
[out] Pointer to a buffer that receives the data from the MIB entry.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Routing Protocol Interface Reference, Routing Protocol Interface Functions, MibGet, 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
[in] Specifies the size of the data for the Get Next Request.
InputData
[in] Pointer to the data for the Get Next Request.
OutputDataSize
[out] 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
[out] Pointer to a buffer that receives the data from the MIB entry.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Routing Protocol Interface Reference, Routing Protocol Interface Functions, MibGet, MibGetFirst, MibSet


MibGetTrapInfo

The MibEntryGetTrapInfo function queries the module that set a trap event for more information about the trap.

typedef DWORD (WINAPI * PMIB_GET_TRAP_INFO) (
  ULONG InputDataSize,
  PVOID InputData,
  PULONG OutputDataSize,
  PVOID OutputData
);

Parameters

InputDataSize
[in] Specifies a ULONG variable that specifies the size in bytes of the data pointed to by InputData.
InputData
[in] Pointer to the input data.
OutputDataSize
[out] Pointer to a ULONG variable that receives the size in bytes of the data pointed to by *OutputData.
OutputData
[out] Receives the address of a pointer to the output data.

Return Values

If the functions succeeds, the return value is NO_ERROR

If the function fails, the return value is one of the following error codes.

Value | Description
ERROR_ACCESS_DENIED | The caller does not have sufficient privileges.
ERROR_NOT_ENOUGH_MEMORY | Insufficient resources to complete the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

MibSetTrapInfo


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
[in] Specifies the size of the data for the Set Request.
InputData
[in] Pointer to a buffer that specifies the data for the Set Request.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Routing Protocol Interface Reference, Routing Protocol Interface Functions, MibGet, MibGetFirst, MibGetNext


MibSetTrapInfo

The MibSetTrapInfo function passes in a handle to an event which is signaled whenever a TRAP needs to be issued.

typedef DWORD (WINAPI * PMIB_SET_TRAP_INFO) (
  HANDLE Event,
  ULONG InputDataSize,
  PVOID InputData,
  PULONG OutputDataSize,
  PVOID OutputData
);

Parameters

Event
[in] Handle to an event that is signaled when a TRAP needs to be issued.
InputDataSize
[in] Specifies a ULONG variable that contains the size in bytes of the data pointed to by InputData.
InputData
[in] Pointer to the input data.
OutputDataSize
[out] Pointer to a ULONG variable that specifies the size in bytes of the data pointed to by *OutputData.
OutputData
[out] Receives the address of a pointer to the output data.

Return Values

If the functions succeeds, the return value is NO_ERROR

If the function fails, the return value is one of the following error codes.

Value | Description
ERROR_ACCESS_DENIED | The caller does not have sufficient privileges.
ERROR_NOT_ENOUGH_MEMORY | Insufficient resources to complete the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

MibGetTrapInfo


QueryPower

The QueryPower function is reserved for future use. It is not currently called by the router manager. Routing protocols should pass NULL as the pointer value for this function in MPR_ROUTING_CHARACTERISTICS

typedef DWORD (WINAPI * PQUERY_POWER) (
  DWORD PowerType
);

Parameters

PowerType
[in] Reserved for future use.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

SetPower


RegisterProtocol

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

DWORD RegisterProtocol (
  PMPR_ROUTING_CHARACTERISTICS pRoutingChar,
  PMPR_SERVICE_CHARACTERISTICS pServiceChar
);

Parameters

pRoutingChar
[in, out] On input, pointer to an MPR_ROUTING_CHARACTERISTICS structure.

On output, receives pointers to functions implemented for the routing protocol.

See the reference page for the MPR_ROUTING_CHARACTERISTICS structure for more information on how to use it with the RegisterProtocol function.

pServiceChar
[in, out] On input, pointer to an MPR_SERVICE_CHARACTERISTICS structure.

On output, receives pointers to functions implemented for the routing protocol.

See the reference page for the MPR_SERVICE_CHARACTERISTICS structure for more information on how to use it with the RegisterProtocol function.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is ERROR_NOT_SUPPORTED.

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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Routing Protocol Interface Reference, Routing Protocol Interface Functions, MPR_ROUTING_CHARACTERISTICS, MPR_SERVICE_CHARACTERISTICS


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
[in] Pointer to a buffer that specifies the protocol-defined global configuration information.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Routing Protocol Interface Reference, Routing Protocol Interface Functions, GetInterfaceInfo, GetGlobalInfo


SetInterfaceInfo

The SetInterfaceInfo function sets the configuration of a specific interface managed by the routing protocol.

DWORD SetInterfaceInfo(
  ULONG InterfaceIndex,   // index of interface
  PVOID InterfaceInfo,    // interface information block
  ULONG StructureVersion,
  ULONG StructureSize,
  ULONG StructureCount
);

Parameters

InterfaceIndex
[in] Specifies the interface in the set of interfaces configured on the router.
InterfaceInfo
[in] Pointer to a buffer that holds the protocol-defined configuration information associated with the interface. This information is private to the routing protocol.
StructureVersion
[in] Specifies the version of the information structures pointed to by the InterfaceInfo parameter. In some cases, this is equal to the version of the routing protocol.
StructureSize
[in] Specifies the size of each of the information structures pointed to by the InterfaceInfo parameter. Since some information structures contain variable length members, the routing protocol isn't necessarily able to determine the size of the information from the version.
StructureCount
[in] Specifies a count of the number of information structures pointed to by the InterfaceInfo parameter. This parameter is always one.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Routing Protocol Interface Reference, Routing Protocol Interface Functions, GetInterfaceInfo


SetPower

The SetPower function is reserved for future use. It is not currently called by the router manager. Routing protocols should pass NULL as the pointer value for this function in MPR_ROUTING_CHARACTERISTICS

typedef DWORD (WINAPI * PSET_POWER) (
  DWORD PowerType
);

Parameters

PowerType
[in] Reserved for future use.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

QueryPower


StartComplete

Router Manager calls the StartComplete function to inform the routing protocol that initialization is complete and all interfaces have been added. The routing protocol should wait for this call before starting any protocol-specific behavior.

typedef DWORD (WINAPI * PSTART_COMPLETE) (VOID);

Parameters

This function takes no parameters.

Return Values

This function should return NO_ERROR.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

StartProtocol


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
  ULONG StructureVersion,
  ULONG StructureSize,
  ULONG StructureCount
);

Parameters

NotificationEvent
[in] Handle to an event object. The routing protocol signals this event when it wants the router manager to retrieve an asynchronous message from the queue maintained by the protocol.
SupportFunctions
[in] 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
[in] Pointer to protocol-defined global, as opposed to interface-specific, configuration information. This information is private to the routing protocol.
StructureVersion
[in] Specifies the version of the information structures pointed to by the GlobalInfo parameter. In some cases, this is equal to the version of the routing protocol.
StructureSize
[in] Specifies the size of each of the information structures pointed to by the GlobalInfo parameter. Since some information structures contain variable length members, the routing protocol isn't necessarily able to determine the size of the information from the version.
StructureCount
[in] Specifies a count of the number of information structures pointed to by the GlobalInfo parameter. This parameter is always one.

Return Values

If the function succeeds, and the protocol is ready to receive interface information, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Routing Protocol Interface Reference, Routing Protocol Interface Functions, GetEventMessage, StopProtocol, SUPPORT_FUNCTIONS


StopProtocol

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

DWORD StopProtocol (void);

Return Values

If the routing protocol shutdown successfully (synchronous completion), the return value is NO_ERROR.

If routing protocol is shutting down asynchronously, the return value is ERROR_PROTOCOL_STOP_PENDING. In this case, the protocol will report the results of the shutdown through the event message queue.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Routing Protocol Interface Reference, Routing Protocol Interface Functions, GetEventMessage, StartProtocol


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
[in] Specifies the interface in the set of interfaces configured on the router.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Routing Protocol Interface Reference, Routing Protocol Interface Functions


Routing Protocol Interface Structures

The Routing Protocol Interface Functions use the following structures.

MESSAGE

MPR_ROUTING_CHARACTERISTICS

MPR_SERVICE_CHARACTERISTICS

UPDATE_COMPLETE_MESSAGE


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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Routing Protocol Interface Reference, Routing Protocol Interface Structures, 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 _MPR50_ROUTING_CHARACTERISTICS {
  DWORD               dwVersion;
  DWORD               dwProtocolId;
  DWORD               fSupportedFunctionality;

  PSTART_PROTOCOL     pfnStartProtocol;
  PSTART_COMPLETE     pfnStartComplete;
  PSTOP_PROTOCOL      pfnStopProtocol;
  PGET_GLOBAL_INFO    pfnGetGlobalInfo;
  PSET_GLOBAL_INFO    pfnSetGlobalInfo;
  PQUERY_POWER        pfnQueryPower;
  PSET_POWER          pfnSetPower;

  PADD_INTERFACE      pfnAddInterface;
  PDELETE_INTERFACE   pfnDeleteInterface;
  PINTERFACE_STATUS   pfnInterfaceStatus;
  PGET_INTERFACE_INFO pfnGetInterfaceInfo;
  PSET_INTERFACE_INFO pfnSetInterfaceInfo;

  PGET_EVENT_MESSAGE  pfnGetEventMessage;

  PDO_UPDATE_ROUTES   pfnUpdateRoutes;

  PCONNECT_CLIENT     pfnConnectClient;
  PDISCONNECT_CLIENT  pfnDisconnectClient;

  PGET_NEIGHBORS      pfnGetNeighbors;
  PGET_MFE_STATUS     pfnGetMfeStatus;

  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;
} MPR50_ROUTING_CHARACTERISTICS

typedef MPR50_ROUTING_CHARACTERISTICS MPR_ROUTING_CHARACTERISTICS;

typedef MPR_ROUTING_CHARACTERISTICS *PMPR_ROUTING_CHARACTERISTICS;

Members

dwVersion
On input: specifies the version of RRAS currently running.

On output: the routing protocol should specify the version of RRAS that it requires.

The symbol MS_ROUTER_VERSION in the header file Routprot.h is defined to be the RRAS 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.
pfnStartComplete
Pointer to an implementation of the StartComplete function for this routing protocol.
pfnStopProtocol
Pointer to an implementation of the StopProtocol 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.
pfnQueryPower
Pointer to an implementation of the QueryPower function for this routing protocol.
pfnSetPower
Pointer to an implementation of the SetPower 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.
pfnInterfaceStatus
Pointer to an implementation of the InterfaceStatus function for this routing protocol.
pfnGetInterfaceInfo
Pointer to an implementation of the GetInterfaceInfo function for this routing protocol.
pfnSetInterfaceInfo
Pointer to an implementation of the SetInterfaceInfo function for this routing protocol.
pfnGetEventMessage
Pointer to an implementation of the GetEventMessage function for this routing protocol.
pfnUpdateRoutes
Pointer to an implementation of the DoUpdateRoutes function for this routing protocol.
pfnConnectClient
Pointer to an implementation of the ConnectClient function for this routing protocol.
pfnDisconnectClient
Pointer to an implementation of the DisconnectClient function for this routing protocol.
pfnGetNeighbors
Pointer to an implementation of the GetNeighbors function for this routing protocol.
pfnGetMfeStatus
Pointer to an implementation of the GetMfeStatus 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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Routing Protocol Interface Reference, Routing Protocol Interface Structures, 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 RRAS currently running.

On output: the routing protocol should specify the version of RRAS that it requires.

The symbol MS_ROUTER_VERSION in the header file Routprot.h is defined to be the RRAS 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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Routing Protocol Interface Reference, Routing Protocol Interface Structures, 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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Routing Protocol Interface Reference, Routing Protocol Interface Structures, 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

MIBEntryGet

MIBEntryGetFirst

MIBEntryGetNext

MIBEntrySet

SetInterfaceReceiveType

ValidateRoute


SUPPORT_FUNCTIONS

The SUPPORT_FUNCTIONS structure is used by the router manager to pass the routing protocol a set of pointers to functions provided by the router manager.

typedef struct _SUPPORT_FUNCTIONS {
  union
  {
    ULONGLONG  _Align8;

    struct
    {
      DWORD    dwVersion;
      DWORD    dwReserved;
    };
  };
  DWORD (WINAPI *DemandDialRequest)( DWORD, DWORD );
  DWORD (WINAPI *SetInterfaceReceiveType)( DWORD, DWORD, DWORD, BOOL );
  DWORD (WINAPI *ValidateRoute)( DWORD, PVOID, PVOID );
  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.
SetInterfaceReceiveType
Pointer to the SetInterfaceReceiveType function provided by the router manager for the routing protocol.
ValidateRoute
Pointer to the ValidateRoute 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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

StartProtocol


DemandDialRequest

The routing protocol calls DemandDialRequest to initiate a demand-dial connection.

DWORD ( * DemandDialRequest) (
  DWORD ProtocolId,     // ID of DLL to process request
  DWORD InterfaceIndex  // ID of the interface
);

Parameters

ProtocolId
[in] Specifies the identifier of the routing protocol on behalf of which the connection should be established. (Normally, this parameter is the identifier of the calling routing protocol.)
InterfaceIndex
[in] Specifies the identifier of the interface for which the connection should be established.

Return Value

If the function succeeds, the return value is NO_ERROR.

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

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Protocol Identifiers


MIBEntryCreate

The routing protocol calls MIBEntryCreate to execute a Create request of the router manager or a peer protocol DLL. Implement this function to handle SNMP-style requests.

DWORD ( * MIBEntryCreate ) (
  DWORD dwRoutingPid,   // 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

dwRoutingPid
[in] Specifies the identifier of the DLL that should process this request. This parameter may be the identifier of the router manager or the identifier of a routing protocol.
InputDataSize
[in] Specifies the size, in bytes, of the data to pass with the Create request.
InputData
[in] Pointer to the data to pass with the Create request.

Return Value

If the function succeeds, the return value is NO_ERROR.

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

Value | Description
ERROR_CAN_NOT_COMPLETE | The attempt to create the MIB entry failed.
ERROR_INVALID_PARAMETER | The size or content of the input data is incompatible with the request.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Routprot.h.

See Also

Protocol Identifiers, MIBEntryDelete


MIBEntryDelete

The routing protocol calls MIBEntryDelete to execute a Delete request of the router manager or a peer protocol DLL. Implement this function to handle SNMP-style requests.

DWORD ( * MIBEntryDelete ) (
  DWORD dwRoutingPid,   // 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

dwRoutingPid
[in] Specifies the identifier of the DLL that should process this request. This parameter may be the identifier of the router manager or the identifier of a routing protocol.
InputDataSize
[in] Specifies the size, in bytes, of the data to pass with the Delete request.
InputData
[in] Pointer to the data to pass with the Delete request.

Return Value

If the function succeeds, the return value is NO_ERROR.

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

Value | Description
ERROR_CAN_NOT_COMPLETE | The attempt to delete the MIB entry failed.
ERROR_INVALID_PARAMETER | The size or content of the input data is incompatible with the request.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Routprot.h.

See Also

Protocol Identifiers, MIBEntryCreate


MIBEntryGet

The routing protocol calls MIBEntryGet to execute a Get request of the router manager or a peer protocol DLL. Implement this function to handle SNMP-style requests.

DWORD ( * MIBEntryGet ) (
  DWORD dwRoutingPid,      // 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

dwRoutingPid
[in] Specifies the identifier of the DLL that should process this request. This parameter may be the identifier of the router manager or the identifier of a routing protocol.
InputDataSize
[in] Specifies the size, in bytes, of the data to pass with the Get request.
InputData
[in] Pointer to the data to pass with the Get request.
OutputDataSize
[in,out] 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 the data placed in the output buffer. If the initial size is not large enough, this variable contains the buffer size required to hold all of the output data.

OutputData
[out] Receives the pointer to a buffer that holds the data from the MIB entry.

Return Value

If the function succeeds, the return value is NO_ERROR.

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

Value | Description
ERROR_CAN_NOT_COMPLETE | The operation failed.
ERROR_INVALID_PARAMETER | The size or content of the input data is 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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Routprot.h.

See Also

Protocol Identifiers, MIBEntrySet, MIBEntryGetFirst, MIBEntryGetNext


MIBEntryGetFirst

The routing protocol calls MIBEntryGetFirst to execute a Get First request of the router manager or a peer protocol DLL. Implement this function to handle SNMP-style requests.

DWORD ( * MIBEntryGetFirst ) (
  DWORD dwRoutingPid,      // 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

dwRoutingPid
[in] Specifies the identifier of the DLL that should process this request. This parameter may be the identifier of the router manager or the identifier of a routing protocol.
InputDataSize
[in] Specifies the size, in bytes, of the data to pass with the Get First request.
InputData
[in] Pointer to the data to pass with the Get First request.
OutputDataSize
[in, out]A pointer to a DWORD variable:

On input, this variable specifies the size, in bytes, of the output buffer.

On output, this variable receives the size, in bytes, of the data placed in the output buffer. If the initial size is not large enough, this variable contains the buffer size required to hold all of the output data.

OutputData
[out] Pointer to a buffer that receives the data from the MIB entry.

Return Value

If the function succeeds, the return value is NO_ERROR.

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

Value | Description
ERROR_CAN_NOT_COMPLETE | The operation failed.
ERROR_INVALID_PARAMETER | The size or content of the input data is incompatible with the request.
ERROR_INSUFFICIENT_BUFFER | The size of the output buffer provided is not large enough to hold the requested information. On return, the required size is pointed to by the OutputDataSize parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Routprot.h.

See Also

Protocol Identifiers, MIBEntryGet, MIBEntryGetNext


MIBEntryGetNext

The routing protocol calls MIBEntryGetNext to execute a Get Next request of the router manager or a peer protocol DLL. Implement this function to handle SNMP-style requests.

DWORD ( * MIBEntryGetNext ) (
  DWORD dwRoutingPid,      // 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

dwRoutingPid
[in] Specifies the identifier of the DLL that should process this request. This parameter may be the identifier of the router manager or the identifier of a routing protocol.
InputDataSize
[in] Specifies the size, in bytes, of the data to pass with the Get Next request.
InputData
[in] Pointer to the data to pass with the Get Next request.
OutputDataSize
[in, out] A pointer to a DWORD variable:

On input, this variable specifies the size, in bytes, of the output buffer.

On output this variable receives the size, in bytes, of the data placed in the output buffer. If the initial size is not large enough, this variable contains the buffer size required to hold all of the output data.

OutputData
[out] Pointer to a buffer that will hold the data from the MIB entry.

Return Value

If the function succeeds, the return value is NO_ERROR.

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

Value | Description
ERROR_CAN_NOT_COMPLETE | The operation failed.
ERROR_INVALID_PARAMETER | The size or content of the input data is incompatible with the request.
ERROR_INSUFFICIENT_BUFFER | The size of the output buffer provided is not large enough to hold the requested information. On return, OutputDataSize points to the required size.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Routprot.h.

See Also

Protocol Identifiers, MIBEntryGet, MIBEntryGetFirst


MIBEntrySet

The routing protocol calls MIBEntrySet to execute an SNMP MIB-style Set request of the router manager or a peer protocol DLL.

DWORD ( * MIBEntrySet ) (
  DWORD dwRoutingPid,   // 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

dwRoutingPid
[in] Specifies the identifier of the DLL that should process this request. This parameter may be the identifier of the router manager or the identifier of a routing protocol.
InputDataSize
[in] Specifies the size, in bytes, of the data to pass with the Set request.
InputData
[in] Pointer to the data to pass with the Set request.

Return Value

If the function succeeds, the return value is NO_ERROR.

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

Value | Description
ERROR_CAN_NOT_COMPLETE | The operation failed.
ERROR_INVALID_PARAMETER | The size or content of the input data is incompatible with the request.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Routprot.h.

See Also

Protocol Identifiers, MIBEntryGet


SetInterfaceReceiveType

The routing protocol calls the SetInterfaceReceiveType function to set the receive capability of the specified interface.

DWORD (WINAPI *SetInterfaceReceiveType)(
  DWORD ProtocolId,
  DWORD InterfaceIndex,
  DWORD InterfaceReceiveType,
  BOOL bActivate
);

Parameters

ProtocolId
[in] Specifies the identifier of the routing protocol.
InterfaceIndex
[in] Specifies the index of the interface on which to set the receive type.
InterfaceReceiveType
[in] Specifies the receive type. This parameter should be one of the following values.

IR_PROMISCUOUS

IR_PROMISCUOUS_MULTICAST

bActivate
[in] Specifies whether to activate the interface.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | The value specified by the dwInterfaceReceiveType parameter is not valid.
Other | The call failed. Use FormatMessage to retrieve the error message that corresponds to the returned error code.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Protocol Identifiers


ValidateRoute

The routing protocol calls the ValidateRoute function to set the route preference and perform other route validation.

DWORD (WINAPI *ValidateRoute)(
  DWORD ProtocolId,
  PVOID RouteInfo,
  PVOID DestAddress   // OPTIONAL
);

Parameters

ProtocolId
[in] Specifies the identifier of the routing protocol.
RouteInfo
[in] Pointer to information that describes the route to validate.
DestAddress
[in] Pointer to information that describes the destination address. This parameter is optional and may be NULL.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | The some or all of the information specified by the RouteInfo or DestAddress parameters is invalid.
Other | The call failed. Use FormatMessage to retrieve the error message that corresponds to the returned error code.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Routprot.h.

See Also

Protocol Identifiers


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

  • Service Table management Functions
  • Service Table Management Structures

(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:

BlockConvertServicesToStatic

BlockDeleteStaticServices

CloseServiceEnumerationHandle

CreateServiceEnumerationHandle

CreateStaticService

DeleteStaticService

EnumerateGetNextService

GetFirstOrderedService

GetNextOrderedService

GetServiceCount

IsService


BlockConvertServicesToStatic

The BlockConvertServicesToStatic function converts all services received on a specified interface to static.

DWORD BlockConvertServicesToStatic (
  ULONG InterfaceIndex
);

Parameters

InterfaceIndex
[in] Specifies the unique number that identifies the interface associated with the services intended for conversion.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Description
ERROR_CAN_NOT_COMPLETE | The SAP Agent is down.
ERROR_INVALID_PARAMETER | The InterfaceIndex parameter is invalid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Stm.h.

See Also

IPX Service Table Management, Service Table Management Functions, BlockDeleteStaticServices


BlockDeleteStaticServices

The BlockDeleteStaticServices function deletes all static services associated with a specified interface.

DWORD BlockDeleteStaticServices (
  ULONG InterfaceIndex
);

Parameters

InterfaceIndex
[in] Specifies the unique number that identifies the interface associated with the services to be deleted.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Description
ERROR_CAN_NOT_COMPLETE | The SAP Agent is down.
ERROR_INVALID_PARAMETER | The InterfaceIndex parameter is invalid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Stm.h.

See Also

IPX Service Table Management, Service Table Management Functions, BlockConvertServicesToStatic


CloseServiceEnumerationHandle

The CloseServiceEnumerationHandle function terminates the enumeration and frees associated resources.

DWORD CloseServiceEnumerationHandle (
  HANDLE EnumerationHandle
);

Parameters

EnumerationHandle
[in] Handle that specifies the enumeration to terminate, obtained from a previous call to CreateServiceEnumerationHandle.

Return Values

If the functions succeeds, the return value is NO_ERROR.

If the function fails, the return value is ERROR_CAN_NOT_COMPLETE.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Stm.h.

See Also

IPX Service Table Management, Service Table Management Functions, CreateServiceEnumerationHandle


CreateServiceEnumerationHandle

The CreateServiceEnumerationHandle function returns a handle that allows the use of fast and change-tolerant enumeration functions. Such functions can scan through all services or a specified subset. The functions are change-tolerant in that they automatically enumerate any changes that other processes make to the set of enumerated services

HANDLE CreateServiceEnumerationHandle (
  DWORD ExclusionFlags,
  PIPX_SERVICE CriteriaService
);

Parameters

ExclusionFlags
[in] Specifies the limits the set of services that CreateServiceEnumerationHandle returns to a subset defined by a combination of ExclusionFlags and values in the corresponding members of CriteriaService. This parameter is 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 member of CriteriaService.
STM_ONLY_THIS_PROTOCOL | Enumerate only those services that were obtained through the protocol specified in the Protocol member 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 member of CriteriaService.

CriteriaService
[in] Pointer to an IPX_SERVICE structure with member values that correspond to those specified in ExclusionFlags.

Return Values

If the function succeeds, the return value is a handle for use with the service enumeration function.

A NULL handle indicates no services exists with the specified criteria, or that the operation failed. For more information, call GetLastError and check the error code against the table below.

Value | Description
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 members in CriteriaService.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Stm.h.

See Also

IPX Service Table Management, Service Table Management Functions, CloseServiceEnumerationHandle, EnumerateGetNextService, GetLastError, IPX_SERVICE


CreateStaticService

The CreateStaticService function adds a static service to the table.

DWORD CreateStaticService (
  ULONG InterfaceIndex,
  PIPX_STATIC_SERVICE_INFO ServiceEntry
);

Parameters

InterfaceIndex
[in] Specifies a unique number that identifies the interface associated with the new service.
ServiceEntry
[in] Pointer to an IPX_STATIC_SERVICE_INFO structure that specifies parameters of the static service to be added.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Stm.h.

See Also

IPX Service Table Management, Service Table Management Functions, DeleteStaticService, IPX_STATIC_SERVICE_INFO


DeleteStaticService

The DeleteStaticService function deletes a static service from the table.

DWORD DeleteStaticService (
  ULONG InterfaceIndex,
  PIPX_STATIC_SERVICE_INFO ServiceEntry
);

Parameters

InterfaceIndex
[in] Specifies a unique number that identifies the interface associated with the service intended for deletion.
ServiceEntry
[in] Pointer to an IPX_STATIC_SERVICE_INFO structure that specifies the parameters of the static service intended for deletion.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Stm.h.

See Also

IPX Service Table Management, Service Table Management Functions, CreateStaticService, IPX_STATIC_SERVICE_INFO


EnumerateGetNextService

The EnumerateGetNextService function returns the next service entry in an enumeration started by CreateServiceEnumerationHandle.

DWORD EnumerateGetNextService (
  HANDLE EnumerationHandle,
  PIPX_SERVICE Service
);

Parameters

EnumerationHandle
[in] Handle that identifies the enumeration and specifies the subset of services on which the enumeration will operate. The handle is obtained from a call to CreateServiceEnumerationHandle.
Service
[out] Pointer to an IPX_SERVICE structure that contains the next service in the enumeration. The services are returned in no particular order, and each service in the subset is returned only once.

Return Values

If the function succeeds, the buffer pointed to by the Service parameter receives the next service in the enumeration. In this case the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Description
ERROR_NO_MORE_ITEMS | No more services exist with the specified criteria.
ERROR_CAN_NOT_COMPLETE | The operation failed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Stm.h.

See Also

IPX Service Table Management, Service Table Management Functions, CreateServiceEnumerationHandle, IPX_SERVICE


GetFirstOrderedService

The GetFirstOrderedService function returns the first service in the specified order from the designated subset of services in the table.

DWORD GetFirstOrderedService (
  DWORD OrderingMethod,
  DWORD ExclusionFlags,
  OUT PIPX_SERVICE Service
);

Parameters

OrderingMethod
[in] Specifies the order in which the services are searched. This parameter must be one of the following values.
STM_ORDER_BY_TYPE_AND_NAME
Search the services first by type and then by name.
STM_ORDER_BY_INTERFACE_TYPE_NAME
Search the services first by interface index, then by type, and finally by name.
ExclusionFlags
[in] Specifies the limits the set of examined services to a subset defined by ExclusionFlags and the values in the members of the structure pointed to by the Service parameter. See CreateServiceEnumerationHandle for a description of the possible flags.
Service
[in, out] Pointer to an IPX_SERVICE structure.

On input, the values in the members correspond to flags specified in ExclusionFlags.

On output, the first service that matches specified criteria.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Description
ERROR_NO_MORE_ITEMS | Services that match the specified criteria do not exist.
ERROR_INVALID_PARAMETER | One or more input parameters are invalid, that is, invalid OrderingMethod, enumeration flags, or field values in Service.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Stm.h.

See Also

IPX Service Table Management, Service Table Management Functions, 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 (
  DWORD OrderingMethod,
  DWORD ExclusionFlags,
  PIPX_SERVICE Service
);

Parameters

OrderingMethod
[in] Specifies the order in which the services are searched. See GetFirstOrderedService for a description of the various ordering methods.
ExclusionFlags
[in] Limits the set of examined services to a subset defined by ExclusionFlags and the values in the corresponding members of the structure pointed to by the Service parameter. See CreateServiceEnumerationHandle for a description of the possible flags.
Service
[in, out] Pointer to an IPX_SERVICE structure.

On input, specifies the service from which to continue searching; also contains member values that correspond to the specified ExclusionFlags.

On output, the structure contains the first service that follows the input service and matches the specified criteria.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Description
ERROR_NO_MORE_SERVICES | There are no more services matching the specified criteria.
ERROR_INVALID_PARAMETER | One or more of the input parameters is invalid; for example, invalid OrderingMethod, enumeration flags, or member values in Service.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Stm.h.

See Also

IPX Service Table Management, Service Table Management Functions, CreateServiceEnumerationHandle, IPX_SERVICE


GetServiceCount

The GetServiceCount function returns the number of services in the table.

ULONG GetServiceCount (void);

Return Values

If the function succeeds, the return value is the number of services in the table.

If the function fails, the return value is one of the following error codes.

Value | Description
NO_ERROR | Operation succeeded but no services are available.
0 (Zero) | No services are available in the table or the operation failed. Call GetLastError to obtain more information:

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Stm.h.

See Also

IPX Service Table Management, Service Table Management Functions, GetLastError


IsService

The IsService function checks whether a service of specified type and name exists in the service table, and optionally returns the service's parameters.

BOOL IsService (
  USHORT Type,
  PUCHAR Name,
  PIPX_SERVICE Service    //OPTIONAL
);

Parameters

Type
[in] Specifies the type of the service being checked.
Name
[in] Specifies the name of the service being checked.
Service
[out] Pointer to a structure in which to receive the information about the matching service (if any).

Return Values

The IsService function returns one of the following values.

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Stm.h.

See Also

IPX Service Table Management, Service Table Management Functions, GetLastError, IPX_SERVICE


Service Table Management Structures

Use the following structures to implement routing protocols that register for service handling:

IPX_SERVER_ENTRY
IPX_SERVICE


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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Stm.h.

See Also

IPX Service Table Management, Service Table Management Structures, IPX_SERVICE


IPX_SERVICE

The IPX_SERVICE structure 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 IPX_PROTOCOL_STATIC protocol.)
Service
Specifies an IPX_SERVER_ENTRY structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Stm.h.

See Also

IPX Service Table Management, Service Table Management Structures, IPX_SERVER_ENTRY


About Routing Table Manager Version 1

The routing table manager is a central repository of routing information for all routing protocols that operate under Routing and Remote Access Service (RRAS). The routing table manager provides routing information to all interested components, such as routing protocols, management agents, and monitoring agents. The routing table manager 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 routing table manager 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 routing table manager. RtmRegisterClient returns a handle that is used by the routing protocol to add or delete route entries. RtmRegisterClient also allows the routing protocol to register an event object with the routing table manager. The routing table manager signals this event object to notify the routing protocol of changes in best-route information. All other components can obtain information stored in the routing table manager through route enumeration.


Route Tables and Route Table Entries

The routing table manager 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 uses 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 is kept in the routing table. If this amount of time elapses, and the route has not been updated, the routing table manager removes 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 RTMv1. However, if this data changes for a route designated as a "best route," the routing table manager sends out route-change notification.
  • Data specific to the routing protocol. This data is completely transparent to the routing table manager, in that, changes to this data do 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 routing table manager creates separate entries for routes that differ in any of these parameter 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 routing table manager ignores differences in interface index or next-hop address. An example of such a protocol is 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 routing table manager to generate a notification message 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 occurs when a new, better-route entry is added, or when the current best-route entry is deleted or aged out, and leaves another route as the new best route.


Routing Table Manager Version 1 Reference

The following functions, structures, and constants provide an interface that routing protocols can use to access the routing tables maintained by the routing table manager:

  • Routing Table Manager Version 1 Functions
  • Routing Table Manager Version 1 Structures


Routing Table Manager Version 1 Functions

Use the following functions to access the routing tables maintained by the routing table manager:

RtmRegisterClient

RtmDeregisterClient

RtmDequeueRouteChangeMessage

RtmAddRoute

RtmDeleteRoute

RtmIsRoute

RtmGetNetworkCount

RtmGetRouteAge

RtmCreateEnumerationHandle

RtmEnumerateGetNextRoute

RtmCloseEnumerationHandle

RtmBlockDeleteRoutes

RtmGetFirstRoute

RtmGetNextRoute


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
[in] Specifies the protocol family of the routing protocol to register.
RoutingProtocol
[in] Specifies the routing protocol identifier, the same as that used when registering with the router manager. See RegisterProtocol.
ChangeEvent
[in] Specifies that a best route to a network in the table has changed. The routing table manager signals this event after a change to the best route to any network in the table. See RtmDequeueRouteChangeMessage for more information about route-change notification.

This parameter is optional. If the caller specifies NULL for this parameter, the routing table manager does not notify the client of changes in best route status.

Flags
[in] Specifies miscellaneous options for special handling of the routing protocol. The following value is currently supported.
Flags | Values
RTM_PROTOCOL_SINGLE_ROUTE | The routing table manager keeps only one route per destination network for the routing protocol. In other words, the routing table manager replaces 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 routing table manager.

A NULL handle indicates that the routing table manager was unable to register the client. Call GetLastError to obtain the reason for the failure.

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtm.h.
Library: Use Rtm.lib.

See Also

Routing Table Manager Version 1 Reference, Routing Table Manager Version 1 Functions, GetLastError, RegisterProtocol, RTMv1 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
[in] Handle that identifies the client to deregister. Obtain this handle by calling RtmRegisterClient.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Description
ERROR_INVALID_HANDLE | The ClientHandle parameter is not a valid handle.
ERROR_NO_SYSTEM_RESOURCES | Insufficient resources to carry out the operation.

Remarks

This function removes all routes that were added by the client.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtm.h.
Library: Use Rtm.lib.

See Also

Routing Table Manager Version 1 Reference, Routing Table Manager Version 1 Functions, 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
[in] Handle that identifies the client for which the operation is performed. Obtain this handle by calling RtmRegisterClient.
Flags
[out] Pointer to a DWORD variable. The value of this variable is set by the routing table manager. The value specifies the type of the change message, and what information was returned in the provided buffers. This parameter is 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 identifier

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
[out] Pointer to a structure that receives 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
[out] Pointer to a structure that receives 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

The return value is one of the following codes.

Value | Description
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 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 routing table manager 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 | There are insufficient resources to carry out the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtm.h.
Library: Use Rtm.lib.

See Also

Routing Table Manager Version 1 Reference, Routing Table Manager Version 1 Functions, 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
[in] Handle that identifies the client, and therefore the routing protocol, that added or updated the route. Obtain this handle by calling RtmRegisterClient.
Route
[in] Pointer to a protocol-family-specific structure that specifies the new or updated route. The following fields are used by the routing table manager to update the routing table:
RR_Network
Specifies the destination network number.
RR_InterfaceID
Specifies the index of the interface through which the route was received.
RR_NextHopAddress
Specifies the address of the next-hop router.
RR_FamilySpecificData
Specifies data that is specific to the protocol family. Although the data is transparent to the routing table manager, 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, this data is used to determine the best route for the destination network.
RR_ProtocolSpecificData
Specifies data which is specific to the routing protocol that supplied the route.
RR_TimeStamp
Specifies the current system time. This field is set by the routing table manager.
TimeToLive
[in] Specifies 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 it is explicitly deleted. The current limit for TimeToLive is 2147483 sec (24+ days).
Flags
[out] Pointer to a DWORD variable. The value of this variable is set by the routing table manager. The value indicates the type of the change, and what information was returned in the provided buffers. This parameter is 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 was added 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 identifier

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
[out] Pointer to a structure that receives 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
[out] Pointer to a structure that receives 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

The return value is one of the following codes.

Value | Description
NO_ERROR | The route was added or updated successfully.
ERROR_INVALID_HANDLE | The client handle parameter is not a valid handle.
ERROR_INVALID_PARAMETER | The route structure contains an invalid parameter.
ERROR_NO_SYSTEM_RESOURCES | There are insufficient resources to carry out the operation.
ERROR_NOT_ENOUGH_MEMORY | There is 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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtm.h.
Library: Use Rtm.lib.

See Also

Routing Table Manager Version 1 Reference, Routing Table Manager Version 1 Functions, 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
[in] Handle that identifies the client and therefore the routing protocol of the added or updated route. Obtain this handle by calling RtmRegisterClient.
Route
[in] Pointer to a protocol-family-specific structure that specifies the new or updated route. The following fields will be used by the routing table manager to update the routing table:
RR_Network
Specifies the destination network number.
RR_InterfaceID
Specifies the index of the interface through which the route was received.
RR_NextHopAddress
Specifies the network address of the next-hop router.
Flags
[out] 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 is one of the following values.
Flags | Values
RTM_NO_CHANGE | Deleting the route did not affect the best route to any destination network. In other words, 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
[out] Pointer to a structure that receives 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

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Description
ERROR_INVALID_HANDLE | The client handle parameter is not a valid handle.
ERROR_INVALID_PARAMETER | The route structure pointed to by the Route parameter contains a member value.
ERROR_NO_SUCH_ROUTE | There are no entries in the routing table that match the parameters of the specified route.
ERROR_NO_SYSTEM_RESOURCES | There are 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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtm.h.
Library: Use Rtm.lib.

See Also

Routing Table Manager Version 1 Reference, Routing Table Manager Version 1 Functions, RtmAddRoute, RtmDequeueRouteChangeMessage


RtmIsRoute

The RtmIsRoute function determines if one or more 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
[in] Specifies the type of data structure pointed to by the Network parameter, for example, IP_NETWORK, IPX_NETWORK.
Network
[in] Pointer to a structure that specifies protocol-family-specific network number data. This data identifies the network for which the caller seeks route information.
BestRoute
[out] Pointer to a protocol-family-specific structure that receives the current best route information, if any.

Return Values

The return value is one of the following codes.

Value | Description
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 | There is no route to the specified network, or the operation failed. Call GetLastError to obtain more information:
NO_ERROR | The operation succeeded, but there is no route to the specified network.
ERROR_INVALID_PARAMETER | The value of the ProtocolFamily parameter does not correspond to any installed protocol family.
ERROR_NO_SYSTEM_RESOURCES | There are insufficient resources to carry out the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtm.h.
Library: Use Rtm.lib.

See Also

Routing Table Manager Version 1 Reference, Routing Table Manager Version 1 Functions, GetLastError, IP_NETWORK, IPX_NETWORK, RTMv1 Protocol Family Identifiers


RtmGetNetworkCount

The RtmGetNetworkCount function retrieves the number of networks to which the routing table manager has routes.

ULONG RtmGetNetworkCount(
  DWORD ProtocolFamily  // type of network (IP or IPX)
);

Parameters

ProtocolFamily
[in] Specifies for which type of network to obtain route information, for example, IP or IPX.

Return Values

If the function succeeds, the return value is the 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.

Value | Description
NO_ERROR | The operation succeeded, but no routes are available.
ERROR_INVALID_PARAMETER | The value of the ProtocolFamily parameter does not correspond to any installed protocol family.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtm.h.
Library: Use Rtm.lib.

See Also

Routing Table Manager Version 1 Reference, Routing Table Manager Version 1 Functions, GetLastError, RTMv1 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
[in] Pointer to a protocol-family-specific structure that specifies route data recently obtained from the routing table manager.

Return Values

The return value is one of the following values.

Value | Description
RouteAge | The time in seconds since a route was created or last updated.
INFINITE | The content of the route structure is invalid. In this case, a call to GetLastError returns ERROR_INVALID_PARAMETER.

Remarks

The route age is computed from the RR_TimeStamp member of the structure that is pointed to by the Route parameter. The routing table manager sets the value of this member when a route is added or updated.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtm.h.
Library: Use Rtm.lib.

See Also

Routing Table Manager Version_1 Reference, Routing Table Manager Version 1 Functions, 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.

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
[in] Specifies the protocol family of the routes to enumerate.
EnumerationFlags
[in] Specifies which routes should be enumerated. This parameter limits the set of routes returned by the enumeration API to a subset defined by the following 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 field 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
[in] 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.

Value | Description
ERROR_NO_ROUTES | There are no routes that have the 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 | There are insufficient resources to carry out the operation.
ERROR_NOT_ENOUGH_MEMORY | There is insufficient memory to allocate the handle.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtm.h.
Library: Use Rtm.lib.

See Also

Routing Table Manager Version 1 Reference, Routing Table Manager Version 1 Functions, 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
[in] Handle that identifies the enumeration and specifies its scope. Obtain this handle by calling RtmCreateEnumerationHandle.
Route
[out] 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

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Description
ERROR_INVALID_HANDLE | The EnumerationHandle parameter is not valid.
ERROR_NO_MORE_ROUTES | There are no more routes in the enumeration.
ERROR_NO_SYSTEM_RESOURCES | There are 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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtm.h.
Library: Use Rtm.lib.

See Also

Routing Table Manager Version 1 Reference, Routing Table Manager Version 1 Functions, 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
[in] Handle to the enumeration to terminate. Obtain this handle by calling RtmCreateEnumerationHandle.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Description
ERROR_INVALID_HANDLE | The EnumerationHandle parameter is not valid.
ERROR_NO_SYSTEM_RESOURCES | There are insufficient resources to carry out the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtm.h.
Library: Use Rtm.lib.

See Also

Routing Table Manager Version 1 Reference, Routing Table Manager Version 1 Functions, 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
[in] Handle that identifies the client, and therefore the routing protocol, of the routes to be deleted.
EnumerationFlags
[in] Specifies which routes should be enumerated. This parameter limits the set of deleted routes to a subset defined by the following 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
[in] 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 NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Description
ERROR_NO_ROUTES | There are no routes that have 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, the enumeration flags are invalid).
ERROR_NO_SYSTEM_RESOURCES | There are insufficient resources to carry out the operation.
ERROR_NOT_ENOUGH_MEMORY | There is insufficient memory to carry out the operation.

Remarks

The function generates appropriate notification messages to all registered clients including the caller.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtm.h.
Library: Use Rtm.lib.

See Also

Routing Table Manager Version 1 Reference, Routing Table Manager Version 1 Functions, 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
[in] Specifies the protocol family of routes to retrieve, for example, IP or IPX.
EnumerationFlags
[in] Specifies the 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
[in, out] On input, 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.

Out output, Route points to the first route that matched the specified criteria.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Description
ERROR_INVALID_PARAMETER | One or more of the input parameters is invalid (for example, the protocol family is unknown, or the enumeration flags are invalid).
ERROR_NO_ROUTES | There are no routes that match the specified criteria.
ERROR_NO_SYSTEM_RESOURCES | There are 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 function (RtmEnumerateGetNextRoute).

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtm.h.
Library: Use Rtm.lib.

See Also

Routing Table Manager Version 1 Reference, Routing Table Manager Version 1 Functions, 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
[in] Specifies the protocol family of routes to retrieve, for example, IP or IPX.
EnumerationFlags
[in] Specifies which routes should be enumerated. This parameter limits the set of deleted routes to a subset defined by the following 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
[in, out] On input, 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 output, Route points to a structure that receives the first route that matched the specified criteria.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Description
ERROR_INVALID_PARAMETER | One or more of the input parameters is invalid (for example, the protocol family is unknown, or the enumeration flags are invalid).
ERROR_NO_ROUTES | There are no routes that match the specified criteria.
ERROR_NO_SYSTEM_RESOURCES | There are 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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtm.h.
Library: Use Rtm.lib.

See Also

Routing Table Manager Version 1 Reference, Routing Table Manager Version 1 Functions, RtmCloseEnumerationHandle, RtmCreateEnumerationHandle, RtmEnumerateGetNextRoute, RtmGetFirstRoute


Routing Table Manager Version 1 Structures

The Routing Table Manager Version 1 Functions use the following structures:

IP_NETWORK

IP_NEXT_HOP_ADDRESS

IP_SPECIFIC_DATA

IPX_NETWORK

IPX_NEXT_HOP_ADDRESS

IPX_SPECIFIC_DATA

PROTOCOL_SPECIFIC_DATA

RTM_IP_ROUTE

RTM_IPX_ROUTE


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
Specifies the IP network number expressed as an IP address in machine-byte order.
N_NetMask
Specifies 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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtm.h.

See Also

Routing Table Manager Version 1 Reference, Routing Table Manager Version 1 Structures, 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
Specifies the IP network address expressed as an IP address in machine-byte order.
N_NetMask
Specifies 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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtm.h.

See Also

Routing Table Manager Version 1 Reference, Routing Table Manager Version 1 Structures, 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 table 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, the route is still 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 routing table manager 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 routing table manager.
FSD_Metric
Specifies a metric value. The routing table manager 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
Specifies 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 routing table manager 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 display only these metric values. They do 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 routing table manager 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 the route should not be used by other routing protocols.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtm.h.

See Also

Routing Table Manager Version 1 Reference, Routing Table Manager Version 1 Structures, 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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtm.h.

See Also

Routing Table Manager Version 1 Reference, Routing Table Manager Version 1 Structures, 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]
Specifies the MAC address of next-hop router.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtm.h.

See Also

Routing Table Manager Version 1 Reference, Routing Table Manager Version 1 Structures, 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
Specifies flags that describe the route. Currently, this member is either zero or the following flag value:
IPX_GLOBAL_CLIENT_WAN_ROUTE
Specifies that this route is for the global network allocated for all WAN clients.
FSD_TickCount
Specifies the number of ticks it takes to reach the destination network. Routing protocols other than RIP should convert their metrics into ticks.
FSD_HopCount
Specifies the hop count associated with the route.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtm.h.

See Also

Routing Table Manager Version 1 Reference, Routing Table Manager Version 1 Structures, 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]
Specifies an array of DWORD variables. This memory is reserved for data that is specific to routing protocols.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtm.h.

See Also

Routing Table Manager Version 1 Reference, Routing Table Manager Version 1 Structures, RTM_IP_ROUTE, RTM_IPX_ROUTE


RTM_IP_ROUTE

The RTM_IP_ROUTE structure contains information that describes a route owned by 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
Specifies the time that the route entry was created or last updated. This member is set by the routing table manager. The time is expressed as a FILETIME structure.
RR_RoutingProtocol
Specifies the routing protocol that added the route.
RR_InterfaceID
Specifies the interface through which the route was obtained.
RR_ProtocolSpecificData
Specifies a PROTOCOL_SPECIFIC_DATA structure that contains memory reserved for routing-protocol-specific data.
RR_Network
Specifies an IP_NETWORK structure that contains an IP network address.
RR_NextHopAddress
Specifies an IP_NEXT_HOP_ADDRESS structure that contains the address of the next-hop router.
RR_FamilySpecificData
Specifies an IP_SPECIFIC_DATA structure that contains IP protocol-family-specific data.

Remarks

The members of the RTM_IP_ROUTE structure are all DWORD aligned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtm.h.

See Also

Routing Table Manager Version 1 Reference, Routing Table Manager Version 1 Structures, 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
Specifies the time that the route entry was created or last updated. This member is set by the routing table manager. The time is expressed as a FILETIME structure.
RR_RoutingProtocol
Specifies the routing protocol that added the route.
RR_InterfaceID
Specifies the interface through which the route was obtained.
RR_ProtocolSpecificData
Specifies a PROTOCOL_SPECIFIC_DATA structure containing memory reserved for data specific to routing protocols.
RR_Network
Specifies an IPX_NETWORK structure that contains an IP network address.
RR_NextHopAddress
Specifies an IPX_NEXT_HOP_ADDRESS structure that contains the address of the next-hop router.
RR_FamilySpecificData
Specifies an IPX_SPECIFIC_DATA structure that contains data specific to the IPX protocol family.

Remarks

The members of the RTM_IPX_ROUTE structure are all DWORD aligned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtm.h.

See Also

Routing Table Manager Version 1 Reference, Routing Table Manager Version_1_Structures, IPX_NETWORK, IPX_NEXT_HOP_ADDRESS, IPX_SPECIFIC_DATA


Routing Table Manager Version 1 Protocol Family Identifiers

The following transport identifiers are listed in Rtm.h. Use these identifiers with the RTMv1 API.

Constant | Description
RTM_PROTOCOL_FAMILY_IPX | Identifies the IPX address family.
RTM_PROTOCOL_FAMILY_IP | Identifies the IP address family.

See Also

Routing Table Manager Version 1 Reference


About Routing Table Manager Version 2

The following documentation describes the Routing Table Manager Version 2 (RTMv2) technology. The RTMv2 API is a feature of Microsoft® Windows® 2000 that you can use to write routing protocols that interact with the routing table manager.

The routing table manager is the central repository of routing information for all routing protocols that operate under the Routing and Remote Access Service (RRAS).

RTMv2 is not available for Microsoft® Windows NT® version 4.0. Additionally, RTMv2 cannot be used for IPX routing protocols that run on Windows NT 4.0 or Microsoft® Windows® 2000. If you are using IPX or writing routing protocols for Windows NT 4.0, please refer to About Routing Table Manager Version 1.

This overview describes the following topics:

  • Components of the Routing Table Manager Architecture
  • Registering with the Routing Table Manager
  • Enumerating Registered Entities
  • Using Methods
  • Using Opaque Pointers
  • Marking Routes for the Hold-Down State
  • Adding Routes
  • Retrieving Route Information
  • Updating Routes
  • Receiving Notification of Changes
  • Working with Next Hops
  • Enumerating Routing Table Entries
  • Finding Specific Information in the Routing Table
  • Maintaining Client-Specific Lists
  • Managing Handles


Components of the Routing Table Manager Architecture

This section describes the major components of the Routing Table Manager Version 2 (RTMv2) technology:

  • Router
  • Client
  • Router Manager
  • Routing Protocol
  • Forwarder
  • Routing Table Manager
  • Routing Table Manager Instance
  • Address Family
  • Routing Table
  • View
  • Routing Table Entries
    • Destinations
    • Routes and the Best Route
    • Next Hops


Router

For the purposes of this documentation, a router is a Windows NT/Windows 2000 server that is running the Routing and Remote Access Service (RRAS) and the routing table manager.


Client

A client of RTMv2 is either an instance of a routing protocol, or a management component that registers and interacts with the routing table manager using the RTMv2 API. Unless otherwise specified, any reference to a routing table manager client refers to a client of RTMv2.

A client must run in the same process as the router manager.


Router Manager

The router manager is the component of a Windows NT/Windows 2000 router that starts and manages the different routing components. The components include routing protocols, the routing table manager, and the multicast group manager.


Routing Protocol

A routing protocol is a type of client that registers with the routing table manager. Routers use routing protocols to exchange information regarding routes to a destination.

Routing protocols are either unicast or multicast. Routing protocols advertise routes to a destination.

A unicast route to a destination is used by a unicast routing protocol to forward unicast data to that destination. Examples of unicast routing protocols include: Routing Information Protocol (RIP), Open Shortest Path First (OSPF), and Border Gateway Protocol (BGP).

A multicast route to a destination is used by some multicast routing protocols to create the information that is used to forward multicast data from hosts on the destination network of the route (known as reverse path forwarding).Examples of multicast routing protocols include: Multicast Open Shortest Path First (MOSPF), Distance Vector Multicast Routing Protocol (DVMRP), and Protocol Independent Multicast (PIM).

The routing table manager supports multiple instances of the same protocol (such as Microsoft OSPF and a third-party OSPF) running on the router. This allows routers to use the different capabilities of each version. These protocols have different protocol identifiers.

Protocol identifiers are comprised of a vendor identifier and a protocol-specific identifier. The protocol-specific identifier is the same for different implementations of the protocol, such as Microsoft OSPF and a third-party implementation of OSPF. Only when the vendor and protocol-specific identifiers are combined is there a unique identifier for a routing protocol.

A protocol with the same protocol identifier (that is, the same vendor identifier and protocol-specific identifier) can register with the routing table manager multiple times. Each time, the protocol registers using a different protocol instance identifier. For example, an implementation of OSPF from a particular vendor can register as Vendor-OSPF-1 and Vendor-OSPF-2. This enables a specific protocol implementation to partition the information that it keeps in the routing table.


Forwarder

The forwarder is the kernel-mode component of the router that is responsible for forwarding data from one router interface to the others. The forwarder also decides whether a packet is destined for local delivery, whether it is destined to be forwarded out of another interface, or both.

There are two kernel-mode forwarders: unicast and multicast.

The router manager obtains the best routes to all destinations from the routing table manager. These routes are passed to the unicast forwarder. The unicast forwarder uses these routes to perform the actual forwarding of unicast data. In this manner, the unicast forwarder maintains a cache of the best routes in the unicast view of the routing table.

The multicast group manager uses information from the multicast view of the routing table to add multicast forwarding entries to the multicast forwarder.


Routing Table Manager

The routing table manager is the central repository of routing information for all routing protocols that operate under the Routing and Remote Access Service (RRAS). It notifies clients when changes have occurred, and allows clients to exchange private information.

The routing table manager provides routing information to all interested clients, such as routing protocols, management programs, and monitoring programs. The routing table manager also determines the best route to each destination network that is known to the routing protocols. The routing table manager determines this route based on routing protocol priorities and on the metrics associated with the routes. The person administering the router can configure routing protocol priorities using the RRAS management console.

The routing table manager passes the best-route information to the forwarders (one per address family, or one per interface) and to all interested clients.

Each client registers with the routing table manager, and in return receives a handle that the client uses to add or delete routes. Clients can retrieve information stored in the routing table. Additionally, clients can register with the routing table manager to receive notification of changes to the best route to a destination.


Routing Table Manager Instance

An instance is a separate table that the routing table manager uses to maintain routing information about a subset of interfaces. Instances are typically used to enable a physical router to act as a set of virtual routers – one virtual router per logical network.

Currently, the routing table manager supports only one instance (identified as zero, the default). The client can register with other instances, but no virtual router except the default one is recognized or used by the router manager.


Address Family

Address families include Internet Packet Exchange (IPX), Internet Protocol Version 4 (IPv4), and Internet Protocol Version 6 (IPv6). Address families can also be referred to as protocol families. These address families are defined in RFC 1700.


Routing Table

The routing table manager maintains a distinct routing table for each address family (such as IPX and IPv4). The IPX address family is supported by the RTMv1 API; IPv4 is supported by the RTMv2 API.

The routing table consists of destinations, routes, and next hops. These entries define a route to a destination network.


View

A view is a subset of the routing table and contains a group of related routes (for example, multicast routes). Currently, only unicast and multicast views are supported. Views are sometimes called routing information bases (RIBs).


Routing Table Entries

The routing table consists of three types of entries: destinations, routes, and next hops.


Destinations

A destination in the routing table is a network entry represented by a network address and a network mask.

A destination entry in the routing table includes:

  • The address, expressed as a network address and network mask.
  • A list of routes to the destination.
  • A list of opaque pointer slots.
  • The views in which this destination is valid. The destination contains a structure for each view that contains the following information:
    • An identifier for the view.
    • A pointer to the best route to the destination in this view.
    • The owner of the best route in this view.
    • Flags associated with the best route in this view.
    • Handle to any routes that are in a hold-down state in this view.


Routes and the Best Route

A route is a "network path" to a destination that has a certain cost associated with it. The cost is represented by its administrative preference and its protocol-specific metric. Routes with lower costs are preferred over all other routes.

A route entry in the routing table includes:

  • A handle to the destination
  • The owner of this route
  • The neighbor (peer) that provided the route information
  • Flags associated with the state of the route
  • Flags associated with the route
  • The preference and metric for the route
  • The list of views to which the route belongs
  • Information that is private to the owner of the route
  • A list of next hops used to reach the destination

The following values, taken together, uniquely identify a route in the routing table:

  • The destination network
  • The owner of the route
  • The neighbor who supplied the route

Metrics and Preference

Each route has an administrative preference (specified by the routing policy), and a client-dependent metric. The routing table manager uses this information to determine which route is the better route to a destination. Routes with lower preference are better routes (one being lowest, and therefore best). If two routes have the same preference, the route with the lower metric is the better route.

Normally, the preference of a route is determined by the preference of the client that added the route. However, for any routes added using the Netsh.exe management tool, a preference value can be specified on a per-route basis.

Preference is normally used to indicate priority between clients. For example, an administrator can assign OSPF a lower (better) preference than RIP. In this case, OSPF routes are preferable to RIP routes.


Next Hops

Routes have one or more next hops associated with them. If the destination is not on a directly connected network, the next hop is the address of the next router (or network) on the outgoing network that can best route data to the destination. The best route is the route that has the least cost, based on the routing policy in use. Each next hop can be used to forward data on the path to the destination. All routes owned by a client share a common set of next-hop entries that were added by the client.

Each next hop is uniquely identified by the address of the next hop and the interface index used to reach the next hop.

If the next hop itself is not directly connected, it is marked as a "remote" next hop. In this case, the forwarder must perform another lookup using the next hop's network address. This lookup is necessary to find the "local" next hop used to reach the remote next hop and the destination.

A next-hop entry in the routing table includes:

  • The network address of the next hop
  • The owner of the next hop
  • The identifier of the outgoing interface
  • The state of the next hop
  • Flags associated with the next hop
  • Information that is private to the owner of the next hop
  • A handle to the destination corresponding to the remote next hop


How the Routing Table Manager Architecture Fits Together

The following illustration shows the relationship between the different components of a router.

When the router is bootstrapped, the router manager service is started, as well as one or more routing protocols. Routing protocols are associated with the various interfaces on the router. The router manager also starts the routing table manager.

The following illustration shows the relationship between clients and the different components of the routing table manager.

The router manager starts one or more instances of the routing table manager. When multiple instances of the routing table manager are started, the router has been configured to act as one or more virtual routers. Each instance of the routing table manager owns one or more interfaces; each interface can only be owned by one instance of the routing table manager.

Each instance of the routing table manager is independent from the others; no information is exchanged between the instances.

Each instance of the routing table manager contains one or more routing tables. Each routing table is associated with an address family.

Each routing table contains one or more views. In this example, the routing table is shown with a unicast and multicast view. Each view is a subset of the routing table.

The following illustration shows the relationship between clients and multiple instances of the routing table manager, routing tables, and views.

An instance of the client can register multiple times with an instance of the routing table manager — once per address family. A client can register with each instance of the routing table manager.

The following illustration shows how the routing table entries are related. For more information on routing table entries, see Routing Table Entries.

The routing table contains destinations. Each destination is related to one or more routes. Each route has zero, one, or more pointers to next hops that are associated with the route. Each pointer refers to the actual next hop in the list of next hops. Each client that registers with the routing table manager creates a list of next hops that the client owns.

Routes can only contain pointers to the next-hop list associated with the client that owns the route.


Registering with the Routing Table Manager

Before a client can access the routing table, it first must register with the routing table manager using the RtmRegisterEntity function.

When a client registers, it passes to the routing table manager an RTM_ENTITY_INFO structure. This structure contains the information that uniquely identifies a client, the address family, and the instance of the routing table manager with which the client is registering. A client can also establish the RTM_EVENT_CALLBACK callback. The routing table manager will use this callback to notify the client of events such as change notifications and client registrations.

The routing table manager completes its registration processing and returns a handle to the client. The client must use this handle for all subsequent calls to RTMv2 functions.

The RtmRegisterEntity function that is used in RTMv2 is analogous to the RtmRegisterClient function that is used in RTMv1. The RtmRegisterClient function is obsolete, except for clients using IPX.

Once a client has finished interacting with the routing table manager, it must call RtmDeregisterEntity. The routing table manager destroys the handle associated with the client. To avoid memory leaks, the client must ensure that it releases all handles and deletes all the routes and next hops that it owns before calling RtmDeregisterEntity .

For sample code that shows how to use these functions, see Register with the Routing Table Manager and Use the Event Notification Callback.


Enumerating Registered Entities

Once a client has registered, the client can obtain a list of all the other clients that have registered with the routing table manager. Some clients must perform certain operations if the presence of a particular type of client is detected.

The client can call the RtmGetRegisteredEntities function. A buffer of RTM_ENTITY_INFO structures is returned. Once the client has processed this information, the client should call RtmReleaseEntities to release the handles in the RTM_ENTITY_INFO structures.

If the routing table manager client supplied a callback function in the call to RtmRegisterEntity, the client is notified when any other clients register or unregister.

For sample code that shows how to use these functions, see Enumerate the Registered Entities and Use the Event Notification Callback.


Using Methods

When a client registers with the routing table manager, it can export a set of methods. These methods are used by other clients to obtain client-specific information. Methods enable private communication between clients of the routing table manager.

A client can obtain the list of methods exported by another client. The client calls the RtmGetEntityMethods function, supplying the target client's handle.

Each method exported by a client is uniquely identified by its method identifier. Each client can export up to 32 methods. Each method corresponds to a bit set in the MethodType member of the RTM_ENTITY_EXPORT_METHOD structure. To invoke multiple methods, the client should perform a logical OR of the identifiers for those methods. The syntax and semantics of input and output structures for each protocol must be specified when the protocol is implemented.

Note Method identifier values that correspond to a bit set in the lower half of the MethodType member (the lower 16 bits) are reserved by Microsoft.

To invoke a second client's method, a client calls the RtmInvokeMethod function. The routing table manager arbitrates all requests to invoke a client's methods. The routing table manager performs two functions when it arbitrates between clients:

  • Preventing the second client from invoking a method for a client that is unregistering.
  • Holding an "invoke" request when methods are blocked, and allowing the request to continue when the methods are unblocked.

If a client must prevent other clients from executing its methods, the client can call RtmBlockMethods. The routing table manager will not allow a call to RtmInvokeMethod to be processed until the client unblocks its methods again.

Clients typically block methods when making changes to the private data that is exchanged between clients. Blocking methods is an optional action. A client can also use internal locks to prevent other clients from invoking methods.

For sample code that shows how to use these functions, see Obtain and Call the Exported Methods for a Client.


Using Opaque Pointers

Clients often must store additional, client-specific information about destinations. The routing table manager enables clients to store this information in destination structures in the routing table. The information is stored and retrieved using "opaque pointers". The information stored is private, and accessible only to the client that owns the opaque pointer.

For example, the multicast group manager keeps a list of multicast forwarding entries that are dependent on a particular destination. The multicast group manager uses an opaque pointer in that destination. In another example, a routing protocol that advertises a particular destination can keep information related to its own route advertisement of the destination using an opaque pointer, even though it does not own the best route.

The number of opaque pointers is limited; these pointers are allocated to clients on a first-come, first-served basis. The router administrator must allocate the correct number of pointers during the router configuration; therefore, routing protocols and other clients must document their use of opaque pointers.


Accessing Opaque Pointers

Clients are able to access the information stored in destinations by using opaque pointers. To use the storage, the client must first call RtmGetOpaqueInformationPointer to obtain the pointer. Whenever a change to the information is necessary, the client must first lock the destination by calling RtmLockDestination with the LockDest parameter set to TRUE. Once the destination is locked, the client can make the necessary change. The destination can be unlocked using another call to RtmLockDestination with the LockDest parameter set to FALSE.

The RtmLockDestination function also allows a client to use either a read lock or a write lock, using the Exclusive parameter. A client should use the write lock only when it is making changes to the information kept using the opaque pointer. Clients can use the read lock to view the opaque pointer information stored in a destination.

For sample code that shows how to use these functions, see Access the Opaque Pointer in a Destination.


Marking Routes for the Hold-Down State

Some clients, such as distance vector protocols like RIP and DVMRP, require that destinations be advertised as unreachable for a certain time after the last route to the destination is deleted. The last route that is deleted must be advertised as unreachable even if newer routes arrive in the meantime. The last route deleted is marked as being in a "hold-down state". The hold-down process prevents the formation of routing loops. Routing loops are caused when a routing protocol advertises obsolete routing information. When the hold-down expires, these protocols resume their advertisement with the new best route.

A protocol that implements hold-down states indicates that a destination is in a hold-down state by using the RtmHoldDestination function. The client calls this function when it advertises the best route to this destination. If all routes to this destination are later deleted, the last route that is deleted is kept in a hold-down state for the period of time specified in the earlier call to RtmHoldDestination.

When a protocol advertises a destination, the route information that is used depends on whether the protocol uses hold-down states and if a route in the hold-down state exists for the destination.

Protocols that do not use hold-down states can ignore route information that relates to hold-down states for a destination, and always advertise the best route.

For sample code that shows how to use these functions, see Use the Route Hold-Down State.


Adding Routes

Once a client has discovered a route, the client can add that route to the routing table by calling the RtmAddNextHop function.

A client can remove routes from the routing table by calling the RtmDeleteRouteToDest function.

For sample code that shows how to use these functions, see Add and Update Routes Using RtmAddRouteToDest.


Retrieving Route Information

There are three methods used to obtain route information from the routing table manager.

  • Enumerating routes (described in Enumerating Routing Table Entries).
  • Searching for specific routes (described in Finding Specific Information in the Routing Table).
  • Retrieving changed destinations (described in Receiving Notification of Changes).


Updating Routes

A client can use either of the following two methods to update or remove routes that it owns:

  • Updating Routes Using RtmAddRouteToDest
  • Updating Routes In Place Using RtmUpdateAndUnlockRoute


Updating Routes Using RtmAddRouteToDest

If the client does not require efficiency when adding a route, it should use the following method of updating routes. This method is less efficient since it requires obtaining a handle to the route and passing the RTM_ROUTE_INFO structure to and from the routing table manager. This method also takes more time. Since RtmAddRouteToDest does not manipulate the routing table directly, using this method trades efficiency for simplicity.

For sample code that shows how to use these functions, see Add and Update Routes Using RtmAddRouteToDest.


Updating Routes In Place Using RtmUpdateAndUnlockRoute

Updating in place is generally more efficient than updating the routing table with an indirect method such as that used by the RtmAddRouteToDest function. This method is more efficient because the client is not required to obtain a handle, nor to pass the RTM_ROUTE_INFO structure to and from the routing table manager. This method also takes less time. However, directly updating the routing table can be risky, since the routing table manager is not functioning as an intermediary.

For sample code that shows how to use these functions, see Update a Route In Place Using RtmUpdateAndUnlockRoute.


Receiving Notification of Changes

Many clients can simultaneously update the routing table, and clients must be notified when changes to routing information occur. For example, a client that is not notified of another client's changes to the routing table could advertise outdated route information. This can be prevented by programming clients to register with the routing table manager to be notified of changes in the routing table. The routing table manager sends notifications of changes to all clients that register to receive them.

Change notification applies only to destinations. There is no way to query the routing table manager for changes to a particular route.

When a change is made to one of the routes to a destination, the routing table manager sends out a notification that a change has occurred. This notification goes only to those clients that have registered with the routing table manager for the type of change that has occurred. All changes to routing information in the routing table manager occur in one or more views, and change notification messages can be requested in any subset of supported views.

There are currently three types of change notifications for which a client can register:

  • Notification of any change to the routes for the destination. This request is made using the RTM_CHANGE_TYPE_ALL flag.
  • Notification if the best route to the destination changes, or any of the following information for the current best route changes:
    • Preference
    • Next hops
    • Route flags

    This request is made using the RTM_CHANGE_TYPE_BEST flag.

  • Notification of all changes of the type RTM_CHANGE_TYPE_BEST, except changes in non-forwarding flags in the best route. For example, the router manager waits for changes of this type in the unicast view, and updates information in the unicast forwarder. This request is made using the RTM_CHANGE_TYPE_FORWARDING flag.

Requests for notifications of changes can also be restricted to a subset of destinations by registering for notifications of changes only to "marked" destinations. The client can mark a destination for change notification by calling RtmMarkDestForChangeNotification.

When a change occurs, the routing table manager checks to see if there are any clients that must be notified of this change. A client must be notified of a change if all of the following conditions are met:

  • The type of change that occurred is a type for which the client has registered for notification
  • Changes to a destination that the client has marked have occurred or any destination, if the client has requested changes for all destinations
  • The client requested change notification for the view in which this change occurred

If the change meets all of the above criteria, the change is cached and the client is notified.

The notification does not specify what the actual changes are, only that they have occurred. The client must retrieve the changes by calling RtmGetChangedDests using the notification handle that was obtained from a previous call to RtmRegisterForChangeNotification.


Registering for Change Notification

A client can register to receive notification of changes to routing information that is stored in the routing table manager. This request can only be made after a client has registered with the routing table manager.

To register for change notification, a client must call RtmRegisterForChangeNotification, specifying the types of changes for which the client must receive notification. If the client must be notified of change to specific destinations, the client calls RtmMarkDestForChangeNotification once for each destination.

The client can stop receiving change notifications by calling RtmDeregisterFromChangeNotification.

For sample code that shows how to use these functions, see Register For Change Notification.


Retrieving Changes

Once a client has registered for notification of certain changes and one or more of these changes occurs, the client receives a notification from the routing table manager. The routing table manager uses the RTM_EVENT_CALLBACK callback that was supplied in a previous call to RtmRegisterEntity. The routing table manager indicates that a RTM_CHANGE_NOTIFICATION event has occurred.

For sample code that shows how to use these functions, see Use the Event Notification Callback.


Retrieving Change Status and Ignoring Changes

The client can query the routing table manager to find out if a notification of a change to a destination is pending by calling RtmGetChangeStatus. This function returns TRUE until the caller retrieves this change by calling RtmGetChangedDests.

A client can use this query to avoid performing an action that would have to be undone after the change notification is received and processed. Using this feature allows the client to work efficiently by deferring certain operations to a later time.

The client can also ignore a pending change notification for a destination by calling RtmIgnoreChangedDests. A later call to RtmGetChangedDests will not return this destination unless another change occurrs after the call to RtmIgnoreChangedDests.


Working with Next Hops

The RTMv2 API allows clients to work with the list of next hops that are associated with routes and destinations. Clients can add or update a next hop by calling RtmAddNextHop. Clients can delete a next hop using RtmDeleteNextHop. Clients can search for next hops by calling RtmFindNextHop.

Clients can also update the next hop directly. To do so, the client must first lock the next hop with the RtmLockNextHop function. Then the client can use the direct pointer to the routing table manager's RTM_NEXTHOP_INFO structure to make necessary modifications. Finally, the client can unlock the next hop.

Note The next-hop address and interface index fields in the next hop uniquely identify the next hop and should not be modified.


Enumerating Routing Table Entries

The enumeration functions allow a client to retrieve information about a specific type of routing table object (routes, destinations, and next hops). Both routing protocols and administration programs can use these functions to locate specific data.

For sample code that shows how to use these functions, see Enumerate All Destinations and Enumerate All Routes.


Finding Specific Information in the Routing Table

Clients must be able to locate specific information in the routing table, rather than being required to enumerate all the data. The RTMv2 API provides the ability to search for specific destinations, routes, and next hops based on certain criteria.


Retrieving Information

RTMv2 allows a client to retrieve the information referred to by a given handle using the RtmGetData_TypeInfo functions, where Data_Type is either Entity, Dest, Route, or NextHop.

Each of these function calls has a corresponding RtmReleaseData_Type function to release the handles associated with the information structure returned by the routing table manager.

Note Information for clients is available only in the current instance and address family.

For sample code that shows how to use these functions, see Search For the Best Route.

Using RtmGetExactMatchRoute and RtmGetExactMatchDestination

The RtmGetExactMatchRoute and RtmGetExactMatchDestination functions are used by clients to find a specific route or destination. These functions save time by doing the comparison work for the client.

For example, when RIP updates a route, RIP must retain the old metric information. RIP searches for the route and its information. Then RIP can copy the information and update the route.

Using RtmGetMostSpecificDestination

The RtmGetMostSpecificDestination function is used to locate the destination that best matches the specified network prefix.

For example, the multicast group manager uses this function to perform a reverse-path-forwarding (RPF) check on a single address. The function can also be used to find the local next hop for a given remote next hop.

For sample code that shows how to use these functions, see Search for Routes Using RtmGetMostSpecificDestination and RtmGetLessSpecificDestination and Search For the Best Route.

Using RtmGetLessSpecificDestination

The RtmGetLessSpecificDestination function is used to locate the destination that is the next-best match for the specified network prefix. This function can be called repeatedly to return the next successive less-specific match, until no more destinations match.

This function is called after a call to RtmGetMostSpecificDestination.

For sample code that illustrates how to use these functions, see Search for Routes Using RtmGetMostSpecificDestination and RtmGetLessSpecificDestination.

Using RtmIsBestRoute

The RtmIsBestRoute function enables a client to quickly find out whether or not a particular route is the best route to a destination. For example, a client may need to store a particular route only if it is the best route. Therefore, the client can call this function, instead of enumerating all routes and making the comparison itself.


Maintaining Client-Specific Lists

RTMv2 provides functions that enable clients to create a private list of routes stored in the routing table. Using this list can be more efficient than enumerating routes from the routing table.

For sample code that shows how to use these functions, see Use a Client-Specific Route List.


Managing Handles

The routing table manager maintains a reference count for all the information that it maintains. This prevents the routing table manager from returning to a client any handles to memory that has been freed. Each time a handle is returned to the caller, either as an explicit handle or as part of an information structure, such as RTM_DEST_INFO, the reference count for the object that corresponds to the handle is incremented. When the handle or the information structure is released, the appropriate reference count is decremented. When the reference count becomes zero, the object is freed.

Each RtmGetData_TypeInfo function, where Data_Type is either Dest, Route, NextHop, or Entity, returns an information structure that has a corresponding RtmReleaseData_TypeInfo function. The release functions free the handles returned by the routing table manager. Similarly there are functions of type RtmReleaseData_Types that release handles that were returned by other functions.

Note The RtmReleaseChangedDests function should be used to release handles that have been returned by a call to RtmGetChangedDests. Do not use RtmReleaseDests for changed destination structures.

If a client must keep a specific handle in an information structure while releasing the rest, the client can call RtmReferenceHandles with that handle before releasing the information structure. The handle can then later be released by a call to RtmReleaseData_Type.


Using Routing Table Manager Version 2

Before you begin developing clients that use the RTMv2 APIs, review the RTMv2 Programming Issues

This section contains sample code that can be used when developing clients such as routing protocols. This sample code shows how to carry out the following tasks:

  • Register with the Routing Table Manager
  • Enumerate the Registered Entities
  • Obtain and Call the Exported Methods for a Client
  • Register for Change Notification
  • Add and Update Routes Using RtmAddRouteToDest
  • Update a Route In Place Using RtmUpdateAndUnlockRoute
  • Use the Route Hold-Down State
  • Enumerate All Destinations
  • Enumerate All Routes
  • Search for the Best Route
  • Search for Routes Using RtmGetMostSpecificDestination and RtmGetLessSpecificDestination
  • Access the Opaque Pointer in a Destination
  • Use a Client-Specific Route List
  • Use the Event Notification Callback


RTMv2 Programming Issues

RTMv2 functions are written with the following assumptions:

  • RTMv2 functions do not allocate memory for the client. The client must always allocate memory.
  • When a client is unregistering, it must perform "clean-up" operations itself, such as releasing all memory allocated.
  • Clients must release handles correctly; memory leaks can occur if a client does not observe this practice.


Register with the Routing Table Manager

The following sample code shows how to register with the routing table manager.

// In the following example, VendorId stands for the 14 bit ID that identifies
// the vendor. For more information, see the Routprot.h file in the SDK.

RTM_ENTITY_INFO EntityInfo;
DWORD       Status;

EntityInfo.RtmInstanceId = 0;   // Must be set to default for now
EntityInfo.AddressFamily = AF_INET;
EntityInfo.EntityId.EntityProtocolId = PROTO_IP_RIP;
EntityInfo.EntityId.EntityInstanceId =
    PROTOCOL_ID(PROTO_TYPE_UCAST, VendorId, PROTO_IP_RIP);

Status = RtmRegisterEntity(EntityInfo,
                           (PRTM_ENTITY_EXPORT_METHODS) ExportMethods,
                           EntityEventCallback,
                           TRUE,
                           &RegnProfile,
                           &RtmRegHandle);

if (Status != NO_ERROR)
{
    // Registration failed - Log an Error and Quit
    ...
    return Status;
}


Enumerate the Registered Entities

The following sample code shows how to create an enumeration of registered clients and obtain the client information from the routing table manager.

NumEntities = 0;

Status = RtmGetRegisteredEntities(RtmRegHandle,
                                  &NumEntities,
                                  NULL,
                                  NULL);

if (Status == ERROR_INSUFFICIENT_BUFFER)
{
    // Plan for growth
    NumEntities += 5;

    // Allocate space (on stack for convenience) to get info
    EntityInfos = _alloca(NumEntities * sizeof(RTM_ENTITY_INFO));
    EntityHandles = _alloca(NumEntities * sizeof(HANDLE));

    Status = RtmGetRegisteredEntities(RtmRegHandle,
                                      &NumEntities,
                                      EntityHandles,
                                      EntityInfos);

    for (i = 0; i < NumEntities; i++)
    {
        // Process entity info
        if (EntityInfo[i].EntityProtocolId == PROTO_IP_OSPF)
        {
            // This is an OSPF registration

            // Do you want to get methods?
            ...
        }
    }

    RtmReleaseEntities(RtmRegHandle, NumEntities, EntityHandles);

    // At this point, we do not have to release entities since
    // the RTM_ENTITY_INFO structures do not contain handles
}


Obtain and Call the Exported Methods for a Client

The following sample code shows how to obtain a list of methods a client has exported, and how to invoke a method for that client.

//_____________________________________

//Obtaining an entity's export methods
//_____________________________________

// Specify 0 to get actual number of methods

NumMethods = 0;

Status = RtmGetEntityMethods(RtmRegHandle,
                             EntityHandle,
                             &NumMethods,
                             NULL);

if (Status == ERROR_INSUFFICIENT_BUFFER)
{
        // Get actual number of methods now

    ExportMethods = malloc(NumMethods * sizeof(PVOID));

    Status = RtmGetEntityMethods(RtmRegHandle,
                                 EntityHandle,
                                 &NumMethods,
                                 ExportMethods);

    if (Status == NO_ERROR)
    {
        // You have obtained methods for the
        // entity corresponding to EntityHandle
    }
}

//__________________________________

//Calling an entity's export methods
//__________________________________

// You cannot call a method directly
// You must use the RtmInvokeMethod API

Input.MethodType = METHOD_TYPE_ALL_METHODS; // Or 'OR' of methods to call

// Set the method input and its size
// (assume input is a route handle)

Input.InputSize = sizeof(HANDLE);
Input.InputData[0] = RouteHandle;

// Assume that there is no output data for
// any function other than an error code

OutputHdrSize = FIELD_OFFSET(RTM_ENTITY_METHOD_OUTPUT, OutputData);
OutputSize = OutputHdrSize * MAX_METHODS;
Output = _alloca(OutputSize);

Status = RtmInvokeMethod(RtmRegHandle,
                         EntityHandle,
                         &Input,
                         &OutputSize,
                         Output);

if (Status == NO_ERROR)
{
    // Parse the output from each method
    ;
}


Register For Change Notification

The following sample code shows how to register for changes to best routes to all destinations in the unicast view of the routing table.

// In this call, you are registering for changes on
// all destinations (not just those destinations marked before)

Status = RtmRegisterForChangeNotification(RtmRegHandle,
                                          RTM_VIEW_MASK_UCAST,  // Unicast route changes only
                                          RTM_CHANGE_TYPE_BEST, // Changes in best routes only
                                          NotifyContext, // Context was returned RTM_EVENT_CALLBACK
                                          &NotifyHandle);

if (Status != NO_ERROR)
{
    // Registration for change notifications failed
    ...
    return Status;
}

// For processing changes upon notification, please
// refer to the implementation of RTM_EVENT_CALLBACK.


Add and Update Routes Using RtmAddRouteToDest

The function RtmAddRouteToDest is used to add new routes and update existing routes for a destination. The following procedures explain both cases. The sample code that follows shows how to implement the first procedure.

To add a route, the client should take the following steps

  1. If the client has already cached the next-hop handle, go to step 4.
  2. Create an RTM_NEXTHOP_INFO structure and fill it with the appropriate information.
  3. Add the next hop to the routing table by calling RtmAddNextHop. The routing table manager returns a handle to the next hop. If the next hop already exists, the routing table does not add the next hop; instead it returns the handle to the next hop.
  4. Create an RTM_ROUTE_INFO structure and fill it with the appropriate information, including the next-hop handle returned by the routing table manager.
  5. Add the route to the routing table by calling RtmAddRouteToDest. The routing table manager compares the new route to the routes that are already in the routing table. Two routes are equal if all of the following conditions are true:
    • The route is being added to the same destination.
    • The route is being added by the same client as specified by the Owner member of the RTM_ROUTE_INFO structure.
    • The route is advertised by the same neighbor as specified by the Neighbor member of the RTM_ROUTE_INFO structure.

    If the route exists, the routing table manager returns the handle to the existing route. Otherwise, the routing table manager adds the route and returns the handle to the new route.

    The client can set the Change_Flags parameter to RTM_ROUTE_CHANGE_NEW to instruct the routing table manager to add a new route on the destination, even if another route with the same owner and neighbor fields exists.

    The client can set the Change_Flags parameter to RTM_ROUTE_CHANGE_FIRST to tell the routing table manager to update the first route on the destination owned by the client. This update can be performed if such a route exists, even if the neighbor field does not match. This flag is used by clients that maintain a single route per destination.

To update a route, the client should take the following steps

  1. Call RtmGetRouteInfo with the handle to the route. The handle is either one previously cached by the client, or returned by the routing table manager from a call that returns a route handle such as RtmGetRouteInfo.
  2. Make the changes to the RTM_ROUTE_INFO structure that is returned by the routing table manager.
  3. Call RtmAddRouteToDest with the handle to the route and the changed RTM_ROUTE_INFO structure.

The following sample code shows how to add a route to a destination using the routing table manager as an intermediary.

// Add a route to a destination given by (addr, masklen)
// using a next hop reachable with an interface

RTM_NEXTHOP_INFO NextHopInfo;

// First, create and add a next hop to the caller's
// next-hop tree (if it does not already exist)

ZeroMemory(&NextHopInfo, sizeof(RTM_NEXTHOP_INFO);

RTM_IPV4_MAKE_NET_ADDRESS(&NextHopInfo.NextHopAddress,
                          nexthop, // Address of the next hop
                          32);

NextHopInfo.InterfaceIndex = interface;

NextHopHandle = NULL;

Status = RtmAddNextHop(RtmRegHandle,
                       &NextHopInfo,
                       &NextHopHandle,
                       &ChangeFlags);

if (Status == NO_ERROR)
{
    // Created a new next hop or found an old one

        // Fill in the route information for the route

    ZeroMemory(&RouteInfo, sizeof(RTM_ROUTE_INFO);

    // Fill in the destination network's address and mask values
    RTM_IPV4_MAKE_NET_ADDRESS(&NetAddress, addr, masklen);

    // Assume 'neighbour learnt from' is the first next hop
    RouteInfo.Neighbour = NextHopHandle;

    // Set metric for route; Preference set internally
    RouteInfo.PrefInfo.Metric = metric;

    // Adding a route to both the unicast and multicast views
    RouteInfo.BelongsToViews = RTM_VIEW_MASK_UCAST|RTM_VIEW_MASK_MCAST;

    RouteInfo.NextHopsList.NumNextHops = 1;
    RouteInfo.NextHopsList.NextHops[0] = NextHopHandle;

    // If you want to add a new route, regardless of
    // whether a similar route already exists, use the following
    //     ChangeFlags = RTM_ROUTE_CHANGE_NEW;

    ChangeFlags = 0;

    Status = RtmAddRouteToDest(RtmRegHandle,
                               &RouteHandle,     // Can be NULL if you do not need handle
                               &NetAddress,
                               &RouteInfo,
                               1000,             // Time out route after 1000 ms
                               RouteListHandle1, // Also add the route to this list
                               0,
                               NULL,
                               &ChangeFlags);

    if (Status == NO_ERROR)
    {
        if (ChangeFlags & RTM_ROUTE_CHANGE_NEW)
        {
        ; // A new route has been created
        }
        else
        {
        ; // An existing route is updated
        }

        if (ChangeFlags & RTM_ROUTE_CHANGE_BEST)
        {
        ; // Best route information has changed
        }

        // Release the route handle if you do not need it
        RtmReleaseRoutes(RtmRegHandle, 1, &RouteHandle);
    }

    // Also release the next hop since it is no longer needed
    RtmReleaseNextHops(RtmRegHandle, 1, &NextHopHandle);
}


Update a Route In Place Using RtmUpdateAndUnlockRoute

The following procedure outlines the steps used to update a route in place. The sample code that follows shows how to implement the procedure.

To update a route in place, the client should take the following steps

  1. Lock the route by calling RtmLockRoute. Currently, this function actually locks the route's destination. The routing table manager returns a pointer to the route.
  2. Use the pointer to the routing table manager's RTM_ROUTE_INFO structure, obtained in step 1, to make the necessary changes to the route. Only certain members of the RTM_ROUTE_INFO structure can be modified when updating in place. These members are: Neighbour, PrefInfo, EntitySpecificInfo, BelongsToViews, and NextHopsList.

    Note If the client adds information to either the Neighbour or NextHopList members, the client must call RtmReferenceHandles to explicitly increment the reference count that the routing table manager keeps on the next-hop object. Similarly, if the client removes information from the NextHopList member, the client must call RtmReleaseNextHops to decrement the reference count.

  3. Call RtmUpdateAndUnlockRoute to notify the routing table manager that a change has taken place. The routing table manager commits the changes, updates the destination to reflect the new information, and then unlocks the route.

The following sample code shows how to update a route directly, using a pointer to the actual route information in the routing table.

Status = RtmLockRoute(RtmRegHandle,
                      RouteHandle,
                      TRUE,
                      TRUE,
                      &RoutePointer);

if (Status == NO_ERROR)
{
        // Update route parameters in place (i.e., directly on
// the routing table manager's copy)

    // Update the metric and views of the route
    RoutePointer->PrefInfo.Metric = 16;

    // Change the views so that the route belongs to only the multicast view
    RoutePointer->BelongsToViews = RTM_VIEW_MASK_MCAST;

    // Set the entity-specific information to X
    RoutePointer->EntitySpecificInfo = X;

    // Note that the following manipulation of
    // next-hop references is not needed when
    // using RtmAddRouteToDest, as it is done
    // by the routing table manager automatically

    // Change next hop from NextHop1 to NextHop2
    NextHop1 = RoutePointer->NextHopsList.NextHop[0];

    // Explicitly dereference the old next hop
    RtmReleaseNextHops(RtmRegHandle, 1, &NextHop1);

    RoutePointer->NextHopsList.NextHop[0] = NextHop2;

    // Explicitly reference next hop being added
    RtmReferenceHandles(RtmRegHandle, 1, &NextHop2);

    // Call the routing table manager to indicate that route information
    // has changed, and that its position might
    // have to be rearranged and the corresponding destination
    // needs to be updated to reflect this change.

    Status = RtmUpdateAndUnlockRoute(RtmRegHandle,
                                     RouteHandle,
                                     INFINITE, // Keep forever
                                     NULL,
                                     0,
                                     NULL,
                                     &ChangeFlags);
    ASSERT(Status == NO_ERROR);
}


Use the Route Hold-Down State

The following sample code shows how to mark a destination for the hold-down state, and how to create a destination enumeration that includes routes that are in the hold-down state.

// Macro to allocate a RTM_DEST_INFO on the stack

#define ALLOC_RTM_DEST_INFO(NumViews, NumInfos)
        (PRTM_DEST_INFO) _alloca(RTM_SIZE_OF_DEST_INFO(NumViews) * NumInfos)

// Mark the destination for hold down in Unicast view

Status = RtmHoldDestination(RtmRegHandle,
                            DestHandle,
                            RTM_VIEW_MASK_UCAST,
                            30*1000); // 30 seconds
// Check Status

// When the last route on this destination is deleted,
// it is moved from the ViewInfo's Route to HoldRoute.

// To enumerate all destinations - even the ones with
// just hold down routes, use the following API calls

// Code to enumerate destinations in the table

MaxHandles = RegnProfile.MaxHandlesInEnum;

DestInfos = ALLOC_RTM_DEST_INFO(NumViews, MaxHandles);

DestInfoSize = RTM_SIZE_OF_DEST_INFO(NumViews);

// Enumerate all destinations in the subtree (0 / 0)
// (basically the whole tree; you can
// also achieve this by using RTM_ENUM_START)

RTM_IPV4_MAKE_NET_ADDRESS(&NetAddress,
                          0x00000000,
                          0);

// Create a destination enumeration in views = RTM_VIEW_MASK_ANY.

Status = RtmCreateDestEnum(RtmRegHandle,
                           RTM_VIEW_MASK_ANY, // MUST BE EXACTLY THE SAME AS THIS
                           RTM_ENUM_RANGE,
                           &NetAddress,
                           RTM_BEST_PROTOCOL, // Get best route on each destination
                           &EnumHandle);

if (Status == NO_ERROR)
{
    do
    {
        NumInfos = MaxHandles;

        Status = RtmGetEnumDests(RtmRegHandle
                                 EnumHandle,
                                 &NumInfos,
                                 DestInfos);

        for (i = 0; i < NumInfos; i++)
        {
            DestInfo = (PRTM_DEST_INFO) ((PUCHAR)DestInfos+(i*DestInfoSize));

            // Process the current destination information
            // As RTM_VIEW_MASK_ANY = 0, we have
            // no view information returned in the call

            // Get actual DestInfo in the specified views
            // (Assume that only unicast is specified)

            Status = RtmGetDestInfo(RtmRegHandle,
                                    DestInfo.DestHandle,
                                    RTM_BEST_PROTOCOL,
                                    RTM_VIEW_MASK_UCAST,
                                    &DestInfoActual);

            if (Status == NO_ERROR)
            {
                HoldRoute = DestInfoActual.ViewInfo[0].HoldRoute;
                BestRoute = DestInfoActual.ViewInfo[0].Route;

                // Advertise best unicast route (or the hold down route)

                if (HoldRoute)
                {
                    // HoldRoute exists; Advertise it if hold down protocol
                    ;
                }

                RtmReleaseDestInfo(RtmRegHandle, &DestInfoActual);
            }

            ...
        }

        RtmReleaseDests(RtmRegHandle, NumInfos, DestInfos);
    }
    while (Status == NO_ERROR)

    // Close the enumeration and release its resources
    RtmDeleteEnumHandle(RtmRegHandle, EnumHandle);
}


Enumerate All Destinations

The following sample code shows how to enumerate all destinations in the routing table.

// Macro to allocate a RTM_DEST_INFO on the stack

#define ALLOC_RTM_DEST_INFO(NumViews, NumInfos)
        (PRTM_DEST_INFO) _alloca(RTM_SIZE_OF_DEST_INFO(NumViews) * NumInfos)

// Code to enumerate destinations in the table

MaxHandles = RegnProfile.MaxHandlesInEnum;

DestInfos = ALLOC_RTM_DEST_INFO(NumViews, MaxHandles);

DestInfoSize = RTM_SIZE_OF_DEST_INFO(NumViews);

// Enumerate all destinations in the subtree (0 / 0)
// (basically the whole tree; you can
// also achieve this by using RTM_ENUM_START)

RTM_IPV4_MAKE_NET_ADDRESS(&NetAddress,
                          0x00000000,
                          0);

Status = RtmCreateDestEnum(RtmRegHandle,
                           RTM_VIEW_MASK_UCAST | RTM_VIEW_MASK_MCAST,
                           RTM_ENUM_RANGE,
                           &NetAddress,
                           RTM_BEST_PROTOCOL, // Get best route for each destination
                           &EnumHandle1);
if (Status == NO_ERROR)
{
    do
    {
        NumInfos = MaxHandles;

        Status = RtmGetEnumDests(RtmRegHandle
                                 EnumHandle1,
                                 &NumInfos,
                                 DestInfos);

        for (i = 0; i < NumInfos; i++)
        {
            DestInfo = (PRTM_DEST_INFO) ((PUCHAR)DestInfos+(i*DestInfoSize));

                        // Process the current destination information

            ASSERT(DestInfo->ViewInfo[0].ViewId == RTM_VIEW_ID_UCAST);
            BestUnicastRoute = DestInfo->ViewInfo[0].Route;

            // Advertise the best unicast route for the destination
            ...

            // You can enumerate all routes for a destination by
            // creating a route enumeration using
            // RtmCreateRouteEnum ( .. DestInfo->DestHandle .. );
        }

        RtmReleaseDests(RtmRegHandle, NumInfos, DestInfos);
    }
    while (Status == NO_ERROR)

    // Close the enumeration and release its resources
    RtmDeleteEnumHandle(RtmRegHandle, EnumHandle1);
}


Enumerate All Routes

The following procedure outlines the steps used to enumerate any of the entities used by the RTMv2 API. The sample code that follows shows how to enumerate all routes.

The basic process for each enumeration is as follows

  1. Start the enumeration by obtaining a handle from the routing table manager. Call RtmCreateData_TypeEnum (where Data_Type is either Dest, Route, or NextHop), and supply the criteria that specifies the kind of information being enumerated. This criteria includes, but is not limited to a range of destinations, a particular interface, and the views in which the information resides.
  2. Call RtmGetEnumData_Type one or more times to retrieve data until the routing table manager returns ERROR_NO_MORE_ITEMS. The route, destination, and next-hop data is returned in order of the address information (and the preference and metric values, if routes are being enumerated).
  3. Call RtmReleaseData_Type when the handles or information structures associated with the enumeration are no longer needed.
  4. Call RtmDeleteEnumHandle to release the enumeration handle that was returned when the enumeration was created. This function is used to release the handle for all types of enumerations.

Note Routes that are in the hold-down state are only enumerated when a client requests data from all views using RTM_VIEW_MASK_ANY.

The following sample code shows how to enumerate all routes in the routing table.

MaxHandles = RegnProfile.MaxHandlesInEnum;

RouteHandles = _alloca(MaxHandles * sizeof(HANDLE));

// Do a "route enumeration" over the whole table
// by passing a NULL DestHandle in this function.

DestHandle = NULL; // Give a valid handle to enumerate over a particular destination

Status = RtmCreateRouteEnum(RtmRegHandle,
                            DestHandle,
                            RTM_VIEW_MASK_UCAST|RTM_VIEW_MASK_MCAST,
                            RTM_ENUM_OWN_ROUTES, // Get only your own routes
                            NULL,
                            0,
                            NULL,
                            0,
                            &EnumHandle2);
if (Status == NO_ERROR)
{
    do
    {
        NumHandles = MaxHandles;

        Status = RtmGetEnumRoutes(RtmRegHandle
                                  EnumHandle2,
                                  &NumHandles,
                                  RouteHandles);

        for (k = 0; k < NumHandles; k++)
        {
            Print("Route %d: %p\n", l++, RouteHandles[k]);

            // Get route information using the route's handle
            Status1 = RtmGetRouteInfo(...RouteHandles[k]...);

            if (Status1 == NO_ERROR)
            {
                // Do whatever you want with the route info
                ...

                // Release the route information once you are done
                RtmReleaseRouteInfo(...);
            }
        }

        RtmReleaseRoutes(RtmRegHandle, NumHandles, RouteHandles);
    }
    while (Status == NO_ERROR)

    // Close the enumeration and release its resources
    RtmDeleteEnumHandle(RtmRegHandle, EnumHandle2);
}


Search For the Best Route

The following sample code shows how to search the routing table for the best route.

// Search for a best matching route to a network
// given (address,mask) for this destination network

// First get the best matching destination

RTM_IPV4_SET_ADDR_AND_MASK(NetAddress, Addr, Mask);

Status = RtmGetMostSpecificDestination(RtmRegHandle,
                                       &NetAddress,
                                       RTM_BEST_PROTOCOL,   // Determines which route information is returned.
                                       RTM_VIEW_MASK_UCAST, // Give the information for the best unicast route
                                       DestInfo);
if (Status == NO_ERROR)
{
    ASSERT(DestInfo->ViewInfo[0].ViewId == RTM_VIEW_ID_UCAST);

    // Get the best unicast route for the destination
    NewBestRoute = DestInfo.ViewInfo[0].Route;

    // Call RtmGetRouteInfo using the handle for information
    ...

    // Release information from RtmGetMostSpecificDestination
    RtmReleaseDestInfo(RtmRegHandle, DestInfo);
}

// To search for an exact match, use RtmGetExactMatchDestionation


Search for Routes using RtmGetMostSpecificDestination and RtmGetLessSpecificDestination

The following sample code shows how to use RtmGetMostSpecificDestination and RtmGetLessSpecificDestination to walk up the prefix tree in the routing table.

// Used to walk up the prefix tree, given the destination and mask

// Search for a best matching route to a network
// given (address,mask) for this destination network

// First get the best matching destination

RTM_IPV4_SET_ADDR_AND_MASK(NetAddress, Addr, Mask);

Status = RtmGetMostSpecificDestination(RtmRegHandle,
                                       &NetAddress,
                                       RTM_BEST_PROTOCOL,   // Determines which route information is returned.
                                       RTM_VIEW_MASK_UCAST, // Give the information for best unicast route
                                       DestInfo1);
// Use RtmGetLessSpecificDestination to go up the
// tree until it returns ERROR_NOT_FOUND. Use two
// RTM_DEST_INFO buffers - DestInfo1 & DestInfo2
// alternately to avoid all unnecessary copying.

while (Status == NO_ERROR)
{
    if (DestInfo1->DestAddress.NumBits == NetAddress.NumBits)
    {
        Print("Exact Match of Destination\n");
    }

    Status = RtmGetLessSpecificDestination(RtmRegHandle,
                                           DestInfo1->DestHandle,
                                           RTM_BEST_PROTOCOL,
                                           RTM_VIEW_MASK_UCAST,
                                           DestInfo2);

    // NOTE that the buffer is DestInfo1 and not DestInfo2
    RtmReleaseDestInfo(RtmRegHandle, DestInfo1);

    if (Status != NO_ERROR)
    {
        break;
    }

    // Use any information you want in DestInfo2
    Print("Mask Len: %d\n", DestInfo2->DestAddress.NumBits);

    Status = RtmGetLessSpecificDestination(RtmRegHandle,
                                           DestInfo2->DestHandle,
                                           RTM_BEST_PROTOCOL,
                                           RTM_VIEW_MASK_UCAST,
                                           DestInfo1);

    // NOTE that the buffer is DestInfo2 and not DestInfo1
    RtmReleaseDestInfo(RtmRegHandle, DestInfo2);

    if (Status != NO_ERROR)
    {
        break;
    }

    // Use any information you want in DestInfo1
    Print("Mask Len: %d\n", DestInfo1->DestAddress.NumBits);
}


Access the Opaque Pointer in a Destination

The following sample code shows how to access the opaque pointer in a destination.

// Opaque Info Blob Defn

typedef struct _OPAQUE_INFO
{
    ULONG  Info1;
    ULONG  Info2;
}
OPAQUE_INFO, *POPAQUE_INFO;

PVOID        OpaqueInfoSlotPointer;  // Pointer to the opaque pointer slot
PVOID        OpaqueInfoSlotInfo;     // Information in the opaque pointer slot
POPAQUE_INFO OpaqueInfoPtr;          // Pointer to opaque information

// Lock the destination in exclusive mode to sync opaque pointer access
// If you know that you will only be reading the opaque pointer
// and not modifying it, then you can use a shared lock

Status = RtmLockDestination(RtmRegHandle, DestHandle, TRUE, TRUE);

if (Status != NO_ERROR)
{
   return Status;
}

// You can get a pointer to your opaque pointer slot,
// assuming that you have reserved one during registration.

Status = RtmGetOpaqueInformationPointer(RtmRegHandle,
                                        DestHandle,
                                        &OpaqueInfoSlotPointer);
if (Status == NO_ERROR)
{
    OpaqueInfoSlotInfo = * (PVOID *) OpaqueInfoSlotPointer;

    if (OpaqueInfoSlotInfo == NULL)
    {
        // No information set yet - create private information BLOB (if required)
        OpaqueInfoPtr = (POPAQUE_INFO) malloc(OpaqueInfoSize);

        if (OpaqueInfoPtr)
        {
            // Set certain information in the opaque information BLOB
            OpaqueInfoPtr->Info1 = 1;
            OpaqueInfoPtr->Info2 = 2;

            * (PVOID *) OpaqueInfoSlotPointer = OpaqueInfoPtr;
        }
        else
        {
            // Already exists; do something with the opaque information
            OpaqueInfoPtr = (POPAQUE_INFO) OpaqueInfoSlotInfo;

            // Set certain information in the opaque information BLOB
            OpaqueInfoPtr->Info1 = 3;
            OpaqueInfoPtr->Info2 = 4;
        }
    }
}

// Unlock destination from exclusive mode that we locked earlier
Status = RtmLockDestination(RtmRegHandle, DestHandle, TRUE, FALSE);

ASSERT(Status == NO_ERROR);


Use a Client-Specific Route List

The following procedures outlines the steps to use the client-specific route lists. The sample code that follows shows how to implement the procedure.

To use this feature, a client should take the following steps

  1. Call RtmCreateRouteList to obtain a handle from the routing table manager.
  2. Call RtmInsertInRouteList whenever the client must add a route to this list.
  3. When the client no longer requires the list, it should call RtmDeleteRouteList to remove the list.

If the client must enumerate the routes on the list, the client should take the following steps

  1. Call RtmCreateRouteListEnum to obtain an enumeration handle from the routing table manager.
  2. Call RtmGetListEnumRoutes to obtain the handles to the routes in the list.
  3. Call RtmReleaseRoutes to release the handles when no longer required.

The following sample code shows how to create and use a client-specific route list.

HANDLE RouteListHandle1;
HANDLE RouteListHandle2;

// Create two entity-specific lists to add routes to

Status = RtmCreateRouteList(RtmRegHandle,
                            &RouteListHandle1);
// Check Status
...

Status = RtmCreateRouteList(RtmRegHandle,
                            &RouteListHandle2);
// Check Status
...

// Assume you have added a bunch of routes
// by calling RtmAddRouteToDest many times
// with 'RouteListHandle1' specified similar to
// Status = RtmAddRouteToDest(RtmRegHandle,
//                            ...
//                            RouteListHandle1,
//                            ...
//                            &ChangeFlags);

// Enumerate routes in RouteListHandle1 list

// Create an enumeration on the route list

Status = RtmCreateRouteListEnum(RtmRegHandle,
                                RouteListHandle1,
                                &EnumHandle);

if (Status == NO_ERROR)
{
        // Allocate space on the top of the stack

    MaxHandles = RegnProfile.MaxHandlesInEnum;

    RouteHandles = _alloca(MaxHandles * sizeof(HANDLE));

    // Note how the termination condition is different
    // from other enumerations - the call to the function
    // RtmGetListEnumRoutes always returns NO_ERROR
    // Quit when you get fewer handles than requested

    do
    {
                // Get next set of routes from the list enumeration

        NumHandles = MaxHandles;

        Status = RtmGetListEnumRoutes(RtmRegHandle,
                                      EnumHandle,
                                      &NumHandles,
                                      RouteHandles);

        for (i = 0; i < NumHandles; i++)
        {
            Print("Route Handle %5lu: %p\n", i, RouteHandles[i]);
        }

        // Move all these routes to another route list
        // They are automatically removed from the old one

        Status = RtmInsertInRouteList(RtmRegHandle,
                                      RouteListHandle2,
                                      NumHandles,
                                      RouteHandles);
        // Check Status...

                // Release the routes that have been enumerated

        RtmReleaseRoutes(RtmRegHandle, NumHandles, RouteHandles);
    }
    while (NumHandles == MaxHandles);

    RtmDeleteEnumHandle(RtmRegHandle, EnumHandle);
}

// Destroy all the entity-specific route lists
// after removing all routes from these lists;
// the routes themselves are not deleted

Status = RtmDeleteRouteList(RtmRegHandle, RouteListHandle1);
ASSERT(Status == NO_ERROR);

Status = RtmDeleteRouteList(RtmRegHandle, RouteListHandle2);
ASSERT(Status == NO_ERROR);


Use the Event Notification Callback

The following procedure outlines the steps used to receive change notification messages. The sample code that follows shows how to implement the procedure.

After the client receives notice of the change from the RTM_EVENT_CALLBACK, the client can retrieve the changes by taking the following steps

  1. Call RtmGetChangedDests to retrieve a set of changes.
  2. Process the changes.
  3. Release the destinations using RtmReleaseChangedDests.
  4. Repeat steps 1, 2, and 3 until RtmGetChangedDests returns ERROR_NO_MORE_ITEMS.

The following sample code shows how to process an RTM_EVENT_CALLBACK callback received from the routing table manager.

// Macro to allocate an RTM_DEST_INFO on the stack

#define ALLOC_RTM_DEST_INFO(NumViews, NumInfos)
        (PRTM_DEST_INFO) _alloca(RTM_SIZE_OF_DEST_INFO(NumViews) * NumInfos)

// Routing table manager entity event callback

DWORD
EntityEventCallback (
    IN      RTM_ENTITY_HANDLE               RtmRegHandle,
    IN      RTM_EVENT_TYPE                  EventType,
    IN      PVOID                           Context1,
    IN      PVOID                           Context2
    )
{
    RTM_ENTITY_HANDLE EntityHandle;
    PENTITY_CHARS     EntityChars;
    PRTM_ENTITY_INFO  EntityInfo;
    RTM_NOTIFY_HANDLE NotifyHandle;
    PRTM_DEST_INFO    DestInfos;
    ULONG             DestInfoSize;
    UINT              NumDests;
    UINT              NumViews, i;
    UINT              MaxHandles;
    RTM_ROUTE_HANDLE  RouteHandle;
    PRTM_ROUTE_INFO   RoutePointer;
    DWORD             ChangeFlags;
    DWORD             Status;

    Print("\nEvent callback called for %p :", RtmRegHandle);

    Print("\n\tEntity Event = ");

    Status = ERROR_NOT_SUPPORTED;

    switch (EventType)
    {
    case RTM_ENTITY_REGISTERED:

                // Get the handle and information of the entity that registered

        EntityHandle = (RTM_ENTITY_HANDLE) Context1;
        EntityInfo   = (PRTM_ENTITY_INFO)  Context2;

        Print("Registration\n\tEntity Handle = %p\n\tEntity IdInst = %p\n\n",
              EntityHandle,
              EntityInfo->EntityId);

                // Do something if you are interested in the entity
                ;

        Status = NO_ERROR;
        break;

    case RTM_ENTITY_DEREGISTERED:

                // Get the handle and information of the entity that deregistered

        EntityHandle = (RTM_ENTITY_HANDLE) Context1;
        EntityInfo   = (PRTM_ENTITY_INFO)  Context2;

        Print("Deregistration\n\tEntity Handle = %p\n\tEntity IdInst = %p\n\n",
               EntityHandle,
              EntityInfo->EntityId);

                // Do something if you are interested in the entity
                ;

        Status = NO_ERROR;
        break;

    case RTM_CHANGE_NOTIFICATION:

        // Get the notification registration on which changes exist and
        // context supplied in RtmRegisterForChangeNotification

        NotifyHandle = (RTM_NOTIFY_HANDLE) Context1;

        NotifyContext = (PVOID) Context2; // Unused

        Print("Changes Available\n\tNotify Handle = %p\n\tNotify Context = %p\n\n",
              NotifyHandle,
              NotifyContext);

        MaxHandles = RegnProfile.MaxHandlesInEnum;

        NumViews = RegnProfile.NumberOfViews;

        DestInfoSize = RTM_SIZE_OF_DEST_INFO(NumViews);

                // Get all changes to destinations

        DestInfos = ALLOC_RTM_DEST_INFO(NumViews, MaxHandles);

        do
        {
            // Try to get as many as possible in one routing table managercall
            NumDests = MaxHandles;

            Status = RtmGetChangedDests(RtmRegHandle,
                                        NotifyHandle,
                                        &NumDests,
                                        DestInfos);

            ASSERT((Status == NO_ERROR) || (Status == ERROR_NO_MORE_ITEMS));

            DestInfo = (PRTM_DEST_INFO) DestInfos;

            for (i = 0; i < NumDests; i++)
            {
                                // Process the current destination information

                // Assuming you asked for unicast view information,
                ASSERT(DestInfo->ViewInfo[0].ViewId == RTM_VIEW_ID_UCAST);

                // Get the best unicast route for the destination.
                NewBestRoute = DestInfo.ViewInfo[0].Route;

                // Do whatever you want with above route
                ...

                // Move to the next changed one
                DestInfo = (PRTM_DEST_INFO) ((PUCHAR)DestInfo + DestInfoSize);
            }

            RtmReleaseChangedDests(RtmRegHandle,
                                   NotifyHandle,
                                   NumDests,
                                   DestInfos);
        }
        while (NumDests > 0);

        Status = NO_ERROR;
        break;

    case RTM_ROUTE_EXPIRED:

                // Get handle and a direct pointer to the route whose timer expired

        RouteHandle = (RTM_ROUTE_HANDLE) Context1;

        RoutePointer = (PRTM_ROUTE_INFO) Context2;

        Print("Route Aged Out\n\tRoute Handle = %p\n\tRoute Pointer = %p\n\n",
               RouteHandle,
              RoutePointer);

        // To just let the routing table manager delete the route, return ERROR_NOT_SUPPORTED
        // If you return any other value, the routing table manager assumes that you have
        // handled the time-out condition in callback for route timer expiration

        // Suppose we just want to update the metric and leave the route

        Status = RtmLockRoute(RtmRegHandle,
                              RouteHandle,
                              TRUE,
                              TRUE,
                              NULL);

        // Check(Status, 46);

        if (Status == NO_ERROR)
        {
            // Set the metric to indicate that it is unreachable
            RoutePointer->PrefInfo.Metric = METRIC_UNREACHABLE;

            Status = RtmUpdateAndUnlockRoute(RtmRegHandle,
                                             RouteHandle,
                                             INFINITE,        // To stay forever
                                             NULL,
                                             0,
                                             NULL,
                                             &ChangeFlags);
            ASSERT(Status == NO_ERROR);
        }

        // If ERROR_NOT_SUPPORTED not returned, release the handle
        RtmReleaseRoutes(RtmRegHandle, 1, &RouteHandle);

        Status = NO_ERROR;
        break;
    }

    return Status;
}


Routing Table Manager Version 2 Reference

The following documentation describes the functions, callbacks, structures, and enumeration types to use when interacting with the routing table manager.

  • Routing Table Manager Version 2 Functions
  • Routing Table Manager Version 2 Callbacks
  • Routing Table Manager Version 2 Structures
  • Routing Table Manager Version 2 Macros
  • Routing Table Manager Version 2 Constants
  • Routing Table Manager Version 2 Enumerations
  • Routing Table Manager Version 2 Simple Data Types


Routing Table Manager Version 2 Functions

The following functions are used to interact with the routing table manager:

Registration Functions

RtmRegisterEntity

RtmDeregisterEntity

RtmGetRegisteredEntities

RtmReleaseEntities

Opaque Pointer Functions

RtmLockDestination

RtmGetOpaqueInformationPointer

Export Method Functions

RtmGetEntityMethods

RtmInvokeMethod

RtmBlockMethods

Handle to Information Structure Functions

RtmGetEntityInfo

RtmGetDestInfo

RtmGetRouteInfo

RtmGetNextHopInfo

RtmReleaseEntityInfo

RtmReleaseDestInfo

RtmReleaseRouteInfo

RtmReleaseNextHopInfo

Routing Table Insertion and Deletion Functions

RtmAddRouteToDest

RtmDeleteRouteToDest

RtmHoldDestination

RtmGetRoutePointer

RtmLockRoute

RtmUpdateAndUnlockRoute

Routing Table Query Functions

RtmGetExactMatchDestination

RtmGetMostSpecificDestination

RtmGetLessSpecificDestination

RtmGetExactMatchRoute

RtmIsBestRoute

Next-Hop Insertion and Deletion Functions

RtmAddNextHop

RtmFindNextHop

RtmDeleteNextHop

RtmGetNextHopPointer

RtmLockNextHop

Routing Table Enumeration Functions

RtmCreateDestEnum

RtmGetEnumDests

RtmReleaseDests

RtmCreateRouteEnum

RtmGetEnumRoutes

RtmReleaseRoutes

RtmCreateNextHopEnum

RtmGetEnumNextHops

RtmReleaseNextHops

RtmDeleteEnumHandle

Change Notification Functions

RtmRegisterForChangeNotification

RtmGetChangedDests

RtmReleaseChangedDests

RtmIgnoreChangedDests

RtmGetChangeStatus

RtmMarkDestForChangeNotification

RtmIsMarkedForChangeNotification

RtmDeregisterFromChangeNotification

Route List Function

RtmCreateRouteList

RtmInsertInRouteList

RtmCreateRouteListEnum

RtmGetListEnumRoutes

RtmDeleteRouteList

Handle Management Functions

RtmReferenceHandles


RtmAddNextHop

The RtmAddNextHop function adds a new next-hop entry or updates an existing next-hop entry to a client's next-hop list. If a next hop already exists, the routing table manager returns a handle to the next hop. This handle can then be used to specify a next hop to a destination when adding or updating a route.

DWORD RtmAddNextHop(
  RTM_ENTITY_HANDLE RtmRegHandle,
  PRTM_NEXTHOP_INFO NextHopInfo,
  PRTM_NEXTHOP_HANDLE NextHopHandle,
  PRTM_NEXTHOP_CHANGE_FLAGS ChangeFlags
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
NextHopInfo
[in] Pointer to a structure that contains information identifying the next hop to add or update. The NextHopOwner and State members are ignored; these members are set by the routing table manager. The Flags member can be one of the following values.
Flag | Description
RTM_NEXTHOP_FLAGS_REMOTE | This next hop points to a remote destination that is not directly reachable. To obtain the complete path, the client must perform a recursive lookup.
RTM_NEXTHOP_FLAGS_DOWN | This flag is reserved for future use.

NextHopHandle
[in, out] f the client has a handle (client is updating a next hop): On input, NextHopHandle is a pointer to the next-hop handle. On output, NextHopHandle is unchanged.

If the client does not have a handle and a handle must be returned (client is adding or updating a next hop): On input, NextHopHandle is a pointer to NULL. On output, NextHopHandle receives a pointer to the next-hop handle. The values in NextHopInfo are used to identify the next hop to update.

If a handle does not need to be returned (client is adding or updating a next hop): On input, NextHopHandle is NULL. The values in NextHopInfo are used to identify the next hop to update.

ChangeFlags
[out] On input, ChangeFlags is a pointer to an RTM_NEXTHOP_CHANGE_FLAGS structure.

On output, ChangeFlags receives a flag indicating whether a next hop was added or updated. If ChangeFlags is zero, a next hop was updated; if ChangeFlags is RTM_NEXTHOP_CHANGE_NEW, a next hop was added.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling client does not own this next hop.
ERROR_NOT_ENOUGH_MEMORY | There is not enough memory to complete this operation.

Remarks

If NextHopHandle points to a non-NULL handle, the next hop specified by the handle is updated. Otherwise, a search is made for the address specified by NextHopInfo. If a next hop is found, it is updated. If no match is found, a new next hop is added.

If a handle was returned, release the handle when it is no longer required by calling RtmReleaseNextHops.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

Next Hop Flags, RTM_NEXTHOP_INFO, RtmDeleteNextHop, RtmFindNextHop, RtmGetNextHopPointer, RtmLockNextHop, RtmReleaseNextHops


RtmAddRouteToDest

The RtmAddRouteToDest function adds a new route to the routing table or updates an existing route in the routing table. If the best route changes, a change notification is generated.

DWORD RtmAddRouteToDest(
  RTM_ENTITY_HANDLE RtmRegHandle,
  PRTM_ROUTE_HANDLE RouteHandle,
  PRTM_NET_ADDRESS DestAddress,
  PRTM_ROUTE_INFO RouteInfo,
  ULONG TimeToLive,
  RTM_ROUTE_LIST_HANDLE RouteListHandle,
  RTM_NOTIFY_FLAGS NotifyType,
  RTM_NOTIFY_HANDLE NotifyHandle,
  PRTM_ROUTE_CHANGE_FLAGS ChangeFlags
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
RouteHandle
[in, out] If the client has a handle (updating a route): On input, RouteHandle is a pointer to the route handle. On output, RouteHandle is unchanged.

If the client does not have a handle and a handle must be returned (client is adding or updating a route): On input, RouteHandle is a pointer to NULL. On output, RouteHandle receives a pointer to the route handle. The values in RouteInfo are used to identify the route to update.

If a handle does not need to be returned (client is adding or updating a route): On input, RouteHandle is NULL. The values in RouteInfo are used to identify the route to update.

DestAddress
[in] Pointer to the destination network address to which the route is being added or updated.
RouteInfo
[in] Pointer to the route information to add or update.
TimeToLive
[in] Specifies the time, in milliseconds, after which the route is expired. Specify INFINITE to prevent routes from expiring.
RouteListHandle
[in] Handle to a route list to which to move the route. This parameter is optional and can be set to NULL.
NotifyType
[in] Set this parameter to NULL. NotifyType is reserved for future use.
NotifyHandle
[in] Set this parameter to NULL. NotifyHandle is reserved for future use.
ChangeFlags
[in, out] On input, ChangeFlags is a pointer to an RTM_ROUTE_CHANGE_FLAGS structure indicating whether the routing table manager should add a new route or update an existing one.

On output, ChangeFlags is a pointer to an RTM_ROUTE_CHANGE_FLAGS structure that receives the flag indicating the type of change that was actually performed, and if the best route was changed. The following flags are used.
Constant | Description
RTM_ROUTE_CHANGE_FIRST | Indicates that the routing table manager should not check the Neighbour member of the RouteInfo parameter when determining if two routes are equal.
RTM_ROUTE_CHANGE_NEW | Returned by the routing table manager to indicate a new route was created.
RTM_ROUTE_CHANGE_BEST | Returned by the routing table manager to indicate that the route that was added or updated was the best route, or that because of the change, a new route became the best route.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling client does not own this route.
ERROR_INVALID_HANDLE | The handle is invalid.
ERROR_INVALID_PARAMETER | A parameter contains incorrect information.
ERROR_NOT_ENOUGH_MEMORY | There is not enough memory to complete this operation.

Remarks

Two routes are considered equal if the following values are equal:

  • The destination network
  • The owner of the route
  • The neighbor that supplied the route

When a client is updating a route, it is more efficient to pass a handle to the route to update in the RouteHandle parameter, because the routing table manager does not have to perform a search for the route in the routing table.

If a handle was returned, release the handle when it is no longer required by calling RtmReleaseRoutes.

For sample code using this function, see Add and Update Routes Using RtmAddRouteToDest.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_NET_ADDRESS, RTM_ROUTE_INFO, RtmDeleteRouteToDest, RtmGetRoutePointer, RtmHoldDestination, RtmLockRoute, RtmReleaseRoutes, RtmUpdateAndUnlockRoute


RtmBlockMethods

The RtmBlockMethods function blocks or unblocks the execution of methods for a specified destination, route, or next hop, or for all destinations, routes, and next hops.

DWORD RtmBlockMethods(
  RTM_ENTITY_HANDLE RtmRegHandle,
  HANDLE TargetHandle,
  UCHAR TargetType,
  DWORD BlockingFlag
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
TargetHandle
[in] Handle to a destination, route, or next hop for which to block methods. This parameter is optional and can be set to NULL to block methods for all targets.
TargetType
[in] Specifies the type of the handle in TargetHandle. This parameter is optional and can be set to NULL to block methods for all targets. The following flags are used.
Type | Description
DEST_TYPE | TargetHandle is a destination.
NEXTHOP_TYPE | TargetHandle is a next hop.
ROUTE_TYPE | TargetHandle is a route.

BlockingFlag
[in] Specifies whether to block or unblock methods. The following flags are used.
Constant | Description
RTM_BLOCK_METHODS | Block methods for the specified target.
RTM_RESUME_METHODS | Unblock methods for the specified target.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

Remarks

Currently, this function does not support blocking methods for a specific destination, route, or next hop.

Methods are typically blocked when client-specific data in the route is being changed; a client blocks methods, rearranges data, and then unblocks methods.

Clients should only block methods for a short period of time. If a second client calls RtmInvokeMethod and the first client's methods are blocked, RtmInvokeMethod will not return until methods are unblocked and the function call is completed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmGetEntityMethods, RtmInvokeMethod


RtmCreateDestEnum

The RtmCreateDestEnum function starts an enumeration of the destinations in the routing table. A client can enumerate destinations for one or more views, or for all views.

DWORD RtmCreateDestEnum(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_VIEW_SET TargetViews,
  RTM_ENUM_FLAGS EnumFlags,
  PRTM_NET_ADDRESS NetAddress,
  ULONG ProtocolId,
  PRTM_ENUM_HANDLE RtmEnumHandle
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
TargetViews
[in] Specifies the set of views to use when creating the enumeration. The following flags are used.
Constant | Description
RTM_VIEW_MASK_ANY | Return destinations from all views. This is the default value.
RTM_VIEW_MASK_UCAST | Return destinations from the unicast view.
RTM_VIEW_MASK_MCAST | Return destinations from the multicast view.

EnumFlags
[in] Specifies which destinations to include in the enumeration. Two sets of flags are used; use one flag from each set (for example, use RTM_ENUM_ALL_DESTS and RTM_ENUM_START).
Constant | Description
RTM_ENUM_ALL_DESTS | Return all destinations.
RTM_ENUM_OWN_DESTS | Return destinations for which the client owns the best route to a destination in any of the specified views.

Constant | Description
RTM_ENUM_NEXT | Enumerate destinations starting at the specified address/mask length (such as 10/8). The enumeration continues to the end of the routing table.
RTM_ENUM_RANGE | Enumerate destinations in the range specified by the address/mask length (such as 10/8).
RTM_ENUM_START | Enumerate destinations starting at 0/0. Specify NULL for NetAddress.

NetAddress
[in] Pointer to an RTM_NET_ADDRESS structure that contains the starting address of the enumeration. Specify NULL if EnumFlags contains RTM_ENUM_START.
ProtocolId
[in] Specifies the protocol identifier used to determine the best route information returned by the RtmGetEnumDests function. The ProtocolID is not part of the search criteria. The routing table manager uses this identifier to determine which route information to return (for example, if a client specifies the RIP protocol identifier, the best RIP route is returned, even if a non-RIP route is the best route to the destination).

Specify RTM_BEST_PROTOCOL to return a route regardless of which protocol owns it. Specify RTM_THIS_PROTOCOL to return the best route for the calling protocol.

RtmEnumHandle
[out] On input, RtmEnumHandle is a pointer to NULL.

On output, RtmEnumHandle receives a pointer to a handle to the enumeration. Use this handle in all subsequent calls to RtmGetEnumDests, RtmReleaseDests, and RtmDeleteEnumHandle.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | A parameter contains incorrect information.
ERROR_NOT_ENOUGH_MEMORY | There is not enough memory to complete this operation.
ERROR_NOT_SUPPORTED | One or more of the specified views is not supported.

Remarks

If EnumFlags contains RTM_ENUM_RANGE, use NetAddress to specify the range of the routing table to enumerate. For example, if a client sets NetAddress to 10/8, destinations in the range 10.0.0.0/8 to 10.255.255.255/32 are returned.

When the enumeration handle is no longer required, release it by calling RtmDeleteEnumHandle.

For sample code using this function, see Enumerate All Destinations.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_NET_ADDRESS, RtmDeleteEnumHandle, RtmGetEnumDests, RtmReleaseDests


RtmCreateNextHopEnum

The RtmCreateNextHopEnum enumerates the next hops in the next-hop list.

DWORD RtmCreateNextHopEnum(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_ENUM_FLAGS EnumFlags,
  PRTM_NET_ADDRESS NetAddress,
  PRTM_ENUM_HANDLE RtmEnumHandle
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
EnumFlags
[in] Specifies which next hops to include in the enumeration. The following flags are used.
Constant | Description
RTM_ENUM_NEXT | Enumerate next hops starting at the specified address/mask length (such as 10/8). The enumeration continues to the end of the next hop list.
RTM_ENUM_RANGE | Enumerate next hops in the specified range specified by the address/mask length (such as 10/8).
RTM_ENUM_START | Enumerate next hops starting at 0/0. Specify NULL for NetAddress.

NetAddress
[in] Pointer to an RTM_NET_ADDRESS structure that contains the starting address of the enumeration. Specify NULL if EnumFlags contains RTM_ENUM_START.
RtmEnumHandle
[out] On input, RtmEnumHandle is a pointer to NULL.

On output, RtmEnumHandle receives a pointer to a handle to the enumeration. Use this handle in all subsequent calls to RtmGetEnumNextHops, RtmReleaseNextHops, and RtmDeleteEnumHandle.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | A parameter contains incorrect information.
ERROR_NOT_ENOUGH_MEMORY | There is not enough memory to complete this operation.

Remarks

If EnumFlags contains RTM_ENUM_RANGE, use NetAddress to specify the range of the routing table to enumerate. For example, if a client sets NetAddress to 10/8, next hops in the range 10.0.0.0/8 to 10.255.255.255/32 are returned.

When the enumeration handle is no longer required, release it by calling RtmDeleteEnumHandle.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_NET_ADDRESS, RtmDeleteEnumHandle, RtmGetEnumNextHops, RtmReleaseNextHops


RtmCreateRouteEnum

The RtmCreateRouteEnum function creates an enumeration of the routes for a particular destination or range of destinations in the routing table. A client can enumerate routes for one or more views, or for all views.

DWORD RtmCreateRouteEnum(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_DEST_HANDLE DestHandle,
  RTM_VIEW_SET TargetViews,
  RTM_ENUM_FLAGS EnumFlags,
  PRTM_NET_ADDRESS StartDest,
  RTM_MATCH_FLAGS MatchingFlags,
  PRTM_ROUTE_INFO CriteriaRoute,
  ULONG CriteriaInterface,
  PRTM_ENUM_HANDLE RtmEnumHandle
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
DestHandle
[in] Handle to the destination for which to enumerate routes. This parameter is optional, and can be set to NULL; specifying NULL enumerates all routes for all destinations. Specify NULL if EnumFlags contains RTM_ENUM_START.
TargetViews
[in] Specifies the set of views to use when creating the enumeration. The following flags are used.
Constant | Description
RTM_VIEW_MASK_ANY | Return destinations from all views. This is the default value.
RTM_VIEW_MASK_UCAST | Return destinations from the unicast view.
RTM_VIEW_MASK_MCAST | Return destinations from the multicast view.

EnumFlags
[in] Specifies which routes to include in the enumeration. Two sets of flags are used; use one flag from each set (such as RTM_ENUM_ALL_ROUTES and RTM_ENUM_START).
Constant | Description
RTM_ENUM_ALL_ROUTES | Return all routes.
RTM_ENUM_OWN_ROUTES | Return only those routes that the client owns.

Constant | Description
RTM_ENUM_NEXT | Enumerate routes starting at the specified address/mask length (such as 10/8). The enumeration continues to the end of the routing table.
RTM_ENUM_RANGE | Enumerate routes in the specified range specified by the address/mask length (such as 10/8).
RTM_ENUM_START | Enumerate routes starting at 0/0. Specify NULL for NetAddress.

StartDest
[in] Pointer to an RTM_NET_ADDRESS structure that contains the starting address of the enumeration. This parameter is ignored if EnumFlags contains RTM_ENUM_START.
MatchingFlags
[in] Specifies the elements of the route to match. Only routes that match the criteria specified in CriteriaRoute and CriteriaInterface are returned, unless otherwise noted. The following flags are used.
Constant | Description
RTM_MATCH_FULL | Match routes with all criteria.
RTM_MATCH_INTERFACE | Match routes that are on the same interface. The client can specify NULL for CriteriaRoute.
RTM_MATCH_NEIGHBOUR | Match routes with the same neighbor.
RTM_MATCH_NEXTHOP | Match routes that have the same next hop.
RTM_MATCH_NONE | Match none of the criteria; all routes for the destination are returned. The CriteriaRoute parameter is ignored if this flag is set.
RTM_MATCH_OWNER | Match routes with same owner.
RTM_MATCH_PREF | Match routes that have the same preference.

CriteriaRoute
[in] Specifies which routes to enumerate. This parameter is optional and can be set to NULL if MatchingFlags contains RTM_MATCH_INTERFACE or RTM_MATCH_NONE.
CriteriaInterface
[in] Pointer to a ULONG that specifies on which interfaces routes should be located. This parameter is ignored unless MatchingFlags contains RTM_MATCH_INTERFACE.
RtmEnumHandle
[out] On input, RtmEnumHandle is a pointer to NULL.

On output, RtmEnumHandle receives a pointer to a handle to the enumeration. Use this handle in all subsequent calls to RtmGetEnumRoutes, RtmReleaseRoutes, and RtmDeleteEnumHandle.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | A parameter contains incorrect information.
ERROR_NOT_ENOUGH_MEMORY | There is not enough memory to complete this operation.
ERROR_NOT_SUPPORTED | One or more of the specified views is not supported.

Remarks

If EnumFlags contains RTM_ENUM_RANGE, use NetAddress to specify the range of the routing table to enumerate. For example, if a client sets NetAddress to 10/8, destinations in the range 10.0.0.0/8 to 10.255.255.255/32 are returned.

When the enumeration handle is no longer required, release it by calling RtmDeleteEnumHandle.

For sample code using this function, see Enumerate All Routes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_NET_ADDRESS, RTM_ROUTE_INFO, RtmDeleteEnumHandle, RtmGetEnumRoutes, RtmReleaseRoutes


RtmCreateRouteList

The RtmCreateRouteList function creates a list in which the caller can keep a copy of the routes it owns.

DWORD RtmCreateRouteList(
  RTM_ENTITY_HANDLE RtmRegHandle,
  PRTM_ROUTE_LIST_HANDLE RouteListHandle
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
RouteListHandle
[out] On input, RouteListHandle is a pointer to NULL.

On output, RouteListHandle receives a pointer to a handle to the new route list.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_NOT_ENOUGH_MEMORY | There is not enough memory to complete this operation.

Remarks

For sample code using this function, see Use a Client-Specific Route List.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmDeleteRouteList, RtmInsertInRouteList


RtmCreateRouteListEnum

The RtmCreateRouteListEnum function creates an enumeration of routes on the specified route list.

DWORD RtmCreateRouteListEnum(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_ROUTE_LIST_HANDLE RouteListHandle,
  PRTM_ENUM_HANDLE RtmEnumHandle
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
RouteListHandle
[in] Handle to the route list to enumerate that is obtained from a previous call to RtmCreateRouteList.
RtmEnumHandle
[out] On input, RtmEnumHandle is a pointer to NULL.

On output, RtmEnumHandle receives a pointer to a handle to the enumeration. Use this handle in all subsequent calls to functions that enumerate the list of routes.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_NOT_ENOUGH_MEMORY | There is not enough memory to complete this operation.

Remarks

When the enumeration handle is no longer required, release it by calling RtmDeleteEnumHandle.

For sample code using this function, see Use a Client-Specific Route List.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmDeleteEnumHandle, RtmGetListEnumRoutes


RtmDeleteEnumHandle

The RtmDeleteEnumHandle function deletes the specified enumeration handle and frees all resources allocated for the enumeration.

DWORD RtmDeleteEnumHandle(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_ENUM_HANDLE EnumHandle
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
EnumHandle
[in] Handle to be released. Any resources associated with the handle are also freed.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmCreateDestEnum, RtmCreateNextHopEnum, RtmCreateRouteEnum, RtmCreateRouteListEnum, RtmGetEnumDests, RtmGetEnumNextHops, RtmGetEnumRoutes, RtmReleaseDests, RtmReleaseNextHops, RtmReleaseRoutes


RtmDeleteNextHop

The RtmDeleteNextHop function deletes a next hop from the next-hop list.

DWORD RtmDeleteNextHop(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_NEXTHOP_HANDLE NextHopHandle,
  PRTM_NEXTHOP_INFO NextHopInfo
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
NextHopHandle
[in] Handle to the next hop to delete. This parameter is optional and can be set to NULL; if it is NULL, the values in NextHopInfo are used to identify the next hop to delete.
NextHopInfo
[in] Pointer to a structure that contains information identifying the next hop to delete. This parameter is optional and can be set to NULL; if it is NULL, the handle in NextHopHandle is used to identify the next hop to delete.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling client does not own this next hop.
ERROR_NOT_ENOUGH_MEMORY | There is not enough memory to complete this operation.
ERROR_NOT_FOUND | The specified next hop was not found.

Remarks

If a client specifies a NextHopHandle, the client should not subsequently release the handle using RtmReleaseNextHops.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_NEXTHOP_INFO, RtmAddNextHop, RtmFindNextHop, RtmGetNextHopPointer


RtmDeleteRouteList

The RtmDeleteRouteList function removes all routes from a client-specific route list, then frees any resources allocated to the list.

DWORD RtmDeleteRouteList(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_ROUTE_LIST_HANDLE RouteListHandle
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
RouteListHandle
[in] Handle to the route list to delete.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

Remarks

This function also releases the handle to the route list.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmCreateRouteList, RtmInsertInRouteList


RtmDeleteRouteToDest

The RtmDeleteRouteToDest function deletes a route from the routing table and updates the best-route information for the corresponding destination, if the best route changed. If the best route changes, a change notification is generated.

DWORD RtmDeleteRouteToDest(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_ROUTE_HANDLE RouteHandle,
  PRTM_ROUTE_CHANGE_FLAGS ChangeFlags
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
RouteHandle
[in] Handle to the route to delete.
ChangeFlags
[out] On input, ChangeFlags is a pointer to RTM_ROUTE_CHANGE_FLAGS.

On output, ChangeFlags receives RTM_ROUTE_CHANGE_BEST if the best route was changed.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling client does not own this route.
ERROR_INVALID_HANDLE | The handle is invalid.
ERROR_NOT_FOUND | The specified route was not found.

Remarks

The RouteHandle should not subsequently be released by a client if the client has already called RtmDeleteRouteToDest using that handle. The RtmDeleteRouteToDest function deletes the route and releases the handle.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmAddRouteToDest, RtmGetRoutePointer, RtmHoldDestination, RtmLockRoute, RtmUpdateAndUnlockRoute


RtmDeregisterEntity

The RtmDeregisterEntity function unregisters a client from a routing table manager instance and address family.

DWORD RtmDeregisterEntity(
  RTM_ENTITY_HANDLE RtmRegHandle
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

Remarks

Before calling this function, the client must ensure that all locks, handles, and information structures are released with the appropriate functions.

When the client calls RtmDeregisterEntity, the handle that was returned by a previous call to RtmRegisterEntity is released. The client must not call any RTMv2 functions after releasing this handle.

If the client does call any functions that access the routing table manager after the client has unregistered, the client's process may be terminated.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmRegisterEntity


RtmDeregisterFromChangeNotification

The RtmDeregisterFromChangeNotification function unregisters a client from change notification and frees all resources allocated to the notification.

DWORD RtmDeregisterFromChangeNotification(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_NOTIFY_HANDLE NotifyHandle
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterForChangeNotification.
NotifyHandle
[in] Handle to the change notification to unregister that is obtained from a previous call to RtmRegisterForChangeNotification.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmMarkDestForChangeNotification, RtmRegisterForChangeNotification, RtmReleaseChangedDests


RtmFindNextHop

The RtmFindNextHop function finds a specific next hop in a client's next-hop list.

DWORD RtmFindNextHop(
  RTM_ENTITY_HANDLE RtmRegHandle,
  PRTM_NEXTHOP_INFO NextHopInfo,
  PRTM_NEXTHOP_HANDLE NextHopHandle,
  PRTM_NEXTHOP_INFO *NextHopPointer
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
NextHopInfo
[in] Pointer to an RTM_NEXTHOP_INFO structure that contains information identifying the next hop to find. Use the NextHopAddress and InterfaceIndex members to identify the next hop to find.
NextHopHandle
[out] If a handle must be returned: On input, NextHopPointer is a pointer to NULL. On output, if the client owns the next hop, NextHopPointer receives a pointer to the next-hop handle; otherwise, NextHopPointer remains unchanged.

If a handle does not need to be returned: On input, NextHopPointer is NULL.

NextHopPointer
[out] If a pointer must be returned: On input, NextHopPointer is a pointer to NULL. On output, if the client owns the next hop, NextHopPointer receives a pointer to the next-hop; otherwise, NextHopPointer remains unchanged.

If a pointer does not need to be returned: On input, NextHopPointer is NULL.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling client does not own this next hop.
ERROR_NOT_FOUND | The specified next hop was not found.

Remarks

The NextHopPointer is valid as long as the client has not released NextHopHandle.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_NEXTHOP_INFO, RtmAddNextHop, RtmDeleteNextHop, RtmGetNextHopPointer, RtmLockNextHop


RtmGetChangedDests

The RtmGetChangedDests function returns a set of destinations with changed information.

DWORD RtmGetChangedDests(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_NOTIFY_HANDLE NotifyHandle,
  PUINT NumDests,
  PRTM_DEST_INFO ChangedDests
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
NotifyHandle
[in] Handle to a change notification obtained from a previous call to RtmRegisterForChangeNotification.
NumDests
[in, out] On input, NumDests is a pointer to a UINT value that specifies the maximum number of destinations that can be received by ChangedDests.

On output, NumDests receives the actual number of destinations received by ChangedDests.

ChangedDests
[out] On input, ChangedDests is a pointer to an array of RTM_DEST_INFO structures.

On output, ChangedDests is filled with the changed destination information.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | A parameter contains incorrect information.
ERROR_NO_MORE_ITEMS | No more changed destinations to retrieve.

Remarks

A client is notified of changes by an RTM_EVENT_CALLBACK. The RTM_EVENT_CALLBACK is only used to notify the client, not deliver the changes. After a change notification is received, the client must call RtmGetChangedDests repeatedly to retrieve all the changes.

If two or more changes to the same destination have occurred since the notification, only the latest change is returned.

When a client no longer needs the handles in ChangedDests, the client must use RtmReleaseChangedDests to release the handles.

For sample code using this function, see Use the Event Notification Callback.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_EVENT_CALLBACK, RTM_DEST_INFO, RtmGetChangeStatus, RtmIgnoreChangedDests, RtmIsMarkedForChangeNotification, RtmMarkDestForChangeNotification, RtmReleaseChangedDests


RtmGetChangeStatus

The RtmGetChangeStatus function checks whether there are pending changes that have not been retrieved with RtmGetChangedDests.

DWORD RtmGetChangeStatus(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_NOTIFY_HANDLE NotifyHandle,
  RTM_DEST_HANDLE DestHandle,
  PBOOL ChangeStatus
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
NotifyHandle
[in] Handle to a change notification.
DestHandle
[in] Handle to the destination for which to return change status.
ChangeStatus
[out] On input, ChangeStatus is a pointer to a BOOL value.

On output, ChangeStatus receives either TRUE or FALSE to indicate if the destination specified by DestHandle has a change notification pending.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

Remarks

This function can be used to make portions of the client code more efficient. For example, a client may postpone some operation if there are changes that the client has not yet processed.

This function can also be used to monitor change notification in another thread.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_EVENT_CALLBACK, RtmGetChangedDests, RtmIgnoreChangedDests, RtmIsMarkedForChangeNotification, RtmMarkDestForChangeNotification, RtmReleaseChangedDests


RtmGetDestInfo

The RtmGetDestInfo function returns information about a destination.

DWORD RtmGetDestInfo(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_DEST_HANDLE DestHandle,
  ULONG ProtocolId,
  RTM_VIEW_SET TargetViews,
  PRTM_DEST_INFO DestInfo
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
DestHandle
[in] Handle to the destination for which to return information.
ProtocolId
[in] Specifies the protocol identifier. The ProtocolID is not part of the search criteria. The routing table manager uses this identifier to determine which route information to return. For example, if a client specifies the RIP protocol identifier, the best RIP route is returned, even if a non-RIP route is the best route to the destination.

Specify RTM_BEST_PROTOCOL to return a route regardless of which protocol owns it. Specify RTM_THIS_PROTOCOL to return the best route for the calling protocol.

TargetViews
[in] Specifies the views from which to return information. If the client specifies RTM_VIEW_MASK_ANY, destination information is returned from all views; however, no view-specific information is returned.
DestInfo
[out] On input, DestInfo is a pointer to an RTM_DEST_INFO structure.

On output, DestInfo is filled with the requested destination information.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

Remarks

The DestInfo structure is a variable-sized structure. If the client specifies more than one view with TargetViews, the size of DestInfo increases for each view. Use the RTM_SIZE_OF_DEST_INFO macro to determine how large a DestInfo structure to allocate before calling this function. Use the value specified for TargetViews as a parameter to RTM_SIZE_OF_DEST_INFO.

Use RtmReleaseDestInfo to release the DestInfo buffer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_DEST_INFO, RtmReleaseDestInfo


RtmGetEntityInfo

The RtmGetEntityInfo function returns information about a previously registered client.

DWORD RtmGetEntityInfo(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_ENTITY_HANDLE EntityHandle,
  PRTM_ENTITY_INFO EntityInfo
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
EntityHandle
[in] Handle to the client for which to return information.
EntityInfo
[out] On input, EntityInfo is a pointer to an RTM_ENTITY_INFO structure.

On output, EntityInfo receives the requested information.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_ENTITY_INFO, RtmReleaseEntityInfo


RtmGetEntityMethods

The RtmGetEntityMethods function queries the specified client to determine which methods are available for another client to invoke.

DWORD RtmGetEntityMethods(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_ENTITY_HANDLE EntityHandle,
  PUINT NumMethods,
  PRTM_ENTITY_EXPORT_METHOD ExptMethods
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
EntityHandle
[in] Handle to the client for which to obtain methods.
NumMethods
[in, out] On input, NumMethods specifies a valid pointer to a UINT value. Specify zero to return the number of methods available to be exported.

On output, NumMethods receives the number of methods exported by the client.

ExptMethods
[out] Receives a pointer to an RTM_ENTITY_EXPORT_METHOD structure containing the set of method identifiers requested by the calling client.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INSUFFICIENT_BUFFER | The buffer supplied is not large enough to hold all the requested information.

Remarks

Do not call another client's method directly, always use RtmInvokeMethod. The routing table manager performs error checking when using RtmInvokeMethod to ensure that the client is not unregistering or already unregistered.

If ERROR_INSUFFICIENT_BUFFER is returned, there may be some data in ExptMethods; NumMethods specifies how many methods actually fit in the buffer.

When the entity handle is no longer required, release it by calling RtmReleaseEntities.

For sample code using this function, see Obtain and Call the Exported Methods for a Client.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmBlockMethods, RtmInvokeMethod


RtmGetEnumDests

The RtmGetEnumDests function retrieves the next set of destinations in the specified enumeration.

DWORD RtmGetEnumDests(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_ENUM_HANDLE EnumHandle,
  PUINT NumDests,
  PRTM_DEST_INFO DestInfos
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
EnumHandle
[in] Handle to the destination enumeration.
NumDests
[in, out] On input, NumDests is a pointer to a UINT value specifying the maximum number of destinations that can be received by DestInfos. On output, NumDests receives the actual number of destinations received by DestInfos.
DestInfos
[out] On input, DestInfo is a pointer to an RTM_DEST_INFO structure.

On output, DestInfo receives an array of handles to destinations.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | The value pointed to by NumRoutes is larger than the maximum number of routes a client is allowed to retrieve with one call. Check RTM_REGN_PROFILE for the maximum number of destinations that the client is allowed to retrieve with one call.
ERROR_NO_MORE_ITEMS | There are no more destinations to enumerate.

Remarks

The DestInfo structure is a variable-sized structure. If the client specifies more than one view with TargetViews, the size of DestInfo increases for each view. Use the RTM_SIZE_OF_DEST_INFO macro to determine how large a DestInfo structure to allocate before calling this function. Use the value specified for TargetViews as a parameter to RTM_SIZE_OF_DEST_INFO.

When the destinations are no longer required, release them by calling RtmReleaseDests.

For sample code using this function, see Enumerate All Destinations.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_DEST_INFO, RtmCreateDestEnum, RtmDeleteEnumHandle, RtmReleaseDests


RtmGetEnumNextHops

The RtmGetEnumNextHops function retrieves the next set of next hops in the specified enumeration.

DWORD RtmGetEnumNextHops(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_ENUM_HANDLE EnumHandle,
  PUINT NumNextHops,
  PRTM_NEXTHOP_HANDLE NextHopHandles
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
EnumHandle
[in] Handle to the next-hop enumeration.
NumNextHops
[in, out] On input, NumNextHops is a pointer to a UINT value specifying the maximum number of next hops that can be received by NextHopHandles.

On output, NumNextHops receives the actual number of next hops received by NextHopHandles.

NextHopHandles
[out] On input, NextHopHandles pointers to an RTM_NEXTHOP_INFO structure.

On output, NextHopHandles receives an array of handles to next hops.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | The value pointed to by NumRoutes is larger than the maximum number of routes a client is allowed to retrieve with one call. Check RTM_REGN_PROFILE for the maximum number of next hops that the client is allowed to retrieve with one call.
ERROR_NO_MORE_ITEMS | There are no more next hops to enumerate.

Remarks

When the next hops are no longer required, release them by calling RtmReleaseNextHops.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmCreateNextHopEnum, RtmDeleteEnumHandle, RtmReleaseNextHops


RtmGetEnumRoutes

The RtmGetEnumRoutes function retrieves the next set of routes in the specified enumeration.

DWORD RtmGetEnumRoutes(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_ENUM_HANDLE EnumHandle,
  PUINT NumRoutes,
  PRTM_ROUTE_HANDLE RouteHandles
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
EnumHandle
[in] Handle to the route enumeration.
NumRoutes
[in, out] On input, NumRoutes is a pointer to a UINT value specifying the maximum number of routes that can be received by RouteHandles.

On output, NumRoutes receives the actual number of routes received by RouteHandles.

RouteHandles
[out] On input, RouteHandles is a pointer to an RTM_ROUTE_INFO structure.

On output, RouteHandles receives an array of handles to routes.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | The value pointed to by NumRoutes is larger than the maximum number of routes a client is allowed to retrieve with one call. Check RTM_REGN_PROFILE for the maximum number of routes that the client is allowed to retrieve with one call.
ERROR_NO_MORE_ITEMS | There are no more routes to enumerate.
ERROR_NOT_ENOUGH_MEMORY | There is not enough memory to complete this operation.

Remarks

When the routes are no longer required, release them by calling RtmReleaseRoutes.

For sample code using this function, see Enumerate All Routes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmCreateRouteEnum, RtmDeleteEnumHandle, RtmReleaseRoutes


RtmGetExactMatchDestination

The RtmGetExactMatchDestination function searches the routing table for a destination that exactly matches the specified network address and subnet mask. If an exact match is found, the information for that destination is returned.

DWORD RtmGetExactMatchDestination(
  RTM_ENTITY_HANDLE RtmRegHandle,
  PRTM_NET_ADDRESS DestAddress,
  ULONG ProtocolId,
  RTM_VIEW_SET TargetViews,
  PRTM_DEST_INFO DestInfo
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
DestAddress
[in] Pointer to the destination network address.
ProtocolId
[in] Specifies the protocol identifier. The ProtocolID is not part of the search criteria. The routing table manager uses this identifier to determine which destination and route information to return. For example, if a client specifies the RIP protocol identifier, the best RIP route is returned, even if a non-RIP route is the best route to the destination.

Specify RTM_BEST_PROTOCOL to return a route regardless of which protocol owns it. Specify RTM_THIS_PROTOCOL to return the best route for the calling protocol.

TargetViews
[in] Specifies the views from which to return information. If the client specifies RTM_VIEW_MASK_ANY, destination information is returned from all views; however, no view-specific information is returned.
DestInfo
[out] On input, DestInfo is a pointer to an RTM_DEST_INFO structure.

On output, DestInfo is filled with the requested destination information.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_NOT_FOUND | The specified destination was not found.

Remarks

The DestInfo structure is a variable-sized structure. If the client specifies more than one view with TargetViews, the size of DestInfo increases for each view. Use the RTM_SIZE_OF_DEST_INFO macro to determine how large a DestInfo structure to allocate before calling this function. Use the value specified for TargetViews as a parameter to RTM_SIZE_OF_DEST_INFO.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_DEST_INFO, RTM_NET_ADDRESS, RtmGetExactMatchRoute, RtmGetLessSpecificDestination, RtmGetMostSpecificDestination, RtmIsBestRoute


RtmGetExactMatchRoute

The RtmGetExactMatchRoute function searches the routing table for a route that exactly matches the specified route. The route to search for is indicated by a network address, subnet mask, and other route-matching criteria. If an exact match is found, the route information is returned.

DWORD RtmGetExactMatchRoute(
  RTM_ENTITY_HANDLE RtmRegHandle,
  PRTM_NET_ADDRESS DestAddress,
  RTM_MATCH_FLAGS MatchingFlags,
  PRTM_ROUTE_INFO RouteInfo,
  ULONG InterfaceIndex,
  RTM_VIEW_SET TargetViews,
  PRTM_ROUTE_HANDLE RouteHandle
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
DestAddress
[in] Pointer to the destination network address.
MatchingFlags
[in] Specifies the criteria to use when searching for the route. The following flags are used.
Constant | Description
RTM_MATCH_FULL | Match routes with all criteria.
RTM_MATCH_INTERFACE | Match routes that are on the same interface.
RTM_MATCH_NEIGHBOUR | Match routes with the same neighbor.
RTM_MATCH_NEXTHOP | Match routes that have the same next hop.
RTM_MATCH_NONE | Match none of the criteria; all routes for the destination are returned.
RTM_MATCH_OWNER | Match routes with the same owner.
RTM_MATCH_PREF | Match routes that have the same preference.

RouteInfo
[in, out] On input, RouteInfo is a pointer an RTM_ROUTE_INFO structure containing the criteria that specifies the route to find.

On output, RouteInfo receives the route information for the route that matched the criteria.

InterfaceIndex
[in] If RTM_MATCH_INTERFACE is specified in MatchingFlags, InterfaceIndex specifies the interface on which the route should be present (that is, the route has a next hop on that interface).
TargetViews
[in] Specifies the views from which to return information. If the client specifies RTM_VIEW_MASK_ANY, destination information is returned from all views; however, no view-specific information is returned.
RouteHandle
[out] If a handle must be returned: On input, RouteHandle is a pointer to NULL.

On output, RouteHandle receives a pointer to the route handle; otherwise, RouteHandle remains unchanged.

If a handle does not need to be returned: On input, RouteHandle is NULL.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_NOT_FOUND | The specified route was not found.

Remarks

Consider using RtmGetExactMatchDestination if you have no route-matching criteria specified in the MatchingFlags parameter.

The following members of the RTM_ROUTE_INFO structure that is passed in the RouteInfo parameter are used to match a route:

  • Neighbour
  • NextHopsList
  • PrefInfo
  • RouteOwner

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_NET_ADDRESS, RTM_ROUTE_INFO, RtmGetExactMatchDestination, RtmGetLessSpecificDestination, RtmGetMostSpecificDestination, RtmIsBestRoute


RtmGetLessSpecificDestination

The RtmGetLessSpecificDestination function searches the routing table for a destination with the next-best-match (longest) prefix, given a destination prefix. The requested destination information is returned.

DWORD RtmGetLessSpecificDestination(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_DEST_HANDLE DestHandle,
  ULONG ProtocolId,
  RTM_VIEW_SET TargetViews,
  PRTM_DEST_INFO DestInfo
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
DestHandle
[in] Handle to the destination.
ProtocolId
[in] Specifies the protocol identifier. The ProtocolID is not part of the search criteria. The routing table manager uses this identifier to determine which route information to return. For example, if a client specifies the RIP protocol identifier, the best RIP route is returned, even if a non-RIP route is the best route to the destination.

Specify RTM_BEST_PROTOCOL to return a route regardless of which protocol owns it. Specify RTM_THIS_PROTOCOL to return the best route for the calling protocol.

TargetViews
[in] Specifies the views from which to return information. If the client specifies RTM_VIEW_MASK_ANY, destination information is returned from all views; however, no view-specific information is returned.
DestInfo
[out] On input, DestInfo is a pointer to an RTM_DEST_INFO structure.

On output, DestInfo is filled with the requested destination information.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | A parameter contains incorrect information.
ERROR_NOT_FOUND | The next best destination cannot be found.

Remarks

The DestInfo parameter is a variable-sized RTM_DEST_INFO structure. If the client specifies more than one view using TargetViews, the size of DestInfo increases for each view. Use the RTM_SIZE_OF_DEST_INFO macro to determine how much memory to allocate for the DestInfo structure before calling this function. Use the value specified for TargetViews as a parameter to RTM_SIZE_OF_DEST_INFO.

The RtmGetLessSpecificDestination function is used after a call to RtmGetMostSpecificDestination to return the next-best match for a destination. This call is also used after a prior call to RtmGetLessSpecificDestination to return the next successive less-specific match. Clients can use this function to "walk up" the prefix tree for a destination.

This call is also used after calls to functions that return an RTM_DEST_INFO structure, such as RtmGetDestInfo and RtmGetChangedDests.

The RtmGetLessSpecificDestination function returns matches until it reaches the default route, if it exists. Once the default route is found, RtmGetLessSpecificDestination returns ERROR_NOT_FOUND.

One common use for the RtmGetLessSpecificDestination and RtmGetMostSpecificDestination functions, is to retrieve each of the matching destinations.

For sample code using this function, see Search for Routes Using RtmGetMostSpecificDestination and RtmGetLessSpecificDestination.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_DEST_INFO, RtmGetExactMatchDestination, RtmGetExactMatchRoute, RtmGetMostSpecificDestination, RtmIsBestRoute


RtmGetListEnumRoutes

The RtmGetListEnumRoutes function enumerates a set of routes in a specified route list.

DWORD RtmGetListEnumRoutes(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_ENUM_HANDLE EnumHandle,
  PUINT NumRoutes,
  PRTM_ROUTE_HANDLE RouteHandles
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
EnumHandle
[in] Handle to the route list to enumerate.
NumRoutes
[in, out] On input, NumRoutes is a pointer to a UINT value that specifies the maximum number of routes that can be received by RouteHandles.

On output, NumRoutes receives the actual number of routes received by RouteHandles.

RouteHandles
[out] On input, DestInfo is a pointer to an array of RTM_DEST_INFO structures.

On output, DestInfo is filled with the requested destination information.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | The value pointed to by NumRoutes is larger than the maximum number of routes a client is allowed to retrieve with one call. Check RTM_REGN_PROFILE for the maximum number of routes that the client is allowed to retrieve with one call.

Remarks

Call this function repeatedly to retrieve all routes.

There are no more routes to enumerate when the routing table manager returns zero in NumRoutes.

For sample code using this function, see Use a Client-Specific Route List.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmCreateRouteListEnum, RtmDeleteEnumHandle


RtmGetMostSpecificDestination

The RtmGetMostSpecificDestination function searches the routing table for a destination with the exact match for a specified network address and subnet mask; if the exact match is not found, the best prefix is matched. The destination information is returned.

DWORD RtmGetMostSpecificDestination(
  RTM_ENTITY_HANDLE RtmRegHandle,
  PRTM_NET_ADDRESS DestAddress,
  ULONG ProtocolId,
  RTM_VIEW_SET TargetViews,
  PRTM_DEST_INFO DestInfo
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
DestAddress
[in] Pointer to the destination network address.
ProtocolId
[in] Specifies the protocol identifier. The ProtocolID is not part of the search criteria. The routing table manager uses this identifier to determine which route information to return. For example, if a client specifies the RIP protocol identifier, the best RIP route is returned, even if a non-RIP route is the best route to the destination.

Specify RTM_BEST_PROTOCOL to return a route regardless of which protocol owns it. Specify RTM_THIS_PROTOCOL to return the best route for the calling protocol.

TargetViews
[in] Specifies the views from which to return information. If the client specifies RTM_VIEW_MASK_ANY, destination information is returned from all views; however, no view-specific information is returned.
DestInfo
[out] On input, DestInfo is a pointer to an RTM_DEST_INFO structure.

On output, DestInfo is filled with the requested destination information.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle was invalid.
ERROR_NOT_FOUND | The specified destination was not found.

Remarks

The DestInfo structure is a variable-sized structure. If the client specifies more than one view with TargetViews, the size of DestInfo increases for each view. Use the RTM_SIZE_OF_DEST_INFO macro to determine how much memory to allocate for the DestInfo structure before calling this function. Use the value specified for TargetViews as a parameter to RTM_SIZE_OF_DEST_INFO.

For sample code using this function, see Search for Routes Using RtmGetMostSpecificDestination and RtmGetLessSpecificDestination.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_DEST_INFO, RTM_NET_ADDRESS, RtmGetExactMatchDestination, RtmGetExactMatchRoute, RtmGetLessSpecificDestination, RtmIsBestRoute


RtmGetNextHopInfo

The RtmGetNextHopInfo function returns information about the specified next hop.

DWORD RtmGetNextHopInfo(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_NEXTHOP_HANDLE NextHopHandle,
  PRTM_NEXTHOP_INFO NextHopInfo
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
NextHopHandle
[in] Handle to the next hop.
NextHopInfo
[out] On input, NextHopInfo a pointer to an RTM_NEXTHOP_INFO structure.

On output, NextHopInfo is filled with the requested next-hop information.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

Remarks

When the next hop handle is no longer required, release it by calling RtmDeleteNextHop.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_NEXTHOP_INFO, RtmReleaseNextHopInfo


RtmGetNextHopPointer

The RtmGetNextHopPointer function obtains a direct pointer to the specified next hop. The pointer allows the next-hop owner direct read access to the routing table manager's RTM_NEXTHOP_INFO structure.

DWORD RtmGetNextHopPointer(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_NEXTHOP_HANDLE NextHopHandle,
  PRTM_NEXTHOP_INFO *NextHopPointer
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
NextHopHandle
[in] Handle to the next hop.
NextHopPointer
[out] If the client is the owner of the next hop, NextHopPointer receives a pointer to the next hop.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling client does not own this next hop.
ERROR_INVALID_HANDLE | The handle is invalid.

Remarks

Clients should only use this pointer for read-only access.

When the next hop handle is no longer required, release it by calling RtmReleaseNextHopInfo.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_NEXTHOP_INFO, RtmAddNextHop, RtmDeleteNextHop, RtmFindNextHop, RtmLockNextHop


RtmGetOpaqueInformationPointer

The RtmGetOpaqueInformationPointer function returns a pointer to the opaque information field in a destination that is reserved for this client. The pointer enables the client to store client-specific information with the destination in the routing table.

DWORD RtmGetOpaqueInformationPointer(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_DEST_HANDLE DestHandle,
  PVOID *OpaqueInfoPointer
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
DestHandle
[in] Handle to the destination.
OpaqueInfoPointer
[out] On input, OpaqueInfoPointer is a pointer to NULL.

On output, OpaqueInfoPointer receives a pointer to the opaque information pointer. If a client has not reserved an opaque pointer during registration, this parameter remains unchanged.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.
ERROR_NOT_FOUND | No opaque pointer was reserved by the client.

Remarks

For sample code using this function, see Access the Opaque Pointer in a Destination.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmLockDestination


RtmGetRegisteredEntities

The RtmGetRegisteredEntities function returns information about all clients that have registered with the specified instance of the routing table manager and specified address family.

DWORD RtmGetRegisteredEntities(
  RTM_ENTITY_HANDLE RtmRegHandle,
  PUINT NumEntities,
  PRTM_ENTITY_HANDLE EntityHandles,
  PRTM_ENTITY_INFO EntityInfos
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
NumEntities
[in, out] On input, NumEntities is a pointer to a UINT value, which specifies the maximum number of clients that can be received by EntityInfos. On output, NumEntities receives the actual number of clients received by EntityInfos.
EntityHandles
[out] If handles must be returned: On input, EntityHandles is a pointer to NULL. On output, EntityHandles receives a pointer to an array of entity handle; otherwise, EntityHandles remains unchanged.

If handles do not need to be returned: On input, EntityHandles is NULL.

EntityInfos
[out] If a pointer must be returned: On input, EntityInfos is a pointer to NULL. On output, EntityInfos receives a pointer to an array of RTM_ENTITY_INFO structures; otherwise, EntityInfos remains unchanged.

If a pointer does not need to be returned: On input, EntityInfos is NULL.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INSUFFICIENT_BUFFER | The buffer supplied is not large enough to hold all the requested information.

Remarks

If ERROR_INSUFFICIENT_BUFFER is returned, there may be some data in EntityHandles. The NumEntities parameter specifies how many entities were actually returned.

The RtmGetRegisteredEntities function can be used by routing protocols to verify which other protocols are running for that address family and routing table manager instance. Based on the information returned, a client can then perform protocol-specific processing.

The RTMv2 API supports only one instance of the routing table manager.

When the entities are no longer required, release them by calling RtmReleaseEntities.

For sample code using this function, see Enumerate the Registered Entities.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_ENTITY_INFO, RtmReleaseEntities


RtmGetRouteInfo

The RtmGetRouteInfo function returns information for the specified route.

DWORD RtmGetRouteInfo(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_ROUTE_HANDLE RouteHandle,
  PRTM_ROUTE_INFO RouteInfo,
  PRTM_NET_ADDRESS DestAddress
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
RouteHandle
[in] Handle to the route to find.
RouteInfo
[out] If a pointer must be returned: On input, RouteInfo is a pointer to NULL. On output, RouteInfo receives a pointer to the route; otherwise, RouteInfo remains unchanged.

If a pointer does not need to be returned: On input, RouteInfo is NULL.

DestAddress
[out] If a pointer must be returned: On input, DestAddress is a pointer to NULL. On output, DestAddress receives a pointer to the destination's RTM_NET_ADDRESS structure; otherwise, DestAddress remains unchanged.

If a pointer does not need to be returned: On input, DestAddress is NULL.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

When the routes are no longer required, release them by calling RtmReleaseRouteInfo.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_NET_ADDRESS, RTM_ROUTE_INFO, RtmReleaseRouteInfo


RtmGetRoutePointer

The RtmGetRoutePointer function obtains a direct pointer to a route that allows the owner of the route read access.

DWORD RtmGetRoutePointer(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_ROUTE_HANDLE RouteHandle,
  PRTM_ROUTE_INFO *RoutePointer
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
RouteHandle
[in] Handle to the route.
RoutePointer
[out] On input, RoutePointer is a pointer to NULL.

On output, RoutePointer receives a pointer to the route.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling client does not own this route.
ERROR_INVALID_HANDLE | The handle is invalid.

Remarks

The pointer that was returned points to the public part of the route.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_ROUTE_INFO, RtmAddRouteToDest, RtmDeleteRouteToDest, RtmHoldDestination, RtmLockRoute, RtmUpdateAndUnlockRoute


RtmHoldDestination

The RtmHoldDestination function marks a destination to be put in the hold-down state for a certain amount of time. A hold down only happens if the last route for the destination in any view is deleted.

Routing protocols that use hold-down states continue to advertise the last route until the hold-down expires, even if newer routes arrive in the meantime. The route is advertised as a deleted route. The newer routes are, however, used by the routing protocols for forwarding purposes. New routes are advertised when the hold down expires.

DWORD RtmHoldDestination(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_DEST_HANDLE DestHandle,
  RTM_VIEW_SET TargetViews,
  ULONG HoldTime
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
DestHandle
[in] Handle to the destination to mark for holding.
TargetViews
[in] Specifies the views in which to hold the destination.
HoldTime
[in] Specifies how long, in milliseconds, to hold the destination.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | The hold time specified was zero.
ERROR_INVALID_HANDLE | The handle is invalid.

Remarks

All routes in a hold-down state are held for all views for a single, maximum hold-down time, regardless of the HoldTime specified.

For sample code using this function, see Use the Route Hold-Down State.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmAddRouteToDest, RtmDeleteRouteToDest, RtmLockRoute, RtmUpdateAndUnlockRoute


RtmIgnoreChangedDests

The RtmIgnoreChangedDests function skips the next change for each destination if it has already occurred. This function can be used after RtmGetChangeStatus to prevent the routing table manager returning this change in response to a call to RtmGetChangedDests.

DWORD RtmIgnoreChangedDests(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_NOTIFY_HANDLE NotifyHandle,
  UINT NumDests,
  PRTM_DEST_HANDLE ChangedDests
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
NotifyHandle
[in] Handle to a change notification.
NumDests
[in] Specifies the number of destinations in ChangedDests.
ChangedDests
[in] Pointer to an array of RTM_DEST_HANDLE handles indicating the destinations for which to ignore any pending changes.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

When the destinations are no longer required, release them by calling RtmReleaseChangedDests.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmGetChangedDests, RtmGetChangeStatus, RtmIsMarkedForChangeNotification, RtmMarkDestForChangeNotification, RtmReleaseChangedDests


RtmInsertInRouteList

The RtmInsertInRouteList function inserts the specified set of routes into the client's route list. If a route is already in another list, the route is removed from the old list and inserted into the new one.

DWORD RtmInsertInRouteList(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_ROUTE_LIST_HANDLE RouteListHandle,
  UINT NumRoutes,
  PRTM_ROUTE_HANDLE RouteHandles
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
RouteListHandle
[in] Handle to the route list to which to add routes. Specify NULL to remove the specified routes from their old lists.
NumRoutes
[in] Specifies the number of routes in RouteHandles.
RouteHandles
[in] Pointer to an array of route handles to move from the old list to the new list.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

When the routes are no longer required, release them by calling RtmReleaseRoutes.

For sample code using this function, see Use a Client-Specific Route List.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmCreateRouteList, RtmDeleteRouteList


RtmInvokeMethod

The RtmInvokeMethod function invokes a method exported by another client.

DWORD RtmInvokeMethod(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_ENTITY_HANDLE EntityHandle,
  PRTM_ENTITY_METHOD_INPUT Input,
  PUINT OutputSize,
  PRTM_ENTITY_METHOD_OUTPUT Output
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
EntityHandle
[in] Handle to the client whose methods are being invoked.
Input
[in] Pointer to an RTM_ENTITY_METHOD_INPUT structure that contains the method to be invoked and a common input buffer.
OutputSize
[in, out] On input, OutputSize is a pointer to a UNIT value specifying the size, in bytes, of Output.

On output, OutputSize receives a pointer to a UINT value specifying the actual size, in bytes, of Output.

Output
[out] Receives a pointer to an array of RTM_ENTITY_METHOD_OUTPUT structures. Each structure consists of a (method identifier, correct output) tuple.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

Remarks

For sample code using this function, see Obtain and Call the Exported Methods for a Client.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_ENTITY_METHOD_INPUT, RTM_ENTITY_METHOD_OUTPUT, RtmBlockMethods, RtmGetEntityMethods


RtmIsBestRoute

The RtmIsBestRoute function returns the set of views in which the specified route is the best route to a destination.

DWORD RtmIsBestRoute(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_ROUTE_HANDLE RouteHandle,
  PRTM_VIEW_SET BestInViews
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
RouteHandle
[in] Handle to the route to check.
BestInViews
[out] Receives a pointer to the set of views for which the specified route is the best route.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmGetExactMatchDestination, RtmGetExactMatchRoute, RtmGetLessSpecificDestination, RtmGetMostSpecificDestination


RtmIsMarkedForChangeNotification

The RtmIsMarkedForChangeNotification function queries the routing table manager to determine if a destination has previously been marked by a call to RtmMarkDestForChangeNotification.

DWORD RtmIsMarkedForChangeNotification(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_NOTIFY_HANDLE NotifyHandle,
  RTM_DEST_HANDLE DestHandle,
  PBOOL DestMarked
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
NotifyHandle
[in] Handle to a change notification, obtained from a previous call to RtmRegisterForChangeNotification.
DestHandle
[in] Handle to the destination to check.
DestMarked
[out] Pointer to a BOOL variable that is TRUE if the destination is marked, FALSE if it is not.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmGetChangedDests, RtmGetChangeStatus, RtmIgnoreChangedDests, RtmMarkDestForChangeNotification, RtmReleaseChangedDests


RtmLockDestination

The RtmLockDestination function locks or unlocks a destination in the routing table. Use this function to protect a destination while changing opaque pointers.

DWORD RtmLockDestination(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_DEST_HANDLE DestHandle,
  BOOL Exclusive,
  BOOL LockDest
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
DestHandle
[in] Handle to the destination to lock.
Exclusive
[in] Specifies whether to lock or unlock the destination in an exclusive (TRUE) or shared (FALSE) mode.
LockDest
[in] Specifies whether to lock or unlock the destination. Specify TRUE to lock the destination; specify FALSE to unlock it.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling client does not own this destination.
ERROR_INVALID_HANDLE | The handle is invalid.

Remarks

This function also locks the associated routes. Avoid locking destinations for long periods of time, because no other client can access the destination and associated routes until the lock is released.

A client can also use this function when reading information for a destination, while preventing changes during the client's read operation. In this case, consider using RtmGetDestInfo instead.

For sample code using this function, see Update a Route In Place Using RtmUpdateAndUnlockRoute.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmGetOpaqueInformationPointer


RtmLockNextHop

The RtmLockNextHop function locks or unlocks a next hop. This function should be called by the next hop's owner to lock the next hop before making changes to the next hop. A pointer to the next hop is returned.

DWORD RtmLockNextHop(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_NEXTHOP_HANDLE NextHopHandle,
  BOOL Exclusive,
  BOOL LockNextHop,
  PRTM_NEXTHOP_INFO *NextHopPointer
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
NextHopHandle
[in] Handle to the next hop to lock or unlock.
Exclusive
[in] Specifies whether to lock or unlock the next hop in an exclusive (TRUE) or shared (FALSE) mode.
LockNextHop
[in] Specifies whether to lock or unlock the next hop. Specify TRUE to lock the next hop; specify FALSE to unlock it.
NextHopPointer
[out] On input, NextHopPointer is a pointer to NULL.

On output, if the client owns the next hop, NextHopPointer receives a pointer to the next-hop; otherwise, NextHopPointer remains unchanged.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling client does not own this next hop.
ERROR_NOT_FOUND | The specified next hop was not found.

Remarks

Clients cannot change the NextHopAddress and InterfaceIndex members; these values are used to uniquely identify a next hop.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_NEXTHOP_INFO, RtmAddNextHop, RtmDeleteNextHop, RtmFindNextHop, RtmGetNextHopPointer


RtmLockRoute

The RtmLockRoute function locks or unlocks a route in the routing table. This protects the route while a client makes the necessary changes to the opaque route pointers owned by the client.

DWORD RtmLockRoute(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_ROUTE_HANDLE RouteHandle,
  BOOL Exclusive,
  BOOL LockRoute,
  PRTM_ROUTE_INFO *RoutePointer
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
RouteHandle
[in] Handle to the route to lock.
Exclusive
[in] Specifies whether to lock or unlock the route in an exclusive (TRUE) or shared (FALSE) mode.
LockRoute
[in] Specifies whether to lock or unlock the route. Specify TRUE to lock the route; specify FALSE to unlock it.
RoutePointer
[out] If a pointer must be returned: On input, RoutePointer is a pointer to NULL. On output, if the client owns the route, RoutePointer receives a pointer to the next-hop; otherwise, RoutePointer remains unchanged.

If a handle does not need to be returned: On input, RoutePointer is NULL.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling client does not own this route.
ERROR_INVALID_HANDLE | The handle is invalid.

Remarks

Do not call any other RTMv2 functions until the route is unlocked by a call to RtmLockRoute and the LockRoute parameter is set to FALSE, or a call to RtmUpdateAndUnlockRoute.

Currently, this function locks the entire destination, not just the route.

Clients can only change the Neighbour, PrefInfo, BelongsToViews, EntitySpecificInfo, and NextHopsList members of the RTM_ROUTE_INFO structure.

If any of these values are changed, the client must call RtmUpdateAndUnlockRoute to notify the routing table manager of the changes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_ROUTE_INFO, RtmAddRouteToDest, RtmDeleteRouteToDest, RtmGetRoutePointer, RtmHoldDestination, RtmUpdateAndUnlockRoute


RtmMarkDestForChangeNotification

The RtmMarkDestForChangeNotification function marks a destination for a client. A marked destination indicates to the routing table manager that it should send the client change notification messages for the marked destination. The client receives change notification messages when a destination changes. The change notifications inform the client of changes to best-route information for the specified destination. This function should be used when RtmRegisterForChangeNotification is called to request changes for specific destinations (RTM_NOTIFY_ONLY_MARKED_DESTS).

DWORD RtmMarkDestForChangeNotification(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_NOTIFY_HANDLE NotifyHandle,
  RTM_DEST_HANDLE DestHandle,
  BOOL MarkDest
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
NotifyHandle
[in] Handle to a change notification obtained via a previous call to RtmRegisterForChangeNotification.
DestHandle
[in] Handle to the destination that the client is marking for notification of changes.
MarkDest
[in] Specifies whether to mark a destination and receive change notifications. Specify TRUE to mark a destination and start receive change notifications for the specified destination. Specify FALSE to stop receiving change notifications a previously marked destination.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmGetChangedDests, RtmGetChangeStatus, RtmIgnoreChangedDests, RtmIsMarkedForChangeNotification, RtmRegisterForChangeNotification, RtmReleaseChangedDests


RtmReferenceHandles

The RtmReferenceHandles function increases the reference count for objects pointed to by one or more handles that the routing manager used to access those objects. A client should use this function when the client must keep a handle but release the rest of the information structure associated with the handle.

DWORD RtmReferenceHandles(
  RTM_ENTITY_HANDLE RtmRegHandle,
  UINT NumHandles,
  HANDLE *RtmHandles
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
NumHandles
[in] Specifies the number of handles in RtmHandles.
RtmHandles
[in] Array of handles to increase the reference count for.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

Remarks

A client must always call this function when caching a handle returned by the routing table manager. This notifies the routing table manager that it should not destroy the object the handle refers to until the handle is released by the client.

When a client must release the handle, the client must call the appropriate release function, based on the type of handle. For example, to release a route, call RtmReleaseRoutes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmDeleteEnumHandle, RtmReleaseChangedDests, RtmReleaseDestInfo, RtmReleaseEntityInfo, RtmReleaseNextHopInfo, RtmReleaseRouteInfo


RtmRegisterEntity

The RtmRegisterEntity function registers a client with an instance of the routing table manager for a specific address family. The routing table manager returns a registration handle and a profile of the instance. The profile contains a list of values that are used when calling other functions. Values include the maximum number of destinations returned in a buffer by a single call.

Registration is the first action a client should take.

DWORD RtmRegisterEntity(
  PRTM_ENTITY_INFO RtmEntityInfo,
  PRTM_ENTITY_EXPORT_METHODS ExportMethods,
  RTM_EVENT_CALLBACK EventCallback,
  BOOL ReserveOpaquePointer,
  PRTM_REGN_PROFILE RtmRegProfile,
  PRTM_ENTITY_HANDLE RtmRegHandle
);

Parameters

RtmEntityInfo
[in] Pointer to an RTM_ENTITY_INFO structure. This structure contains information identifying the client to the routing table manager, such as the routing table manager instance and address family with which to register.
ExportMethods
[in] Pointer to a list of methods exported by the client. This parameter is optional and can be set to NULL if the calling client has no methods to export.
EventCallback
[in] Specifies the callback the routing table manager will use to notify the client of events. The events are when a client registers and unregisters, when routes expire, and when changes to the best route to a destination have occurred. Only those changes specified when the client called RtmRegisterForChangeNotification.
ReserveOpaquePointer
[in] Specifies whether to reserve an opaque pointer in each destination for this instance of the protocol. Specify TRUE to reserve an opaque pointer in each destination. Specify FALSE to skip this action. These opaque pointers can be used to point to a private, protocol-specific context for each destination.
RtmRegProfile
[out] On input, RtmRegProfile is a pointer to an RTM_REGN_PROFILE structure.

On output, RtmRegProfile is filled with the requested registration profile structure. The client must use the information returned in other function calls (information returned includes the number of equal-cost next hops and the maximum number of items returned by an enumeration function call).

RtmRegHandle
[out] Receives a registration handle for the client. This handle must be used in all subsequent calls to the routing table manager.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ALREADY_EXISTS | The specified client has already registered with the routing table manager.
ERROR_BAD_CONFIGURATION | Registry information for the routing table manager is corrupt.
ERROR_FILE_NOT_FOUND | Registry information for the routing table manager was not found.
ERROR_INVALID_DATA | A parameter contains incorrect information.
ERROR_INVALID_PARAMETER | A parameter contains incorrect information.
ERROR_NO_SYSTEM_RESOURCES | There are not enough available system resources to complete this operation.
ERROR_NOT_ENOUGH_MEMORY | There is not enough memory to complete this operation.

Remarks

For sample code using this function, see Register With the Routing Table Manager.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_EVENT_CALLBACK, RTM_ENTITY_EXPORT_METHODS, RTM_ENTITY_INFO, RTM_REGN_PROFILE, RtmDeregisterEntity, RtmGetRegisteredEntities, RtmReleaseEntities


RtmRegisterForChangeNotification

The RtmRegisterForChangeNotification function informs the routing table manager that the client should receive change notifications for the specified types of changes. The routing table manager returns a change notification handle, which the client must use when requesting change information after receiving a change notification message.

DWORD RtmRegisterForChangeNotification(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_VIEW_SET TargetViews,
  RTM_NOTIFY_FLAGS NotifyFlags,
  PVOID NotifyContext,
  PRTM_NOTIFY_HANDLE NotifyHandle
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
TargetViews
[in] Specifies the views in which to register for change notification.
NotifyFlags
[in] Specifies the flags that indicate the type of changes for which the client requests notification. The following flags are used. (The flags are to be joined using a logical OR.)
Constant | Description
RTM_CHANGE_TYPE_ALL | Notify the client of any change to a destination.
RTM_CHANGE_TYPE_BEST | Notify the client of changes to the current best route, or when the best route changes.
RTM_CHANGE_TYPE_FORWARDING | Notify the client of any best route changes that affect forwarding, such as next hop changes.
RTM_NOTIFY_ONLY_MARKED_DESTS | Notify the client of changes to destinations that the client has marked. If this flag is not specified, change notification messages for all destinations are sent.

NotifyContext
[in] Specifies the notification context that the RTM_EVENT_CALLBACK uses to indicate new changes. The notification context is the Context2 parameter of the RTM_EVENT_CALLBACK callback.
NotifyHandle
[out] Receives a handle to a change notification. The handle must be used when calling RtmGetChangedDests.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | A parameter contains incorrect information.
ERROR_NO_SYSTEM_RESOURCES | There are not enough available system resources to complete this operation. The routing table manager has exceeded the maximum number of change notifications that can be cached.
ERROR_NOT_ENOUGH_MEMORY | There is not enough memory to complete this operation.
ERROR_NOT_SUPPORTED | One or more of the specified views is not supported.

Remarks

A client calls RtmMarkDestForChangeNotification when it is registering for changes to a specific destination.

The routing table manager uses the RTM_EVENT_CALLBACK callback, specified when the client called RtmRegisterEntity, to notify the client when changes have occurred; the client must call RtmGetChangedDests to receive the actual change information.

For sample code using this function, see Register For Change Notification.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmDeregisterFromChangeNotification, RtmGetChangedDests, RtmMarkDestForChangeNotification


RtmReleaseChangedDests

The RtmReleaseChangedDests function releases the changed destination handles.

DWORD RtmReleaseChangedDests(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_NOTIFY_HANDLE NotifyHandle,
  UINT NumDests,
  PRTM_DEST_INFO ChangedDests
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
NotifyHandle
[in] Handle to a change notification, obtained from a previous call to RtmRegisterForChangeNotification.
NumDests
[in] Specifies the number of destinations in ChangedDests.
ChangedDests
[in] Pointer to an array of RTM_DEST_INFO structures to release. The changed destinations were obtained from a prior call to RtmGetChangedDests.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

Remarks

Always use this function to release changed RTM_DEST_INFO structures obtained from a call to RtmGetChangedDests.

The RTM_DEST_INFO structure is a variable-sized structure. If a destination contains information for more than one view, the size of RTM_DEST_INFO increases for each view. Use the RTM_SIZE_OF_DEST_INFO macro to determine how large a ChangedDests buffer to allocate before calling this function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_DEST_INFO, RtmGetChangedDests, RtmGetChangeStatus, RtmIgnoreChangedDests, RtmIsMarkedForChangeNotification, RtmMarkDestForChangeNotification


RtmReleaseDestInfo

The RtmReleaseDestInfo function releases a destination structure.

DWORD RtmReleaseDestInfo(
  RTM_ENTITY_HANDLE RtmRegHandle,
  PRTM_DEST_INFO DestInfo
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
DestInfo
[in] Pointer to the destination to release. The destination was obtained from a previous call to a function that returns an RTM_DEST_INFO structure.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_DEST_INFO, RtmGetDestInfo


RtmReleaseDests

The RtmReleaseDests function releases the destination handles.

DWORD RtmReleaseDests(
  RTM_ENTITY_HANDLE RtmRegHandle,
  UINT NumDests,
  PRTM_DEST_INFO DestInfos
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
NumDests
[in] Specifies the number of destinations in DestInfos.
DestInfos
[in] Pointer to an array of RTM_DEST_INFO structures to release. The destinations were obtained from a previous call to RtmGetEnumDests.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

Remarks

Do not use this function to release RTM_DEST_INFO structures obtained from a call to RtmGetChangedDests. Use RtmReleaseChangedDests instead.

The RTM_DEST_INFO structure is a variable-sized structure. If a destination contains information for more than one view, the size of RTM_DEST_INFO increases for each view. Use the RTM_SIZE_OF_DEST_INFO macro to determine how large a DestInfos buffer to allocate before calling this function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_DEST_INFO, RtmCreateDestEnum, RtmDeleteEnumHandle, RtmGetEnumDests


RtmReleaseEntities

The RtmReleaseEntities function releases the client handles returned by RtmGetRegisteredEntities.

DWORD RtmReleaseEntities(
  RTM_ENTITY_HANDLE RtmRegHandle,
  UINT NumEntities,
  PRTM_ENTITY_HANDLE EntityHandles
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
NumEntities
[in] Specifies the number of clients in EntityHandles.
EntityHandles
[in] Pointer to an array of client handles to release. The handles were obtained from a previous call to RtmGetRegisteredEntities.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmGetRegisteredEntities


RtmReleaseEntityInfo

The RtmReleaseEntityInfo function releases a client structure.

DWORD RtmReleaseEntityInfo(
  RTM_ENTITY_HANDLE RtmRegHandle,
  PRTM_ENTITY_INFO EntityInfo
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
EntityInfo
[in] Pointer to the handle to release. The handle was obtained with a previous call to RtmGetEntityInfo.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_ENTITY_INFO, RtmGetEntityInfo


RtmReleaseNextHopInfo

The RtmReleaseNextHopInfo function releases a next-hop structure.

DWORD RtmReleaseNextHopInfo(
  RTM_ENTITY_HANDLE RtmRegHandle,
  PRTM_NEXTHOP_INFO NextHopInfo
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
NextHopInfo
[in] Pointer to the RTM_NEXTHOP_INFO structure to release. The next hop was obtained with a previous call to RtmGetNextHopInfo.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_NEXTHOP_INFO, RtmFindNextHop, RtmGetNextHopInfo


RtmReleaseNextHops

The RtmReleaseNextHops function releases the next-hop handles.

DWORD RtmReleaseNextHops(
  RTM_ENTITY_HANDLE RtmRegHandle,
  UINT NumNextHops,
  PRTM_NEXTHOP_HANDLE NextHopHandles
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
NumNextHops
[in] Specifies the number of next hops in NextHopHandles.
NextHopHandles
[in] Pointer to an array of next-hop handles to release. The handles were obtained with a previous call to RtmGetEnumNextHops.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmCreateNextHopEnum, RtmGetEnumNextHops


RtmReleaseRouteInfo

The RtmReleaseRouteInfo function releases a route structure.

DWORD RtmReleaseRouteInfo(
  RTM_ENTITY_HANDLE RtmRegHandle,
  PRTM_ROUTE_INFO RouteInfo
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
RouteInfo
[in] Pointer to the RTM_ROUTE_INFO structure to release. The route was obtained with a previous call to RtmGetRouteInfo.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RTM_ROUTE_INFO, RtmGetRouteInfo


RtmReleaseRoutes

The RtmReleaseRoutes function releases the route handles.

DWORD RtmReleaseRoutes(
  RTM_ENTITY_HANDLE RtmRegHandle,
  UINT NumRoutes,
  PRTM_ROUTE_HANDLE RouteHandles
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
NumRoutes
[in] Specifies the number of routes in RouteHandles.
RouteHandles
[in] Pointer to an array of route handles to release. The handles were obtained with a previous call to RtmGetEnumRoutes.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_INVALID_HANDLE | The handle is invalid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmCreateRouteEnum, RtmDeleteEnumHandle, RtmGetEnumRoutes


RtmUpdateAndUnlockRoute

The RtmUpdateAndUnlockRoute function updates the position of the route in the set of routes for a destination, and adjusts the best route information for the destination.

This function is used after a client has locked a route and updated it directly (also known as "in-place updating").

DWORD RtmUpdateAndUnlockRoute(
  RTM_ENTITY_HANDLE RtmRegHandle,
  RTM_ROUTE_HANDLE RouteHandle,
  ULONG TimeToLive,
  RTM_ROUTE_LIST_HANDLE RouteListHandle,
  RTM_NOTIFY_FLAGS NotifyType,
  RTM_NOTIFY_HANDLE NotifyHandle,
  PRTM_ROUTE_CHANGE_FLAGS ChangeFlags
);

Parameters

RtmRegHandle
[in] Handle to the client obtained from a previous call to RtmRegisterEntity.
RouteHandle
[in] Handle to the route to change.
TimeToLive
[in] Specifies the time, in milliseconds, after which the route is expired. Specify INFINITE to prevent routes from expiring.
RouteListHandle
[in] Handle to an optional route list to which to move the route. This parameter is optional and can be set to NULL.
NotifyType
[in] Set this parameter to NULL. NotifyType is reserved for future use.
NotifyHandle
[in] Set this parameter to NULL. NotifyHandle is reserved for future use.
ChangeFlags
[out] Receives RTM_ROUTE_CHANGE_BEST if the best route was changed.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The calling client does not own this route.

Remarks

Before calling this function, the client should lock the route using RtmLockRoute, which returns a pointer to the route. Then, the client can update the route information using the pointer. Finally, the client should call RtmUpdateAndUnlockRoute. If the function executes successfully, the route is unlocked. If the call failed, the client must unlock the route by calling RtmLockRoute with the LockRoute parameter set to FALSE.

For sample code using this function, see Update a Route In Place Using RtmUpdateAndUnlockRoute.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.
Library: Use Rtm.lib.

See Also

RtmAddRouteToDest, RtmDeleteRouteToDest, RtmGetRoutePointer, RtmHoldDestination, RtmLockRoute


Routing Table Manager Version 2 Callbacks

The following callbacks are used to inform clients of registration events.

RTM_ENTITY_EXPORT_METHOD

RTM_EVENT_CALLBACK


RTM_ENTITY_EXPORT_METHOD

The RTM_ENTITY_EXPORT_METHOD callback is the prototype for any method exported by a client.

typedef VOID (WINAPI * _ENTITY_METHOD) (
  RTM_ENTITY_HANDLE CallerHandle,
  RTM_ENTITY_HANDLE CalleeHandle,
  RTM_ENTITY_METHOD_INPUT *Input,
  RTM_ENTITY_METHOD_OUTPUT *Output
);

Parameters

CallerHandle
Handle to the calling client.
CalleeHandle
Handle to the client being called.
Input
Handle to the method to be invoked. Contains an input buffer.
Output
An array of RTM_ENTITY_METHOD_OUTPUT structures. Each structure consists of a (method identifier, correct output) tuple.

Remarks

Methods can be exported when a client registers. Other clients, such as routing protocols, can invoke these methods to obtain client-specific information. For example, BGP can use a method to obtain OSFP information.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.

See Also

RTM_ENTITY_METHOD_INPUT, RTM_ENTITY_METHOD_OUTPUT


RTM_EVENT_CALLBACK

The RTM_EVENT_CALLBACK callback is used by the routing table manager to inform a client that the specified event occurred.

typedef DWORD (WINAPI * _EVENT_CALLBACK) (
  IRTM_ENTITY_HANDLE RtmRegHandle,
  RTM_EVENT_TYPE EventType,
  PVOID Context1,
  PVOID Context2
);

Parameters

RtmRegHandle
Handle to the client to which the routing table manager is sending the notification.
EventType
Specifies the event about which the routing table manager is notifying the client. The following values are used.
Value | Description
RTM_ENTITY_REGISTERED | A client has just registered with the routing table manager.
RTM_ENTITY_DEREGISTERED | A client has just unregistered.
RTM_ROUTE_EXPIRED | A route has timed out.
RTM_CHANGE_NOTIFICATION | A change notification has been made.

Context1
For RTM_ENTITY_REGISTERED calls: Contains the handle to the entity that registered.

For RTM_ENTITY_DEREGISTERED calls: Contains the handle to the entity that unregistered.

For RTM_ROUTE_EXPIRED calls: Contains the handle to the route that timed out.

For RTM_CHANGE_NOTIFICATION calls: Contains the handle to the change notification.

Context2
For RTM_ENTITY_REGISTERED calls: Contains a pointer to the RTM_ENTITY_INFO structure referred to by the handle in Context1. If the client must retain this information, the client must copy it to a structure it has allocated.

For RTM_ENTITY_DEREGISTERED calls: Contains a pointer to the RTM_ENTITY_INFO structure referred to by the handle in Context1. If the client must retain this information, the client must copy it to a structure it has allocated.

For RTM_ROUTE_EXPIRED calls: Contains a pointer to the RTM_ROUTE_INFO structure referred to by the handle in Context1. If the client must retain this information, the client must copy it to a structure it has allocated.

For RTM_CHANGE_NOTIFICATION calls: Contains the notification context that was given to the client by a previous call to RtmRegisterForChangeNotification.

Return Values

If the routing table manager issues an RTM_ROUTE_EXPIRED callback, and the client returns to the routing table manager the value ERROR_NOT_SUPPORTED, the routing table manager will delete the route from the routing table.

All other errors returned by the client are ignored.

Remarks

After a client has registered for change notification, the routing table manager uses this callback to keep the client informed about events.

If a client receives an RTM_EVENT_CALLBACK for the RTM_ENTITY_REGISTERED or RTM_ENTITY_DEREGISTERED events, the client must not make calls to RtmRegisterEntity, RtmDeregisterEntity, or RtmGetRegisteredEntities in the context of this callback.

If a client receives an RTM_EVENT_CALLBACK for the RTM_CHANGE_NOTIFICATION event, the client must not call RtmRegisterForChangeNotification in the context of this callback.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.

See Also

RTM_EVENT_TYPE, RtmRegisterEntity


Routing Table Manager Version 2 Structures

The RTMv2 functions use the following structures:

RTM_DEST_INFO

RTM_ENTITY_EXPORT_METHODS

RTM_ENTITY_ID

RTM_ENTITY_INFO

RTM_ENTITY_METHOD_INPUT

RTM_ENTITY_METHOD_OUTPUT

RTM_NET_ADDRESS

RTM_NEXTHOP_INFO

RTM_NEXTHOP_LIST

RTM_PREF_INFO

RTM_REGN_PROFILE

RTM_ROUTE_INFO


RTM_DEST_INFO

The RTM_DEST_INFO structure is used to exchange destination information with clients registered with the routing table manager.

typedef struct _RTM_DEST_INFO {
  RTM_DEST_HANDLE       DestHandle;
  RTM_NET_ADDRESS       DestAddress;
  FILETIME              LastChanged;
  RTM_VIEW_SET          BelongsToViews;
  UINT                  NumberOfViews;
  struct
  {
    RTM_VIEW_ID         ViewId;
    UINT                NumRoutes;
    RTM_ROUTE_HANDLE    Route;
    RTM_ENTITY_HANDLE   Owner;
    DWORD               DestFlags;
    RTM_ROUTE_HANDLE    HoldRoute;
  }                 ViewInfo[1];
} RTM_DEST_INFO, *PRTM_DEST_INFO;

Members

DestHandle
Handle to the destination.
DestAddress
Specifies the destination network address as an address and a mask.
LastChanged
Specifies the last time this destination was updated.
BelongsToViews
Specifies the views to which this destination belongs.
NumberOfViews
Indicates the number of ViewInfo structures present in this destination.
ViewInfo
Structure of the following components.
ViewId
Specifies the view this information applies to.
NumRoutes
Specifies the number of routes in each of the supported views.
Route
Handle to the best route (with matching criteria) in each of the supported views.
Owner
Handle to the owner of the best route in each of the supported views.
DestFlags
Specifies the flags for the best route in each of the supported views.
HoldRoute
Handle to the route that is in a hold-down state in each of the supported views.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.

See Also

RTM_NET_ADDRESS, RtmGetChangedDests, RtmGetDestInfo, RtmGetEnumDests, RtmGetExactMatchDestination, RtmGetLessSpecificDestination, RtmGetMostSpecificDestination, RtmReleaseChangedDests, RtmReleaseDestInfo, RtmReleaseDests


RTM_ENTITY_EXPORT_METHODS

The RTM_ENTITY_EXPORT_METHODS structure contains the set of methods exported by a client.

typedef struct _RTM_ENTITY_EXPORT_METHODS {
  UINT                     NumMethods;
  RTM_ENTITY_EXPORT_METHOD Methods[1];
} RTM_ENTITY_EXPORT_METHODS, *PRTM_ENTITY_EXPORT_METHODS;

Members

NumMethods
Specifies the number of methods exported by the client in the Methods member.
Methods
Specifies which methods the client is exporting.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.

See Also

RtmRegisterEntity


RTM_ENTITY_ID

The RTM_ENTITY_ID structure is used to uniquely identify a client to the routing table manager. The protocol identifier and the instance identifier are the values that are used to uniquely identify a client.

typedef struct _RTM_ENTITY_ID {
  union
  {
    struct {
      ULONG    EntityProtocolId;
      ULONG    EntityInstanceId;
    };
    ULONGLONG  EntityId;
  };
} RTM_ENTITY_ID, *PRTM_ENTITY_ID;

Members

EntityProtocolId
Specifies a client's protocol identifier (such as RIP or OSPF).
EntityInstanceId
Specifies a client's protocol instance (such as RIPv1 or RIPv2).
EntityId
Specifies a client's identifier, which is a combination of the EntityProtocolId and the EntityInstanceId.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.

See Also

RTM_ENTITY_INFO


RTM_ENTITY_INFO

The RTM_ENTITY_INFO structure is used to exchange client information with the routing table manager.

typedef struct _RTM_ENTITY_INFO {
  USHORT         RtmInstanceId;
  USHORT         AddressFamily;
  RTM_ENTITY_ID  EntityId;
} RTM_ENTITY_INFO, *PRTM_ENTITY_INFO;

Members

RtmInstanceId
Specifies the instance of the routing table manager with which the client registered.
AddressFamily
Specifies the address family to which the client belongs.
EntityId
Specifies the identifier that uniquely identifies a client.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.

See Also

RTM_ENTITY_ID, RtmGetEntityInfo, RtmGetRegisteredEntities, RtmRegisterEntity, RtmReleaseEntityInfo


RTM_ENTITY_METHOD_INPUT

The RTM_ENTITY_METHOD_INPUT structure is used to pass information to a client when invoking its method.

typedef struct _RTM_ENTITY_METHOD_INPUT {
  RTM_ENTITY_METHOD_TYPE  MethodType;
  UINT                    InputSize;
  UCHAR                   InputData[1];
} RTM_ENTITY_METHOD_INPUT, *PRTM_ENTITY_METHOD_INPUT;

Members

MethodType
Specifies the method.
InputSize
Specifies the size, in bytes, of InputData.
InputData
Buffer for input data for the method.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.

See Also

RtmInvokeMethod


RTM_ENTITY_METHOD_OUTPUT

The RTM_ENTITY_METHOD_INPUT structure is used to pass information to the calling client when the routing table manager invokes a method.

typedef struct _RTM_ENTITY_METHOD_OUTPUT {
  RTM_ENTITY_METHOD_TYPE  MethodType;
  DWORD                   MethodStatus;
  UINT                    OutputSize;
  UCHAR                   OutputData[1];
} RTM_ENTITY_METHOD_OUTPUT, *PRTM_ENTITY_METHOD_OUTPUT;

Members

MethodType
Specifies the method identifier
MethodStatus
Receives the status of the method after execution.
OutputSize
Specifies the size, in bytes, of OutputData.
OutputData
Buffer for data returned by the method.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.

See Also

RtmInvokeMethod


RTM_NET_ADDRESS

The RTM_NET_ADDRESS structure is used to communicate address information to the routing table manager for any address family. The address family must use only with contiguous address masks that are less than 8 bytes.

typedef struct _RTM_NET_ADDRESS {
  USHORT   AddressFamily;
  USHORT   NumBits;
  UCHAR    AddrBits[RTM_MAX_ADDRESS_SIZE];
} RTM_NET_ADDRESS, *PRTM_NET_ADDRESS;

Members

AddressFamily
Specifies the type of network address for this address (such as IPv4).
NumBits
Specifies the number of bits in the network part of the AddrBits bit array (for example, 255.0.0.0 has 8 bits).
AddrBits
Specifies an array of bits that form the address prefix.

Remarks

If the client specifies an address and a mask length that do not correspond to each other, inconsistent results will be returned by the routing table manager. For example, if a client specifies an address as 10.10.10.10 and a length as 24 when calling RTM_IPV4_SET_ADDR_AND_LEN, the routing table manager may return an incorrect NetAddress.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.

See Also

RTM_DEST_INFO, RTM_NEXTHOP_INFO, RtmAddRouteToDest, RtmCreateDestEnum, RtmCreateNextHopEnum, RtmCreateRouteEnum, RtmGetExactMatchDestination, RtmGetExactMatchRoute, RtmGetMostSpecificDestination, RtmGetRouteInfo


RTM_NEXTHOP_INFO

The RTM_NEXTHOP_INFO structure is used to exchange next-hop information with the routing table manager.

typedef struct _RTM_NEXTHOP_INFO {
  //
  // Information that the owner can directly access for read only
  //
  RTM_NET_ADDRESS     NextHopAddress;
  RTM_ENTITY_HANDLE   NextHopOwner;
  ULONG               InterfaceIndex;
  USHORT              State;
  //
  // Information that the owner can directly access for read/write
  //
  USHORT              Flags;
  PVOID               EntitySpecificInfo;
  RTM_DEST_HANDLE     RemoteNextHop;
} RTM_NEXTHOP_INFO, *PRTM_NEXTHOP_INFO;

Members

NextHopAddress
Specifies the network address for this next hop.
NextHopOwner
Handle to the client that owns this next hop.
InterfaceIndex
Specifies the outgoing interface index.
State
Flags that indicates the state of this next hop. The following flags are used.
Constant | Description
RTM_NEXTHOP_STATE_CREATED | The next hop has been created.
RTM_NEXTHOP_STATE_DELETED | The next hop has been deleted.

Flags
Flags that convey status information for the next hop. The following flags are used.
Constant | Description
RTM_NEXTHOP_FLAGS_REMOTE | This next hop points to a remote destination that is not directly reachable. To obtain the complete path, the client must perform a recursive lookup.
RTM_NEXTHOP_FLAGS_DOWN | This flag is reserved for future use.

EntitySpecificInfo
Contains information specific to the client that owns this next hop.
RemoteNextHop
Handle to the destination with the indirect next-hop address. This member is only valid when the Flags member is set to RTM_NEXTHOP_FLAGS_REMOTE. This cached handle can prevent multiple lookups for this indirect next hop.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.

See Also

RTM_NET_ADDRESS, RtmAddNextHop, RtmDeleteNextHop, RtmFindNextHop, RtmGetNextHopInfo, RtmGetNextHopPointer, RtmLockNextHop, RtmReleaseNextHopInfo


RTM_NEXTHOP_LIST

The RTM_NEXTHOP_LIST structure contains a list of next hops used to determine equal-cost paths in a route.

typedef struct _RTM_NEXTHOP_LIST {
  USHORT              NumNextHops;
  RTM_NEXTHOP_HANDLE  NextHops[1];
} RTM_NEXTHOP_LIST, *PRTM_NEXTHOP_LIST;

Members

NumNextHops
Specifies the number of equal cost next hops in NextHops.
NextHops
Array of next-hop handles.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.

See Also

RTM_ROUTE_INFO


RTM_PREF_INFO

The RTM_PREF_INFO structure contains the information used when comparing any two routes. The value of the Preference member is given more weight than the value of the Metric member.

typedef struct _RTM_PREF_INFO {
  ULONG               Metric;
  ULONG               Preference;
} RTM_PREF_INFO, *PRTM_PREF_INFO;

Members

Metric
Specifies a metric. The metric is specific to a particular routing protocol.
Preference
Specifies a preference. The preference is determined by the router policy.

Remarks

Preference is more important than metric. The metric will only be checked if the preferences are equal.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.

See Also

RTM_ROUTE_INFO


RTM_REGN_PROFILE

The RTM_REGN_PROFILE structure contains information returned during the registration process. The information is used for later function calls (such as the maximum number of routes that can be returned by a call to RtmGetEnumRoutes).

typedef struct _RTM_REGN_PROFILE {
  UINT          MaxNextHopsInRoute;
  UINT          MaxHandlesInEnum;
  RTM_VIEW_SET  ViewsSupported;
  UINT          NumberOfViews;
} RTM_REGN_PROFILE, *PRTM_REGN_PROFILE;

Members

MaxNextHopsInRoute
Specifies the maximum number of equal-cost next hops in a route.
MaxHandlesInEnum
Specifies the maximum number of handles that can be returned in one call to RtmGetEnumDests, RtmGetChangedDests, RtmGetEnumRoutes, or RtmGetListEnumRoutes. The number of handles that can be returned is limited (and configurable) to improve efficiency and performance of the routing table manager.
ViewsSupported
Views supported by this address family.
NumberOfViews
Number of views.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.

See Also

RtmRegisterEntity


RTM_ROUTE_INFO

The RTM_ROUTE_INFO structure is used to exchange route information with the routing table manager. Do not change the read-only information.

typedef struct _RTM_ROUTE_INFO {
  //
  // Information that the owner can directly access for read only
  //
  RTM_DEST_HANDLE     DestHandle;
  RTM_ENTITY_HANDLE   RouteOwner;
  RTM_NEXTHOP_HANDLE  Neighbour;
  UCHAR               State;
  //
  // Information that the owner can directly access for read/write
  //
  UCHAR               Flags1;
  USHORT              Flags;
  RTM_PREF_INFO       PrefInfo;
  RTM_VIEW_SET        BelongsToViews;
  PVOID               EntitySpecificInfo;
  RTM_NEXTHOP_LIST    NextHopsList;
} RTM_ROUTE_INFO, *PRTM_ROUTE_INFO;

Members

DestHandle
Handle to the destination that owns the route.
RouteOwner
Handle to the client that owns this route.
Neighbour
Handle to the neighbor that informed the routing table manager of this route. This member is NULL for a link-state protocol.
State
Flags the specify the state of this route. The following flags are used.
Constant | Description
RTM_ROUTE_STATE_CREATED | Route has been created.
RTM_ROUTE_STATE_DELETING | Route is being deleted.
RTM_ROUTE_STATE_DELETED | Route has been deleted.

Flags1
Flags used for compatibility with RTMv1.
Flags
Flags used to specify information about the route. The following flags are used.
Constant | Description
RTM_ROUTE_FLAGS_ANY_BCAST | The route is one of the following broadcast types: RTM_ROUTE_FLAGS_LIMITED_BC, RTM_ROUTE_FLAGS_ONES_NETBC, RTM_ROUTE_FLAGS_ONES_SUBNET_BC, RTM_ROUTE_FLAGS_ZEROS_NETBC, RTM_ROUTE_FLAGS_ZEROS_SUBNETBC
RTM_ROUTE_FLAGS_ANY_MCAST | The route is one of the following multicast types: RTM_ROUTE_FLAGS_MCAST, RTM_ROUTE_FLAGS_LOCAL_MCAST
RTM_ROUTE_FLAGS_ANY_UNICAST | The route is one of the following unicast types: RTM_ROUTE_FLAGS_LOCAL, RTM_ROUTE_FLAGS_REMOTE, RTM_ROUTE_FLAGS_MYSELF
RTM_ROUTE_FLAGS_LIMITED_BC | Indicates that this route is a limited broadcast address. Packets to this destination should not be forwarded.
RTM_ROUTE_FLAGS_LOCAL | Indicates a destination is on a directly reachable network.
RTM_ROUTE_FLAGS_LOCAL_MCAST | Indicates that this route is a route to a local multicast address.
RTM_ROUTE_FLAGS_MCAST | Indicates that this route is a route to a multicast address.
RTM_ROUTE_FLAGS_MYSELF | Indicates the destination is one of the router's addresses.
RTM_ROUTE_FLAGS_NET_BCAST | Flag grouping that contains: RTM_ROUTE_FLAGS_ONES_NETBC, RTM_ROUTE_FLAGS_ZEROS_NETBC
RTM_ROUTE_FLAGS_ONES_NETBC | Indicates that the destination matches an interface's "all-ones" broadcast address. If broadcast forwarding is enabled, packets should be received and resent out all appropriate interfaces.
RTM_ROUTE_FLAGS_ONES_SUBNETBC | Indicates that the destination matches an interface's "all-ones" subnet broadcast address. If subnet broadcast forwarding is enabled, packets should be received and resent out all appropriate interfaces.
RTM_ROUTE_FLAGS_REMOTE | Indicates that the destination is not on a directly reachable network.
RTM_ROUTE_FLAGS_ZEROS_SUBNETBC | Indicates that the destination matches an interface's "all-zeros" subnet broadcast address. If subnet broadcast forwarding is enabled, packets should be received and resent out all appropriate interfaces.
RTM_ROUTE_FLAGS_ZEROS_NETBC | Indicates that the destination matches an interface's "all-zeros" broadcast address. If broadcast forwarding is enabled, packets should be received and resent out all appropriate interfaces.

PrefInfo
Specifies the preference and metric information for this route.
BelongsToViews
Specifies the views in which this route is included.
EntitySpecificInfo
Contains the client-specific information for the client that owns this route.
NextHopsList
Specifies a list of equal-cost next hops.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.

See Also

RTM_PREF_INFO, RTM_NEXTHOP_LIST, RtmAddRouteToDest, RtmCreateRouteEnum, RtmGetExactMatchRoute, RtmGetRouteInfo, RtmGetRoutePointer, RtmLockRoute, RtmReleaseRouteInfo


Routing Table Manager Version 2 Macros

RTMv2 uses the following macros:

Size of Structure Macros

RTM_SIZE_OF_DEST_INFO

RTM_SIZE_OF_ROUTE_INFO

IPv4 Address Macros

RTM_IPV4_GET_ADDR_AND_LEN

RTM_IPV4_GET_ADDR_AND_MASK

RTM_IPV4_LEN_FROM_MASK

RTM_IPV4_MAKE_NET_ADDRESS

RTM_IPV4_MASK_FROM_LEN

RTM_IPV4_SET_ADDR_AND_LEN

RTM_IPV4_SET_ADDR_AND_MASK


RTM_IPV4_GET_ADDR_AND_LEN

The RTM_IPV4_GET_ADDR_AND_LEN macro converts a generic net address and length to an IPv4 address and a length.

RTM_IPV4_GET_ADDR_AND_LEN(
  Addr,
  Len,
  NetAddress
);

Parameters

Addr
Receives the converted IPv4 address.
Len
Receives the converted length.
NetAddress
Specifies the network address to convert.

Remarks

For example, if a client supplies the NetAddress 10.10.10/24, the Addr 10.10.10.0 and the Len 24 are returned.

The macro is defined as follows:

#define RTM_IPV4_GET_ADDR_AND_LEN(Addr, Len, NetAddress)    \
        (Len) = (NetAddress)->NumBits;                      \
        (Addr) = (* (ULONG *) ((NetAddress)->AddrBits));    \

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.

See Also

RTM_IPV4_GET_ADDR_AND_MASK, RTM_IPV4_LEN_FROM_MASK, RTM_IPV4_MAKE_NET_ADDRESS, RTM_IPV4_MASK_FROM_LEN, RTM_IPV4_SET_ADDR_AND_LEN, RTM_IPV4_SET_ADDR_AND_MASK, RTM_NET_ADDRESS


RTM_IPV4_GET_ADDR_AND_MASK

The RTM_IPV4_GET_ADDR_AND_MASK macro converts a generic net address and length to an IPv4 address and mask.

RTM_IPV4_GET_ADDR_AND_MASK(
  Addr,
  Mask,
  NetAddress
);

Parameters

Addr
Receives the converted IPv4 address.
Mask
Receives the converted IPv4 mask.
NetAddress
Specifies the network address to convert.

Remarks

For example, if a client supplies the NetAddress 10.10.10/24, the Addr 10.10.10.0 and the Mask 255.255.255.255 are returned.

The macro is defined as follows:

#define RTM_IPV4_GET_ADDR_AND_MASK(Addr, Mask, NetAddress)  \
        (Addr) = (* (ULONG *) ((NetAddress)->AddrBits));    \
        (Mask) = RTM_IPV4_MASK_FROM_LEN((NetAddress)-       \
            >NumBits);

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.

See Also

RTM_IPV4_GET_ADDR_AND_LEN, RTM_IPV4_LEN_FROM_MASK, RTM_IPV4_MAKE_NET_ADDRESS, RTM_IPV4_MASK_FROM_LEN, RTM_IPV4_SET_ADDR_AND_LEN, RTM_IPV4_SET_ADDR_AND_MASK, RTM_NET_ADDRESS


RTM_IPV4_LEN_FROM_MASK

The RTM_IPV4_LEN_FROM_MASK macro converts an IPv4 mask to a generic route length.

RTM_IPV4_LEN_FROM_MASK(
  Len,
  Mask
);

Parameters

Len
Receives the converted length
Mask
Specifies the mask to convert.

Remarks

For example, if a client supplies the Mask 255.255.255.255, the Len 24 is returned, the mask is returned.

The macro is defined as follows:

#define RTM_IPV4_LEN_FROM_MASK(Len, Mask)                   \
        {                                                   \
            ULONG _Temp_ = ntohl(Mask);                     \
            (Len) = 0;                                      \
            RTM_CHECK_NTH_BIT(_Temp_, 16, (Len));           \
            RTM_CHECK_NTH_BIT(_Temp_,  8, (Len));           \
            RTM_CHECK_NTH_BIT(_Temp_,  4, (Len));           \
            while (_Temp_)                                  \
            {                                               \
                (Len) +=  1; _Temp_ <<=  1;                 \
            }                                               \
        }                                                   \

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.

See Also

RTM_IPV4_GET_ADDR_AND_LEN, RTM_IPV4_GET_ADDR_AND_MASK, RTM_IPV4_MAKE_NET_ADDRESS, RTM_IPV4_MASK_FROM_LEN, RTM_IPV4_SET_ADDR_AND_LEN, RTM_IPV4_SET_ADDR_AND_MASK, RTM_NET_ADDRESS


RTM_IPV4_MAKE_NET_ADDRESS

The RTM_IPV4_MAKE_NET_ADDRESS macro converts an IPv4 address and a length to a generic RTM_NET_ADDRESS structure.

RTM_IPV4_MAKE_NET_ADDRESS(
  NetAddress,
  Addr,
  Len
);

Parameters

NetAddress
Receives the converted address structure.
Addr
Specifies the IPv4 address to convert.
Len
Specifies the length to convert.

Remarks

For example, if a client supplies the Addr 10.10.10.0 and the Len 24, the NetAddress 10.10.10/24 is returned.

The macro is defined as follows:

#define RTM_IPV4_MAKE_NET_ADDRESS(NetAddress, Addr, Len)    \
        RTM_IPV4_SET_ADDR_AND_LEN(NetAddress, Addr, Len)

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.

See Also

RTM_IPV4_GET_ADDR_AND_LEN, RTM_IPV4_GET_ADDR_AND_MASK, RTM_IPV4_LEN_FROM_MASK, RTM_IPV4_MASK_FROM_LEN, RTM_IPV4_SET_ADDR_AND_LEN, RTM_IPV4_SET_ADDR_AND_MASK, RTM_NET_ADDRESS


RTM_IPV4_MASK_FROM_LEN

The RTM_IPV4_MASK_FROM_LEN macro converts a generic route length to an IPv4 mask.

RTM_IPV4_MASK_FROM_LEN(
  Len
);

Parameters

Len
Specifies the generic length to convert.

Return Values

The return value is the size of the subnet mask.

Remarks

For example, if a client supplies the Len 24, the mask 255.255.255.255 is returned.

The macro is defined as follows:

#define RTM_IPV4_MASK_FROM_LEN(Len)                         \
        ((Len) ? htonl(~0 << (32 - (Len))): 0);             \

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.

See Also

RTM_IPV4_GET_ADDR_AND_LEN, RTM_IPV4_GET_ADDR_AND_MASK, RTM_IPV4_LEN_FROM_MASK, RTM_IPV4_MAKE_NET_ADDRESS, RTM_IPV4_SET_ADDR_AND_LEN, RTM_IPV4_SET_ADDR_AND_MASK, RTM_NET_ADDRESS


RTM_IPV4_SET_ADDR_AND_LEN

The RTM_IPV4_SET_ADDR_AND_LEN macro converts an IPv4 address and a length to a generic RTM_NET_ADDRESS structure.

RTM_IPV4_SET_ADDR_AND_LEN(
  NetAddress,
  Addr,
  Len
);

Parameters

NetAddress
Receives the converted address structure.
Addr
Specifies the IPv4 address to convert.
Len
Specifies the length to convert.

Remarks

For example, if a client supplies the Addr 10.10.10.0 and the Len 24, the NetAddress 10.10.10/24 is returned.

The macro is defined as follows:

#define RTM_IPV4_SET_ADDR_AND_LEN(NetAddress, Addr, Len)  \
        (NetAddress)->AddressFamily = AF_INET;            \
        (NetAddress)->NumBits  = (USHORT) (Len);          \
        (* (ULONG *) ((NetAddress)->AddrBits)) = (Addr);  \

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.

See Also

RTM_IPV4_GET_ADDR_AND_LEN, RTM_IPV4_GET_ADDR_AND_MASK, RTM_IPV4_LEN_FROM_MASK, RTM_IPV4_MAKE_NET_ADDRESS, RTM_IPV4_MASK_FROM_LEN, RTM_IPV4_SET_ADDR_AND_MASK, RTM_NET_ADDRESS


RTM_IPV4_SET_ADDR_AND_MASK

The RTM_IPV4_SET_ADDR_AND_MASK macro converts an IPv4 address and mask to a generic RTM_NET_ADDRESS structure.

RTM_IPV4_SET_ADDR_AND_MASK(
  NetAddress,
  Addr,
  Mask
);

Parameters

NetAddress
Receives the converted address structure.
Addr
Specifies the IPv4 address to convert.
Mask
Specifies the IPv4 mask to convert.

Remarks

For example, if a client supplies the Addr 10.10.10.0 and the Mask 255.255.255.255, the NetAddress 10.10.10/24 is returned.

The macro is defined as follows:

#define RTM_IPV4_SET_ADDR_AND_MASK(NetAddress, Addr, Mask)  \
        (NetAddress)->AddressFamily = AF_INET;              \
        (* (ULONG *) ((NetAddress)->AddrBits)) = (Addr);    \
        RTM_IPV4_LEN_FROM_MASK((NetAddress)->NumBits, Mask)

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.

See Also

RTM_IPV4_GET_ADDR_AND_LEN, RTM_IPV4_GET_ADDR_AND_MASK, RTM_IPV4_LEN_FROM_MASK, RTM_IPV4_MAKE_NET_ADDRESS, RTM_IPV4_MASK_FROM_LEN, RTM_IPV4_SET_ADDR_AND_LEN, RTM_NET_ADDRESS


RTM_SIZE_OF_DEST_INFO

The RTM_SIZE_OF_DEST_INFO macro returns the size the destination information structure (RTM_DEST_INFO). The size of this structure is variable, and is based on the number of views for which it contains information. Use this macro when allocating memory for destination information.

ULONG RTM_SIZE_OF_DEST_INFO(
  NumViews
);

Parameters

NumViews
Specifies the number of views in the destination structure.

Return Values

The return value is the size of the destination information structure with the specified number of views.

Remarks

If the client will only use one view per destination, the client can allocate an RTM_DEST_INFO structure statically.

The macro is defined as follows:

#define RTM_BASIC_DEST_INFO_SIZE                            \
    FIELD_OFFSET(RTM_DEST_INFO, ViewInfo)
#define RTM_DEST_VIEW_INFO_SIZE                             \
    (sizeof(RTM_DEST_INFO) - RTM_BASIC_DEST_INFO_SIZE)
#define RTM_SIZE_OF_DEST_INFO(NumViews)                     \
    (RTM_BASIC_DEST_INFO_SIZE + (NumViews) *                \
    RTM_DEST_VIEW_INFO_SIZE)

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.


RTM_SIZE_OF_ROUTE_INFO

The RTM_SIZE_OF_ROUTE_INFO macro returns the size of the route information structure, RTM_ROUTE_INFO. The size of this structure is variable, and is based on the number of next hops associated with the route. Use this macro when allocating memory for route structures.

ULONG RTM_SIZE_OF_ROUTE_INFO(
  NumHops
);

Parameters

NumHops
Specifies the number of next hops in the route structure.

Return Values

The return value is the size of the route information structure with the specified number of next hops.

Remarks

If the client will only allocate one next hop per route, the client can allocate an RTM_ROUTE_INFO structure statically.

The macro is defined as follows:

#define RTM_BASIC_ROUTE_INFO_SIZE                           \
    FIELD_OFFSET(RTM_ROUTE_INFO, NextHopsList.NumNextHops)
#define RTM_SIZE_OF_ROUTE_INFO(NumHops)                     \
    (RTM_BASIC_ROUTE_INFO_SIZE + (NumHops) *                \
     sizeof(RTM_NEXTHOP_HANDLE))

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.


Routing Table Manager Version 2 Constants

The RTMv2 functions use the following constants:

View Flags

Route Flags

Next Hop Flags

Routing Table Query Flags

Enumeration Flags

Change Notification Flags


View Flags

Constant | Value | Description
RTM_MAX _ADDRESS_SIZE | 16 | Max address size for an address family.
RTM_MAX_VIEWS | 32 | Maximum number of views that can be active in the routing table.
RTM_VIEW_ID_UCAST | 0 | Specifies a unicast view.
RTM_VIEW_ID_MCAST | 1 | Specifies a multicast view.
RTM_VIEW_MASK_SIZE | 0x20 | Specifies the maximum number of views that can be configured.
RTM_VIEW_MASK_NONE | 0x00000000 | Return information regardless of the view.
RTM_VIEW_MASK_ANY | 0x00000000 | Return destinations from all views. This is the default value.
RTM_VIEW_MASK_UCAST | 0x00000001 | Return destinations from the unicast view.
RTM_VIEW_MASK_MCAST | 0x00000002 | Return destinations from the multicast view.
RTM_VIEW_MASK_ALL | 0xFFFFFFFF | Return information from all views.


Route Flags

State of the Route Constants

Constant | Value | Description
RTM_ROUTE_STATE_CREATED | 0 | Route has been created.
RTM_ROUTE_STATE_DELETING | 1 | Route is being deleted.
RTM_ROUTE_STATE_DELETED | q | Route has been deleted.

Route Update Flags

Constant | Value | Description
RTM_ROUTE_CHANGE_FIRST | 0x01 | Indicates that the routing table manager should not check the Neighbour member of the RTM_ROUTE_INFO structure when determining when two routes are equal.
RTM_ROUTE_CHANGE_NEW | 0x02 | Returned by the routing table manager to indicate a new route was created.
RTM_ROUTE_CHANGE_BEST | 0x00010000 | Returned by the routing table manager to indicate that the route that was added or updated was the best route, or that because of the change, a new route became the best route.

Unicast Flags

Constant | Value | Description
RTM_ROUTE_FLAGS_LOCAL | 0x0010 | Indicates a destination is on a directly reachable network.
RTM_ROUTE_FLAGS_REMOTE | 0x0020 | Indicates that the destination is not on a directly reachable network.
RTM_ROUTE_FLAGS_MYSELF | 0x0040 | Indicates the destination is one of the router's addresses.

Broadcast and Multicast Flags

Constant | Value | Description
RTM_ROUTE_FLAGS_MCAST | 0x0100 | Indicates that this route is a route to a multicast address.
RTM_ROUTE_FLAGS_LOCAL_MCAST | 0x0200 | Indicates that this route is a route to a local multicast address.
RTM_ROUTE_FLAGS_LIMITED_BC | 0x0400 | Indicates that this route is a limited broadcast address. Packets to this destination should not be forwarded.
RTM_ROUTE_FLAGS_ZEROS_NETBC | 0x1000 | Indicates that the destination matches an interface's "all-zeros" broadcast address. If broadcast forwarding is enabled, packets should be received and resent out all appropriate interfaces.
RTM_ROUTE_FLAGS_ZEROS_SUBNETBC | 0x2000 | Indicates that the destination matches an interface's "all-zeros" subnet broadcast address. If subnet broadcast forwarding is enabled, packets should be received and resent out all appropriate interfaces.
RTM_ROUTE_FLAGS_ONES_NETBC | 0x4000 | Indicates that the destination matches an interface's "all-ones" broadcast address. If broadcast forwarding is enabled, packets should be received and resent out all appropriate interfaces.
RTM_ROUTE_FLAGS_ONES_SUBNETBC | 0x8000 | Indicates that the destination matches an interface's "all-ones" subnet broadcast address. If subnet broadcast forwarding is enabled, packets should be received and resent out all appropriate interfaces.

Grouping of Flags

Group | Members | Description
RTM_ROUTE_FLAGS_FORWARDING | RTM_ROUTE_FLAGS_MARTIAN, RTM_ROUTE_FLAGS_BLACKHOLE, RTM_ROUTE_FLAGS_DISCARD, RTM_ROUTE_FLAGS_INACTIVE | Specifies any forwarding flags.
RTM_ROUTE_FLAGS_ANY_UNICAST | RTM_ROUTE_FLAGS_LOCAL, RTM_ROUTE_FLAGS_REMOTE, RTM_ROUTE_FLAGS_MYSELF | Specifies any unicast flags.
RTM_ROUTE_FLAGS_ANY_MCAST | RTM_ROUTE_FLAGS_MCAST, RTM_ROUTE_FLAGS_LOCAL_MCAST | Specifies any unicast flags.
RTM_ROUTE_FLAGS_SUBNET_BCAST | RTM_ROUTE_FLAGS_ONES_SUBNET_BC, RTM_ROUTE_FLAGS_ZEROS_SUBNETBC | Specifies any subnet broadcast flags.
RTM_ROUTE_FLAGS_NET_BCAST | RTM_ROUTE_FLAGS_ONES_NETBC, RTM_ROUTE_FLAGS_ZEROS_NETBC | Specifies any net-wide broadcast flags.
RTM_ROUTE_FLAGS_ANY_BCAST | RTM_ROUTE_FLAGS_LIMITED_BC, RTM_ROUTE_FLAGS_ONES_NETBC, RTM_ROUTE_FLAGS_ONES_SUBNET_BC, RTM_ROUTE_FLAGS_ZEROS_NETBC, RTM_ROUTE_FLAGS_ZEROS_SUBNETBC | Specifies any of the subnet or net-wide broadcast flags.


Next Hop Flags

Next Hop State Flags

Constant | Value | Description
RTM_NEXTHOP_STATE_CREATED | 0 | Indicates that the next hop was created.
RTM_NEXTHOP_STATE_DELETED | 1 | Indicates that the next hop was deleted.

Next Hop Flags

Constant | Value | Description
RTM_NEXTHOP_FLAGS_REMOTE | 0x0001 | This next hop points to a remote destination that is not directly reachable. To obtain the complete path, the client must perform a recursive lookup.
RTM_NEXTHOP_FLAGS_DOWN | 0x0002 | This flag is reserved for future use.

Next Hop Added

Constant | Value | Description
RTM_NEXTHOP_CHANGE_NEW | 0x01 | A new next hop was created.


Routing Table Query Flags

Constant | Value | Description
RTM_MATCH_NONE | 0x00000000 | Match none of the criteria; all routes for the destination are returned.
RTM_MATCH_OWNER | 0x00000001 | Match routes with same owner.
RTM_MATCH_NEIGHBOUR | 0x00000002 | Match routes with the same neighbor.
RTM_MATCH_PREF | 0x00000004 | Match routes that have the same preference.
RTM_MATCH_NEXTHOP | 0x00000008 | Match routes that have the same next hop.
RTM_MATCH_INTERFACE | 0x00000010 | Match routes that are on the same interface.
RTM_MATCH_FULL | 0x0000FFFF | Match routes with all criteria.
RTM_BEST_PROTOCOL | 0 | Return a route regardless of which protocol owns it.
RTM_THIS_PROTOCOL | ~0 | Returns the best route for the calling protocol.


Enumeration Flags

Constant | Value | Description
RTM_ENUM_START | 0x00000000 | Enumerate routes or destinations starting at 0/0.
RTM_ENUM_NEXT | 0x00000001 | Enumerate routes or destinations starting at the specified address/mask length (such as 10/8). The enumeration continues to the end of the routing table.
RTM_ENUM_RANGE | 0x00000002 | Enumerate routes or destinations in the specified subtree specified by the address/mask length (such as 10/8).
RTM_ENUM_ALL_DESTS | 0x00000000 | Return all destinations.
RTM_ENUM_OWN_DESTS | 0x01000000 | Return only those destinations that the client owns.
RTM_ENUM_ALL_ROUTES | 0x00000000 | Return all routes.
RTM_ENUM_OWN_ROUTES | 0x00010000 | Return only those routes that the client owns.


Change Notification Flags

Constant | Value | Description
RTM_NUM_CHANGE_TYPES | 3 | Specifies the number of change types that are currently used by the routing table manager.
RTM_CHANGE_TYPE_ALL | 0x0001 | Notify the client of any change to a destination.
RTM_CHANGE_TYPE_BEST | 0x0002 | Notify the client of changes to the best route, or when the best route changes.
RTM_CHANGE_TYPE_FORWARDING | 0x0004 | Notify the client of any best route changes that affect forwarding (such as next hop changes).
RTM_NOTIFY_ONLY_MARKED_DESTS | 0x00010000 | Notify the client of changes to destinations that the client has marked. If this flag is not specified, change notification messages for all destinations are sent.


Routing Table Manager Version 2 Enumerations

The RTMv2 functions use the following enumerations:

RTM_EVENT_TYPE


RTM_EVENT_TYPE

Enumerates the events that the routing table manager can notify the client about using the RTM_EVENT_CALLBACK callback.

typedef enum _RTM_EVENT_TYPE {
  RTM_ENTITY_REGISTERED,
  RTM_ENTITY_DEREGISTERED,
  RTM_ROUTE_EXPIRED,
  RTM_CHANGE_NOTIFICATION
} RTM_EVENT_TYPE, *PRTM_EVENT_TYPE;

Values

RTM_ENTITY_REGISTERED
A client has just registered with the routing table manager.
RTM_ENTITY_DEREGISTERED
A client has just unregistered.
RTM_ROUTE_EXPIRED
A route has timed out.
RTM_CHANGE_NOTIFICATION
A change notification has been made.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Rtmv2.h.

See Also

RTM_EVENT_CALLBACK


Routing Table Manager Version 2 Simple Data Types

The RTMv2 API defines several simple data types. The following table lists these data types.

Data type | Description | Typedef
RTM_VIEW_ID, *PRTM_VIEW_ID | Identifies a particular view | INT
DWORD RTM_VIEW_SET, *PRTM_VIEW_SET | Identifies a set of views; expressed as a mask | DWORD
RTM_ENTITY_HANDLE, *PRTM_ENTITY_HANDLE, RTM_DEST_HANDLE, *PRTM_DEST_HANDLE, RTM_ROUTE_HANDLE, *PRTM_ROUTE_HANDLE, RTM_NEXTHOP_HANDLE, *PRTM_NEXTHOP_HANDLE, RTM_ENUM_HANDLE, *PRTM_ENUM_HANDLE, RTM_ROUTE_LIST_HANDLE, *PRTM_ROUTE_LIST_HANDLE, RTM_NOTIFY_HANDLE, *PRTM_NOTIFY_HANDLE | Handles pointing to RTMv2 data | HANDLE
RTM_ENTITY_METHOD_TYPE, *PRTM_ENTITY_METHOD_TYPE | Identifies methods exported by a registered client | DWORD
RTM_ENTITY_EXPORT_METHOD, *PRTM_ENTITY_EXPORT_METHOD | Specifies the common prototype for client methods | _ENTITY_METHOD
RTM_ROUTE_CHANGE_FLAGS, *PRTM_ROUTE_CHANGE_FLAGS | Input and output flags used to specify the state when a route is added or updated | DWORD
RTM_NEXTHOP_CHANGE_FLAGS, *PRTM_NEXTHOP_CHANGE_FLAGS | Output flags used to specify the state when a next hop is added | DWORD
RTM_MATCH_FLAGS, *PRTM_MATCH_FLAGS | Input flags used to specify criteria when matching routes in the routing table | DWORD
RTM_ENUM_FLAGS, *PRTM_ENUM_FLAGS | Identifies enumerations | DWORD
RTM_NOTIFY_FLAGS, *PRTM_NOTIFY_FLAGS | Output flags used to specify which type of notification is being issued; composed as follows: (Change Types | Dests) a client is interested in | DWORD
RTM_EVENT_CALLBACK, *PRTM_EVENT_CALLBACK; | Identifies the callback used to notify clients that a change has occurred in route state or clients registered | RTM_EVENT_CALLBACK


About Multicast Group Manager

This documentation describes the Multicast Group Manager (MGM) technology, a feature of Microsoft® Windows® 2000.

Multicasting allows a host to send data to only those destinations that specifically request to receive the data. In this way, multicasting differs from sending broadcast data, since broadcast data is sent to all hosts.

Multicasting saves network bandwidth because multicast data is only received by those hosts that request the data, and the data travels over any link only once. Multicasting saves server bandwidth because a server has to send only one multicast message per network instead of one unicast message per receiver. Examples of popular multicast applications are online meetings and Internet radio.

The MGM API enables developers to write multicast routing protocols that interoperate with Windows 2000 routers running the multicast group manager.

When more than one multicast routing protocol is enabled on a router, the multicast group manager coordinates operations between all routing protocols. The multicast group manager informs each routing protocol when group membership changes occur, and when multicast data from a new source or destined to a new group is received.

The MGM API provides the following features:

  • Protocol registration
  • Group management
  • Multicast forwarding entry (MFE) enumeration
  • Callback definitions for multicast routing protocols

This overview describes the components of the multicast architecture, the client scenarios that are used to interoperate with the multicast group manager, and programming considerations for using the MGM API.

The multicast group manager is incorporated into Microsoft Windows 2000 as a part of the RRAS technology. It is not available for Microsoft® Windows NT® version 4.0.


Components of the Multicast Architecture

The major components of the multicast routing architecture are explained in the following topics:

  • Router
  • Multicast Routing Protocol
  • Interface
  • Multicast Source
  • Multicast Group
  • (s, g), (*, g), and (*, *) pairs
  • Destination
  • Next Hop
  • Multicast Group Manager Client

The section How the Multicast Architecture Fits Together explains how these components interact.


Router

A router is a Windows NT/Windows 2000 server that is running the RRAS service. Such a server handles data forwarding and runs routing protocols.


Multicast Routing Protocol

A multicast routing protocol is one type of service provider that functions as a client within the framework of the router architecture. The Windows NT/Windows 2000 routing architecture is designed to be extended by such router client modules.

A multicast routing protocol manages group membership and controls the path that multicast data takes over the network. Examples of multicast routing protocols include: Protocol Independent Multicast (PIM), Multicast Open Shortest Path First (MOSPF), and Distance Vector Multicast Routing Protocol (DVMRP). The Internet Group Management Protocol (IGMP) is a special multicast routing protocol that acts as an intermediary between hosts and routers.


Interface

An interface is a logical connection to a network. Each interface is identified by a unique index. Multicast routing protocols (such as MOSPF) deal with all types of interfaces similarly.

In the case of a LAN interface, the interface corresponds to an actual physical device in the computer (the LAN adapter). In the case of a WAN interface, the interface is mapped to a port when a connection is established. WAN interfaces can be based on tunnels and the port could be a virtual private network (VPN) port.

Windows 2000 supports a "point-to-multipoint" interface. This type of interface can be viewed as a collection of point-to-point links that share a single termination point.

To uniquely identify an exact link in a point-to-multipoint interface, the MGM API uses the next hop address of the interface ID. To support this identification, the MGM API uses an extended interface ID, which includes a next hop address.


Multicast Source

A multicast source is the IP address of the host from which the multicast data originated. A source is referred to by either the symbol "S" or "s".


Multicast Group

A multicast group is a Class D IP address (that is, in the range of 224.0.0.0- 239.255.255.255). Multicast data that is sent to an address in this range is not destined for a single target. Instead, this data can be received by any host that makes a request to join a specific group. A multicast group is referred to by either the symbol "G" or "g".


(s, g), (*, g), and (*, *) Pairs

The notation (s, g) represents a specific source and group. Only data from the source "s" and the group "g" is requested.

The notation (*, g) represents a wildcard source and a specific group. All data from any source to the group "g" has been requested.

The notation (*, *) represents a wildcard source and wildcard group. All data from all sources and to all groups has been requested.

These notations are used to describe the addition and removal of group memberships.


Destination

A destination is a host that has joined a multicast group. Such a host has informed the local router, using IGMP, that it is interested in receiving data sent to one or more multicast groups.


Next Hop

A next hop is the next router on the path towards a destination. Packets from a source are forwarded to a destination on a hop-by-hop basis.

The address of the router that is the next hop in a route is used to uniquely identify links on a point-to-multipoint interface, where all the links share the same interface index.


Multicast Group Manager Client

A client is an entity that calls an MGM function, such as a routing protocol or an administrative application.

The MGM API is used primarily by multicast routing protocols. Developers of multicast routing protocols use the MGM API to:

  • Maintain group membership
  • Control interface ownership
  • Receive notifications from the multicast group manager regarding other multicast routing protocols' requests for multicast data

Specific administrative applications that must monitor multicast forwarding entries (MFEs) can do so without adding or removing group membership. Administrative application developers use specific MGM functions to review information in MFEs.

Note Multicast routing protocols also access MFEs.

An MFE is forwarding information that the multicast group manager creates based on group membership. The MFEs that are retrieved from the multicast group manager can provide statistical information. An administrative application can then use this information to determine the appropriate actions. For example, an administrative application could perform actions that are based on the volume of packets on a specific interface.


How the Multicast Architecture Fits Together

This section describes a sample configuration and how the major components fit together.

The following illustration shows the relationship between the various components of a Windows 2000 router.

The multicast group manager is a part of the RRAS service that runs on a Windows 2000 server that is operating as a router.

The router shown has three multicast routing protocols (Protocol 1, Protocol 2, Protocol 3) running on it. Each protocol can own one or more interfaces (in this illustration, Protocol 1 owns Interface 1, Protocol 2 owns Interface 2, and Protocol 3 owns Interface 3). Each interface can be owned by only one routing protocol (in addition to IGMP, which is a special case).

The multicast group manager runs on the router and coordinates the distribution of group information between the routing protocols.

The following illustration shows the relationship between two routers in a multicast architecture.

In the previous illustration, Router 2 sends a multicast message to Network 2 on Interface 3. Router 1 receives the multicast message from Network 2 on Interface 3. On both routers, Protocol 3 owns the respective Interface 3.

The following illustration shows the path a message from a multicast source (to a multicast group) takes to reach the host that has joined the multicast group. The routers in the illustration use the same configuration as previous illustrations; however, the interface and protocol details are not shown in order to keep the figure simple.

The following scenario describes the events that take place when a host joins a multicast group. Refer to the previous illustration for relationships between the various entities.

  1. Host 1 joins the multicast group G on Network 3.
  2. Router 3 learns about G via IGMP.
  3. The multicast group manager on Router 3 notifies Protocol 3 on Router 3 that there are new receivers for G.
  4. Protocol 3 on Router 3 then notifies Protocol 3 on Router 1 about G.
  5. In turn, Protocol 3 on Router 1 notifies the multicast group manager on Router 1 about G.
  6. The multicast group manager on Router 1 then notifies Protocol 1 and Protocol 2 about G.
  7. Protocol 2 may inform Router 2 about G, if the protocol is designed to do so.

The following scenario describes the events that take place when a message is sent to a multicast group. Refer to the previous illustration for the relationships between the various entities.

  1. A source on Network 1 sends a message to Group G.
  2. The message sent from Source S goes first to Router 2, which then forwards it to Router 1 using Interface 2 (since Router 2 has been informed by Protocol 2 that receivers are present downstream).
  3. Router 1 forwards the message to Router 3 (since Router 1 has been informed by Protocol 2 that receivers are present downstream).
  4. Router 3 forwards the message to Network 3, and therefore it arrives at Host 1.

For further information on multicast routing protocol interaction, see RFC 2715, Interoperability Rules for Multicast Routing Protocols.


Overview of MGM Callbacks

There are two types of callbacks in the MGM API:

  • Routing Protocol Callbacks
  • IGMP Enable and Disable Callbacks

These callbacks, combined with the MGM APIs, enable the ongoing communication between routing protocols, IGMP, and the multicast group manager.


Routing Protocol Callbacks

The following topics describe the calls into routing protocols made by the multicast group manager.

  • Join Alert Callbacks
  • Prune Alert Callbacks
  • Local Join Callbacks
  • Local Leave Callbacks
  • Wrong Interface Alert Callbacks
  • RPF Alert Callbacks


Join Alert Callbacks

When the multicast group manager is notified that there are new receivers present for a group on an interface, the multicast group manager invokes the PMGM_JOIN_ALERT_CALLBACK callback. This callback notifies the routing protocols that new hosts have joined the specified groups . Therefore, the routing protocols must request multicast data for the groups specified by the callback.

The multicast group manager uses a predefined set of rules that are used to determine when this callback is invoked. This set of rules is based on both the type of join request sent by the client and the order the join requests were received in.

Wildcard Join Requests

When a wildcard join for a group (*, g) is received from the first client, the multicast group manager invokes the PMGM_JOIN_ALERT_CALLBACK callback to all other registered clients. When a wildcard join for a group is received from the second client, the multicast group manager invokes this callback to the first client to join the group.

Source-Specific Join Requests

The multicast group manager does not invoke this callback for any subsequent joins to the group.

When a source-specific join for a group (s, g) is received, the multicast group manager invokes the PMGM_JOIN_ALERT_CALLBACK callback only for the client that owns the incoming interface towards the source "s".


Prune Alert Callbacks

When the multicast group manager is notified that receivers are leaving a group on an interface, the multicast group manager invokes the PMGM_PRUNE_ALERT_CALLBACK callback. This callback notifies the routing protocols that clients no longer belong to the specified group. Therefore, the routing protocols must stop requesting multicast data for the specified groups.

The multicast group manager has a predefined set of rules that are used to determine when this callback is invoked. These rules are based on both the type of prune request sent by the client and the order the prune requests were received in.

Wildcard Prune Requests

When a wildcard prune for a group (*, g) is received and the final interface is being removed for the second-to-last client (that is, when interfaces for only a single client remain), the multicast group manager invokes the PMGM_PRUNE_ALERT_CALLBACK callback to that remaining client. After the final interface is removed for the last client (that is, when no other interfaces remain), then this callback is invoked for all the other clients that are registered with the multicast group manager.

Source-Specific Prune Requests

When a source-specific prune for a group (s, g) is received, the multicast group manager invokes the PMGM_PRUNE_ALERT_CALLBACK callback only for the client that owns the incoming interface towards the source "s".


Local Join Callbacks

After the multicast group manager is notified by IGMP that new receivers are present for a group on an interface, the multicast group manager invokes the PMGM_LOCAL_JOIN_CALLBACK callback to the routing protocol that owns the interface if one exists. This callback notifies the routing protocol of the change.

This callback and the PMGM_LOCAL_LEAVE_CALLBACK callback are used to synchronize forwarding between IGMP and routing protocols.


Local Leave Callbacks

After the multicast group manager is notified by IGMP that there are no more receivers present for a group on an interface, the multicast group manager invokes the PMGM_LOCAL_LEAVE_CALLBACK callback to the routing protocol on that interface if one exists. This callback notifies the routing protocol of the change.

This callback and the PMGM_LOCAL_JOIN_CALLBACK callback are used to synchronize forwarding between IGMP and routing protocols.


Wrong Interface Alert Callbacks

After the kernel forwarder receives multicast data from a specific source on the wrong interface, it notifies the multicast group manager. The multicast group manager then invokes the PMGM_WRONG_IF_CALLBACK callback to the routing protocol that owns the interface on which the data incorrectly arrived.

Note This callback is not currently implemented in this version of the MGM API.


RPF Alert Callbacks

After the multicast group manager receives notification of a packet from a new source or of a packet that is destined for a new group, the multicast group manager looks up the route to the source in the multicast view of the routing table. The multicast group manager then invokes the PMGM_RPF_CALLBACK callback to the protocol that owns the interface the data arrived on.

After this callback is invoked, the routing protocol can change the incoming interface if the routing protocol must receive the data for the group on a different interface.


IGMP Enable and Disable Callbacks

The multicast group manager uses two callbacks to IGMP to coordinate changes in interface ownership from IGMP to a routing protocol, and from a routing protocol to IGMP. The callbacks enable IGMP to coexist on an interface with another routing protocol (such as DVMRP).

After the ownership of an interface changes, the multicast group manager first invokes the PMGM_DISABLE_IGMP_CALLBACK callback. IGMP must stop adding and deleting group memberships on the specified interface until the multicast group manager invokes the PMGM_ENABLE_IGMP_CALLBACK callback.

The multicast group manager invokes the PMGM_ENABLE_IGMP_CALLBACK callback after the change of interface ownership is complete.


Using the Multicast Group Manager

This section discusses the following topics:

  • MGM Programming Considerations
  • Multicast Routing Protocol Scenario
  • Administrative Application Scenario


MGM Considerations Issues

Platform SDK: RAS/Routing and RAS

MGM Programming Considerations

When you are developing multicast group manager clients, observe the following guidelines:

  • Function calls must be made from within the router process. If functions are called from another process, their results will not be valid; the client will not interact with the multicast group manager.
  • Clients that use the MGM API must provide their own error checking, ensuring that only valid data is passed to the multicast group manager. MGM functions do not return detailed error messages about invalid parameters; the ERROR_INVALID_PARAMETER value is returned without explanation.
  • Clients should exercise caution in using locks while calling MGM functions. Doing so can prevent deadlocks. When calling MGM functions, clients should not hold any locks that might simultaneously be held in a callback from the multicast group manager.


Multicast Routing Protocol Scenario

All multicast routing protocols go through three basic phases: startup, operation, and shutdown. The following topics outline a basic set of interactions between a multicast routing protocol and the multicast group manager:

  • Starting Up a Multicast Routing Protocol
  • Processing Groups and Callbacks
  • Enumerating Groups
  • Shutting Down a Multicast Routing Protocol


Starting Up a Multicast Routing Protocol

The following table summarizes a series of steps in a startup interaction between a routing protocol and the multicast group manager. The first column describes actions that the routing protocol performs and the responses of the routing protocol to the multicast group manager. The second column describes the multicast group manager's responses to the routing protocol and any actions the multicast group manager performs such as callbacks. The third column presents any additional information.

Each row of the table represents one step.

Routing protocol action | Multicast group manager action | Notes
Register with the multicast group manager using the MgmRegisterMProtocol function. | Return to the routing protocol a handle that the protocol must use to identify itself in subsequent MGM API calls. |
Determine if an interface is already owned, and the routing protocol that owns it using the MgmGetProtocolOnInterface function. |  | IGMP can use this function to determine the owner of an interface, and perform protocol-specific processing with the information returned by this function.
Take ownership of all the interfaces on which the protocol is enabled using the MgmTakeInterfaceOwnership function. | If IGMP has already taken ownership of an interface and the MgmTakeInterfaceOwnership function call is received for the same interface, contact IGMP using the PMGM_DISABLE_IGMP_CALLBACK callback. Once all changes to multicast data regarding interface ownership have been made, contact IGMP again using PMGM_ENABLE_IGMP_CALLBACK. | Only one protocol can own an interface at a given time, in addition to IGMP.
Determine the current state of group membership on the router. This action is performed using the group membership enumeration functions: MgmGroupEnumerationStart, MgmGroupEnumerationGetNext, and MgmGroupEnumerationEnd. | Return the list of groups. | Routing protocols can use the results to determine what actions to take based on the groups that have already been joined. See Enumerating Groups for a complete example of using these functions.


Processing Groups and Callbacks

The following table summarizes a series of steps in an operational interaction between a routing protocol and the multicast group manager. The first column describes the actions that the routing protocol performs and the routing protocol's responses to the multicast group manager. The second column describes the multicast group manager's responses to the routing protocol and any actions the multicast group manager performs such as callbacks. The third column presents any additional information.

Each row of the table represents one step.

The tasks listed in this table do not occur in any specific order; rather, they occur based on the status of multicast group memberships. The table below shows an example order.

Routing protocol action | Multicast group manager action | Notes
Manage group memberships based on protocol information received on those interfaces that the protocol owns. Management is performed using the following functions: MgmAddGroupMembershipEntry and MgmDeleteGroupMembershipEntry. | Add to and delete from the outgoing interface list for the specified (s, g), (*, g), and (*, *) entries. This list represents the set of interfaces on which data for this group is forwarded. The data for this group is from the specified source. |
 | Send alerts to routing protocols in the form of callbacks. The following events trigger the multicast group manager to invoke a callback: Join or leave groups (PMGM_JOIN_ALERT_CALLBACK, PMGM_PRUNE_ALERT_CALLBACK) Group membership changed by IGMP (PMGM_LOCAL_JOIN_CALLBACK, PMGM_LOCAL_LEAVE_CALLBACK) Data received on wrong interface (PMGM_WRONG_IF_CALLBACK) Data received from new sources or to a new group (PMGM_CREATION_ALERT_CALLBACK and PMGM_RPF_CALLBACK). | Using these callbacks, the multicast group manager is able to coordinate packet forwarding when several multicast routing protocols are present on a router.
Enumerate the multicast forwarding entries (MFEs), using the MgmGetFirstMfe, MgmGetNextMfe, and MgmGetMfe functions. Make decisions about multicast data based on the results of the enumeration. | Return the requested MFEs. Return ERROR_NO_MORE ITEMS when there are no more MFEs to return. | Use the MgmGetFirstMfeStats, MgmGetNextMfeStats, MgmGetMfeStats functions to enumerate MFE statistics. See Administrative Application Scenario for a complete example of using these functions.
Modify the upstream neighbor in an MFE using the MgmSetMfe function. |  | Clients use this function to modify the information regarding the incoming interface.


Enumerating Groups

The following table summarizes a series of steps in an interaction between a routing protocol and the multicast group manager. The first column describes the actions that the routing protocol performs and the routing protocol's responses to the multicast group manager. The second column describes the multicast group manager's responses to the routing protocol. The third column presents any additional information.

Each row of the table represents one step.

Routing protocol action | Multicast group manager action | Notes
Obtain a handle to an enumeration using the MgmGroupEnumerationStart function. | Return a handle. |
Obtain one or more groups using the MgmGroupEnumerationGetNext function. | Return as many groups as fit in the buffer supplied by the client. If no groups can be returned in the supplied buffer, return ERROR_INSUFFICIENT_BUFFER and the size of the buffer that is needed to return one group. Return ERROR_NO_MORE_ITEMS when there are no more groups. |
If ERROR_INSUFFICIENT_BUFFER is received, call the MgmGroupEnumerationGetNext function again using a buffer of the size indicated. |  |
Continue calling the MgmGroupEnumerationGetNext function until ERROR_NO_MORE_ITEMS is received. |  |
End the enumeration process using the MgmGroupEnumerationEnd function. | Destroy the handle. |


Shutting Down a Multicast Routing Protocol

The following table summarizes a series of steps in a shutdown interaction between the multicast group manager and the routing protocol when the routing protocol is shutting down. The first column describes the actions that the routing protocol performs and the routing protocol's responses to the multicast group manager. The second column describes the multicast group manager's responses to the routing protocol and any actions the multicast group manager performs such as callbacks. The third column presents any additional information.

Each row of the table represents one step.

Routing protocol action | Multicast group manager action | Notes
Release ownership of each interface that the routing protocol owns using the MgmReleaseInterfaceOwnership function. | If IGMP is also running on the interface that was just released by a routing protocol, contact IGMP using the PMGM_DISABLE_IGMP_CALLBACK callback. Once all changes to multicast data regarding interface ownership have been made, contact IGMP again using PMGM_ENABLE_IGMP_CALLBACK callback. Delete all the forwarding entries associated with this interface. |
Deregister with the multicast group manager using the MgmDeRegisterMProtocol function. | Destroy the handle that was returned to the routing protocol by a previous call to the MgmDeRegisterMProtocol function. | The routing protocol can no longer use this handle to call MGM functions.


Administrative Application Scenario

Administrative applications call a subset of MGM functions that are related to enumerating multicast forwarding entries (MFEs) and MFE statistics. An application does not need to register with the multicast group manager to use these functions (that is, the application does not need a handle).

Enumerating MFEs

The following table summarizes a series of steps in an interactions between an administrative application and the multicast group manager. The first column describes the actions that the administrative application performs and the administrative application's responses to the multicast group manager. The second column describes the multicast group manager's responses to the administrative application. The third column presents any additional information.

Each row of the table represents one step.

Administrative application action | Multicast group manager action | Notes
Obtain one or more MFEs using the MgmGetFirstMfe function. | Return as many MFEs as fit in the buffer supplied by the client. If no MFEs can be returned in the supplied buffer, return ERROR_INSUFFICIENT_BUFFER and the size of the buffer that is needed to return one MFE. | Clients can also retrieve MFE statistics using the corresponding statistics functions, MgmGetFirstMfeStats and MgmGetNextMfeStats.
If ERROR_INSUFFICIENT_BUFFER is received, call the MgmGetFirstMfe function again using a buffer of the size indicated. |  |
Continue calling the MgmGetNextMfe function, supplying as one of the parameters the last MFE that was returned by the previous call to the MgmGetFirstMfe function. | Return as many MFEs as fit in the buffer supplied by the client. If no MFEs can be returned in the supplied buffer, return ERROR_INSUFFICIENT_BUFFER and the size of the buffer that is needed for one MFE. Return ERROR_NO_MORE_ITEMS when no more MFEs remain. |
Continue the enumeration until ERROR_NO_MORE_ITEMS is received. |  |

Note Use the MgmGetMfe and MgmGetMfeStats functions to retrieve a specific MFE or specific set of MFE statistics.


Multicast Group Manager Reference

The following documentation describes the functions, callbacks, structures, and enumeration types to use when working with the multicast group manager:

  • Multicast Group Manager Functions
  • Multicast Group Manager Callbacks
  • Multicast Group Manager Structures
  • Multicast Group Manager Enumerations


Multicast Group Manager Functions

The following functions are used to register with the multicast group manager:

MgmRegisterMProtocol

MgmDeRegisterMProtocol

The following functions are used to manage interface ownership:

MgmGetProtocolOnInterface

MgmTakeInterfaceOwnership

MgmReleaseInterfaceOwnership

The following functions are used to manage group membership:

MgmAddGroupMembershipEntry

MgmDeleteGroupMembershipEntry

The following functions are used to obtain multicast forwarding entries (MFEs) and MFE statistics:

MgmGetFirstMfe

MgmGetNextMfe

MgmGetMfe

MgmGetFirstMfeStats

MgmGetNextMfeStats

MgmGetMfeStats

The following function is used to modify MFEs:

MgmSetMfe

The following functions are used obtain a list of groups that have been joined:

MgmGroupEnumerationStart

MgmGroupEnumerationGetNext

MgmGroupEnumerationEnd


MgmAddGroupMembershipEntry

The MgmAddGroupMembershipEntry function notifies the multicast group manager that there are new receivers for the specified groups on the specified interface. The receivers can restrict the set of sources from which they should receive multicast data by specifying a source range.

A multicast routing protocol calls this function when it is notified that there are receivers for a multicast group on an interface. The protocol must call this function so that multicast data can be forwarded out over an interface.

DWORD MgmAddGroupMembershipEntry(
  HANDLE hProtocol,
  DWORD dwSourceAddr,
  DWORD dwSourceMask,
  DWORD dwGroupAddr,
  DWORD dwGroupMask,
  DWORD dwIfIndex,
  DWORD dwIfNextHopIPAddr,
  DWORD dwFlags
);

Parameters

hProtocol
[in] Handle to the protocol obtained from a previous call to MgmRegisterMProtocol.
dwSourceAddr
[in] Specifies the source address from which to receive multicast data. Specify zero to receive data from all sources (a wildcard receiver for a group); otherwise, specify the IP address of the source or source network.

To specify a range of source addresses, specify the source network using dwSourceAddr, and specify a subnet mask using dwSourceMask.

dwSourceMask
[in] Specifies the subnet mask that corresponds to dwSourceAddr. The dwSourceAddr and dwSourceMask parameters are used together to define a range of sources from which to receive multicast data.

Specify zero for this parameter if zero was specified for dwSourceAddr (a wildcard receiver).

dwGroupAddr
[in] Specifies the multicast group for which to receive data. Specify zero to receive all groups (a wildcard receiver); otherwise, specify the IP address of the group.

To specify a range of group addresses, specify the group address using dwGroupAddr, and specify a subnet mask using dwGroupMask.

dwGroupMask
[in] Specifies the subnet mask that corresponds to dwGroupAddr. The dwGroupAddr and dwGroupMask parameters are used together to define a range of multicast groups.

Specify zero for this parameter if zero was specified for dwGroupAddr (a wildcard receiver).

dwIfIndex
[in] Specifies the interface on which to add the group membership. Multicast data for the specified groups will be forwarded out over this interface.
dwIfNextHopIPAddr
[in] Specifies the address of the next hop that corresponds to the index specified by dwIfIndex. The dwIfIndex and dwIfNextHopIPAddr parameters uniquely identify a next hop on point-to-multipoint interfaces. A point-to-multipoint interface is a connection where one interface connects to multiple networks. Examples of point-to-multipoint interfaces include non-broadcast multiple access (NBMA) interfaces and the internal interface on which all dial-up clients connect.

For broadcast interfaces (such as Ethernet interfaces) or point-to-point interfaces, which are identified by only the value of dwIfIndex, specify zero.

dwFlags
[in] Specifies any additional processing that must take place when the group membership is added. Valid values are:
Value | Meaning
MGM_JOIN_STATE_FLAG | Add group membership for the specified source and group. Update any forwarding entries for the specified source group to reflect this change in group membership.
MGM_FORWARD_STATE | Add the specified interface to the list of outgoing interfaces for the forwarding entry that corresponds to the specified source and group.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_CAN_NOT_COMPLETE | Could not complete the call to this function.
ERROR_INVALID_PARAMETER | Invalid handle to the protocol.
ERROR_NOT_ENOUGH_MEMORY | Not enough memory to complete this operation.

Remarks

This version of the MGM API supports only wildcard sources or specific sources, not a range of sources. The same restriction applies to groups, that is, no group ranges are permitted.

When this function is called, the multicast group manager may invoke the PMGM_JOIN_ALERT_CALLBACK callback to notify other routing protocols that there are new receivers for the specified group.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.
Library: Use Rtm.lib.

See Also

MgmDeleteGroupMembershipEntry, PMGM_JOIN_ALERT_CALLBACK


MgmDeleteGroupMembershipEntry

The MgmDeleteGroupMembershipEntry function notifies the multicast group manager that there are no more receivers present for the specified groups on the specified interface.

A multicast routing protocol calls this function after it is notified that there are no more receivers for a multicast group on an interface. The protocol must call this function to stop multicast data from being forwarded out over an interface.

DWORD MgmDeleteGroupMembershipEntry(
  HANDLE hProtocol,
  DWORD dwSourceAddr,
  DWORD dwSourceMask,
  DWORD dwGroupAddr,
  DWORD dwGroupMask,
  DWORD dwIfIndex,
  DWORD dwIfNextHopIPAddr,
  DWORD dwFlags
);

Parameters

hProtocol
[in] Handle to the protocol obtained from a previous call to MgmRegisterMProtocol.
dwSourceAddr
[in] Specifies the source address from which to stop receiving multicast data. Specify zero to stop receiving data from all sources (a wildcard receiver for a group); otherwise, specify the IP address of the source or source network.

To specify a range of source addresses, specify the source network using dwSourceAddr, and specify a subnet mask using dwSourceMask.

dwSourceMask
[in] Specifies the subnet mask that corresponds to dwSourceAddr. The dwSourceAddr and dwSourceMask parameters are used together to define a range of sources from which to stop receiving multicast data.

Specify zero for this parameter if zero was specified for dwSourceAddr (a wildcard receiver).

dwGroupAddr
[in] Specifies the multicast group for which to stop receiving data. Specify zero to stop receiving all groups (a wildcard receiver); otherwise, specify the IP address of the group.

To specify a range of group addresses, specify the group address using dwGroupAddr, and specify a subnet mask using dwGroupMask.

dwGroupMask
[in] Specifies the subnet mask that corresponds to dwGroupAddr. The dwGroupAddr and dwGroupMask parameters are used together to define a range of multicast groups.

Specify zero for this parameter if zero was specified for dwGroupAddr (a wildcard receiver).

dwIfIndex
[in] Specifies the interface on which to delete the group membership. Multicast data for the specified groups will no longer be forwarded out over this interface.
dwIfNextHopIPAddr
[in] Specifies the address of the next hop that corresponds to the index specified by dwIfIndex. The dwIfIndex and dwIfNextHopIPAddr parameters uniquely identify a next hop on point-to-multipoint interfaces. A point-to-multipoint interface is a connection where one interface connects to multiple networks. Examples of point-to-multipoint interfaces include non-broadcast multiple access (NBMA) interfaces and the internal interface on which all dial-up clients connect.

For broadcast interfaces (such as Ethernet interfaces) or point-to-point interfaces, which are identified by only the value of dwIfIndex, specify zero.

dwFlags
[in] Specifies any additional processing that must take place when the group membership is removed. Valid values are:
Value | Meaning
MGM_JOIN_STATE_FLAG | Remove group membership for the specified source and group. Update any forwarding entries for the specified source group to reflect this change in group membership.
MGM_FORWARD_STATE | Remove the specified interface from the list of outgoing interfaces for the forwarding entry that corresponds to the specified source and group.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_CAN_NOT_COMPLETE | Could not complete the call to this function.
ERROR_INVALID_PARAMETER | Invalid handle to a protocol, or the interface is owned by another protocol.
ERROR_NOT_FOUND | The specified interface was not found.

Remarks

This version of the MGM API supports only wildcard sources or specific sources, not a range of sources. The same restriction applies to groups (that is, no group ranges are permitted).

When this function is called, the multicast group manager may invoke the PMGM_PRUNE_ALERT_CALLBACK callback to notify other routing protocols that no more receivers are present for the specified group.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.
Library: Use Rtm.lib.

See Also

MgmAddGroupMembershipEntry, PMGM_PRUNE_ALERT_CALLBACK


MgmDeRegisterMProtocol

The MgmDeRegisterMProtocol function deregisters a client handle obtained from a call to MgmRegisterMProtocol.

DWORD MgmDeRegisterMProtocol(
  HANDLE hProtocol
);

Parameters

hProtocol
[in] Handle to the protocol obtained from a previous call to MgmRegisterMProtocol.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_CAN_NOT_COMPLETE | Could not complete the call to this function. The client did not first release the interfaces it owns.
ERROR_INVALID_PARAMETER | Invalid handle to a client.

Remarks

A multicast routing protocol must not call this function until it has released ownership of all the interfaces the protocol owns by calling MgmReleaseInterfaceOwnership.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.
Library: Use Rtm.lib.

See Also

MgmRegisterMProtocol, MgmReleaseInterfaceOwnership


MgmGetFirstMfe

The MgmGetFirstMfe function retrieves MFEs starting at the beginning of the MFE list. The function can retrieve zero, one, or more MFEs. The number of MFEs returned depends on the size of the MFEs and the size of the buffer supplied by the client when the function is called.

The data returned in the buffer is ordered first by group, and then by the sources within a group.

DWORD MgmGetFirstMfe(
  PDWORD pdwBufferSize,
  PBYTE pbBuffer,
  PDWORD pdwNumEntries
);

Parameters

pdwBufferSize
[in, out] On input, pdwBufferSize is a pointer to a DWORD-sized memory location containing the size, in bytes, of pbBuffer.

On output, if the return value is ERROR_INSUFFICIENT_BUFFER, pdwBufferSize receives the minimum size pbBuffer must be to hold the MFE; otherwise, the value of pdwBufferSize remains unchanged.

pbBuffer
[in, out] On input, the client must supply a pointer to a buffer.

On output, pbBuffer contains one or more MFEs. Each MFE is a MIB_IPMCAST_MFE structure.

pdwNumEntries
[in, out] On input, the client must supply a pointer to a DWORD-sized memory location.

On output, pdwNumEntries receives the number of MFEs contained in pbBuffer.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_CAN_NOT_COMPLETE | Could not complete the call to this function.
ERROR_INSUFFICIENT_BUFFER | The specified buffer is too small for even one MFE. The client should check the value of pdwBufferSize for the minimum buffer size required to retrieve one MFE.
ERROR_MORE_DATA | More MFEs are available.
ERROR_NO_MORE_ITEMS | No more MFEs are available. Zero or more MFEs were returned; check the value of pdwNumEntries to verify how many MFEs were returned.

Remarks

This function is used to begin sequential retrieval of MFEs; use MgmGetNextMfe to continue the retrieval process.

In general, to retrieve MFEs, first call MgmGetFirstMfe. Then, call MgmGetNextMfe one or more times, until there are no more MFEs to return. Each call to MgmGetNextMfe should begin after the last MFE returned by the previous call to MgmGetNextMfe (or the initial call to MgmGetFirstMfe). To do this, the client specifies the last source and group in the buffer returned by a previous call.

Note The minimum size of the buffer pointed to by pbBuffer is not fixed; it is different for each MFE. Use the SIZEOF_MIB_MFE macro to determine the size of each MFE returned in the buffer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.
Library: Use Rtm.lib.

See Also

MgmGetMfe, MgmGetNextMfe, MIB_IPMCAST_MFE, SIZEOF_MIB_MFE


MgmGetFirstMfeStats

The MgmGetFirstMfeStats function retrieves MFE statistics starting at the beginning of the MFE list. The function can retrieve zero, one, or more sets of MFE statistics. The number of sets returned depends on the size of the entries and the size of the buffer supplied by the client when the function is called.

The data returned in the buffer is ordered first by group, and then by the sources within a group. The statistics returned include the packets received, bytes received, and packets forwarded on each outgoing interface.

DWORD MgmGetFirstMfeStats(
  PDWORD pdwBufferSize,
  PBYTE pbBuffer,
  PDWORD pdwNumEntries
);

Parameters

pdwBufferSize
[in, out] On input, pdwBufferSize is a pointer to a DWORD-sized memory location containing the size, in bytes, of pbBuffer.

On output, if the return value is ERROR_INSUFFICIENT_BUFFER, pdwBufferSize receives the minimum size pbBuffer must be to hold a set of MFE statistics; otherwise, the value of pdwBufferSize remains unchanged.

pbBuffer
[in, out] On input, the client must supply a pointer to a buffer.

On output, pbBuffer contains one or more sets of MFE statistics. Each set of MFE statistics is a MIB_IPMCAST_MFE_STATS structure.

pdwNumEntries
[in, out] On input, the client must supply a pointer to a DWORD-sized memory location.

On output, pdwNumEntries receives the number of sets of MFE statistics contained in pbBuffer.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_CAN_NOT_COMPLETE | Could not complete the call to this function.
ERROR_INSUFFICIENT_BUFFER | The specified buffer is too small for even one set of MFE statistics. The client should check the value of pdwBufferSize for the minimum buffer size required to retrieve one set of statistics.
ERROR_MORE_DATA | More MFE statistics are available.
ERROR_NO_MORE_ITEMS | No more MFE statistics are available. Zero or more sets of MFE statistics were returned; check the value of pdwNumEntries to verify how many sets of statistics were returned.

Remarks

This function is used to begin sequential retrieval of MFE statistics; use MgmGetNextMfeStats to continue the retrieval process.

In general, to retrieve MFE statistics, first call MgmGetFirstMfeStats. Then, call MgmGetNextMfeStats one or more times, until there are no more MFEs to return. Each call to MgmGetNextMfeStats should begin after the last MFE returned by the previous call to MgmGetNextMfeStats (or the initial call to MgmGetFirstMfeStats) To do this, the client specifies the last source and group in the buffer returned by a previous call.

Note The minimum size of the buffer pointed to by pbBuffer is not fixed; it is different for each set of MFE statistics. Use the SIZEOF_MIB_MFE_STATS macro to determine the size of each set of statistics returned in the buffer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.
Library: Use Rtm.lib.

See Also

MgmGetMfeStats, MgmGetNextMfeStats, MIB_IPMCAST_MFE_STATS, SIZEOF_MIB_MFE_STATS


MgmGetMfe

The MgmGetMfe function retrieves a specific MFE.

DWORD MgmGetMfe(
  PMIB_IPMCAST_MFE pimm,
  PDWORD pdwBufferSize,
  PBYTE pbBuffer
);

Parameters

pimm
[in] Pointer to a MIB_IPMCAST_MFE structure that specifies the MFE to retrieve. The information to be returned is indicated by the dwSource and dwGroup members of the MIB_IPMCAST_MFE structure.
pdwBufferSize
[in, out] On input, pdwBufferSize is a pointer to a DWORD-sized memory location that contains the size, in bytes, of the buffer pointed to by pbBuffer.

On output, if the return value is ERROR_INSUFFICIENT_BUFFER, pdwBufferSize receives the minimum size the buffer pointed to by pbBuffer must be to hold the MFE; otherwise the value of pdwBufferSize remains unchanged.

pbBuffer
[in, out] On input, the client must supply a pointer to a buffer.

On output, pbBuffer contains the specified MFE. The MFE is a MIB_IPMCAST_MFE structure.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_CAN_NOT_COMPLETE | Could not complete the call to this function.
ERROR_INSUFFICIENT_BUFFER | The specified buffer is too small to hold the MFE. The client should check the value of pdwBufferSize for the minimum buffer size required to retrieve the MFE.
ERROR_NOT_FOUND | The specified MFE was not found.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.
Library: Use Rtm.lib.

See Also

MgmGetFirstMfe, MgmGetNextMfe, MIB_IPMCAST_MFE


MgmGetMfeStats

The MgmGetMfeStats function retrieves the statistics for a specific MFE. The statistics returned include the packets received, bytes received, and the packets forwarded on each outgoing interface.

DWORD MgmGetMfeStats(
  PMIB_IPMCAST_MFE pimm,
  PDWORD pdwBufferSize,
  PBYTE pbBuffer
);

Parameters

pimm
[in] Pointer to a MIB_IPMCAST_MFE structure that specifies the MFE for which to retrieve statistics. The information to be returned is indicated by the dwSource and dwGroup members of the MIB_IPMCAST_MFE structure.
pdwBufferSize
[in, out] On input, pdwBufferSize is a pointer to a DWORD-sized memory location that contains the size, in bytes, of the buffer pointed to by pbBuffer.

On output, if the return value is ERROR_INSUFFICIENT_BUFFER, pdwBufferSize receives the minimum size the buffer pointed to by pbBuffer must be to hold the set of MFE statistics; otherwise the value of pdwBufferSize remains unchanged.

pbBuffer
[in, out] On input, the client must supply a pointer to a buffer.

On output, pbBuffer contains the specifies set of MFE statistics. The MFE statistics is a MIB_IPMCAST_MFE_STATS structure.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_CAN_NOT_COMPLETE | Could not complete the call to this function.
ERROR_INSUFFICIENT_BUFFER | The specified buffer is too small for the statistics for even one MFE. The client should check the value of pdwBufferSize for the minimum buffer size required to retrieve statistics for one MFE.
ERROR_NOT_FOUND | The specified MFE was not found.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.
Library: Use Rtm.lib.

See Also

MgmGetFirstMfeStats, MgmGetNextMfeStats, MIB_IPMCAST_MFE_STATS


MgmGetNextMfe

The MgmGetNextMfe function retrieves one or more MFEs. The routing table manager starts retrieving MFEs starting with the MFE that follows the specified MFE. The function can retrieve zero, one, or more MFEs. The number of MFEs returned depends on the size of the MFEs and the size of the buffer supplied by the client when the function is called.

The data returned in the buffer is ordered first by group, and then by the sources within a group.

DWORD MgmGetNextMfe(
  PMIB_IPMCAST_MFE pimmStart,
  PDWORD pdwBufferSize,
  PBYTE pbBuffer,
  PDWORD pdwNumEntries
);

Parameters

pimmStart
[in] Pointer to a MIB_IPMCAST_MFE structure that specifies from where to begin retrieving MFEs. The dwSource and dwGroup members of the MIB_IPMCAST_MFE structure identify an MFE. Specify the source and group of the last MFE that was returned by the previous call to MgmGetFirstMfe or MgmGetNextMfe.
pdwBufferSize
[in, out] On input, pdwBufferSize is a pointer to a DWORD-sized memory location containing the size, in bytes, of pbBuffer.

On output, if the return value is ERROR_INSUFFICIENT_BUFFER, pdwBufferSize receives the minimum size pbBuffer must be to hold the MFE; otherwise, the value of pdwBufferSize remains unchanged.

pbBuffer
[in, out] On input, the client must supply a pointer to a buffer.

On output, pbBuffer contains one or more MFEs. Each MFE is a MIB_IPMCAST_MFE structure.

pdwNumEntries
[in, out] On input, the client must supply a pointer to a DWORD-sized memory location.

On output, pdwNumEntries receives the number of MFEs contained in pbBuffer.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_CAN_NOT_COMPLETE | Could not complete the call to this function.
ERROR_INSUFFICIENT_BUFFER | The specified buffer is too small for even one MFE. The client should check the value of pdwBufferSize for the minimum buffer size required to retrieve one MFE.
ERROR_MORE_DATA | More MFEs are available.
ERROR_NO_MORE_ITEMS | No more MFEs are available. Zero or more MFEs were returned; check the value of pdwNumEntries to verify how many MFEs were returned.

Remarks

This function is used to continue the sequential retrieval of MFEs; use MgmGetFirstMfe to start the retrieval process.

In general, to retrieve MFEs, first call MgmGetFirstMfe. Then, call MgmGetNextMfe one or more times, until there are no more MFEs to return. Each call to MgmGetNextMfe should begin after the last MFE returned by the previous call to MgmGetNextMfe (or the initial call to MgmGetFirstMfe). To do this, the client specifies the last source and group in the buffer returned by a previous call.

Note The minimum size of the buffer pointed to by pbBuffer is not fixed; it is different for each MFE. Use the SIZEOF_MIB_MFE macro to determine the size of each MFE returned in the buffer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.
Library: Use Rtm.lib.

See Also

MgmGetFirstMfe, MgmGetMfe, MIB_IPMCAST_MFE, SIZEOF_MIB_MFE


MgmGetNextMfeStats

The MgmGetNextMfeStats function retrieves one or more sets of MFE statistics. The routing table manager starts retrieving statistics starting with the MFE that follows the specified MFE. The function can retrieve zero, one, or more sets of MFE statistics. The number of sets returned depends on the size of the entries and the size of the buffer supplied by the client when the function is called.

The data returned in the buffer is ordered first by group, and then by the sources within a group. The statistics returned include the packets received, bytes received, and packets forwarded on each outgoing interface.

DWORD MgmGetNextMfeStats(
  PMIB_IPMCAST_MFE pimmStart,
  PDWORD pdwBufferSize,
  PBYTE pbBuffer,
  PDWORD pdwNumEntries
);

Parameters

pimmStart
[in] Pointer to a MIB_IPMCAST_MFE structure that specifies from where to begin retrieving MFE statistics. The dwSource and dwGroup members of the MIB_IPMCAST_MFE structure identify an MFE. Specify the source and group of the last MFE that was returned by the previous call to MgmGetFirstMfeStats or MgmGetNextMfeStats.
pdwBufferSize
[in, out] On input, pdwBufferSize is a pointer to a DWORD-sized memory location containing the size, in bytes, of pbBuffer.

On output, if the return value is ERROR_INSUFFICIENT_BUFFER, pdwBufferSize receives the minimum size pbBuffer must be to hold a set of MFE statistics; otherwise, the value of pdwBufferSize remains unchanged.

pbBuffer
[in, out] On input, the client must supply a pointer to a buffer.

On output, pbBuffer contains one or more sets of MFE statistics. Each set of MFE statistics is a MIB_IPMCAST_MFE_STATS structure.

pdwNumEntries
[in, out] On input, the client must supply a pointer to a DWORD-sized memory location.

On output, pdwNumEntries receives the number of sets of MFE statistics contained in pbBuffer.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_CAN_NOT_COMPLETE | Could not complete the call to this function.
ERROR_INSUFFICIENT_BUFFER | The specified buffer is too small for even one set of MFE statistics. The client should check the value of pdwBufferSize for the minimum buffer size required to retrieve one set of statistics.
ERROR_MORE_DATA | More MFE statistics are available.
ERROR_NO_MORE_ITEMS | No more MFE statistics are available. Zero or more sets of MFE statistics were returned; check the value of pdwNumEntries to verify how many sets of statistics were returned.

Remarks

This function is used to continue the sequential retrieval of MFE statistics; use MgmGetFirstMfeStats to start the retrieval process.

In general, to retrieve MFE statistics, first call MgmGetFirstMfeStats. Then, call MgmGetNextMfeStats one or more times, until there are no more MFEs to return. Each call to MgmGetNextMfeStats should begin after the last MFE returned by the previous call to MgmGetNextMfeStats (or the initial call to MgmGetFirstMfeStats) To do this, the client specifies the last source and group in the buffer returned by a previous call.

Note The minimum size of the buffer pointed to by pbBuffer is not fixed; it is different for each set of MFE statistics. Use the SIZEOF_MIB_MFE_STATS macro to determine the size of each set of statistics returned in the buffer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.
Library: Use Rtm.lib.

See Also

MgmGetFirstMfeStats, MgmGetMfeStats, MIB_IPMCAST_MFE_STATS, SIZEOF_MIB_MFE_STATS


MgmGetProtocolOnInterface

The MgmGetProtocolOnInterface function retrieves the protocol ID of the multicast routing protocol that owns the specified interface.

DWORD MgmGetProtocolOnInterface(
  DWORD dwIfIndex,
  DWORD dwIfNextHopAddr,
  PDWORD pdwIfProtocolId,
  PDWORD pdwIfComponentId
);

Parameters

dwIfIndex
[in] Specifies the index of the interface for which to retrieve the protocol ID.
dwIfNextHopAddr
[in] Specifies the address of the next hop that corresponds to the index specified by dwIfIndex. The dwIfIndex and dwIfNextHopIPAddr parameters uniquely identify a next hop on point-to-multipoint interfaces. A point-to-multipoint interface is a connection where one interface connects to multiple networks. Examples of point-to-multipoint interfaces include non-broadcast multiple access (NBMA) interfaces and the internal interface on which all dial-up clients connect.

For broadcast interfaces (such as Ethernet interfaces) or point-to-point interfaces, which are identified by only the value of dwIfIndex, specify zero.

pdwIfProtocolId
[in, out] On input, the client must supply a pointer to a DWORD-sized memory location.

On output, pdwIfProtocolId receives the ID of the protocol on the interface specified by dwIfIndex.

pdwIfComponentId
[in, out] On input, the client must supply a pointer to a DWORD value.

On output, pdwIfComponentId receives the component ID for the instance of the protocol on the interface. This parameter is used with pdwIfProtocolId to uniquely identify an instance of a routing protocol.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_CAN_NOT_COMPLETE | Could not complete the call to this function.
ERROR_NOT_FOUND | The specified interface was not found by the multicast group manager.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.
Library: Use Rtm.lib.

See Also

MgmReleaseInterfaceOwnership, MgmTakeInterfaceOwnership


MgmGroupEnumerationEnd

The MgmGroupEnumerationEnd function releases the specified enumeration handle that was obtained from a previous call to MgmGroupEnumerationStart.

DWORD MgmGroupEnumerationEnd(
  HANDLE hEnum
);

Parameters

hEnum
[in] Specifies the enumeration handle to release.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_CAN_NOT_COMPLETE | Could not complete the call to this function.
ERROR_INVALID_PARAMETER | Invalid enumeration handle.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.
Library: Use Rtm.lib.

See Also

MgmGroupEnumerationGetNext, MgmGroupEnumerationStart


MgmGroupEnumerationGetNext

The MgmGroupEnumerationGetNext function retrieves the next set of group entries. The information that is returned by this function is a list of groups joined and the sources requested, if any.

The groups are not returned in any particular order.

DWORD MgmGroupEnumerationGetNext(
  HANDLE hEnum,
  PDWORD pdwBufferSize,
  PBYTE pbBuffer,
  PDWORD pdwNumEntries
);

Parameters

hEnum
[in] Handle to the enumeration that was obtained from a previous call to MgmGroupEnumerationStart.
pdwBufferSize
[in, out] On input, pdwBufferSize is a pointer to a DWORD-sized memory location that contains the size, in bytes, of the buffer pointed to by pbBuffer.

On output, if the return value is ERROR_INSUFFICIENT_BUFFER, pdwBufferSize receives the minimum size that the buffer pointed to by pbBuffer must be to hold a group entry; otherwise the value of pdwBufferSize remains unchanged.

pbBuffer
[in, out] On input, the client must supply a pointer to a buffer.

On output, pbBuffer contains one or more group entries. Each group entry is a SOURCE_GROUP_ENTRY structure.

pdwNumEntries
[in, out] On input, the client must supply a pointer to a DWORD value.

On output, pdwNumEntries receives the number of groups in pbBuffer.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_CAN_NOT_COMPLETE | Could not complete the call to this function.
ERROR_INSUFFICIENT_BUFFER | The specified buffer is too small to hold even one group. The client should check the value of pdwBufferSize for the minimum buffer size required to retrieve one group.
ERROR_INVALID_PARAMETER | Invalid handle to an enumeration.
ERROR_MORE_DATA | More groups are available.
ERROR_NO_MORE_ITEMS | No more groups are available. Zero or more groups were returned; check the value of pdwNumEntries to verify how many groups were returned.
ERROR_NOT_ENOUGH_MEMORY | Not enough memory to complete this operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.
Library: Use Rtm.lib.

See Also

MgmGroupEnumerationEnd, MgmGroupEnumerationStart, SOURCE_GROUP_ENTRY


MgmGroupEnumerationStart

The MgmGroupEnumerationStart function obtains an enumeration handle that is later used to obtain the list of groups that have been joined. After the client obtains the handle, it should use the MgmGroupEnumerationGetNext function to enumerate the groups.

DWORD MgmGroupEnumerationStart(
  HANDLE hProtocol,
  MGM_ENUM_TYPES metEnumType,
  HANDLE *phEnumHandle
);

Parameters

hProtocol
[in] Handle to the protocol obtained from a previous call to MgmRegisterMProtocol.
metEnumType
[in] Specifies the type of enumeration. The following enumerations are available.
Enumeration | Meaning
ALL_SOURCES | Retrieves wildcard joins (*, g) and source-specific joins (s, g).
ANY_SOURCE | Retrieves group entries that have at least one source specified.

phEnumHandle
[out] Receives the handle to the enumeration. Use this handle in calls to MgmGroupEnumerationGetNext and MgmGroupEnumerationEnd.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_CAN_NOT_COMPLETE | Could not complete the call to this function.
ERROR_INVALID_PARAMETER | Invalid handle to a protocol.
ERROR_NOT_ENOUGH_MEMORY | Not enough memory to complete this operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.
Library: Use Rtm.lib.

See Also

MGM_ENUM_TYPES, MgmGroupEnumerationEnd, MgmGroupEnumerationGetNext


MgmRegisterMProtocol

The MgmRegisterMProtocol function is used by clients to register with the multicast group manager. When the registration is complete, the multicast group manager returns a handle to the client. The client must supply this handle in subsequent MGM function calls.

DWORD MgmRegisterMProtocol(
  PROUTING_PROTOCOL_CONFIG prpiInfo,
  DWORD dwProtocolId,
  DWORD dwComponentId,
  HANDLE *phProtocol
);

Parameters

prpiInfo
[in] Pointer to a ROUTING_PROTOCOL_CONFIG structure that contains pointers to callbacks into the client.
dwProtocolId
[in] Specifies the ID of the client. The ID is unique for each client.
dwComponentId
[in] Specifies the component ID for a specific instance of the client. This parameter is used with dwProtocolId to uniquely identify an instance of a client.
phProtocol
[out] On input, the client must supply a pointer to a handle.

On output, phProtocol receives the registration handle for the client. This handle must be used in subsequent calls to the multicast group manager.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ALREADY_EXISTS | Cannot register the specified client because an entry with the same protocol ID and component ID already exists.
ERROR_CAN_NOT_COMPLETE | Could not complete the call to this function.
ERROR_NOT_ENOUGH_MEMORY | Not enough memory to complete this operation.

Remarks

Registering a protocol is the first operation any multicast routing protocol should perform. After registration, a routing protocol should take ownership of the appropriate interfaces before adding or deleting group memberships.

Only one routing protocol may take ownership of an interface at any given time. Multiple routing protocols may be registered with the multicast group manager, each protocol owning different interfaces.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.
Library: Use Rtm.lib.

See Also

MgmDeRegisterMProtocol, MgmTakeInterfaceOwnership, ROUTING_PROTOCOL_CONFIG


MgmReleaseInterfaceOwnership

The MgmReleaseInterfaceOwnership function is used by a client to relinquish ownership of an interface. When this function is called, all MFEs maintained by the multicast group manager on behalf of the client and for the specified interface are deleted.

DWORD MgmReleaseInterfaceOwnership(
  HANDLE hProtocol,
  DWORD dwIfIndex,
  DWORD dwIfNextHopAddr
);

Parameters

hProtocol
[in] Handle to the protocol obtained from a previous call to MgmRegisterMProtocol.
dwIfIndex
[in] Specifies the index of the interface to release.
dwIfNextHopAddr
[in] Specifies the address of the next hop that corresponds to the index specified by dwIfIndex. The dwIfIndex and dwIfNextHopIPAddr parameters uniquely identify a next hop on point-to-multipoint interfaces. A point-to-multipoint interface is a connection where one interface connects to multiple networks. Examples of point-to-multipoint interfaces include non-broadcast multiple access (NBMA) interfaces and the internal interface on which all dial-up clients connect.

For broadcast interfaces (such as Ethernet interfaces) or point-to-point interfaces, which are identified by only the value of dwIfIndex, specify zero.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes:

Value | Meaning
ERROR_CAN_NOT_COMPLETE | Could not complete the call to this function.
ERROR_INVALID_PARAMETER | Invalid handle to a client, or the interface was not found.

Remarks

A client must release ownership of all the interfaces it owns before deregistering itself with the MgmDeRegisterMProtocol function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.
Library: Use Rtm.lib.

See Also

MgmDeRegisterMProtocol, MgmTakeInterfaceOwnership


MgmSetMfe

The MgmSetMfe function changes the upstream neighbor for an MFE. An MFE contains the information about which interface is receiving and which interfaces are forwarding multicast data.

DWORD MgmSetMfe(
  HANDLE hProtocol,
  PMIB_IPMCAST_MFE pmimm
);

Parameters

hProtocol
[in] Handle to the protocol obtained from a previous call to MgmRegisterMProtocol.
pmimm
[in] Pointer to a MIB_IPMCAST_MFE structure that specifies the MFE to change. Specify the new neighbor in the dwUpstreamNeighbor member.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_CAN_NOT_COMPLETE | Could not complete the call to this function.
ERROR_INVALID_PARAMETER | Invalid handle to a client.
ERROR_NOT_FOUND | The specified MFE was not found.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.
Library: Use Rtm.lib.

See Also

MIB_IPMCAST_MFE


MgmTakeInterfaceOwnership

The MgmTakeInterfaceOwnership function is called by a client (such as a routing protocol) when it is enabled on an interface.

Only one client can take ownership of a given interface at any time. The only exception to this rule is the IGMP. IGMP can coexist with another client on an interface.

DWORD MgmTakeInterfaceOwnership(
  HANDLE hProtocol,
  DWORD dwIfIndex,
  DWORD dwIfNextHopAddr
);

Parameters

hProtocol
[in] Handle to the protocol obtained from a previous call to MgmRegisterMProtocol.
dwIfIndex
[in] Specifies the index of the interface of which to take ownership.
dwIfNextHopAddr
[in] Specifies the address of the next hop that corresponds to the index specified by dwIfIndex. The dwIfIndex and dwIfNextHopIPAddr parameters uniquely identify a next hop on point-to-multipoint interfaces. A point-to-multipoint interface is a connection where one interface connects to multiple networks. Examples of point-to-multipoint interfaces include non-broadcast multiple access (NBMA) interfaces and the internal interface on which all dial-up clients connect.

For broadcast interfaces (such as Ethernet interfaces) or point-to-point interfaces, which are identified by only the value of dwIfIndex, specify zero.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ALREADY_EXISTS | The specified interface is already owned by another routing protocol.
ERROR_CAN_NOT_COMPLETE | Could not complete the call to this function.
ERROR_INVALID_PARAMETER | Invalid handle to a client.
ERROR_NOT_ENOUGH_MEMORY | Not enough memory to complete this operation.

Remarks

A client must take ownership of an interface only after registering itself with the multicast group manager, but before it adds group membership entries.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.
Library: Use Rtm.lib.

See Also

MgmGetProtocolOnInterface, MgmRegisterMProtocol, MgmReleaseInterfaceOwnership


Multicast Group Manager Callbacks

The multicast group manager uses the following callbacks to notify clients (typically, routing protocols) of events and state changes:

PMGM_CREATION_ALERT_CALLBACK

PMGM_JOIN_ALERT_CALLBACK

PMGM_PRUNE_ALERT_CALLBACK

PMGM_LOCAL_JOIN_CALLBACK

PMGM_LOCAL_LEAVE_CALLBACK

PMGM_RPF_CALLBACK

PMGM_WRONG_IF_CALLBACK

The multicast group manager uses the following callbacks to notify IGMP of events and state changes:

PMGM_DISABLE_IGMP_CALLBACK

PMGM_ENABLE_IGMP_CALLBACK


PMGM_CREATION_ALERT_CALLBACK

The PMGM_CREATION_ALERT_CALLBACK callback is a call into a routing protocol. This call determines the subset of interfaces owned by the routing protocol on which a multicast packet from a new source should be forwarded.

When a packet sent from a new source, or destined for a new group, arrives on an interface, the multicast group manager creates a new MFE. The multicast group manager then invokes this callback to those routing protocols that have outgoing interfaces in this new MFE. A routing protocol can choose to disable the forwarding of data from the source to the group on specific interfaces.

typedef DWORD(*PMGM_CREATION_ALERT_CALLBACK)(
  DWORD dwSourceAddr,
  DWORD dwSourceMask,
  DWORD dwGroupAddr,
  DWORD dwGroupMask,
  DWORD dwInIfIndex,
  DWORD dwInIfNextHopAddr,
  DWORD dwIfCount,
  PMGM_IF_ENTRY pmieOutIfList
);

Parameters

dwSourceAddr
[in] Specifies the source address from which the multicast data was received. Zero indicates that data is received from all sources (a wildcard receiver for a group); otherwise, the value of dwSourceAddr is the IP address of the source or source network.

To specify a range of source addresses, the multicast group manager specifies the source network using dwSourceAddr, and specifies a subnet mask using dwSourceMask.

dwSourceMask
[in] Specifies the subnet mask that corresponds to dwSourceAddr. The dwSourceAddr and dwSourceMask parameters are used together to define a range of sources from which to receive multicast data.

The multicast group manager specifies zero for this parameter if it also specified zero for dwSourceAddr (a wildcard receiver).

dwGroupAddr
[in] Specifies the multicast group for which the data is destined. Zero indicates that all groups are received (a wildcard receiver); otherwise, the value of dwGroupAddr is the IP address of the group.

To specify a range of group addresses, the multicast group manager specifies the group address using dwGroupAddr, and specifies a subnet mask using dwGroupMask.

dwGroupMask
[in] Specifies the subnet mask that corresponds to dwGroupAddr. The dwGroupAddr and dwGroupMask parameters are used together to define a range of multicast groups.

The multicast group manager specifies zero for this parameter if it also specified zero for dwGroupAddr (a wildcard receiver).

dwInIfIndex
[in] Specifies the interface on which the multicast data from the source should arrive.
dwInIfNextHopAddr
[in] Specifies the address of the next hop that corresponds to the index specified by dwIfIndex. The dwIfIndex and dwIfNextHopIPAddr parameters uniquely identify a next hop on point-to-multipoint interfaces. A point-to-multipoint interface is a connection where one interface connects to multiple networks. Examples of point-to-multipoint interfaces include non-broadcast multiple access (NBMA) interfaces and the internal interface on which all dial-up clients connect.

For broadcast interfaces (such as Ethernet interfaces) or point-to-point interfaces, which are identified by only the value of dwIfIndex, specify zero.

dwIfCount
[in] Specifies the number of interfaces in the buffer pointed to by pmieOutIfList.
pmieOutIfList
[in, out] On input, a pointer to a buffer containing the set of interfaces owned by the protocol on which data will be forwarded.

On output, the client can set the bIsEnabled member of the corresponding MGM_IF_ENTRY structure to FALSE to prevent forwarding on any of its interfaces. A client may not be required to prevent forwarding; such a client would accept the default value of bIsEnabled.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.

See Also

MGM_IF_ENTRY


PMGM_DISABLE_IGMP_CALLBACK

The PMGM_DISABLE_IGMP_CALLBACK callback is a call into IGMP to notify it that a routing protocol is taking or releasing ownership of an interface on which IGMP is enabled.

When this callback is invoked, IGMP should stop adding and deleting group memberships on the specified interface.

typedef DWORD(*PMGM_DISABLE_IGMP_CALLBACK)(
  DWORD dwIfIndex,
  DWORD dwIfNextHopAddr
);

Parameters

dwIfIndex
[in] Specifies the interface on which to disable IGMP.
dwIfNextHopAddr
[in] Specifies the address of the next hop that corresponds to the index specified by dwIfIndex. The dwIfIndex and dwIfNextHopIPAddr parameters uniquely identify a next hop on point-to-multipoint interfaces. A point-to-multipoint interface is a connection where one interface connects to multiple networks. Examples of point-to-multipoint interfaces include non-broadcast multiple access (NBMA) interfaces and the internal interface on which all dial-up clients connect.

For broadcast interfaces (such as Ethernet interfaces) or point-to-point interfaces, which are identified by only the value of dwIfIndex, specify zero.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.

See Also

PMGM_ENABLE_IGMP_CALLBACK


PMGM_ENABLE_IGMP_CALLBACK

The PMGM_ENABLE_IGMP_CALLBACK callback is a call into IGMP to notify it that a routing protocol has finished taking or releasing ownership of an interface.

When this callback is invoked, IGMP should add all its group memberships on the specified interface using calls to the MgmAddGroupMembershipEntry function.

typedef DWORD(*PMGM_ENABLE_IGMP_CALLBACK)(
  DWORD dwIfIndex,
  DWORD dwIfNextHopAddr
);

Parameters

dwIfIndex
[in] Specifies the index of the interface on which to enable IGMP.
dwIfNextHopAddr
[in] Specifies the address of the next hop that corresponds to the index specified by dwIfIndex. The dwIfIndex and dwIfNextHopIPAddr parameters uniquely identify a next hop on point-to-multipoint interfaces. A point-to-multipoint interface is a connection where one interface connects to multiple networks. Examples of point-to-multipoint interfaces include non-broadcast multiple access (NBMA) interfaces and the internal interface on which all dial-up clients connect.

For broadcast interfaces (such as Ethernet interfaces) or point-to-point interfaces, which are identified by only the value of dwIfIndex, specify zero.

Remarks

IGMP must not add group memberships in the context of this callback. The multicast group manager and IGMP will become deadlocked.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.

See Also

PMGM_DISABLE_IGMP_CALLBACK


PMGM_JOIN_ALERT_CALLBACK

The PMGM_JOIN_ALERT_CALLBACK callback is a call into a routing protocol to notify the protocol that new receivers are present for one or more groups on interfaces that are owned by other routing protocols. Once a routing protocol receives this callback, it should begin forwarding multicast data for the specified source and group.

typedef DWORD(*PMGM_JOIN_ALERT_CALLBACK)(
  DWORD dwSourceAddr,
  DWORD dwSourceMask,
  DWORD dwGroupAddr,
  DWORD dwGroupMask,
  BOOL bMemberUpdate
);

Parameters

dwSourceAddr
[in] Specifies the source address from which the multicast data was received. Zero indicates that data is received from all sources (a wildcard receiver for a group); otherwise, the value of dwSourceAddr is the IP address of the source or source network.

To specify a range of source addresses, the multicast group manager specifies the source network using dwSourceAddr, and specifies a subnet mask using dwSourceMask.

dwSourceMask
[in] Specifies the subnet mask that corresponds to dwSourceAddr. The dwSourceAddr and dwSourceMask parameters are used together to define a range of sources from which to receive multicast data.

The multicast group manager specifies zero for this parameter if it also specified zero for dwSourceAddr (a wildcard receiver).

dwGroupAddr
[in] Specifies the multicast group for which the data is destined. Zero indicates that all groups are received (a wildcard receiver); otherwise, the value of dwGroupAddr is the IP address of the group.

To specify a range of group addresses, the multicast group manager specifies the group address using dwGroupAddr, and specifies a subnet mask using dwGroupMask.

dwGroupMask
[in] Specifies the subnet mask that corresponds to dwGroupAddr. The dwGroupAddr and dwGroupMask parameters are used together to define a range of multicast groups.

The multicast group manager specifies zero for this parameter if it also specified zero for dwGroupAddr (a wildcard receiver).

bMemberUpdate
[in] Specifies whether the callback was invoked because the MgmAddGroupMembershipEntry was called by a client (the multicast group manager sets this parameter to TRUE), or because an MFE was created or updated (the multicast group manager sets this parameter to FALSE).

Remarks

The multicast group manager sets the bMemberUpdate parameter to TRUE and invokes this callback if a client calls the MgmAddGroupMembershipEntry function for a (s, g), (*, g), or (*, *) entry (that is, the group membership has changed).

The multicast group manager sets the bMemberUpdate parameter to FALSE if the outgoing interface list for an MFE changes. This change typically occurs for a change in membership for the group corresponding to the MFE.

A multicast routing protocol can use the bMemberUpdate parameter to distinguish between changes to group membership and changes to the MFE.

The action taken by the routing protocol when this callback is received is protocol-specific. The protocol may ignore the callback if the bMemberUpdate parameter is set to FALSE, if the protocol specification indicates that this is the correct behavior.

When MgmAddGroupMembershipEntry is called, the multicast group manager uses this callback to notify other multicast group manager clients that there are receivers for the specified source and group.

The multicast group manager uses the following rules to determine when to invoke this callback for wildcard (*, g) joins:

  • If this is the first client to inform the multicast group manager that there are receivers on an interface for a group, the multicast group manager invokes the PMGM_JOIN_ALERT_CALLBACK callback to all other registered clients.
  • If this is the second client to inform the multicast group manager that there are receivers on an interface for a group, the multicast group manager invokes this callback to the first client to join the group.

The multicast group manager does not invoke this callback for any subsequent joins to the group.

The multicast group manager uses the following rule to determine when to invoke this callback for source-specific (s, g) joins:

  • If this is the first client to inform the multicast group manager that there are receivers on an interface for a source and group, the multicast group manager invokes the PMGM_JOIN_ALERT_CALLBACK callback only for the client that owns the incoming interface towards the source "s".

This version of the Multicast Group Manager API supports only wildcard sources (*, g) or specific sources (s, g), not a range of sources. The same restriction applies to groups (that is, no group ranges are permitted).

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.


PMGM_LOCAL_JOIN_CALLBACK

The PMGM_LOCAL_JOIN_CALLBACK callback is a call into a routing protocol to notify the protocol that IGMP has detected new receivers for a group on an interface that is currently owned by the routing protocol.

This callback is invoked when the MgmAddGroupMembershipEntry function is called by IGMP.

typedef DWORD(*PMGM_LOCAL_JOIN_CALLBACK)(
  DWORD dwSourceAddr,
  DWORD dwSourceMask,
  DWORD dwGroupAddr,
  DWORD dwGroupMask,
  DWORD dwIfIndex,
  DWORD dwIfNextHopAddr
);

Parameters

dwSourceAddr
[in] Specifies the source address from which the multicast data was received. Zero indicates that data is received from all sources (a wildcard receiver for a group); otherwise, the value of dwSourceAddr is the IP address of the source or source network.

To specify a range of source addresses, the multicast group manager specifies the source network using dwSourceAddr, and specifies a subnet mask using dwSourceMask.

dwSourceMask
[in] Specifies the subnet mask that corresponds to dwSourceAddr. The dwSourceAddr and dwSourceMask parameters are used together to define a range of sources from which to receive multicast data.

The multicast group manager specifies zero for this parameter if it also specified zero for dwSourceAddr (a wildcard receiver).

dwGroupAddr
[in] Specifies the multicast group for which the data is destined. Zero indicates that all groups are received (a wildcard receiver); otherwise the value of dwGroupAddr is the IP address of the group.

To specify a range of group addresses, the multicast group manager specifies the group address using dwGroupAddr, and specifies a subnet mask using dwGroupMask.

dwGroupMask
[in] Specifies the subnet mask that corresponds to dwGroupAddr. The dwGroupAddr and dwGroupMask parameters are used together to define a range of multicast groups.

The multicast group manager specifies zero for this parameter if it also specified zero for dwGroupAddr (a wildcard receiver).

dwIfIndex
[in] Specifies the interface on which the multicast data from the source should arrive.
dwIfNextHopAddr
[in] Specifies the address of the next hop that corresponds to the index specified by dwIfIndex. The dwIfIndex and dwIfNextHopIPAddr parameters uniquely identify a next hop on point-to-multipoint interfaces. A point-to-multipoint interface is a connection where one interface connects to multiple networks. Examples of point-to-multipoint interfaces include non-broadcast multiple access (NBMA) interfaces and the internal interface on which all dial-up clients connect.

For broadcast interfaces (such as Ethernet interfaces) or point-to-point interfaces, which are identified by only the value of dwIfIndex, specify zero.

Remarks

This version of the Multicast Group Manager API supports only wildcard sources (*, g) or specific sources (s, g), not a range of sources. The same restriction applies to groups (that is, no group ranges are permitted).

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.

See Also

PMGM_LOCAL_LEAVE_CALLBACK


PMGM_LOCAL_LEAVE_CALLBACK

The PMGM_LOCAL_LEAVE_CALLBACK callback is a call into a routing protocol to notify the routing protocol that the IGMP has detected that it no longer has receivers for a group on an interface that is currently owned by the routing protocol.

This callback is invoked when the MgmDeleteGroupMembershipEntry function is called by IGMP.

typedef DWORD(*PMGM_LOCAL_LEAVE_CALLBACK)(
  DWORD dwSourceAddr,
  DWORD dwSourceMask,
  DWORD dwGroupAddr,
  DWORD dwGroupMask,
  DWORD dwIfIndex,
  DWORD dwIfNextHopAddr
);

Parameters

dwSourceAddr
[in] Specifies the source address from which to stop receiving multicast data. Zero indicates to stop receiving data from all sources (a wildcard receiver for a group); otherwise, the value of dwSourceAddr is the IP address of the source or source network.

To specify a range of source addresses, the multicast group manager specifies the source network using dwSourceAddr, and specifies a subnet mask using dwSourceMask.

dwSourceMask
[in] Specifies the subnet mask that corresponds to dwSourceAddr. The dwSourceAddr and dwSourceMask parameters are used together to define a range of sources from which to stop receiving multicast data.

The multicast group manager specifies zero for this parameter if it also specified zero for dwSourceAddr (a wildcard receiver).

dwGroupAddr
[in] Specifies the multicast group for which to stop receiving data. Zero indicates to stop receiving data for all groups (a wildcard receiver); otherwise, the value of dwGroupAddr is the IP address of the group.

To specify a range of group addresses, the multicast group manager specifies the group address using dwGroupAddr, and specifies a subnet mask using dwGroupMask.

dwGroupMask
[in] Specifies the subnet mask that corresponds to dwGroupAddr. The dwGroupAddr and dwGroupMask parameters are used together to define a range of multicast groups.

The multicast group manager specifies zero for this parameter if it also specified zero for dwGroupAddr (a wildcard receiver).

dwIfIndex
[in] Specifies the interface on which to stop receiving multicast data.
dwIfNextHopAddr
[in] Specifies the address of the next hop that corresponds to the index specified by dwIfIndex. The dwIfIndex and dwIfNextHopIPAddr parameters uniquely identify a next hop on point-to-multipoint interfaces. A point-to-multipoint interface is a connection where one interface connects to multiple networks. Examples of point-to-multipoint interfaces include non-broadcast multiple access (NBMA) interfaces and the internal interface on which all dial-up clients connect.

For broadcast interfaces (such as Ethernet interfaces) or point-to-point interfaces, which are identified by only the value of dwIfIndex, specify zero.

Remarks

This version of the Multicast Group Manager API supports only wildcard sources (*, g) or specific sources (s, g), not a range of sources. The same restriction applies to groups (that is, no group ranges are permitted).

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.

See Also

PMGM_LOCAL_JOIN_CALLBACK


PMGM_PRUNE_ALERT_CALLBACK

The PMGM_PRUNE_ALERT_CALLBACK callback is a call into a routing protocol to notify the protocol that receivers are no longer present on interfaces owned by other routing protocols.

typedef DWORD(*PMGM_PRUNE_ALERT_CALLBACK)(
  DWORD dwSourceAddr,
  DWORD dwSourceMask,
  DWORD dwGroupAddr,
  DWORD dwGroupMask,
  DWORD dwIfIndex,
  DWORD dwIfNextHopAddr,
  BOOL bMemberDelete,
  PDWORD pdwTimeout
);

Parameters

dwSourceAddr
[in] Specifies the source address from which to stop receiving multicast data. Zero indicates to stop receiving data from all sources (a wildcard receiver for a group); otherwise, the value of dwSourceAddr is the IP address of the source or source network.

To specify a range of source addresses, the multicast group manager specifies the source network using dwSourceAddr, and specifies a subnet mask using dwSourceMask.

dwSourceMask
[in] Specifies the subnet mask that corresponds to dwSourceAddr. The dwSourceAddr and dwSourceMask parameters are used together to define a range of sources from which to stop receiving receive multicast data.

The multicast group manager specifies zero for this parameter if it also specified zero for dwSourceAddr (a wildcard receiver).

dwGroupAddr
[in] Specifies the multicast group for which to stop receiving data. Zero indicates to stop receiving data for all groups (a wildcard receiver); otherwise, the value of dwGroupAddr is the IP address of the group.

To specify a range of group addresses, the multicast group manager specifies the group address using dwGroupAddr, and specifies a subnet mask using dwGroupMask.

dwGroupMask
[in] Specifies the subnet mask that corresponds to dwGroupAddr. The dwGroupAddr and dwGroupMask parameters are used together to define a range of multicast groups.

The multicast group manager specifies zero for this parameter if it also specified zero for dwGroupAddr (a wildcard receiver).

dwIfIndex
[in] Specifies the interface on which to stop receiving multicast data.
dwIfNextHopAddr
[in] Specifies the address of the next hop that corresponds to the index specified by dwIfIndex. The dwIfIndex and dwIfNextHopIPAddr parameters uniquely identify a next hop on point-to-multipoint interfaces. A point-to-multipoint interface is a connection where one interface connects to multiple networks. Examples of point-to-multipoint interfaces include non-broadcast multiple access (NBMA) interfaces and the internal interface on which all dial-up clients connect.

For broadcast interfaces (such as Ethernet interfaces) or point-to-point interfaces, which are identified by only the value of dwIfIndex, specify zero.

bMemberDelete
[in] Specifies whether the callback was invoked because the MgmAddGroupMembershipEntry was called by a client (the multicast group manager sets this parameter to TRUE), or because an MFE was created or updated (the multicast group manager sets this parameter to FALSE).
pdwTimeout
[in, out] On input, pdwTimeout points to a DWORD-sized memory location.

If bMemberDelete is FALSE, this parameter can be used to specify how long the corresponding MFE should remain in the multicast forwarding cache. If the client does not specify a value, the default value is 900 seconds.

On output, pdwTimeout receives the time-out value, in seconds, for this MFE.

Remarks

The multicast group manager sets the bMemberDelete parameter to TRUE and invokes this callback if a client calls the MgmDeleteGroupMembershipEntry function for a (s, g), (*, g), or (*, *) entry (that is, the group membership changes).

The multicast group manager sets the bMemberDelete parameter to FALSE if the outgoing interface list for an MFE changes. This change typically occurs for a change in membership for the group corresponding to the MFE.

A multicast routing protocol can use the bMemberDelete parameter to distinguish between changes to group membership and changes to the MFE.

The action taken by the routing protocol when this callback is received is protocol-specific. The protocol may ignore the callback if the bMemberDelete parameter is set to FALSE, if the protocol specification indicates that this is the correct behavior.

When MgmDeleteGroupMembershipEntry is called, the multicast group manager uses this callback to notify other multicast group manager clients that there are no more receivers for the specified source and group.

The multicast group manager uses the following rules to determine when to invoke this callback for wildcard (*, g) joins:

  • If the final interface is being removed for the second-to-last client (that is, when interfaces for only a single client remain), the multicast group manager invokes the PMGM_PRUNE_ALERT_CALLBACK callback to that remaining client.
  • If the final interface is being removed for the last client (that is, when no other interfaces remain), then this callback is invoked for all the other clients that are registered with the multicast group manager.

The multicast group manager uses the following rule to determine when to invoke this callback for source-specific (s, g) joins:

  • When a source-specific prune for a group (s, g) is received, the multicast group manager invokes the PMGM_PRUNE_ALERT_CALLBACK callback only for the client that owns the incoming interface towards the source "s".

This version of the Multicast Group Manager API supports only wildcard sources (*, g) or specific sources (s, g), not a range of sources. The same restriction applies to groups (that is, no group ranges are permitted).

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.

See Also

PMGM_CREATION_ALERT_CALLBACK


PMGM_RPF_CALLBACK

The PMGM_RPF_CALLBACK callback is a call into a routing protocol to determine if a given packet was received on the correct interface.

This callback is invoked when a packet from a new source or destined for a new group is received. The multicast group manager invokes this callback to the routing protocol that owns the incoming interface towards the source.

typedef DWORD(*PMGM_RPF_CALLBACK)(
  DWORD dwSourceAddr,
  DWORD dwSourceMask,
  DWORD dwGroupAddr,
  DWORD dwGroupMask,
  PDWORD pdwInIfIndex,
  PDWORD pdwInIfNextHopAddr,
  PDWORD pdwUpStreamNbr,
  DWORD dwHdrSize,
  PBYTE pbPacketHdr,
  PBYTE pbRoute
);

Parameters

dwSourceAddr
[in] Specifies the source address from which the multicast data was received. Zero indicates that data is received from all sources (a wildcard receiver for a group); otherwise, the value of dwSourceAddr is the IP address of the source or source network.

To specify a range of source addresses, the multicast group manager specifies the source network using dwSourceAddr, and specifies a subnet mask using dwSourceMask.

dwSourceMask
[in] Specifies the subnet mask that corresponds to dwSourceAddr. The dwSourceAddr and dwSourceMask parameters are used together to define a range of sources from which to receive multicast data.

The multicast group manager specifies zero for this parameter if it also specified zero for dwSourceAddr (a wildcard receiver).

dwGroupAddr
[in] Specifies the multicast group for which the data is destined. Zero indicates that all groups are received (a wildcard receiver); otherwise, the value of dwGroupAddr is the IP address of the group.

To specify a range of group addresses, the multicast group manager specifies the group address using dwGroupAddr, and specifies a subnet mask using dwGroupMask.

dwGroupMask
[in] Specifies the subnet mask that corresponds to dwGroupAddr. The dwGroupAddr and dwGroupMask parameters are used together to define a range of multicast groups.

The multicast group manager specifies zero for this parameter if it also specified zero for dwGroupAddr (a wildcard receiver).

pdwInIfIndex
[in, out] On input, a pointer to a DWORD-sized memory location that specifies the index of the interface on which data from the source is expected to be received, based on the multicast view of the routing table.

On output, pdwInIfIndex points to a DWORD-sized memory location that contains the index of the interface on which the protocol expects to receive packets. The interface index may differ on output from the index specified on input.

pdwInIfNextHopAddr
[in, out] On input, pdwInIfNextHopAddr specifies the address of the next hop that corresponds to the index specified by dwIfIndex.

The dwIfIndex and dwIfNextHopIPAddr parameters uniquely identify a next hop on point-to-multipoint interfaces. A point-to-multipoint interface is a connection where one interface connects to multiple networks. Examples of point-to-multipoint interfaces include non-broadcast multiple access (NBMA) interfaces and the internal interface on which all dial-up clients connect.

For broadcast interfaces (such as Ethernet interfaces) or point-to-point interfaces, which are identified by only the value of dwIfIndex, specify zero.

On output, pdwInIfNextHopAddr points to the next hop that corresponds to pdwInIfIndex.

pdwUpStreamNbr
[in, out] On input, pdwUpStreamNbr points to a DWORD value specifying the immediate upstream neighbor towards the source (the source is found in the multicast view of the routing table).

On output, pdwUpStreamNbr may have been modified by the protocol. This parameter is for informational purposes only.

dwHdrSize
[in] Specifies, in bytes, the size of the buffer pointed to by pbPacketHdr.
pbPacketHdr
[in] Pointer to a buffer that contains the IP header of the packet, including the IP options and a fragment of the data. This parameter is used by those protocols that examine the contents of the packet header.
pbRoute
[in, out] On input, pbRoute points to a buffer that contains the route towards the source. The buffer contains an RTM_DEST_INFO structure.

On output, pbRoute points to a buffer that contains the route used by the protocol to determine the interface towards the source.

Remarks

This callback is invoked when an MFE is created. MFEs are created when data from a new multicast source, or destined to a new group, is received.

The multicast group manager invokes this callback to the routing protocol that owns the incoming interface towards the source. The multicast group manager determines the interface by looking up the source of the multicast data in the multicast view of the routing table. This interface is not always the same as the interface on which the data was actually received; this condition occurs if multicast data was received on the wrong interface.

When this callback is invoked, the routing protocol can change the incoming interface if the routing protocol behavior requires it to receive the data for the group from another interface.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.


PMGM_WRONG_IF_CALLBACK

The PMGM_WRONG_IF_CALLBACK is a call into a routing protocol to notify the protocol that a packet has been received from the specified source and for the specified group on the wrong interface.

typedef DWORD(*PMGM_WRONG_IF_CALLBACK)(
  DWORD dwSourceAddr,
  DWORD dwGroupAddr,
  DWORD dwIfIndex,
  DWORD dwIfNextHopAddr,
  DWORD dwHdrSize,
  PBYTE pbPacketHdr
);

Parameters

dwSourceAddr
[in] Specifies the source address from which the multicast data was received. Zero indicates that data is received from all sources (a wildcard receiver for a group); otherwise, the value of dwSourceAddr is the IP address of the source or source network.
dwGroupAddr
[in] Specifies the multicast group for which the data is destined. Zero indicates that all groups are received (a wildcard receiver); otherwise, the value of dwGroupAddr is the IP address of the group.
dwIfIndex
[in] Specifies the interface on which the packet arrived.
dwIfNextHopAddr
[in] Specifies the address of the next hop that corresponds to the index specified by dwIfIndex. The dwIfIndex and dwIfNextHopIPAddr parameters uniquely identify a next hop on point-to-multipoint interfaces. A point-to-multipoint interface is a connection where one interface connects to multiple networks. Examples of point-to-multipoint interfaces include non-broadcast multiple access (NBMA) interfaces and the internal interface on which all dial-up clients connect.

For broadcast interfaces (such as Ethernet interfaces) or point-to-point interfaces, which are identified by only the value of dwIfIndex, specify zero.

dwHdrSize
[in] Specifies, in bytes, the size of the buffer pointed to by pbPacketHdr.
pbPacketHdr
[in] Pointer to a buffer that contains the IP header of the packet, including the IP options and a fragment of the data. This parameter is used by those protocols that examine the contents of the packet header.

Remarks

This callback is not currently available.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.


Multicast Group Manager Structures

The MGM API use the following structures:

MGM_IF_ENTRY

ROUTING_PROTOCOL_CONFIG

SOURCE_GROUP_ENTRY


MGM_IF_ENTRY

The MGM_IF_ENTRY structure describes a router interface. This structure is used in the PMGM_CREATION_ALERT_CALLBACK. In the context of this callback, the routing protocol must enable or disable multicast forwarding on each interface, notifying the multicast group manager by using the bIsEnabled member.

typedef struct _MGM_IF_ENTRY {
  DWORD            dwIfIndex;
  DWORD            dwIfNextHopAddr;
  BOOL             bIGMP;
  BOOL             bIsEnabled;
} MGM_IF_ENTRY, *PMGM_IF_ENTRY;

Members

dwIfIndex
Specifies the index of the interface.
dwIfNextHopAddr
[in] Specifies the address of the next hop that corresponds to the index specified by dwIfIndex. The dwIfIndex and dwIfNextHopIPAddr parameters uniquely identify a next hop on point-to-multipoint interfaces. A point-to-multipoint interface is a connection where one interface connects to multiple networks. Examples of point-to-multipoint interfaces include non-broadcast multiple access (NBMA) interfaces and the internal interface on which all dial-up clients connect.

For broadcast interfaces (such as Ethernet interfaces) or point-to-point interfaces, which are identified by only the value of dwIfIndex, specify zero.

bIGMP
Indicates whether or not IGMP is enabled on this interface. If bIGMP is TRUE, then IGMP is enabled on this interface. If bIGMP is FALSE, then IGMP is not enabled on this interface.
bIsEnabled
Indicates whether or not multicast forwarding is enabled on this interface. If bIsEnabled is TRUE, multicast forwarding is enabled on this interface. If bIsEnabled is FALSE, multicast forwarding is disabled on this interface.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.

See Also

PMGM_CREATION_ALERT_CALLBACK


ROUTING_PROTOCOL_CONFIG

The ROUTING_PROTOCOL_CONFIG structure describes the routing protocol configuration information that is passed to the multicast group manager when a protocol registers with the multicast group manager.

typedef struct _ROUTING_PROTOCOL_CONFIG {
  DWORD                           dwCallbackFlags;
  PMGM_RPF_CALLBACK               pfnRpfCallback;
  PMGM_CREATION_ALERT_CALLBACK    pfnCreationAlertCallback;
  PMGM_PRUNE_ALERT_CALLBACK       pfnPruneAlertCallback;
  PMGM_JOIN_ALERT_CALLBACK        pfnJoinAlertCallback;
  PMGM_WRONG_IF_CALLBACK          pfnWrongIfCallback;
  PMGM_LOCAL_JOIN_CALLBACK        pfnLocalJoinCallback;
  PMGM_LOCAL_LEAVE_CALLBACK       pfnLocalLeaveCallback;
  PMGM_DISABLE_IGMP_CALLBACK      pfnDisableIgmpCallback;
  PMGM_ENABLE_IGMP_CALLBACK       pfnEnableIgmpCallback;
} ROUTING_PROTOCOL_CONFIG, *PROUTING_PROTOCOL_CONFIG;

Members

dwCallbackFlags
Reserved for future use.
pfnRpfCallback
Callback into a routing protocol to perform an RPF check.
pfnCreationAlertCallback
Callback into a routing protocol to determine the subset of interfaces owned by the routing protocol on which a multicast packet from a new source or to a new group should be forwarded.
pfnPruneAlertCallback
Callback into a routing protocol to notify the protocol that receivers for the specified source and group are no longer present on an interface owned by other routing protocols.
pfnJoinAlertCallback
Callback into a routing protocol to notify the protocol that new receivers for the specified source and group are present on an interface owned by another routing protocol.
pfnWrongIfCallback
Callback into a routing protocol to notify the protocol that a packet has been received from the specified source and for the specified group on the wrong interface.
pfnLocalJoinCallback
Callback into a routing protocol to notify the protocol that IGMP has detected new receivers for a group on an interface.
pfnLocalLeaveCallback
Callback into a routing protocol to notify the protocol that IGMP has detected that there are no more receivers for a group on an interface.
pfnDisableIgmpCallback
Callback into IGMP to notify IGMP that a protocol is taking or releasing ownership of an interface on which IGMP is enabled.
pfnEnableIgmpCallback
Callback into IGMP to notify IGMP that a protocol has finished taking or releasing ownership of an interface on which IGMP is enabled.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.

See Also

MgmRegisterMProtocol


SOURCE_GROUP_ENTRY

The SOURCE_GROUP_ENTRY structure describes the entry returned by the group enumeration function MgmGroupEnumerationGetNext.

typedef struct _SOURCE_GROUP_ENTRY {
  DWORD               dwSourceAddr;
  DWORD               dwSourceMask;
  DWORD               dwGroupAddr;
  DWORD               dwGroupMask;
} SOURCE_GROUP_ENTRY, *PSOURCE_GROUP_ENTRY;

Members

dwSourceAddr
[in] Specifies the source address from which to receive multicast data. Specify zero to receive data from all sources (a wildcard receiver for a group); otherwise, specify the IP address of the source or source network.

To specify a range of source addresses, specify the source network using dwSourceAddr, and specify a subnet mask using dwSourceMask.

dwSourceMask
[in] Specifies the subnet mask that corresponds to dwSourceAddr. The dwSourceAddr and dwSourceMask parameters are used together to define a range of sources from which to receive multicast data.

Specify zero for this parameter if zero was specified for dwSourceAddr (a wildcard receiver).

dwGroupAddr
[in] Specifies the multicast group for which to receive data. Specify zero to receive all groups (a wildcard receiver); otherwise, specify the IP address of the group.

To specify a range of group addresses, specify the group address using dwGroupAddr, and specify a subnet mask using dwGroupMask.

dwGroupMask
[in] Specifies the subnet mask that corresponds to dwGroupAddr. The dwGroupAddr and dwGroupMask parameters are used together to define a range of multicast groups.

Specify zero for this parameter if zero was specified for dwGroupAddr (a wildcard receiver).

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.

See Also

MGM_ENUM_TYPES, MgmGroupEnumerationEnd, MgmGroupEnumerationGetNext, MgmGroupEnumerationStart


Multicast Group Manager Enumerations

The MGM API use the following enumeration:

MGM_ENUM_TYPES


MGM_ENUM_TYPES

The MGM_ENUM_TYPES enumeration lists the types of group enumerations that the multicast group manager uses. This structure is used by the MgmGroupEnumerationStart function.

typedef enum _MGM_ENUM_TYPES {
  ANY_SOURCE = 0,
  ALL_SOURCES
} MGM_ENUM_TYPES;

Values

ANY_SOURCE
Enumerate group entries that have at least one source.
ALL_SOURCES
Enumerate all source entries for a group.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Mgm.h.

See Also

MgmGroupEnumerationStart


About Tracing

The following documentation describes the implementation of the common tracing API that provides a uniform mechanism for generating diagnostic output for the Microsoft® Windows NT®/Windows® 2000 Routing and Remote Access Service (RRAS) components as well as any other application that wishes to use tracing. The tracing API 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 to use in calls to the output functions. On this call, tracing 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 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 identifier returned by TraceRegister. When the application no longer requires tracing 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 identifier 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 API. All that is required is that the client define the constant UNICODE before including the header containing definitions for the tracing functions.

This section describes the following tasks:

  • Configuration
  • Console Manipulation


Configuration

In order to enable console tracing, the value EnableConsoleTracing must exist under the registry key

HKEY_LOCAL_MACHINE\SOFTWARE\MICROSOFT\TRACING

and be nonzero. If this value does not exist, or is zero, console tracing is disabled. This value is read when Rtutils.dll is loaded; changes to this value after Rtutils.dll is already loaded will have no effect until the DLL is unloaded and loaded again.

In addition to the preceding "global" value, the registry may also contain values for individual clients. When a client "xyz" calls TraceRegister, tracing searches under the registry key

HKEY_LOCAL_MACHINE\SOFTWARE\MICROSOFT\TRACING\XYZ

for the following values:

  • EnableConsoleTracing: This is a REG_DWORD that defaults to zero; tracing to the console is enabled if this value is nonzero.
  • EnableFileTracing: This is a REG_DWORD that defaults to zero; tracing to a file named XYZ.LOG is enabled if this value is nonzero.
  • 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 %ALLUSERSPROFILE%\Application Data\Microsoft\Windows NT\TracingLogs; this is the directory in which the tracing file is created.

The defaults are used only if the key is found or is 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 tracing 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 API would not attempt to read the registry key for the client. Similarly,

    TraceRegisterEx("abc", TRACE_USE_FILE);

would register the client "abc" to use a file for tracing, bypassing the registry key for the client. However, for console tracing, using TraceRegisterEx still requires that the global EnableConsoleTracing value exist under

HKEY_LOCAL_MACHINE\SOFTWARE\MICROSOFT\TRACING

and be nonzero.


Console Manipulation

The tracing API 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:

TraceDeregister

TraceDump

TraceDumpEx

TracePrintf

TracePrintfEx

TracePuts

TracePutsEx

TraceRegister

TraceRegisterEx

TraceVprintf

TraceVprintfEx


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(
  DWORD dwTraceID  // handle from initial TraceRegister call
);

Parameters

dwTraceID
[in] 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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: RtutIls.idl.
Library: Use Rtutils.lib.

See Also

About Tracing, Tracing Reference, TraceRegister, TracePrintf, TraceVprintf, TracePuts, TraceDump


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(
  DWORD dwTraceID,      // handle from initial TraceRegister call
  LPBYTE lpbBytes,      // pointer to dump buffer
  DWORD dwByteCount,    // number of bytes to dump
  DWORD dwGroupSize,    // size of byte grouping (1,2 or4)
  BOOL bAddressPrefix,  // include memory address toggle
  LPCTSTR lpszPrefix    // prefix
);

Parameters

dwTraceID
[in] Handle returned by the calling service or application's initial TraceRegister call.
lpbBytes
[in] Pointer to the buffer from which the hex dump is to be generated
dwByteCount
[in] Specifies the number of bytes to dump from the buffer.
dwGroupSize
[in] Specifies the byte grouping size of the output. Valid values are 1, 2, or 4.
bAddressPrefix
[in] Specifies the 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
[in] 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. The byte ordering of the dump is dependent on the type of processor. Also note that the last line of the dump is padded with zeroes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: RtutIls.idl.
Library: Use Rtutils.lib.

See Also

About Tracing, Tracing Reference, TraceDumpEx, TraceRegister, TraceDeregister, TracePrintf, TraceVprintf, TracePuts


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(
  DWORD dwTraceID,
  DWORD dwFlags,      // OPTIONAL
  LPBYTE lpbBytes,
  DWORD dwByteCount,
  DWORD dwGroupSize,
  BOOL bAddressPrefix,
  LPCTSTR lpszPrefix
);

Parameters

dwTraceID
[in] Handle returned by the calling service or application's initial TraceRegister call.
dwFlags
[in] Specifies the 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 isgenerated by comparing the high-order word of dwFlags against registry values FileTracingMask and ConsoleTracingMask.
lpbBytes
[in] Pointer to the buffer from which the hex dump is to be generated.
dwByteCount
[in] Specifies the number of bytes to dump from the buffer.
dwGroupSize
[in] Specifies the byte grouping size of the output. Valid values are 1, 2, or 4.
bAddressPrefix
[in] Specifies the 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
[in] 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. The byte ordering of the dump is dependent on the processor. Also note that the last line of the dump is padded with zeroes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: RtutIls.idl.
Library: Use Rtutils.lib.

See Also

About Tracing, Tracing Reference, TraceDump, TraceRegisterEx, TracePrintfEx, TraceVprintfEx, TracePutsEx


TracePrintf

The TracePrintf function outputs tracing information, including the following: calling service or application 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(
  DWORD dwTraceID,     // handle from initial TraceRegister call
  LPCTSTR lpszFormat,  // printf()-style formatting information
  ...                  // one or more optional arguments
);

Parameters

dwTraceID
[in] Handle returned by the calling service or application's initial TraceRegister call.
lpszFormat
[in] Pointer to a null-terminated string that contains printf-style format control information.
...
[in] Specifies one or more optional arguments that depends on the format control specified in lpszFormat.

Return Values

If the function succeeds, TracePrintf returns the number of characters output, excluding the terminating null-character.

If the function fails, the return value is zero. This may also indicate that tracing is disabled in the registry. See Tracing Configuration for more information.

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 is 129:

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: RtutIls.idl.
Library: Use Rtutils.lib.

See Also

About Tracing, Tracing Reference, TracePrintfEx, TraceRegister, TraceDeregister, TraceVprintf, TracePuts, TraceDump


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 the following: calling service or application 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(
  DWORD dwTraceID,     // handle returned by TraceRegister
  DWORD dwFlags,       // flags to control output
  LPCTSTR lpszFormat,  // pointer to printf-style format string
  ...                  // optional args, which depend on
                       // format string.
);

Parameters

dwTraceID
[in] Specifies the handle returned by the calling service or application's initial TraceRegister call.
dwFlags
[in] Specifies optional 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 isgenerated by comparing the high-order word of dwFlags against registry values FileTracingMask and ConsoleTracingMask.
lpszFormat
[in] Pointer to a null-terminated string that contains printf-style format control information.
...
[in] Specifies one or more optional arguments that depends on the format control specified in lpszFormat.

Return Values

If the function is successful, TracePrintfEx returns the number of characters output, excluding the terminating null-character.

If the function fails, the return value is zero. This may indicate that tracing is disabled in the registry. See Tracing Configuration for more information.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: RtutIls.idl.
Library: Use Rtutils.lib.

See Also

About Tracing, Tracing Reference, TracePrintf, TraceRegisterEx, TraceVprintfEx, TracePutsEx, TraceDumpEx


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(
  DWORD dwTraceID,
  LPCTSTR lpszString
);

Parameters

dwTraceID
[in] Handle returned by the calling service or application's initial TraceRegister call.
lpszString
[in] Specifies the string to be output.

Return Value

If the function is successful, TracePuts returns the number of characters output, excluding the terminating null-character.

If the function fails, the return value is zero. This may also indicate that tracing is disabled in the registry. See Tracing Configuration for more information.

Remarks

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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: RtutIls.idl.
Library: Use Rtutils.lib.

See Also

About Tracing, Tracing Reference, TracePutsEx, TraceRegister, TraceDeregister, TracePrintf, TraceVprintf, TraceDump


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(
  DWORD dwTraceID,
  DWORD dwFlags,      // OPTIONAL
  LPCTSTR lpszString
);

Parameters

dwTraceID
[in] Handle returned by the calling service or application's initial TraceRegister call.
dwFlags
[in] Specifies the 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 is generated by comparing the high-order word of dwFlags against registry values FileTracingMask and ConsoleTracingMask.
lpszString
[in] Specifies the string to be output.

Return Values

If the function is successful, TracePuts returns the number of characters output, excluding the terminating null-character.

If the function fails, the return value is zero. This may indicate that tracing is disabled in the registry. See Tracing Configuration for more information.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: RtutIls.idl.
Library: Use Rtutils.lib.

See Also

About Tracing, Tracing Reference, TracePuts, TraceRegisterEx, TracePrintfEx, TraceVprintfEx, TraceDumpEx


TraceRegister

Use the TraceRegister function to register services or applications with the tracing API. Its successful return value is an identifier that provides a handle to subsequent tracing functions available in Windows NT/Windows 2000. This function, or its extended functionality counterpart TraceRegisterEx, must be called before any other tracing functions are called. However, TraceRegister should not be called from within DllMain, the DLL entry-point function.

DWORD TraceRegister(
  LPCTSTR lpszCallerName  // caller name
);

Parameters

lpszCallerName
[in] Pointer to a null-terminated string that contains the service or application name being registered. This is the name with which the service tracing functions identifies the caller.

Return Values

If successful, this function returns 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

TraceDeregister or TraceDeregisterEx should be called when trace functions are no longer needed, in order to free resources.

Upon successful execution of TraceRegister, a configuration for the service or application calling TraceRegister is created and kept in the registry path \System\CurrentControlSet\Services\Tracing\<client name> 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 fails. There are certain values within this key that aremodified 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 is 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, regulates 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 becomes 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.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: RtutIls.idl.
Library: Use Rtutils.lib.

See Also

About Tracing, Tracing Reference, TraceRegisterEx, TraceDeregister, TracePrintf, TraceVprintf, TracePuts, TraceDump


TraceRegisterEx

The TraceRegisterEx function registers services or applications with the tracing API. 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®/Windows® 2000. This function, or its counterpart TraceRegister, must be called before any other tracing functions are called. However, TraceRegisterEx should not be called from within DllMain, the DLL entry-point function.

DWORD TraceRegisterEx(
  LPCTSTR lpszCallerName,
  DWORD dwFlags            // OPTIONAL
);

Parameters

lpszCallerName
[in] Pointer to a null-terminated string that contains the service or application name being registered. This is the name with which the service tracing functions will identify the caller.
dwFlags
[in] Specifies the 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 returns a DWORD to be used as the service or application identifier (handle) for subsequent calls to tracing functions.

Value | Meaning
INVALID_TRACEID | The caller was not registered. Call GetLastError to retrieve the error code.

Remarks

If no flags are passed to TraceRegisterEx (if dwFlags is zero), TraceRegisterEx behaves exactly as TraceRegister.

TraceDeregister or TraceDeregisterEx are called when trace functions are no longer needed, in order to free resources.

Upon successful execution of TraceRegisterEx, configuration for the service or application calling TraceRegisterEx istaken from the parameters passed as dwFlags, and registry reads or writes do not occur. If the value of dwFlags is zero, then a call to TraceRegisterEx behaves exactly as a call to TraceRegister, and initialization and configuration parameters are created and kept in the registry path

\System\CurrentControlSet\Services\Tracing\<client name>

under the HKEY_LOCAL_MACHINE key.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: RtutIls.idl.
Library: Use Rtutils.lib.

See Also

About Tracing, Tracing Reference, TraceRegister, TracePrintfEx, TraceVprintfEx, TracePutsEx, TraceDumpEx


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(
  DWORD dwTraceID,     // handle from initial TraceRegister call
  LPCTSTR lpszFormat,  // printf-style formatting information
  va_list arglist      // prepared list of variable arguments
);

Parameters

dwTraceID
[in] Handle returned by the calling service or application's initial TraceRegister call.
lpszFormat
[in] Pointer to a null-terminated string that contains printf-style format control information.
arglist
[in] Specifies the prepared list of printf()-style arguments that define the format of TraceVprintf output.

Return Values

If the function succeeds, TraceVprintf returns the number of characters output, excluding the terminating null-character.

If the function fails, the return value is zero. This may also indicate that tracing is disabled in the registry. See Tracing Configuration for more information.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: RtutIls.idl.
Library: Use Rtutils.lib.

See Also

About Tracing, Tracing Reference, TraceVprintfEx, TraceRegister, TraceDeregister, TracePrintf, TracePuts, TraceDump


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(
  DWORD dwTraceID,
  DWORD dwFlags,      // OPTIONAL
  LPCTSTR lpszFormat,
  va_list arglist
);

Parameters

dwTraceID
[in] Handle returned by the calling service or application's initial TraceRegister call.
dwFlags
[in] Specifies the flags that control appearance of TraceVprintfEx output. Ensure dwFlags is one or more of the following:
Flag | Meaning
TRACE_NO_STDINFO | Suppresses output of the standard information associated with dwTraceID.
TRACE_USE_MASK | Determines whether file and/or console output is generated by comparing the high-order word of dwFlags against registry values FileTracingMask and ConsoleTracingMask.
TRACE_USE_MSEC | Reports the time with millisecond accuracy.

lpszFormat
[in] Pointer to a null-terminated string that contains printf-style format control information.
arglist
[in] Specifies the prepared list of printf()-style arguments that define the format of TraceVprintf output.

Return Values

If the function is succesful, TraceVprintfEx returns the number of characters output, excluding the terminating null-character.

If the function fails, the return value is zero. This may indicate that tracing is disabled in the registry. See Tracing Configuration for more information.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later. Available as a redistributable for Windows NT 4.0.
Header: RtutIls.idl.
Library: Use Rtutils.lib.

See Also

About Tracing, Tracing Reference, TraceVprintf, TraceRegisterEx, TracePrintfEx, TracePutsEx, TraceDumpEx


Request for Comments

Requests for Comments (RFCs) are an ongoing series of documents that discuss the Internet and Internet-related technologies. Particular RFCs are identified by number. The following RFCs are referenced in the Routing and Remote Access Service (RRAS) section of the Platform SDK. For more information about RFCs and how to locate copies of a particular RFC, see http://www.rfc-editor.org/rfc.html.

Request for Comments

RFC 1171 – The Point-to-Point Protocol

RFC 1172 – The PPP Initial Configuration Options, July, 1990

RFC 1267 – A Border Gateway Protocol 3 (BGP-3), October 1991

RFC 1268 – Application of the Border Gateway protocol in the Internet, October, 1991

RFC 1354 – IP Forwarding Table MIB, July, 1992

RFC 1570 – PPP LCP Extensions, January, 1994

RFC 1700 – Assigned Numbers, October, 1994

RFC 1962 – The PPP Compression Control Protocol (CCP)

RFC 1974 – PPP Stac LZS Compression Protocol, August 1996

RFC 1990 – The PPP Multilink Protocol (MP), August 1996

RFC 2118 – Microsoft Point-To-Point Compression (MPPC) Protocol

RFC 2284 – PPP Extensible Authentication Protocol, March 1998

RFC 2484 – PPP LCP Internationalization Configuration Option, January 1999

RFC 2548 Microsoft Vendor-specific RADIUS Attributes

RFC 2715 – Interoperability Rules for Multicast Routing Protocols, July 1998

RFC 2865 – Remote Authentication Dial In User Service (RADIUS), June 2000

RFC 2866 Radius Accounting, June 2000

RFC 2868 Radius Attributes for Tunnel Protocol Support, June 2000

RFC 2869 – RADIUS Extensions, June 2000

Internet Drafts

Draft Radius Tunnel 09 – RADIUS Attributes for Tunnel Protocol Support, August 1999. Updated by RFC 2868.

Draft Radius Accounting v2 05 – RADIUS Accounting, February, 2000. Updated by RFC 2866.

Draft Radius MSCHAP Attr 01 – RADIUS Attributes for MS-CHAP Support, November, 1997


Glossary

This glossary contains definitions for terms used in the documentation of the Routing and Remote Access Services (RRAS) for the Microsoft® Platform Software Development Kit (PSDK).

RRAS uses its own collection of terms. Please read the following list of definitions carefully in order to understand what is meant when these terms occur in the RRAS documentation.

Providing a comprehensive list of routing terms is outside the scope of this glossary.

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z


A

aged out
Also, aged out of the cache. In RRAS, a route is aged out when it is removed from the routing table after a specified period of time.
authentication
Authentication is the process of verifying that a user is who he or she claims to be. Authentication is typically performed using a user name and password.
autonomous system (AS)
An autonomous system is a group of routers that share a single administrative policy. These routers all use the same routing protocol to communicate (called an interior gateway protocol). See also exterior gateway protocol.
autostatic route
An autostatic route is a route that is dynamically obtained from a routing protocol. After a route is obtained in this manner, it behaves as a static route.


B

best route
The best route is an optimal route to a network destination, based on a specified criteria. This concept is based on the fact that there is a certain "cost" involved in taking a route across a network.

The best route to take is the one with the lowest cost, based on a specified criteria. This criteria can include the number of networks crossed, the type of network crossed (for example, public or private), or a monetary or bandwidth limit.

border gateway protocol (BGP)
BGP is an exterior gateway protocol. BGP forwards information between two autonomous system. It is defined in RFC 1267 and RFC 1268.
brute-force attack
An attempt to compromise a cipher by trying every possible.


C

Cyclic Redundancy Check (CRC)
A CRC is a numerical value related to a block of data. This value provides information that allows an application to determine if the data has been modified. A CRC is similar to a checksum, but is considered a stronger error-checking mechanism.
Compression Control Protocol (CCP)
The compression control protocol (CCP) allows two computers that communicate through PPP to negotiate compatible algorithms for sending and receiving compressed PPP frames. The two computers may not use CCP until the network-control-protocol phase of the PPP connection.

For more information see RFC 1962. Also see PPP_CCP_INFO and RASPPPCCP.


D

dictionary attack
A type of brute-force attack in which the attacker attempts to guess a password by trying every password in a dictionary.


E

exterior gateway protocol (EGP)
An exterior gateway protocol (EGP) distributes routing information to the routers that connect autonomous systems to a backbone. See also interior gateway protocol.


I

interior gateway protocol (IGP)
An interior gateway protocol forwards routing information to the other routers in the autonomous system. See also exterior gateway protocol.


P

point-to-multipoint interface
The Multicast Group Manager technology uses this term to mean an interface that provides communication between a single source and a single destination, such as a PPP link.
point-to-point interface
The Multicast Group Manager technology uses this term to mean an interface that provides communication between a single host and multiple destinations. Point-to-multipoint interfaces can be thought of as a collection of point-to-point links with a single termination, such as an ATM link.


S

static route
A static route is a route that is manually added to the routing table. Compare to autostatic route.


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.