rtm.h

vc6.0完整版

	ERROR_INVALID_HANDLE - client handle is not a valid RTM handle
	ERROR_NOT_ENOUGH_MEMORY - route could not be adeed because of memory
								allocation problem
	ERROR_NO_SYSTEM_RESOURCES - not enough resources to perform the operation,
							try again later

*******************************************************************
--*/
DWORD WINAPI
RtmAddRoute (
	IN HANDLE	    ClientHandle,
	IN PVOID		Route,
	IN DWORD		TimeToLive,
	OUT DWORD		*Flags,
    OUT PVOID		CurBestRoute OPTIONAL,
    OUT PVOID		PrevBestRoute OPTIONAL
    );
     

/*++
*******************************************************************

	R t m D e l e t e R o u t e

Routine Description:
	Deletes existing route entry and generates route change
	message if best route to a destination network has changed as the
	result of this operation.
	Note that route change message is not sent to the client that
	makes this change, but rather relevant information is returned
	by this routine directly.

Arguments:
	ClientHandle - handle that identifies the client for which the opertation
					is performed, it also supplies RoutingProtocol field
					of the route to be deleted
	Route - route to be deleted.
			The following fields of protocol family dependent
			RTM_??_ROUTE structure are used to identify
			route entry to be deleted:
		RR_Network:			destination network
		RR_InterfaceID: 	id of interface through which route was received
		RR_NextHopAddress:	address of next hop router

		If the deleted entry represented the best route to a destination
		network, this operation will generate route change message
	Flags - returns what change message (if any) will be generated by the
			RTM as the result of this deletion and identifies what
			information was palced into the provided buffer:
		RTM_NO_CHANGE - the deleted route did not affect best route to 
						any destination network (there is another entry that
						represents route to the same destination nework and
						it has better metric)
		RTM_ROUTE_DELETED - the deleted route was the only route avaliable
							for the destination network
		RTM_ROUTE_CHANGED - after this route was deleted another route
						became the best to the destination network,
						CurBestRoute will be filled with that route info
	CurBestRoute - buffer to receive current best route info (if any)
Return Value:
	NO_ERROR 				- route was deleted OK
	ERROR_INVALID_PARAMETER - route contains invalid parameter 
	ERROR_INVALID_HANDLE - client handle is not a valid RTM handle
	ERROR_NO_SUCH_ROUTE - there is no entry in the table that
						has specified parameters
	ERROR_NO_SYSTEM_RESOURCES - not enough resources to perform the operation,
							try again later

*******************************************************************
--*/
DWORD WINAPI
RtmDeleteRoute (
	IN HANDLE	    ClientHandle,
	IN PVOID		Route,
	OUT	DWORD		*Flags,
    OUT PVOID		CurBestRoute OPTIONAL
	);



/*++
*******************************************************************

	R t m I s R o u t e

Routine Description:
	Checks if route exists to specified network and returns best
	route info

Arguments:
	ProtocolFamily - identifies protocol family of route of interest
	Network - contains protocol family dependent network number data
			(as defined by ??_NETWORK structures above)
	BestRoute - buffer to receive current best route info (if any)
Return Value:
	TRUE - route to network of interest exists
	FALSE - not route exist or operation failed, call GetLastError()
	to obtain reason of failure:
		NO_ERROR 				- operation succeded but not route exists
		ERROR_INVALID_PARAMETER - input parameter(s) is invalid (unsupported
									protocol family)
		ERROR_NO_SYSTEM_RESOURCES - not enough resources to perform the operation,
							try again later

*******************************************************************
--*/
BOOL WINAPI
RtmIsRoute (
	IN 	DWORD		ProtocolFamily,
	IN 	PVOID   	Network,
    OUT	PVOID 		BestRoute OPTIONAL
	);

	
/*++
*******************************************************************

	R t m G e t N e t w o r k C o u n t

Routine Description:
	Returns number of networks that RTM has routes to.

Arguments:
	ProtocolFamily - identifies protocol family of interest
Return Value:
	Number of known networks
	0 if no routes are availabel in the table or operation failed,
	call GetLastError () to get reason of failure:
		NO_ERROR - operation succeded but no routes available
		ERROR_INVALID_PARAMETER - input parameter is invalid (unsupported
									protocol family)

*******************************************************************
--*/
ULONG WINAPI
RtmGetNetworkCount (
	IN	DWORD		ProtocolFamily
	);

/*++
*******************************************************************

	R t m G e t R o u t e A g e

Routine Description:
	Returns route age (time since it was created or updated) in seconds
	Route structure must have been recently filled by RTM for this to
	return valid results (route age is actually computed from
	RR_TimeStamp field)

Arguments:
	Route - protocol family dependent route data (RTM_??_ROUTE data
			structure) that was obtained from RTM (returned by
			its routines)
Return Value:
	Route age in seconds
	INFINITE - if content of route is invalid (GetLastError () returns
		ERROR_INVALID_PARAMETER)

*******************************************************************
--*/
ULONG WINAPI
RtmGetRouteAge (
	IN PVOID		Route
	);





/*++
*******************************************************************

	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

Routine Description:
	Creates a handle that will allow the caller to use fast and change
	tolerant enumeration API to scan through all routes or a subset of them
	known to the RTM. Note that scans performed by this API do not return
	routes in any particular order.

Arguments:
	ProtocolFamily - identifies protocol family of interest
	EnumerationFlags - limit routes returned by enumeration API to a subset
						members of which have same values in the fields
						specified by the flags as in CriteriaRoute
						(RTM_ONLY_BEST_ROUTES does not require a criterion)
	CriteriaRoute - protocol family dependent structure (RTM_??_ROUTE) with
					set values in fields that correspond to EnumerationFlags
Return Value:
	Handle that can be used with enumeration API below
	NULL no routes exists with specified criteria or operation failed,
			call GetLastError () to get reason of failure:
		ERROR_NO_ROUTES - no routes exist with specified criteria
		ERROR_INVALID_PARAMETER - input parameter(s) is invalid (unsupported
					protocol family, invalid enumeration flag, etc)
		ERROR_NOT_ENOUGH_MEMORY - handle could not be created because of memory
								allocation problem
		ERROR_NO_SYSTEM_RESOURCES - not enough resources to perform the operation,
							try again later

*******************************************************************
--*/
HANDLE WINAPI
RtmCreateEnumerationHandle (
	IN	DWORD		ProtocolFamily,
	IN	DWORD		EnumerationFlags,
	IN	PVOID		CriteriaRoute
	);


/*++
*******************************************************************

	R t m E n u m e r a t e G e t N e x t R o u t e

Routine Description:
	Returns next route entry in enumeration started by
	RtmCreateEnumerationHandle.

Arguments:
	EnumerationHandle - handle that identifies enumeration
	Route - buffer (RTM_??_ROUTE structure) that receives next
			route in enumeration
Return Value:
	NO_ERROR - next availbale route was placed in the buffer
	ERROR_NO_MORE_ROUTES - no more routes exist with soecified criteria
	ERROR_INVALID_HANDLE - enumeration handle is not a valid RTM handle
	ERROR_NO_SYSTEM_RESOURCES - not enough resources to perform the operation,
							try again later

*******************************************************************
--*/
DWORD WINAPI
RtmEnumerateGetNextRoute (
	IN  HANDLE    	EnumerationHandle,
	OUT PVOID		Route
	);

/*++
*******************************************************************

	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

Routine Description:
	Terminates enumerationand frees associated resources

Arguments:
	EnumerationHandle - handle that identifies enumeration
Return Value:
	NO_ERROR - enumeration was termineted ok
	ERROR_INVALID_HANDLE - enumeration handle is not a valid RTM handle
	ERROR_NO_SYSTEM_RESOURCES - not enough resources to perform the operation,
							try again later

*******************************************************************
--*/
DWORD WINAPI
RtmCloseEnumerationHandle (
	IN HANDLE		EnumerationHandle
	);


/*++
*******************************************************************

	R t m B l o c k D e l e t e R o u t e s

Routine Description:
	Deletes all routes in subset specified by enumeration flags and
	corresponding criteria.  This operation can only be performed by
	the registered client and applies only to routes added by this
	client.
	Route change messages will be generated for deleted routes that
	were the best
Arguments:
	ClientHandle - handle that identifies the client and routing protocol
						of routes to be deleted
	EnumerationFlags - further limit subset of routes being deleted to only
						those that have same values in the fields
						specified by the flags as in CriteriaRoute
		Note that only RTM_ONLY_THIS_NETWORK and RTM_ONLY_THIS_INTERFACE
		can be used (RTM_ONLY_BEST_ROUTES does not apply because best
		route designation is adjusted as routes are deleted and
		all routes will be deleted anyway)
	CriteriaRoute - protocol family dependent structure (RTM_??_ROUTE) with
					set values in fields that correspond to EnumerationFlags
Return Value:
	NO_ERROR - routes were deleted ok
	ERROR_NO_ROUTES - no routes exist that match specified criteria
	ERROR_INVALID_HANDLE - client handle is not a valid RTM handle
	ERROR_NOT_ENOUGH_MEMORY - could not allocate memory to perform
						the operation
	ERROR_NO_SYSTEM_RESOURCES - not enough resources to perform the operation,
							try again later

*******************************************************************
--*/
DWORD WINAPI
RtmBlockDeleteRoutes (
	IN HANDLE		ClientHandle,
	IN DWORD		EnumerationFlags,
	IN PVOID		CriteriaRoute
	);

/*++
*******************************************************************

	R t m G e t F i r s t R o u t e

Routine Description:
	Returns first route in the NetworkNumber.RoutingProtocol.InterfaceID.
	NextHopAddress order from the subset specifed by the enumeration flags.
	Note that this operation may consume significant processing time because
	first all recently changed routes will have to be merged into the
	ordered list, and this list will then have to be traversed to locate
	the route of interest.

Arguments:
	ProtocolFamily - identifies protocol family of interest
	EnumerationFlags - limit routes returned by enumeration API to a subset
						members of which have same values in the fields
						specified by the flags as in CriteriaRoute
						(RTM_ONLY_BEST_ROUTES does not require a criterion)
	Route - protocol family dependent structure (RTM_??_ROUTE) with
					set values in fields that correspond to EnumerationFlags
					on INPUT and first route that matches specified
					criteria on OUTPUT
Return Value:
	NO_ERROR - matching route was found
	ERROR_NO_ROUTES - no routes exist with specified criteria
	ERROR_INVALID_PARAMETER - input parameter(s) is invalid (unsupported
					protocol family, invalid enumeration flag, etc)
	ERROR_NO_SYSTEM_RESOURCES - not enough resources to perform the operation,
							try again later

*******************************************************************
--*/
DWORD WINAPI
RtmGetFirstRoute (
	IN	DWORD		ProtocolFamily,
	IN	DWORD		EnumerationFlags,
	IN OUT PVOID 	Route
	);

#define RtmGetSpecificRoute(ProtocolFamily,Route)		\
		RtmGetFirstRoute(ProtocolFamily,				\
						RTM_ONLY_THIS_NETWORK			\
							| RTM_ONLY_THIS_PROTOCOL	\
							| RTM_ONLY_THIS_INTERFACE,	\
						Route)

/*++
*******************************************************************

	R t m G e t N e x t R o u t e

Routine Description:
	Returns route that follows specified route in the NetworkNumber.
	RoutingProtocol.InterfaceID.NextHopAddress order from the subset defined
	by the enumeration flags.
	Note that this operation may consume significant processing time because
	first all recently changed routes will have to be merged into the
	ordered list, and this list may then have to be traversed to locate
	the route of interest.

Arguments:
	ProtocolFamily - identifies protocol family of interest
	EnumerationFlags - limit routes returned by enumeration API to a subset
						members of which have same values in the fields
						specified by the flags as in Route
						(RTM_ONLY_BEST_ROUTES does not require a criterion)
	Route - protocol family dependent structure (RTM_??_ROUTE) which both
					provides the route from which to start the search and
					set values in fields that correspond to EnumerationFlags
					on INPUT and route that both follows input route in
					NetworkNumber.RoutingProtocol.InterfaceID.NextHopAddress
					order and matches specified criteria on OUTPUT
Return Value:
	NO_ERROR - matching route was found
	ERROR_NO_ROUTES - no routes exist with specified criteria
	ERROR_INVALID_PARAMETER - input parameter(s) is invalid (unsupported
					protocol family, invalid enumeration flag, etc)
	ERROR_NO_SYSTEM_RESOURCES - not enough resources to perform the operation,
							try again later

*******************************************************************
--*/
DWORD WINAPI
RtmGetNextRoute (
	IN	DWORD		ProtocolFamily,
	IN	DWORD		EnumerationFlags,
	IN OUT PVOID 	Route
	);

#ifdef __cplusplus
}
#endif

#endif //__ROUTING_RTM_H__