Managing Interfaces Using GetInterfaceInfo

The GetInterfaceInfo function fills a pointer to an IP_INTERFACE_INFO structure with information about the interfaces associated with the system.

To use GetInterfaceInfo

1. Declare a pointer to an IP_INTERFACE_INFO object called pInfo, and a ULONG object called ulOutBufLen. Also declare a DWORD object called dwRetVal (used for error checking).

       ULONG               ulOutBufLen;
       DWORD               dwRetVal;
       unsigned int       i;
   
       IP_INTERFACE_INFO*  pInterfaceInfo;
   

2. Allocate memory for the structures.

   Note

   The size of ulOutBufLen is not sufficient to hold the information. See the next step.

    

       pInterfaceInfo = (IP_INTERFACE_INFO *) malloc(sizeof (IP_INTERFACE_INFO));
       ulOutBufLen = sizeof(IP_INTERFACE_INFO);
   
   

3. Make an initial call to GetInterfaceInfo to get the size needed into the ulOutBufLen variable.

   Note

   This call to the function is meant to fail, and is used to ensure that the ulOutBufLen variable specifies a size sufficient for holding all the information returned to pInfo. This is a common programming model in IP Helper for data structures and functions of this type.

    

       if (GetInterfaceInfo(pInterfaceInfo, &ulOutBufLen) ==
           ERROR_INSUFFICIENT_BUFFER) {
           free(pInterfaceInfo);
           pInterfaceInfo = (IP_INTERFACE_INFO *) malloc(ulOutBufLen);
       }
   

4. Make a second call to GetInterfaceInfo with general error checking and return its value to the DWORD variable dwRetVal (for more advanced error checking).

       if ((dwRetVal = GetInterfaceInfo(pInterfaceInfo, &ulOutBufLen)) != NO_ERROR) {
           printf("  GetInterfaceInfo failed with error: %d\n", dwRetVal);
       }
   

5. If the call was successful, access the data from the pInfo data structure.

           printf("  GetInterfaceInfo succeeded.\n");
   
           printf("  Num Adapters: %ld\n\n", pInterfaceInfo->NumAdapters);
           for (i = 0; i < (unsigned int) pInterfaceInfo->NumAdapters; i++) {
               printf("  Adapter Index[%d]: %ld\n", i,
                      pInterfaceInfo->Adapter[i].Index);
               printf("  Adapter Name[%d]:  %ws\n\n", i,
                      pInterfaceInfo->Adapter[i].Name);
           }
       }
   

   Note

   The %ws in the first line denotes a wide string. This is used because the Name attribute of the IP_ADAPTER_INDEX_MAP structure Adapter is a WCHAR, which is a Unicode string.

    

6. Free any memory allocated for the pInfo structure.

       if (pInterfaceInfo) {
           free(pInterfaceInfo);
           pInterfaceInfo = NULL;
       }
   

Next Step: Managing IP Addresses Using GetIpAddrTable

Previous Step: Managing Network Adapters Using GetAdaptersInfo