CPNATFWT_PROVIDER_REACH_TRANSPORT_ID Function Pointer
[This documentation is preliminary and is subject to change.]
The CPNATFWT_PROVIDER_REACH_TRANSPORT_ID function is called by the Connectivity Platform (CP) check if a transport ID is unambiguously reachable over the Provider instance.
Syntax
typedef HRESULT ( CALLBACK *CPNATFWT_PROVIDER_REACH_TRANSPORT_ID )(
__in CPNATFWT_PROVIDER_INSTANCE providerInstance,
__in PVOID providerInstanceUserContext,
__in CPNATFWT_TRANSPORT_ID *transportId,
__in PVOID completionContext,
__in CPNATFWT_PLATFORM_COMPLETION_ROUTINE completionRoutine
);
Parameters
providerInstance [in]
A handle to the Provider instance object previously returned to the Provider by the CPNatfwtCreateProviderInstance function and used by the Provider to register with the CP using the CPNatfwtRegisterProviderInstance function.providerInstanceUserContext [in]
A pointer to context data supplied by Provider when the Provider instance was created using the CPNatfwtCreateProviderInstance function.transportId [in]
A pointer to the transport ID to check whether it is unambiguously reachable over the Provider instance.A CPNATFWT_TRANSPORT_ID structure represents a binary data blob that is used as an identifier for data exchange between Provider instances.
completionContext [in]
Context data supplied by CP that is passed to the completion routine pointed to by the completionRoutine parameter if the Provider executes the CPNATFWT_PROVIDER_REACH_TRANSPORT_ID function asynchronously .This parameter can be ignored if the Provider executes the CPNATFWT_PROVIDER_REACH_TRANSPORT_ID function synchronously .
completionRoutine [in]
A pointer to the completion routine supplied by CP that the Provider calls to complete this call if the Provider executes the CPNATFWT_PROVIDER_REACH_TRANSPORT_ID function asynchronously. In this case, the Provider returns HRESULT_FROM_WIN32(ERROR_IO_PENDING) to CP from the CPNATFWT_PROVIDER_REACH_TRANSPORT_ID function to pend the call and indicate to CP that the call will be completed asynchronously.This parameter can be ignored if the Provider executes the CPNATFWT_PROVIDER_REACH_TRANSPORT_ID function synchronously .
Return Value
If the Provider executes CPNATFWT_PROVIDER_REACH_TRANSPORT_ID synchronously, this function returns S_OK if the call succeeds.
If the Provider executes CPNATFWT_PROVIDER_REACH_TRANSPORT_ID asynchronously, this function returns HRESULT_FROM_WIN32(ERROR_IO_PENDING) to indicate the operation is in progress. The results of the function are supplied later when the completion routine pointed to by the completionRoutine parameter is called by the Provider. The results are returned to CP in the status parameter passed to the completion routine. If the function succeeds, S_OK should be returned in the status parameter. If the function fails, the specific error code should be returned in the status parameter. The specific error may be determined from the HRESULT returned.
If the Provider executes CPNATFWT_PROVIDER_REACH_TRANSPORT_ID synchronously and the function fails, the return value in the HRESULT indicates the error. The specific error may be determined from the HRESULT returned.
For Windows system errors, the HRESULT returned by the Provider should be generated using the HRESULT_FROM_WIN32 inline function or macro defined in the Winerror.h header file. When the HRESULT indicates a FACILITY_WIN32 error, the lower 16 bits should contain the Windows system error.
The Provider may return a variety of error codes on failure. A few possible errors that the Provider may return include the following, but many other error codes may be returned that are specific to the Provider.
| Return code | Description |
|---|---|
ERROR_DUP_NAME |
A duplicate name exists on the network. This error is returned if the pointer to the transport ID in the transportId parameter is reachable by the Provider but ambiguous (two or more peers claim the same transport ID). |
ERROR_IO_PENDING |
An operation is in progress. This value is returned if the Provider executes the function asynchronously. The results of the function are supplied later when the completion routine pointed to by the completionRoutine parameter is called by the Provider. In this case, the Provider returns without waiting for the associated activities to complete for processing the CPNATFWT_PROVIDER_REACH_TRANSPORT_ID function. |
Other |
The Provider may return a variety of error codes on failure (E_FAIL, for example). CP treats any return value other than S_OK, ERROR_IO_PENDING, and ERROR_DUP_NAME as an indication of failure. On Windows 7, CP treats any return value other than S_OK, ERROR_IO_PENDING, and ERROR_DUP_NAME as an indication that the transport ID pointed to by transportId parameter is not reachable. |
Remarks
The CPNATFWT_PROVIDER_REACH_TRANSPORT_ID function is used for the Connectivity Platform feature supported on Windows 7 and later.
The Connectivity Platform (CP) provides a mechanism for specialized applications and services to provide custom network traversal of network address translation (NAT) and firewalls on Windows 7 and later. A Provider registers with the Connectivity Platform to provide network traversal for other applications that use standard Windows networking APIs such as Windows Sockets.
The CPNATFWT_PROVIDER_REACH_TRANSPORT_ID function is called by the Connectivity Platform to check if a peer with a particular transport ID is unambiguously reachable over the Provider instance with a matching address prefix. A transport ID corresponds to assigning an IPv4 or IPv6 address to the associated network interface. Once the Provider instance is in an active state, CP can make one or more calls to the CPNATFWT_PROVIDER_REACH_TRANSPORT_ID function to check for reachability with the Provider instance.
The CPNATFWT_PROVIDER_REACH_TRANSPORT_ID function return code must allow distinguishing 3 cases:
- The transport ID pointed to by transportId parameter is uniquely reachable. The CPNATFWT_PROVIDER_REACH_TRANSPORT_ID should return with S_OK for this case.
- The transport ID pointed to by transportId parameter is reachable but ambiguous (two or more peers claim the same transport ID). The CPNATFWT_PROVIDER_REACH_TRANSPORT_ID should return with an error code of HRESULT_FROM_WIN32(ERROR_DUP_NAME) for this case.
- The transport ID pointed to by transportId parameter is not reachable. The CPNATFWT_PROVIDER_REACH_TRANSPORT_ID should return with an error code of E_FAIL for this case.
**Windows 7: **The Provider may return a variety of error codes on failure (E_FAIL, for example). On Windows 7, CP treats any return value other than S_OK, ERROR_IO_PENDING, and ERROR_DUP_NAME as an indication that the transport ID pointed to by transportId parameter is not reachable.
If the CPNATFWT_PROVIDER_REACH_TRANSPORT_ID function fails for any other reason, the Provider should return an appropriate error code.
During the particular session with the Provider instance, CP may call the CPNATFWT_PROVIDER_REACH_TRANSPORT_ID function with the same transport ID multiple times and the function can return different results (the peer is or not reachable at a particular moment in time). While the Provider may implement some caching policies to optimize network bandwidth usage, it should ensure that the information returned to CP is reasonably up-to-date. The Provider should also not make any assumptions regarding how often CP makes these calls, or the relative timing of these calls and other CP calls such as the CPNATFWT_PROVIDER_SEND_BUFFERS function.
Many of callback functions exposed by the Provider via dispatch table have completionContext and completionRoutine parameters, which allow the Provider to return from that function asynchronously before the associated activities actually complete. The Provider can inform CP about their completion later by calling the corresponding completion routine with corresponding completion context to provide CP a return value.
The Provider is allowed to complete a call in any of the following ways:
- Complete the call synchronously and return any HRESULT except for HRESULT_FROM_WIN32(ERROR_IO_PENDING). The Provider returns S_OK for success, HRESULT_FROM_WIN32(ERROR_DUP_NAME) if the transport ID is ambiguous, or an error code for failure. In this case, it is illegal for the Provider to later call the completion routine passed in the completionRoutine parameter.
- Complete the call asynchronously and return HRESULT_FROM_WIN32(ERROR_IO_PENDING). In parallel or later, the Provider calls the completion routine passed in the completionRoutine parameter and provides the completion status (S_OK, HRESULT_FROM_WIN32(ERROR_DUP_NAME), or an error code on failure).
Note Note if the Provider pends the call by returning HRESULT_FROM_WIN32(ERROR_IO_PENDING), all function parameters that are pointers (all input parameters that are pointers) will remain valid until the Provider calls the corresponding completion routine. The Provider must never assume availability of these parameters once it invokes completion routine.
The CP completion routine pointed to by the completionRoutine is defined as a function of type VOID with the following syntax:
typedef
VOID
(WINAPI *CPNATFWT_PLATFORM_COMPLETION_ROUTINE) (
__in PVOID completionContext,
__in HRESULT status
);
The parameters passed to the completion routine include the following:
| Parameter | Description |
|---|---|
completionContext |
The completionContext parameter passed to the CPNATFWT_PROVIDER_REACH_TRANSPORT_ID function. This parameter is used by CP to identify the CPNATFWT_PROVIDER_REACH_TRANSPORT_ID call that the completion routine is responding to. |
status |
This parameter contains the final completion status of the CPNATFWT_PROVIDER_REACH_TRANSPORT_ID operation by the Provider. |
The goal of supporting asynchronous call completion is to minimize blockage of threads that make the calls.
Independently of whether a call exited synchronously or was completed asynchronously, if the call completion from the Provider doesn’t occur in a timely manner, CP will initiate a session termination with the Provider (call the CPNATFWT_PROVIDER_TERMINATE_SESSION_INDICATION). This action is designed to prevent excessive resource consumption by a Provider.
Requirements
| Minimum supported client | Windows 7 |
| Minimum supported server | None supported |
| Header | Iphlpapi.h (include Iphlpapi.h) |
See Also
CPNATFWT_PROVIDER_ADD_TRANSPORT_ID
CPNATFWT_PROVIDER_ESTABLISH_SESSION_INDICATION
CPNATFWT_PROVIDER_INSTANCE_DISPATCH_TABLE
CPNATFWT_PROVIDER_REMOVE_TRANSPORT_ID
CPNATFWT_PROVIDER_TERMINATE_SESSION_INDICATION
CPNATFWT_PROVIDER_TRANSITION_ACTIVE
CPNATFWT_PROVIDER_TRANSITION_DORMANT
CPNATFWT_TRANSPORT_ID
CPNatfwtCreateProviderInstance
CPNatfwtRegisterProviderInstance
Send comments about this topic to Microsoft
Build date: 2/3/2009