CPNatfwtRegisterProviderInstance Function

Article
02/03/2009

[This documentation is preliminary and is subject to change.]

The CPNatfwtRegisterProviderInstance function is called by a Provider to register with the Connectivity Platform (CP) after a Provider Instance object has been created.

Syntax

HRESULT WINAPI CPNatfwtRegisterProviderInstance(
  __in         CPNATFWT_PROVIDER_INSTANCE providerInstance,
  __in_opt     WCHAR *interfaceFriendlyName,
  __inout_opt  IF_LUID *interfaceLuid,
  __in         ULONG flags,
  __in_opt     WCHAR *sddl
);

Parameters

providerInstance [in]
A handle to the Provider instance object previously obtained using the CPNatfwtCreateProviderInstance function.
interfaceFriendlyName [in, optional]
An optional NULL-terminated friendly name that is to be used for the network interface associated with the Provider instance. If NULL is specified, the default friendly name will be used (“Microsoft Connectivity Platform Adapter #N”).

In case the specified friendly name conflicts with some other interface friendly name already present on the local computer, the Connectivity Platform will add a numeric suffix to the supplied friendly name, to make the friendly name unique.

The maximum length, in wide characters, for the friendly name is defined by CPNATFWT_MAX_INTERFACE_NAME_LENGTH in the Iphlpapi.h header file. If the wide-character string pointed to by the interfaceFriendlyName parameter exceeds this length, then the friendly name is silently truncated.
interfaceLuid [in, out, optional]
A optional pointer to a LUID of the network interface that should be associated with the Provider instance.

If the interfaceLuid parameter is specified on input and is not zero, it should correspond to an interface that is already associated with the Provider. In this case, the Provider should have previously registered an instance and obtained the LUID during a previous session or sessions.

On output when the CPNatfwtRegisterProviderInstance function completes, the Connectivity Platform fills in the value at the location pointed to by the interfaceLuid parameter with the LUID of the network interface associated with the Provider instance if this parameter was not NULL on input.

A new network interface is created for the Provider instance for the following conditions:
- If the interfaceLuid parameter is NULL.
- The LUID value is zero.
- If CP can’t associate an interface with the specified LUID with the given Provider instance.
flags [in]
A bit mask of additional provider registration flags. Possible values for these flags are listed in the Iphlpapi.h header file.

Value Meaning

CPNATFWT_REGISTER_FLAGS_NONE
0

No register flags are set.

CPNATFWT_REGISTER_FLAGS_REMOVE_INTERFACE_ON_DEREGISTER
1

Remove the interface when deregistering this Provider.
sddl [in, optional]
An optional wide character null-terminated string in SDDL format that specifies the user access to the network interface associated with the Provider. If this parameter is NULL, the default SDDL will be in effect allowing access to the interface only to the Windows user account under which credentials the Provider is running.

Value	Meaning
CPNATFWT_REGISTER_FLAGS_NONE 0	No register flags are set.
CPNATFWT_REGISTER_FLAGS_REMOVE_INTERFACE_ON_DEREGISTER 1	Remove the interface when deregistering this Provider.

Return Value

If the function succeeds, the return value is S_OK.

If the function fails, the return value indicates the error. The specific error may be determined from the HRESULT returned. For Windows system errors, the returned HRESULT is 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 contain the Windows system error. The possible errors returned in the HRESULT may be one of the following return codes.

Return code	Description
ERROR_ACCESS_DENIED	Access denied. This error is returned if the Provider is not run under the security permissions of a member of the Administrator's group and the Provider was not run elevated.
ERROR_ALREADY_EXISTS	Registration for this provider instance already exists.
ERROR_BUSY	The requested resource is in use. This error is returned if registration of the Provider has already been completed or is already in progress. This error is also returned if deregistration of the Provider is already in progress.
ERROR_CONNECTION_REFUSED	The RPC service refused the network connection.
ERROR_GEN_FAILURE	A device attached to the system is not functioning. This error is returned if the security check failed, an RPC error occurred, or a general failure occurred.
ERROR_INVALID_PARAMETER	A parameter is incorrect. This error is returned if any of the following conditions occur: The providerInstance parameter is NULL. The flags parameter contains an illegal value. The length of the string pointed to by the sddl parameter is an illegal value.
ERROR_INVALID_SID	The security ID structure is invalid. This error is returned if an internal error occurs with security and a SID.
ERROR_NOT_ENOUGH_MEMORY	Not enough storage is available to process this command.
ERROR_NOT_READY	The device is not ready. This error is returned if CP is administratively disabled.
ERROR_SERVICE_NOT_ACTIVE	The service has not been started. This error is returned if there was an internal error in the CP service and service is an an unusable state.
Other	Various RPC and other error codes. Use FormatMessage to obtain the message string for the returned error.

Remarks

The CPNatfwtRegisterProviderInstance function is used by 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.

A Provider must call the CPNatfwtCreateProviderInstance function to create a provider instance object before the Provider can call the CPNatfwtRegisterProviderInstance function to register with the Connectivity Platform.

After calling the CPNatfwtCreateProviderInstance function, the Provider calls the CPNatfwtRegisterProviderInstance function to register a provider instance with the Connectivity Platform. Before calling the CPNatfwtRegisterProviderInstance function, the Provider must be ready to accept calls on the entry points in the provider instance dispatch table passed as the CPNATFWT_PROVIDER_INSTANCE_DISPATCH_TABLE structure to the CPNatfwtCreateProviderInstance function.

If the Provider tries to register the Provider instance with the Connectivity Platform and the registration succeeds, CP will create a new IP interface (if a LUID was not specified or if the specified LUID cannot be re-used for some reason) or reuse an existing IP interface (if a LUID was specified and the existing interface with this LUID can be reused).

After the registration succeeds, the provider instance is assumed to be in a dormant state. When the Provider is eventually activated from dormancy (by an outgoing packet sent over any of the CP interfaces, by a listening application with permitting edge traversal policy, or by a notification from the NotifyStableUnicastIpAddressTable function), CP will attempt to assign an IPv4 and IPv6 address from the default CP address spaces. The 169.254/16 network block is used for the default for an IPv4 address. A well-known ULA/64 prefix is used for the default for an IPv6 address.

If the flags parameter is not specified as CPNATFWT_REGISTER_FLAGS_REMOVE_INTERFACE_ON_DEREGISTER at registration, the interface will not be removed once the provider instance is deregistered (or the session is otherwise terminated). However, the interface can be removed if the Provider performs registration/deregistration again with the CPNATFWT_REGISTER_FLAGS_REMOVE_INTERFACE_ON_DEREGISTER flag set on the same interface.

If the CPNatfwtRegisterProviderInstance call succeeds, some functions from the provider instance dispatch table may be called before the CPNatfwtRegisterProviderInstance call returns control. In the case that execution of these functions causes an abortive deregistration of the provider instance, the deregistration will be handled as it is handled in case of any other error. For details, see the description of the corresponding hander for each function in the provider dispatch table.

After the registration call completes successfully, the provider can obtain the LUID of the network interface associated with the Provider instance from the value pointer to by the interfaceLuid parameter, if on input the interfaceLuid parameter was not NULL.

The CPNatfwtRegisterProviderInstance call will fail with an appropriate error code if the caller supplied invalid parameters, the call does not pass the security check required by CP for the Provider, or if CP is not available. If the CPNatfwtRegisterProviderInstance call fails, the HRESULT returned indicates the error. If the registration call fails, no functions from the provider instance dispatch table will be called.

The CPNatfwtRegisterProviderInstance function must be called by a thread running in the context of a member of the Administrators group. The LocalSystemAccount, a predefined local account used by the service control manager, can also be used to call this function since it also has Administrator rights. If CPNatfwtRegisterProviderInstance is called in the context of a user that lacks membership in the Administrators group or this is not the LocalSystemAccount, the function call will fail.

The CPNatfwtRegisterProviderInstance function can also fail because of user account control (UAC). If an application or service that calls this function is executed in the context of a user that is a member of the Administrators group other than the built-in Administrator, this call will fail unless the application or service has been marked in the manifest file with a requestedExecutionLevel set to requireAdministrator. If the application or service lacks this manifest file, a user logged on as a member of the Administrators group other than the built-in Administrator must then be executing the application or service in an enhanced shell as the built-in Administrator (RunAs administrator) for this function to succeed. A service run by the LocalSystemAccount does not require a manifest file.

Requirements

Minimum supported client	Windows 7
Minimum supported server	None supported
Header	Iphlpapi.h (include Iphlpapi.h)
Library	Iphlpapi.lib
DLL	Iphlpapi.dll