Windows Driver Kit: Network Devices and Protocols
INetCfg
The INetCfg interface is the root of all networking configuration and installation. The INetCfg interface provides methods that load into memory basic networking information, apply changes to network configuration, and retrieve network components and binding paths.
The interface identifier (IID) for this interface is IID_INetCfg.
When to Implement
It is not necessary to implement the methods of this interface. They are implemented in Netcfgx.dll.
When to Use
Use this interface to retrieve network components and binding paths.
Methods
The following methods are listed in Vtable order:
| IUnknown method | Description |
|---|
| QueryInterface | Returns pointers to supported interfaces. |
| AddRef | Increments the reference count. |
| Release | Decrements the reference count. |
| INetCfg method | Description |
|---|
| Initialize | Initializes network configuration by loading into memory all basic networking information. |
| Uninitialize | Unloads from memory all basic networking information. |
| Apply | Applies all changes made to the configuration state of the network to the registry. |
| Cancel | Disregards any proposed changes to the configuration state of the network. |
| EnumComponents | Retrieves an enumeration containing a collection of network components of a particular type. |
| FindComponent | Retrieves the first network component that matches the specified component identifier. |
| QueryNetCfgClass | Retrieves a pointer to a specific class of network component. |
Comments
The INetCfg interface is the only network configuration interface that applications can receive after they call the COM CoCreateInstance function to create a network configuration object. Applications must obtain all other network configuration interfaces from INetCfg by either enumerating the interfaces or by calling methods that return the interfaces.
When notify objects initialize, they receive a pointer to INetCfg that represents the current networking configuration. Notify objects can use INetCfg to access all aspects of networking configuration.
After an application creates a network configuration object, the application should call Initialize to initialize network configuration. After the application finishes with the network configuration object, the application should call Uninitialize before releasing the network configuration object.
Example
The following example creates a network configuration object, accesses a specific network component, and, finally, releases the network configuration object. This example shows a typical sequence of operations.
INetCfg *pnetcfg = NULL;
INetCfgLock *pncfglock = NULL;
INetCfgComponent *pncfgcomp = NULL;
HRESULT hr = S_OK;
LPWSTR *ppszwrClient = NULL;
hr = CoCreateInstance(CLSID_CNetCfg, NULL, CLSCTX_SERVER,
IID_INetCfg, (LPVOID*)&pnetcfg);
hr = pnetcfg->QueryInterface(IID_INetCfgLock, (LPVOID*)&pncfglock);
hr = pncfglock->AcquireWriteLock(5, TEXT("MY CLIENT"), &ppszwrClient);
hr = pnetcfg->Initialize(NULL);
hr = pnetcfg->FindComponent(TEXT("MS_TCPIP"), &pncfgcomp);
// Call various methods on pncfgcomp here.
pncfgcomp->Release();
hr = pnetcfg->Apply();
hr = pnetcfg->Uninitialize();
hr = pncfglock->ReleaseWriteLock();
pnetcfg->Release();
Requirements
Headers: Defined in Netcfgx.h. Include Netcfgx.h.