IP Helper API: Retrieving Basic Information

Getting the Adapter's Info

With the IP Helper API, you can manage network adapters. An adapter is a datalink-level abstraction for network stuff. Later in this article, you will find one more similar term—an interface, which is an IP-level abstraction.

There are several functions that provide all necessary information about adapters:

• GetAdaptersInfo: Returns an array of IP_ADAPTER_INFO structures, one for each adapter
• GetPerAdapterInfo: Returns additional information about a specific adapter in the IP_PER_ADAPTER_INFO struct
• GetAdapterIndex: Returns the adapter index from the adapter name

The next code snippet shows how to obtain info about all available adapters:

void CNWParamsDlg::ShowAdapters(PIP_ADAPTER_INFO pAdapterInfo)
{
   m_ListBox.ResetContent();
   do
   {
      m_ListBox.AddString(L"Adapter: " +
                          CString(pAdapterInfo->AdapterName));
      m_ListBox.AddString(L"   Desc: " +
                          CString(pAdapterInfo->Description));

      if(pAdapterInfo->AddressLength>0)
      {
         CString strToChar;
         CString strCurrentMac;
         BYTE *pAddress = pAdapterInfo->Address;
         for(int nCount=0; nCount-pAdapterInfo->
             AddressLength;nCount++,pAddress++)
         {
            strToChar.Format(L"%02X",*pAddress);
            strCurrentMac+=strToChar;
            if ( nCount + 1 < pAdapterInfo->AddressLength )
               strCurrentMac += L":";
         }
         m_ListBox.AddString(L"   MAC: " + strCurrentMac);
      }
      pAdapterInfo = pAdapterInfo->Next;
   }
   while(pAdapterInfo);

   ((CStatic*)GetDlgItem(IDC_STATIC_INFO))->
      SetWindowText(L"Adapters:");
}

void CNWParamsDlg::OnButtonAdapters()
{
   IP_ADAPTER_INFO *pAdapterInfo = NULL;
   ULONG ulBufLen = 0;
   int nErr = ERROR_SUCCESS;

   nErr = GetAdaptersInfo(pAdapterInfo,&ulBufLen);

   // If buffer size is smaller - allocate memory and try again
   if ( nErr == ERROR_BUFFER_OVERFLOW )
   {
      pAdapterInfo = (IP_ADAPTER_INFO *)new char[ulBufLen];

      nErr = GetAdaptersInfo(pAdapterInfo,&ulBufLen);

      if( nErr == ERROR_SUCCESS )
      {
         ShowAdapters(pAdapterInfo);
         return;
      }
   }
}

This sample gives you a common example of IP Helper API data structures. Most of them contain a linked list of the same structs, so you should iterate through it to get desired info. The IP_ADAPTER_INFO struct keeps details about various network parameters per specific adapter; for example, WINS, Gateway, DHCP, and so on:

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 sample above displays only a small part of the available information: name, description, and MAC address. The last one may be useful to identify a specific device because a MAC address is a unique number. Let me leave all the rest of this type of API calls for you to play with.