home *** CD-ROM | disk | FTP | other *** search
/ Magazyn Internet 2000 May / MICD_2000_05.iso / CBuilder5 / INSTALL / DATA1.CAB / Program_Built_Files / Include / rtm.h < prev    next >
C/C++ Source or Header  |  2000-02-01  |  29KB  |  820 lines
  1. /*++
  2.  
  3. Copyright (c) 1995-1999 Microsoft Corporation
  4.  
  5. Module Name:
  6.  
  7.     rtm.h
  8.  
  9. Abstract:
  10.     Interface for Routing Table Manager DLL
  11.  
  12. --*/
  13.  
  14. #ifndef __ROUTING_RTM_H__
  15. #pragma option push -b -a8 -pc -A- /*P_O_Push*/
  16. #define __ROUTING_RTM_H__
  17.  
  18. #if _MSC_VER > 1000
  19. #pragma once
  20. #endif
  21.  
  22. #pragma warning(disable:4201)
  23.  
  24. #ifdef __cplusplus
  25. extern "C" {
  26. #endif
  27.  
  28. // Currently supported protocol families
  29. #define RTM_PROTOCOL_FAMILY_IPX            0
  30. #define RTM_PROTOCOL_FAMILY_IP            1
  31.  
  32. // Error messages specific to Routing Table Manager
  33. #define ERROR_MORE_MESSAGES                ERROR_MORE_DATA
  34. #define ERROR_CLIENT_ALREADY_EXISTS        ERROR_ALREADY_EXISTS
  35. #define ERROR_NO_MESSAGES                ERROR_NO_MORE_ITEMS
  36.  
  37. #define ERROR_NO_MORE_ROUTES            ERROR_NO_MORE_ITEMS
  38. #define ERROR_NO_ROUTES                    ERROR_NO_MORE_ITEMS
  39. #define ERROR_NO_SUCH_ROUTE                ERROR_NO_MORE_ITEMS
  40.  
  41. // Protocol family dependent network number structures
  42. typedef struct _IPX_NETWORK {
  43.     DWORD    N_NetNumber;
  44.     } IPX_NETWORK, *PIPX_NETWORK;
  45.  
  46.  
  47. typedef struct _IP_NETWORK {
  48.     DWORD    N_NetNumber;
  49.     DWORD    N_NetMask;
  50.     } IP_NETWORK, *PIP_NETWORK;
  51.  
  52.  
  53.  
  54. // Protocol family dependent next hop router address structures
  55. typedef struct _IPX_NEXT_HOP_ADDRESS {
  56.     BYTE            NHA_Mac[6];
  57.     } IPX_NEXT_HOP_ADDRESS, *PIPX_NEXT_HOP_ADDRESS;
  58.  
  59. typedef IP_NETWORK IP_NEXT_HOP_ADDRESS, *PIP_NEXT_HOP_ADDRESS;
  60.  
  61.  
  62. // Protocol family dependent specific data structures
  63. typedef struct _IPX_SPECIFIC_DATA {
  64.     DWORD        FSD_Flags;    // should be set to 0 if no flags are defined
  65.     USHORT        FSD_TickCount;    // ticks to destination network
  66.     USHORT        FSD_HopCount;    // hops to destination network
  67.     } IPX_SPECIFIC_DATA, *PIPX_SPECIFIC_DATA;
  68.  
  69. // The following flags are defined for the IPX family dependent Flags field
  70.  
  71. #define   IPX_GLOBAL_CLIENT_WAN_ROUTE    0x00000001
  72.  
  73.  
  74. typedef    struct _IP_SPECIFIC_DATA
  75. {
  76.     DWORD       FSD_Type;               // One of : other,invalid,local,remote (1-4)
  77.     DWORD       FSD_Policy;             // See RFC 1354
  78.     DWORD       FSD_NextHopAS;          // Autonomous System Number of Next Hop
  79.     DWORD       FSD_Priority;           // For comparing Inter Protocol Metrics
  80.     DWORD       FSD_Metric;             // For comparing Intra Protocol Metrics
  81.     DWORD        FSD_Metric1;            // Protocol specific metrics for MIB II
  82.     DWORD        FSD_Metric2;            // conformance. MIB II agents will not
  83.     DWORD        FSD_Metric3;            // display FSD_Metric, they will only
  84.     DWORD        FSD_Metric4;            // display Metrics1-5, so if you want your
  85.     DWORD        FSD_Metric5;            // metric displayed, put it in one of these
  86.                                         // fields ALSO (It has to be in the
  87.                                         // FSD_Metric field always). It is up to the
  88.                                         // implementor to keep the fields consistent
  89.     DWORD       FSD_Flags;              // Flags defined below
  90. } IP_SPECIFIC_DATA, *PIP_SPECIFIC_DATA;
  91.  
  92. //
  93. // All routing protocols MUST clear out the FSD_Flags field.
  94. // If RTM notifies a protocol of a route and that route is marked
  95. // invalid, the protocols MUST disregard this route. A protocol
  96. // may mark a route as invalid, if it does not want the route to
  97. // be indicated to other protocols or set to the stack. e.g. RIPv2
  98. // marks summarized routes as INVALID and uses the RTM purely as
  99. // a store for such routes. These routes are not considered when
  100. // comparing metrics etc to decide the "best" route
  101. //
  102.  
  103. #define IP_VALID_ROUTE      0x00000001
  104.  
  105. #define ClearRouteFlags(pRoute)         \
  106.     ((pRoute)->RR_FamilySpecificData.FSD_Flags = 0x00000000)
  107.  
  108.  
  109. #define IsRouteValid(pRoute)            \
  110.     ((pRoute)->RR_FamilySpecificData.FSD_Flags & IP_VALID_ROUTE)
  111.  
  112.  
  113.  
  114. #define SetRouteValid(pRoute)          \
  115.     ((pRoute)->RR_FamilySpecificData.FSD_Flags |= IP_VALID_ROUTE)
  116.  
  117. #define ClearRouteValid(pRoute)        \
  118.     ((pRoute)->RR_FamilySpecificData.FSD_Flags &= ~IP_VALID_ROUTE)
  119.  
  120.  
  121.  
  122.  
  123. #define IsRouteNonUnicast(pRoute)      \
  124.     (((DWORD)((pRoute)->RR_Network.N_NetNumber & 0x000000FF)) >= ((DWORD)0x000000E0))
  125.  
  126. #define IsRouteLoopback(pRoute)        \
  127.     ((((pRoute)->RR_Network.N_NetNumber & 0x000000FF) == 0x0000007F) ||     \
  128.         ((pRoute)->RR_NextHopAddress.N_NetNumber == 0x0100007F))
  129.  
  130.  
  131. // Protocol dependent specific data structure
  132. typedef struct _PROTOCOL_SPECIFIC_DATA {
  133.     DWORD        PSD_Data[4];
  134.     } PROTOCOL_SPECIFIC_DATA, *PPROTOCOL_SPECIFIC_DATA;
  135.  
  136.     
  137.  
  138.  
  139. #define DWORD_ALIGN(type,field)    \
  140.     union {                        \
  141.         type    field;            \
  142.         DWORD    field##Align;    \
  143.         }
  144.  
  145. // Standard header associated with all types of routes
  146. #define ROUTE_HEADER                                 \
  147. DWORD_ALIGN (                                        \
  148.     FILETIME,                    RR_TimeStamp);        \
  149.     DWORD                        RR_RoutingProtocol;    \
  150.     DWORD                        RR_InterfaceID;        \
  151. DWORD_ALIGN (                                        \
  152.     PROTOCOL_SPECIFIC_DATA,        RR_ProtocolSpecificData)
  153.  
  154.     // Ensure dword aligment of all fields
  155.  
  156. // Protocol family dependent route entries
  157. // (intended for use by protocol handlers to pass paramerters
  158. // to and from RTM routines)
  159. typedef struct _RTM_IPX_ROUTE {
  160.     ROUTE_HEADER;
  161. DWORD_ALIGN (
  162.     IPX_NETWORK,                RR_Network);
  163. DWORD_ALIGN (
  164.     IPX_NEXT_HOP_ADDRESS,    RR_NextHopAddress);
  165. DWORD_ALIGN (
  166.     IPX_SPECIFIC_DATA,        RR_FamilySpecificData);
  167.     } RTM_IPX_ROUTE, *PRTM_IPX_ROUTE;
  168.  
  169. typedef struct _RTM_IP_ROUTE {
  170.     ROUTE_HEADER;
  171. DWORD_ALIGN (
  172.     IP_NETWORK,                RR_Network);
  173. DWORD_ALIGN (
  174.     IP_NEXT_HOP_ADDRESS,    RR_NextHopAddress);
  175. DWORD_ALIGN (
  176.     IP_SPECIFIC_DATA,        RR_FamilySpecificData);
  177.     } RTM_IP_ROUTE, *PRTM_IP_ROUTE;
  178.  
  179.  
  180.  
  181. // RTM route change message flags
  182.     // Flags to test the presence of route change information
  183.     // in the buffers filled by RTM routines
  184. #define RTM_CURRENT_BEST_ROUTE            0x00000001
  185. #define RTM_PREVIOUS_BEST_ROUTE            0x00000002
  186.  
  187.     // Flags that convey what acutally happened
  188. #define RTM_NO_CHANGE        0
  189. #define RTM_ROUTE_ADDED        RTM_CURRENT_BEST_ROUTE
  190. #define RTM_ROUTE_DELETED    RTM_PREVIOUS_BEST_ROUTE
  191. #define RTM_ROUTE_CHANGED    (RTM_CURRENT_BEST_ROUTE|RTM_PREVIOUS_BEST_ROUTE)
  192.  
  193. // Enumeration flags limit that enumerations of routes in the table
  194. // to only entries with the specified field(s)
  195. #define RTM_ONLY_THIS_NETWORK           0x00000001
  196. #define RTM_ONLY_THIS_INTERFACE            0x00000002
  197. #define RTM_ONLY_THIS_PROTOCOL            0x00000004
  198. #define RTM_ONLY_BEST_ROUTES            0x00000008
  199.  
  200. #define RTM_PROTOCOL_SINGLE_ROUTE        0x00000001
  201.  
  202. /*++
  203. *******************************************************************
  204.  
  205.     R t m R e g i s t e r C l i e n t
  206.  
  207. Routine Description:
  208.     Registers client as a handler of specified protocol.
  209.     Establishes route change notification mechanism for the client
  210.  
  211. Arguments:
  212.     ProtocolFamily - protocol family of the routing protocol to register
  213.     RoutingProtocol - which routing protocol is handled by the client
  214.     ChangeEvent - this event will be signalled when best route to any
  215.                     network in the table changes
  216.     Flags - flags that enable special features applied to routes maintained
  217.             by the protocol:
  218.                 RTM_PROTOCOL_SINGLE_ROUTE - RTM will only keep
  219.                     one route per destination network for the protocol
  220. Return Value:
  221.     Handle to be used to identify the client in calls made to Rtm
  222.     NULL - operation failed, call GetLastError() to get reason of
  223.     failure:
  224.         ERROR_INVALID_PARAMETER - specified protocol family is not supported
  225.         ERROR_CLIENT_ALREADY_EXISTS - another client already registered
  226.                                 to handle specified protocol
  227.         ERROR_NO_SYSTEM_RESOURCES - not enough resources to perform the opertaion,
  228.                             try again later
  229.         ERROR_NOT_ENOUGH_MEMORY - not enough memory to allocate client
  230.                              control block
  231.  
  232. *******************************************************************
  233. --*/
  234. HANDLE WINAPI
  235. RtmRegisterClient (
  236.     IN DWORD          ProtocolFamily,
  237.     IN DWORD          RoutingProtocol,
  238.     IN HANDLE        ChangeEvent OPTIONAL,
  239.     IN DWORD        Flags
  240.     );
  241.  
  242.  
  243. /*++
  244. *******************************************************************
  245.  
  246.     R t m D e r e g i s t e r C l i e n t
  247.  
  248. Routine Description:
  249.     Deregister client and frees associated resources (including all
  250.     routes added by the client).
  251.  
  252. Arguments:
  253.     ClientHandle - handle that identifies the client to deregister from RTM
  254. Return Value:
  255.     NO_ERROR - client was deregisterd and resources were disposed OK.
  256.     ERROR_INVALID_HANDLE - client handle is not a valid RTM handle
  257.     ERROR_NO_SYSTEM_RESOURCES - not enough resources to complete the operation,
  258.                             try again later
  259.  
  260. *******************************************************************
  261. --*/
  262. DWORD WINAPI
  263. RtmDeregisterClient (
  264.     IN HANDLE        ClientHandle
  265.     );
  266.  
  267.  
  268. /*++
  269. *******************************************************************
  270.  
  271.     R t m D e q u e u e R o u t e C h a n g e M e s s a g e
  272.  
  273. Routine Description:
  274.     Dequeues and returns first route change message from the queue
  275.     associated with the client
  276.  
  277. Arguments:
  278.     ClientHandle - handle that identifies the client for which the opertation
  279.                     is performed
  280.     Flags - identifies what kind of change the message is about and what
  281.             information was palced into the provided buffers:
  282.         RTM_ROUTE_ADDED - first route was added for a destination network,
  283.                             CurBestRoute is filled with added route info
  284.         RTM_ROUTE_DELETED - the only route available for a destination
  285.                             network was deleted, PrevBestRoute is filled
  286.                             with deleted route info
  287.         RTM_ROUTE_CHANGED - there was a change in any of the following
  288.                             parameters of the BEST route to a destination
  289.                             network:
  290.                                 RoutingProtocol,
  291.                                 InterfaceID,
  292.                                 Metric,
  293.                                 NextHopAddress,
  294.                                 FamilySpecificData.
  295.                             PrevBestRoute contains the route info as it was
  296.                             before the change, CurBestRoute contains current
  297.                             best route info.
  298.                 Note that the route change message can be generated
  299.                 both as result of protocol adding/deleting the route
  300.                 that becomes/was the best and changing best route parameters
  301.                 such that route becomes/no longer is the best route.
  302.     CurBestRoute - buffer to receive current best route info (if any)
  303.     PrevBestRoute - buffer to receive previous best route info (if any)
  304. Return Value:
  305.     NO_ERROR - this was the last (or only) message in the client's
  306.                  queue (event is reset)
  307.     ERROR_MORE_MESSAGES - there are more messages awaiting client,
  308.                 this call should be made again as soon as possible
  309.                 to let RTM free resources associated with unprocessed
  310.                 messages
  311.     ERROR_NO_MESSAGES - there are no messages in the clients queue,
  312.                 this was an unsolicited call (event is reset)
  313.     ERROR_INVALID_HANDLE - client handle is not a valid RTM handle
  314.     ERROR_NO_SYSTEM_RESOURCES - not enough resources to perform the operation,
  315.                             try again later
  316.  
  317. *******************************************************************
  318. --*/
  319. DWORD WINAPI
  320. RtmDequeueRouteChangeMessage (
  321.     IN    HANDLE        ClientHandle,
  322.     OUT    DWORD        *Flags,
  323.     OUT PVOID        CurBestRoute    OPTIONAL,
  324.     OUT    PVOID        PrevBestRoute    OPTIONAL
  325.     );
  326.  
  327.  
  328.  
  329. /*++
  330. *******************************************************************
  331.  
  332.     R t m A d d R o u t e
  333.  
  334. Routine Description:
  335.     Adds or updates existing route entry and generates route change
  336.     message if best route to a destination network has changed as the
  337.     result of this operation.
  338.     Note that route change message is not sent to the client that
  339.     makes this change, but rather relevant information is returned
  340.     by this routine directly.
  341.  
  342. Arguments:
  343.     ClientHandle - handle that identifies the client for which the opertation
  344.                     is performed, it also supplies RoutingProtocol field
  345.                     of the new/updated route
  346.     Route - route to be added/updated.
  347.             The following fields of protocol family dependent
  348.             RTM_??_ROUTE structure are used to construct/update
  349.             route entry:
  350.         RR_Network:            destination network
  351.         RR_InterfaceID:     id of interface through which route was received
  352.         RR_NextHopAddress:    address of next hop router
  353.         RR_FamilySpecificData: data specific to protocol's family
  354.         RR_ProtocolSpecificData: data specific to protocol which supplies the
  355.                             route (subject to size limitation defined by
  356.                             PROTOCOL_SPECIFIC_DATA structure above)
  357.         RR_TimeStamp:        current time, which is actually read from system
  358.                             timer (need not be supplied)
  359.         Note that combination of
  360.             RoutingProtocol,
  361.             Network,
  362.             InterfaceID, and
  363.             NextHopAddress
  364.                                 uniquely identifies route entry in the table.
  365.         New entry is created if one of these fields does not match those of
  366.         an existing entry, otherwise existing entry is changed (see also
  367.         ReplaceEntry flag below).
  368.  
  369.         Regardless of whether new entry is created or old one is updated,
  370.         this operation will generate a route change message if affected
  371.         route becomes/is/no longer is the best route to a destination network
  372.         and at least one of the following parameters in the best route is
  373.         changed as the result of this operation:
  374.                                 RoutingProtocol,
  375.                                 InterfaceID,
  376.                                 NextHopAddress,
  377.                                 FamilySpecificData.
  378.     TimeToLive -  how long route should be kept in the table in seconds.
  379.                 Pass INFINITE if route is to be kept until deleted explicitly
  380.         Note the current limit for TimeToLive is 2147483 sec (24+ days).
  381.     Flags - returns what change message (if any) will be generated by the
  382.             RTM as the result of this addition/update and identifies what
  383.             information was palced into the provided buffers:
  384.         RTM_NO_CHANGE - this was an update that either did not change any of
  385.                         the significant route parameters (described above)
  386.                         or the route entry affected is not the best
  387.                         to the destination network
  388.         RTM_ROUTE_ADDED - the route added is the first known route for a
  389.                             destination network,
  390.                             CurBestRoute is filled with added route info
  391.         RTM_ROUTE_CHANGED - there was a change in any of the significant
  392.                             parameters of the BEST route to a destination
  393.                             network as the result if this operation.
  394.                             PrevBestRoute contains the route info as it was
  395.                             before the change, CurBestRoute contains current
  396.                             best route info.
  397.                 Note the the CurBestRoute does not neccessarily the same
  398.                 as added route, because if update causes route metric
  399.                 to change, another route entry may become the best for
  400.                 a given destination and its info will be returned in
  401.                 CurBestRoute buffer.  PrevBestRoute buffer in the latter
  402.                 case will contain route entry as it was before this operation
  403.                 was performed.
  404.     CurBestRoute - buffer to receive current best route info (if any)
  405.     PrevBestRoute - buffer to receive previous best route info (if any)
  406. Return Value:
  407.     NO_ERROR                 - route was added/updated OK
  408.     ERROR_INVALID_PARAMETER - route contains invalid parameter
  409.     ERROR_INVALID_HANDLE - client handle is not a valid RTM handle
  410.     ERROR_NOT_ENOUGH_MEMORY - route could not be adeed because of memory
  411.                                 allocation problem
  412.     ERROR_NO_SYSTEM_RESOURCES - not enough resources to perform the operation,
  413.                             try again later
  414.  
  415. *******************************************************************
  416. --*/
  417. DWORD WINAPI
  418. RtmAddRoute (
  419.     IN HANDLE        ClientHandle,
  420.     IN PVOID        Route,
  421.     IN DWORD        TimeToLive,
  422.     OUT DWORD        *Flags,
  423.     OUT PVOID        CurBestRoute OPTIONAL,
  424.     OUT PVOID        PrevBestRoute OPTIONAL
  425.     );
  426.  
  427.  
  428. /*++
  429. *******************************************************************
  430.  
  431.     R t m D e l e t e R o u t e
  432.  
  433. Routine Description:
  434.     Deletes existing route entry and generates route change
  435.     message if best route to a destination network has changed as the
  436.     result of this operation.
  437.     Note that route change message is not sent to the client that
  438.     makes this change, but rather relevant information is returned
  439.     by this routine directly.
  440.  
  441. Arguments:
  442.     ClientHandle - handle that identifies the client for which the opertation
  443.                     is performed, it also supplies RoutingProtocol field
  444.                     of the route to be deleted
  445.     Route - route to be deleted.
  446.             The following fields of protocol family dependent
  447.             RTM_??_ROUTE structure are used to identify
  448.             route entry to be deleted:
  449.         RR_Network:            destination network
  450.         RR_InterfaceID:     id of interface through which route was received
  451.         RR_NextHopAddress:    address of next hop router
  452.  
  453.         If the deleted entry represented the best route to a destination
  454.         network, this operation will generate route change message
  455.     Flags - returns what change message (if any) will be generated by the
  456.             RTM as the result of this deletion and identifies what
  457.             information was palced into the provided buffer:
  458.         RTM_NO_CHANGE - the deleted route did not affect best route to
  459.                         any destination network (there is another entry that
  460.                         represents route to the same destination nework and
  461.                         it has better metric)
  462.         RTM_ROUTE_DELETED - the deleted route was the only route avaliable
  463.                             for the destination network
  464.         RTM_ROUTE_CHANGED - after this route was deleted another route
  465.                         became the best to the destination network,
  466.                         CurBestRoute will be filled with that route info
  467.     CurBestRoute - buffer to receive current best route info (if any)
  468. Return Value:
  469.     NO_ERROR                 - route was deleted OK
  470.     ERROR_INVALID_PARAMETER - route contains invalid parameter
  471.     ERROR_INVALID_HANDLE - client handle is not a valid RTM handle
  472.     ERROR_NO_SUCH_ROUTE - there is no entry in the table that
  473.                         has specified parameters
  474.     ERROR_NO_SYSTEM_RESOURCES - not enough resources to perform the operation,
  475.                             try again later
  476.  
  477. *******************************************************************
  478. --*/
  479. DWORD WINAPI
  480. RtmDeleteRoute (
  481.     IN HANDLE        ClientHandle,
  482.     IN PVOID        Route,
  483.     OUT    DWORD        *Flags,
  484.     OUT PVOID        CurBestRoute OPTIONAL
  485.     );
  486.  
  487.  
  488.  
  489. /*++
  490. *******************************************************************
  491.  
  492.     R t m I s R o u t e
  493.  
  494. Routine Description:
  495.     Checks if route exists to specified network and returns best
  496.     route info
  497.  
  498. Arguments:
  499.     ProtocolFamily - identifies protocol family of route of interest
  500.     Network - contains protocol family dependent network number data
  501.             (as defined by ??_NETWORK structures above)
  502.     BestRoute - buffer to receive current best route info (if any)
  503. Return Value:
  504.     TRUE - route to network of interest exists
  505.     FALSE - not route exist or operation failed, call GetLastError()
  506.     to obtain reason of failure:
  507.         NO_ERROR                 - operation succeded but not route exists
  508.         ERROR_INVALID_PARAMETER - input parameter(s) is invalid (unsupported
  509.                                     protocol family)
  510.         ERROR_NO_SYSTEM_RESOURCES - not enough resources to perform the operation,
  511.                             try again later
  512.  
  513. *******************************************************************
  514. --*/
  515. BOOL WINAPI
  516. RtmIsRoute (
  517.     IN     DWORD        ProtocolFamily,
  518.     IN     PVOID       Network,
  519.     OUT    PVOID         BestRoute OPTIONAL
  520.     );
  521.  
  522.     
  523. /*++
  524. *******************************************************************
  525.  
  526.     R t m G e t N e t w o r k C o u n t
  527.  
  528. Routine Description:
  529.     Returns number of networks that RTM has routes to.
  530.  
  531. Arguments:
  532.     ProtocolFamily - identifies protocol family of interest
  533. Return Value:
  534.     Number of known networks
  535.     0 if no routes are availabel in the table or operation failed,
  536.     call GetLastError () to get reason of failure:
  537.         NO_ERROR - operation succeded but no routes available
  538.         ERROR_INVALID_PARAMETER - input parameter is invalid (unsupported
  539.                                     protocol family)
  540.  
  541. *******************************************************************
  542. --*/
  543. ULONG WINAPI
  544. RtmGetNetworkCount (
  545.     IN    DWORD        ProtocolFamily
  546.     );
  547.  
  548. /*++
  549. *******************************************************************
  550.  
  551.     R t m G e t R o u t e A g e
  552.  
  553. Routine Description:
  554.     Returns route age (time since it was created or updated) in seconds
  555.     Route structure must have been recently filled by RTM for this to
  556.     return valid results (route age is actually computed from
  557.     RR_TimeStamp field)
  558.  
  559. Arguments:
  560.     Route - protocol family dependent route data (RTM_??_ROUTE data
  561.             structure) that was obtained from RTM (returned by
  562.             its routines)
  563. Return Value:
  564.     Route age in seconds
  565.     INFINITE - if content of route is invalid (GetLastError () returns
  566.         ERROR_INVALID_PARAMETER)
  567.  
  568. *******************************************************************
  569. --*/
  570. ULONG WINAPI
  571. RtmGetRouteAge (
  572.     IN PVOID        Route
  573.     );
  574.  
  575.  
  576.  
  577.  
  578.  
  579. /*++
  580. *******************************************************************
  581.  
  582.     R t m C r e a t e E n u m e r a t i o n H a n d l e
  583.  
  584. Routine Description:
  585.     Creates a handle that will allow the caller to use fast and change
  586.     tolerant enumeration API to scan through all routes or a subset of them
  587.     known to the RTM. Note that scans performed by this API do not return
  588.     routes in any particular order.
  589.  
  590. Arguments:
  591.     ProtocolFamily - identifies protocol family of interest
  592.     EnumerationFlags - limit routes returned by enumeration API to a subset
  593.                         members of which have same values in the fields
  594.                         specified by the flags as in CriteriaRoute
  595.                         (RTM_ONLY_BEST_ROUTES does not require a criterion)
  596.     CriteriaRoute - protocol family dependent structure (RTM_??_ROUTE) with
  597.                     set values in fields that correspond to EnumerationFlags
  598. Return Value:
  599.     Handle that can be used with enumeration API below
  600.     NULL no routes exists with specified criteria or operation failed,
  601.             call GetLastError () to get reason of failure:
  602.         ERROR_NO_ROUTES - no routes exist with specified criteria
  603.         ERROR_INVALID_PARAMETER - input parameter(s) is invalid (unsupported
  604.                     protocol family, invalid enumeration flag, etc)
  605.         ERROR_NOT_ENOUGH_MEMORY - handle could not be created because of memory
  606.                                 allocation problem
  607.         ERROR_NO_SYSTEM_RESOURCES - not enough resources to perform the operation,
  608.                             try again later
  609.  
  610. *******************************************************************
  611. --*/
  612. HANDLE WINAPI
  613. RtmCreateEnumerationHandle (
  614.     IN    DWORD        ProtocolFamily,
  615.     IN    DWORD        EnumerationFlags,
  616.     IN    PVOID        CriteriaRoute
  617.     );
  618.  
  619.  
  620. /*++
  621. *******************************************************************
  622.  
  623.     R t m E n u m e r a t e G e t N e x t R o u t e
  624.  
  625. Routine Description:
  626.     Returns next route entry in enumeration started by
  627.     RtmCreateEnumerationHandle.
  628.  
  629. Arguments:
  630.     EnumerationHandle - handle that identifies enumeration
  631.     Route - buffer (RTM_??_ROUTE structure) that receives next
  632.             route in enumeration
  633. Return Value:
  634.     NO_ERROR - next availbale route was placed in the buffer
  635.     ERROR_NO_MORE_ROUTES - no more routes exist with soecified criteria
  636.     ERROR_INVALID_HANDLE - enumeration handle is not a valid RTM handle
  637.     ERROR_NO_SYSTEM_RESOURCES - not enough resources to perform the operation,
  638.                             try again later
  639.  
  640. *******************************************************************
  641. --*/
  642. DWORD WINAPI
  643. RtmEnumerateGetNextRoute (
  644.     IN  HANDLE        EnumerationHandle,
  645.     OUT PVOID        Route
  646.     );
  647.  
  648. /*++
  649. *******************************************************************
  650.  
  651.     R t m C l o s e E n u m e r a t i o n H a n d l e
  652.  
  653. Routine Description:
  654.     Terminates enumerationand frees associated resources
  655.  
  656. Arguments:
  657.     EnumerationHandle - handle that identifies enumeration
  658. Return Value:
  659.     NO_ERROR - enumeration was termineted ok
  660.     ERROR_INVALID_HANDLE - enumeration handle is not a valid RTM handle
  661.     ERROR_NO_SYSTEM_RESOURCES - not enough resources to perform the operation,
  662.                             try again later
  663.  
  664. *******************************************************************
  665. --*/
  666. DWORD WINAPI
  667. RtmCloseEnumerationHandle (
  668.     IN HANDLE        EnumerationHandle
  669.     );
  670.  
  671.  
  672. /*++
  673. *******************************************************************
  674.  
  675.     R t m B l o c k D e l e t e R o u t e s
  676.  
  677. Routine Description:
  678.     Deletes all routes in subset specified by enumeration flags and
  679.     corresponding criteria.  This operation can only be performed by
  680.     the registered client and applies only to routes added by this
  681.     client.
  682.     Route change messages will be generated for deleted routes that
  683.     were the best
  684. Arguments:
  685.     ClientHandle - handle that identifies the client and routing protocol
  686.                         of routes to be deleted
  687.     EnumerationFlags - further limit subset of routes being deleted to only
  688.                         those that have same values in the fields
  689.                         specified by the flags as in CriteriaRoute
  690.         Note that only RTM_ONLY_THIS_NETWORK and RTM_ONLY_THIS_INTERFACE
  691.         can be used (RTM_ONLY_BEST_ROUTES does not apply because best
  692.         route designation is adjusted as routes are deleted and
  693.         all routes will be deleted anyway)
  694.     CriteriaRoute - protocol family dependent structure (RTM_??_ROUTE) with
  695.                     set values in fields that correspond to EnumerationFlags
  696. Return Value:
  697.     NO_ERROR - routes were deleted ok
  698.     ERROR_NO_ROUTES - no routes exist that match specified criteria
  699.     ERROR_INVALID_HANDLE - client handle is not a valid RTM handle
  700.     ERROR_NOT_ENOUGH_MEMORY - could not allocate memory to perform
  701.                         the operation
  702.     ERROR_NO_SYSTEM_RESOURCES - not enough resources to perform the operation,
  703.                             try again later
  704.  
  705. *******************************************************************
  706. --*/
  707. DWORD WINAPI
  708. RtmBlockDeleteRoutes (
  709.     IN HANDLE        ClientHandle,
  710.     IN DWORD        EnumerationFlags,
  711.     IN PVOID        CriteriaRoute
  712.     );
  713.  
  714. /*++
  715. *******************************************************************
  716.  
  717.     R t m G e t F i r s t R o u t e
  718.  
  719. Routine Description:
  720.     Returns first route in the NetworkNumber.RoutingProtocol.InterfaceID.
  721.     NextHopAddress order from the subset specifed by the enumeration flags.
  722.     Note that this operation may consume significant processing time because
  723.     first all recently changed routes will have to be merged into the
  724.     ordered list, and this list will then have to be traversed to locate
  725.     the route of interest.
  726.  
  727. Arguments:
  728.     ProtocolFamily - identifies protocol family of interest
  729.     EnumerationFlags - limit routes returned by enumeration API to a subset
  730.                         members of which have same values in the fields
  731.                         specified by the flags as in CriteriaRoute
  732.                         (RTM_ONLY_BEST_ROUTES does not require a criterion)
  733.     Route - protocol family dependent structure (RTM_??_ROUTE) with
  734.                     set values in fields that correspond to EnumerationFlags
  735.                     on INPUT and first route that matches specified
  736.                     criteria on OUTPUT
  737. Return Value:
  738.     NO_ERROR - matching route was found
  739.     ERROR_NO_ROUTES - no routes exist with specified criteria
  740.     ERROR_INVALID_PARAMETER - input parameter(s) is invalid (unsupported
  741.                     protocol family, invalid enumeration flag, etc)
  742.     ERROR_NO_SYSTEM_RESOURCES - not enough resources to perform the operation,
  743.                             try again later
  744.  
  745. *******************************************************************
  746. --*/
  747. DWORD WINAPI
  748. RtmGetFirstRoute (
  749.     IN    DWORD        ProtocolFamily,
  750.     IN    DWORD        EnumerationFlags,
  751.     IN OUT PVOID     Route
  752.     );
  753.  
  754. #define RtmGetSpecificRoute(ProtocolFamily,Route)        \
  755.         RtmGetFirstRoute(ProtocolFamily,                \
  756.                         RTM_ONLY_THIS_NETWORK            \
  757.                             | RTM_ONLY_THIS_PROTOCOL    \
  758.                             | RTM_ONLY_THIS_INTERFACE,    \
  759.                         Route)
  760.  
  761. /*++
  762. *******************************************************************
  763.  
  764.     R t m G e t N e x t R o u t e
  765.  
  766. Routine Description:
  767.     Returns route that follows specified route in the NetworkNumber.
  768.     RoutingProtocol.InterfaceID.NextHopAddress order from the subset defined
  769.     by the enumeration flags.
  770.     Note that this operation may consume significant processing time because
  771.     first all recently changed routes will have to be merged into the
  772.     ordered list, and this list may then have to be traversed to locate
  773.     the route of interest.
  774.  
  775. Arguments:
  776.     ProtocolFamily - identifies protocol family of interest
  777.     EnumerationFlags - limit routes returned by enumeration API to a subset
  778.                         members of which have same values in the fields
  779.                         specified by the flags as in Route
  780.                         (RTM_ONLY_BEST_ROUTES does not require a criterion)
  781.     Route - protocol family dependent structure (RTM_??_ROUTE) which both
  782.                     provides the route from which to start the search and
  783.                     set values in fields that correspond to EnumerationFlags
  784.                     on INPUT and route that both follows input route in
  785.                     NetworkNumber.RoutingProtocol.InterfaceID.NextHopAddress
  786.                     order and matches specified criteria on OUTPUT
  787. Return Value:
  788.     NO_ERROR - matching route was found
  789.     ERROR_NO_ROUTES - no routes exist with specified criteria
  790.     ERROR_INVALID_PARAMETER - input parameter(s) is invalid (unsupported
  791.                     protocol family, invalid enumeration flag, etc)
  792.     ERROR_NO_SYSTEM_RESOURCES - not enough resources to perform the operation,
  793.                             try again later
  794.  
  795. *******************************************************************
  796. --*/
  797. DWORD WINAPI
  798. RtmGetNextRoute (
  799.     IN    DWORD        ProtocolFamily,
  800.     IN    DWORD        EnumerationFlags,
  801.     IN OUT PVOID     Route
  802.     );
  803.  
  804.  
  805. BOOL WINAPI
  806. RtmLookupIPDestination(
  807.     DWORD                       dwDestAddr,
  808.     PRTM_IP_ROUTE               prir
  809. );
  810.  
  811.  
  812. #ifdef __cplusplus
  813. }
  814. #endif
  815.  
  816. #pragma warning(default:4201)
  817.  
  818. #pragma option pop /*P_O_Pop*/
  819. #endif //__ROUTING_RTM_H__
  820.