The Ipconfig.exe utility presents two pieces of information: IP configuration information and IP configuration parameters specific to each network adapter installed on your machine. To retrieve IP configuration information, use the GetNetworkParams function, which is defined as
DWORD GetNetworkParams( PFIXED_INFO pFixedInfo, PULONG pOutBufLen ); |
The pFixedInfo parameter receives a pointer to a buffer that receives a FIXED_INFO data structure your application must provide to retrieve the IP configuration information. The pOutBufLen parameter is a pointer to a variable that specifies the size of the buffer you passed in the pFixedInfo parameter. If your buffer is not large enough, GetNetworkParams returns ERROR_BUFFER_OVERFLOW and sets the pOutBufLen parameter to the required buffer size.
The FIXED_INFO structure used in GetNetworkParams is defined as
typedef struct { char HostName[MAX_HOSTNAME_LEN + 4] ; char DomainName[MAX_DOMAIN_NAME_LEN + 4]; PIP_ADDR_STRING CurrentDnsServer; IP_ADDR_STRING DnsServerList; UINT NodeType; char ScopeId[MAX_SCOPE_ID_LEN + 4]; UINT EnableRouting; UINT EnableProxy; UINT EnableDns; } FIXED_INFO, *PFIXED_INFO; |
The fields are defined as follows:
Table B-1. Possible node type values
Value | Description |
---|---|
BROADCAST_NODETYPE | Known as b-node NetBIOS name resolution, in which the system uses IP broadcasting to perform NetBIOS name registration and name resolution. |
PEER_TO_PEER_NODETYPE | Known as p-node NetBIOS name resolution, in which the system uses point-to-point communication with a NetBIOS name server (such as WINS) to register and resolve computer names to IP addresses. |
MIXED_NODETYPE | Known as m-node (mixed node) NetBIOS name resolution, in which the system uses both the b-node and p-node techniques just described. The b-node method is used first; if it fails, the p-node method is used next. |
HYBRID_NODETYPE | Known as h-node (hybrid node) NetBIOS name resolution, in which the system uses both the b-node and p-node techniques. The p-node method is used first; if it fails, the b-node method is used next. |
The DnsServerList field of a FIXED_INFO structure is an IP_ADDR_STRING structure that represents the beginning of a linked list of IP addresses. This field is defined as
typedef struct _IP_ADDR_STRING { struct _IP_ADDR_STRING* Next; IP_ADDRESS_STRING IpAddress; IP_MASK_STRING IpMask; DWORD Context; } IP_ADDR_STRING, *PIP_ADDR_STRING; |
The Next field identifies the next DNS server IP address in the list. If Next is set to NULL, it indicates the end of the list. The IpAddress field is a string of characters that represents an IP address as a dotted decimal string. The IpMask field is a string of characters that represents the subnet mask associated with the IP address listed in IpAddress. The final field, Context, identifies the IP address with a unique value on the system.
The Ipconfig.exe utility is also capable of retrieving IP configuration information specific to a network interface. A network interface can be a hardware Ethernet adapter or even a RAS dial-up adapter. You can retrieve adapter information by calling GetAdaptersInfo, which is defined below.
DWORD GetAdaptersInfo ( PIP_ADAPTER_INFO pAdapterInfo, PULONG pOutBufLen ); |
Use the pAdapterInfo parameter to pass a pointer to an application-provided buffer that receives an ADAPTER_INFO data structure with the adapter configuration information. The pOutBufLen parameter is a pointer to a variable that specifies the size of the buffer you passed in the pAdapterInfo parameter. If your buffer is not large enough, GetAdaptersInfo returns ERROR_BUFFER_OVERFLOW and sets the pOutBufLen parameter to the required buffer size.
The IP_ADAPTER_INFO structure is actually a list of structures containing IP configuration information specific to every network adapter available on your machine. IP_ADAPTER_INFO is defined as
typedef struct _IP_ADAPTER_INFO { struct _IP_ADAPTER_INFO* Next; DWORD ComboIndex; char AdapterName[MAX_ADAPTER_NAME_LENGTH + 4]; char Description[MAX_ADAPTER_DESCRIPTION_LENGTH + 4]; UINT AddressLength; BYTE Address[MAX_ADAPTER_ADDRESS_LENGTH]; DWORD Index; UINT Type; UINT DhcpEnabled; PIP_ADDR_STRING CurrentIpAddress; IP_ADDR_STRING IpAddressList; IP_ADDR_STRING GatewayList; IP_ADDR_STRING DhcpServer; BOOL HaveWins; IP_ADDR_STRING PrimaryWinsServer; IP_ADDR_STRING SecondaryWinsServer; time_t LeaseObtained; time_t LeaseExpires; } IP_ADAPTER_INFO, *PIP_ADAPTER_INFO; |
The fields of the structure are defined as follows:
Table B-2. Adapter types
Adapter Type Value | Description |
---|---|
MIB_IF_TYPE_ETHERNET | Ethernet adapter |
MIB_IF_TYPE_FDDI | FDDI adapter |
MIB_IF_TYPE_LOOPBACK | Loopback adapter |
MIB_IF_TYPE_OTHER | Other type of adapter |
MIB_IF_TYPE_PPP | PPP adapter |
MIB_IF_TYPE_SLIP | Slip adapter |
MIB_IF_TYPE_TOKENRING | Token Ring adapter |
The Ipconfig.exe utility also features the ability to release and renew IP addresses obtained from the DHCP server by specifying the /release and /renew command line parameters. If you want to programmatically release an IP address, you can call the IPReleaseAddress function, which is defined as
DWORD IpReleaseAddress ( PIP_ADAPTER_INDEX_MAP AdapterInfo ); |
If you want to renew an IP address, you can call the IPRenewAddress function, which is defined as
DWORD IpRenewAddress ( PIP_ADAPTER_INDEX_MAP AdapterInfo ); |
Each of these two functions features an AdapterInfo parameter that is an IP_ADAPTER_INDEX_MAP structure, which identifies the adapter to release or renew the address for. The IP_ADAPTER_INDEX_MAP structure is defined as
typedef struct _IP_ADAPTER_INDEX_MAP { ULONG Index; WCHAR Name[MAX_ADAPTER_NAME]; }IP_ADAPTER_INDEX_MAP, *PIP_ADAPTER_INDEX_MAP; |
The fields of this structure are defined as follows:
You can retrieve the IP_ADAPTER_INDEX_MAP structure for a particular adapter by calling the GetInterfaceInfo function, which is defined as
DWORD GetInterfaceInfo ( IN PIP_INTERFACE_INFO pIfTable, OUT PULONG dwOutBufLen ); |
The pIfTable parameter is a pointer to an IP_INTERFACE_INFO application buffer that will receive interface information. The dwOutBufLen parameter is a pointer to a variable that specifies the size of the buffer you passed in the pIfTable parameter. If the buffer is not large enough to hold the interface information, GetInterfaceInfo returns the error ERROR_INSUFFICIENT_BUFFER and sets the dwOutBufLen parameter to the required buffer size.
The IP_INTERFACE_INFO structure is defined as
typedef struct _IP_INTERFACE_INFO { LONG NumAdapters; IP_ADAPTER_INDEX_MAP Adapter[1]; } IP_INTERFACE_INFO,*PIP_INTERFACE_INFO; |
Its fields are defined as follows:
Once you have obtained the IP_ADAPTER_INDEX_MAP structure for a particular adapter, you can release or renew the DHCP-assigned IP address using the IPReleaseAddress and IPRenewAddress functions we just described.
The Ipconfig.exe utility does not allow you to change an IP address for a network adapter (except in the case of DHCP). However, two functions will allow you to add or delete an IP address for a particular adapter: the AddIpAddress and DeleteIpAddress IP Helper functions. These functions require you to understand adapter index numbers and IP context numbers. In Windows, every network adapter has a unique index ID (which we described earlier), and every IP address has a unique context ID. Adapter index IDs and IP context numbers can be retrieved using GetAdaptersInfo. The AddIpAddress function is defined as
DWORD AddIPAddress ( IPAddr Address, IPMask IpMask, DWORD IfIndex, PULONG NTEContext, PULONG NTEInstance ); |
The Address parameter specifies the IP address to add as an unsigned long value. The IpMask parameter specifies the subnet mask for the IP address as an unsigned long value. The IfIndex parameter specifies the adapter index to add the address to. The NTEContext parameter receives the context value associated with the IP address added. The NTEInstance parameter receives an instance value associated with an IP address.
If you want to programmatically delete an IP address for an adapter, you can call DeleteIpAddress, which is defined below.
DWORD DeleteIPAddress ( ULONG NTEContext ); |
The NTEContext parameter identifies a context value associated with an IP address. This value can be obtained from GetAdaptersInfo, which we described earlier in the chapter.