IOCTL_TCP_QUERY_INFORMATION_EX IOCTL (tcpioctl.h)

[Этот код элемента управления может быть изменен или недоступен в будущих версиях Windows. Используйте вспомогательный API протокола Интернета вместо этого кода элемента управления.]

Извлекает сведения из драйвера TCP/IP.

Чтобы выполнить операцию IOCTL_TCP_QUERY_INFORMATION_EX, вызовите функцию DeviceIoControl со следующими параметрами.

BOOL DeviceIoControl(
  (HANDLE) hDevice,                  // Open handle to the TCP driver
  IOCTL_TCP_QUERY_INFORMATION_EX,    // dwIoControlCode
  NULL,                              // lpInBuffer (the output buffer is used for input too)
  0,                                 // nInBufferSize
  (LPVOID) lpOutBuffer,              // Pointer to the output buffer
  (DWORD) nOutBufferSize,            // Size of the output buffer
  (LPDWORD) lpBytesReturned,         // Number of bytes returned (if called synchronously)
  (LPOVERLAPPED) lpOverlapped        // OVERLAPPED structure (if called asynchronously)
);

Замечания

Чтобы использовать IOCTL_TCP_QUERY_INFORMATION_EX, вы должны ознакомиться с разработкой драйверов Windows, как описано в комплекте драйверов Windows (WDK), а также в частности с драйверами интерфейса драйвера транспорта (TDI).

примечание. Чтобы использовать этот код элемента управления, включите файл заголовка Windows.h. Кроме того, в частности, включите tcpioctl.h, файл заголовка, опубликованный в пакете SDK для Windows для использования с IOCTL_TCP_QUERY_INFORMATION_EX, а также Tdiinfo.h и Tdistat.h, файлы заголовков, опубликованные в WDK для разработки драйверов TDI.

 

Примечание различные флаги и другие константы, определенные в файле заголовка Tdiinfo.h WDK для операции IOCTL_TCP_QUERY_INFORMATION_EX, используют следующее соглашение об именовании.

Письма	Означать	Комментарии
"AT"	Перевод адресов	Разрешение адресов, например разрешение адресов, предоставленное ARP (протокол разрешения адресов).
"NL"	Сетевой уровень	Как и в эталонной модели взаимодействия с открытыми системами (OSI).
"TL"	Транспортный уровень	Как и в эталонной модели OSI.
"CL"	Connection-Less	Протокол без подключения на основе широковещательных пакетов.
"CO"	Связанный	Подключенный протокол на основе направленных пакетов.
"ER"	Эхо-запрос/ответ	Типы пакетов, используемые Ping для проверки подключения TCP/IP.
"IF"	Интерфейс	Интерфейс, используемый в SNMP.

 

 

Операция IOCTL_TCP_QUERY_INFORMATION_EX извлекает различные типы сведений в зависимости от того, на какую структуру TCP_REQUEST_QUERY_INFORMATION_EX указывает параметр lpInBuffer, как описано в следующем абзаце и примере кода.

1. Перечисление сущностей TDI.

Чтобы получить массив структур TDIEntityID, определяющих все сущности TCP на компьютере, задайте для элемента входной структуры ID.toi_entity.tei_entity значение GENERIC_ENTITY. ID.toi_class необходимо задать значение INFO_CLASS_GENERIC, ID.toi_type должно быть задано значение INFO_TYPE_PROVIDER, а ID.toi_id должно быть задано значение ENTITY_LIST_ID, или операция завершается ошибкой с кодом ошибки TDI_INVALID_PARAMETER. Элемент контекста входной структуры игнорируется при запросе списка. Выходные данные в этом случае являются массивом структур TDIEntityID. Функция GetEntityArray в первом примере кода ниже показывает, как получить такой массив.

2. Получение сведений о типе конкретной сущности TDI.

Если элемент ID.toi_entity входной структуры идентифицирует определенную сущность (как в случае TDIEntityID структур, возвращаемых запросом перечисления выше), то при задании ID.toi_class значения INFO_CLASS_GENERIC, ID.toi_type для INFO_TYPE_PROVIDER, а ID.toi_id для ENTITY_TYPE_ID приводит к тому, что одно или несколько значений флагов будут иметь значение возвращается в без знака длинный, на который указывает параметр lpOutBuffer. Эти значения флага определяют тип указанной сущности. Еще раз контекст элемент входной структуры игнорируется.

Возможные значения флага типа, которые можно возвращать, отображаются в следующей таблице.

Флаг	Значение
AT_ARP	Сущность реализует ARP (протокол разрешения адресов).
AT_NULL	Сущность не выполняет перевод адресов.
CL_NL_IP	Сущность реализует IP-адрес (интернет-протокол), без подключения на сетевом уровне.
CL_NL_IPX	Сущность реализует IPX (протокол Exchange пакетов Internetwork), без подключения на сетевом уровне.
CL_TL_NBF	Сущность реализует протокол NBF (протокол кадра NetBEUI), без подключения на транспортном уровне.
CL_TL_UDP	Сущность реализует протокол UDP (протокол пользовательской диаграммы) без подключения на транспортном уровне.
CO_TL_NBF	Сущность реализует протокол NBF (протокол кадра NetBEUI), направленные пакеты на транспортном уровне.
CO_TL_SPP	Сущность реализует SPP (протокол последовательного пакета), направленные пакеты на уровне транспорта.
CO_TL_SPX	Сущность реализует SPX (протокол Обмена последовательность пакетов), направленные пакеты на уровне транспорта.
CO_TL_TCP	Сущность реализует протокол TCP (протокол управления передачей), направленные пакеты на уровне транспорта.
ER_ICMP	Сущность реализует ICMP (протокол сообщений управления Интернетом) для эхо-запроса или ответа.
IF_GENERIC	Сущность реализует универсальный интерфейс.
IF_MIB	Сущность реализует интерфейс с поддержкой SNMP MIB-II.

 

3. Получите MIB-II сведения о сущности интерфейса.

Если тип сущности IF_MIB, то запрос MIB можно отправить в него, который приводит к возвращению структуры IFEntry. Задайте элемент ID.toi_entity входной структуры для идентификации сущности, ID.toi_classINFO_CLASS_PROTOCOL, ID.toi_typeINFO_TYPE_PROVIDERи ID.toi_id значение IF_MIB_STATS_ID.

Обратите внимание, что поскольку IFEntry является структурой переменной длины, выходной буфер должен быть выделен не только как "sizeof(IFEntry)", но и как "sizeof(IFEntry) + MAX_ADAPTER_DESCRIPTION_LENGTH + 1".

4. Получите MIB-II сведения о конкретной сущности IP-адреса.

Сведения MIB также можно получить из ip-сущности (один тип которого CL_NL_ENTITY), задав элемент ID.toi_entity для идентификации сущности, ID.toi_classINFO_CLASS_PROTOCOL, ID.toi_type для INFO_TYPE_PROVIDERи ID.toi_id для IP_MIB_STATS_ID. В этом случае возвращается структура IPSNMPInfo , а выходной буфер можно выделить для "sizeof(IPSNMPInfo)".

5. Получение сведений об адресе конкретной сущности IP-адреса.

Если элемент ipsi_numaddr структуры IPSNMPInfo, возвращаемой для конкретной сущности IP, не является ненулевой, массив структур IPAddrEntry можно получить, задав элемент ID.toi_entity для идентификации сущности, ID.toi_class значение INFO_CLASS_PROTOCOL, ID.toi_type для INFO_TYPE_PROVIDER, и ID.toi_id для IP_MIB_ADDRTABLE_ENTRY_ID. В этом случае выходной буфер должен быть выделен для хранения массива размеров:

sizeof(IPAddrEntry) * pIpSnmpInfoReturned->ipsi_numaddr

6. Получение сведений об интерфейсе конкретного IP-адреса.

Дополнительные сведения об интерфейсе можно получить для заданного IP-адреса, возвращаемого в массиве IPAddrEnt ry выше, оставив набор элементов ID.toi_entity для идентификации сущности IP, ID.toi_class задано значение INFO_CLASS_PROTOCOL, а ID.toi_type задано значение INFO_TYPE_PROVIDER, а затем путем задания ID.toi_id значение IP_INTFC_INFO_ID и контекста член структуры TCP_REQUEST_QUERY_INFORMATION_EX в адресЕ IPv4 или IPv6.

Выделение буфера вывода достаточно большого размера, чтобы содержать sizeof(IPINTERFACEINFO) + MAX_PHYSADDR_SIZE.

При возврате выходной буфер содержит заполненную структуру IPInterfaceInfo.

Примеры

В следующем примере показано, как получить список сущностей, присутствующих на tcp-адаптере на текущем компьютере.

#define  UNICODE
#define  _WIN32_WINNT  0x0500

#include <stdio.h>
#include <windows.h>
#include <iptypes.h>
#include "winternl.h"
#include "tdiinfo.h"
#include "tdistat.h"
#include "tcpioctl.h"


/*  Function:              GetTCPHandle
    Description:
      Opens a handle to the TCP driver
    Parameters:
      pTCPDriverHandle --  Pointer to a handle variable.
    Return Value (DWORD):  Returns TRUE if successful, and places 
                           a valid handle to the TCP driver in the
                           handle pointed to by pTCPDriverHandle, or
                           returns FALSE otherwise, and sets the
                           handle to INVALID_HANDLE_VALUE.
*/
DWORD GetTCPHandle( PHANDLE pTCPDriverHandle )
{
#define FILE_OPEN_IF                    0x00000003
#define FILE_SYNCHRONOUS_IO_NONALERT    0x00000020
#define OBJ_CASE_INSENSITIVE            0x00000040L

typedef NTSTATUS (NTAPI *P_NT_CREATE_FILE)(
    OUT PHANDLE              FileHandle,
    IN  ACCESS_MASK          DesiredAccess,
    IN  POBJECT_ATTRIBUTES   ObjectAttributes,
    OUT PIO_STATUS_BLOCK     IoStatusBlock,
    IN  PLARGE_INTEGER       AllocationSize OPTIONAL,
    IN  ULONG                FileAttributes,
    IN  ULONG                ShareAccess,
    IN  ULONG                CreateDisposition,
    IN  ULONG                CreateOptions,
    IN  PVOID                EaBuffer OPTIONAL,
    IN  ULONG                EaLength );

  HINSTANCE hNtDLL;
  P_NT_CREATE_FILE pNtCreateFile;
  NTSTATUS rVal;
  WCHAR TCPDriverName[] = DD_TCP_DEVICE_NAME;

  OBJECT_ATTRIBUTES  objectAttributes;
  IO_STATUS_BLOCK    ioStatusBlock;
  UNICODE_STRING     UnicodeStr;

  *pTCPDriverHandle = INVALID_HANDLE_VALUE;

  if( ( hNtDLL = LoadLibrary( L"ntdll" ) ) == NULL )
    return( FALSE );

  pNtCreateFile = (P_NT_CREATE_FILE) GetProcAddress( hNtDLL, 
            "NtCreateFile" );
  if( pNtCreateFile == NULL )
    return( FALSE );

  UnicodeStr.Buffer = TCPDriverName;
  UnicodeStr.Length = (USHORT)(wcslen(TCPDriverName) * sizeof(WCHAR));
  UnicodeStr.MaximumLength = UnicodeStr.Length + sizeof(UNICODE_NULL);

  objectAttributes.Length = sizeof( OBJECT_ATTRIBUTES );
  objectAttributes.ObjectName = &UnicodeStr;
  objectAttributes.Attributes = OBJ_CASE_INSENSITIVE;
  objectAttributes.RootDirectory = NULL;
  objectAttributes.SecurityDescriptor = NULL;
  objectAttributes.SecurityQualityOfService = NULL;

  rVal = pNtCreateFile( pTCPDriverHandle,
                       SYNCHRONIZE | GENERIC_EXECUTE,
                       &objectAttributes,
                       &ioStatusBlock,
                       NULL,
                       FILE_ATTRIBUTE_NORMAL,
                       FILE_SHARE_READ | FILE_SHARE_WRITE,
                       FILE_OPEN_IF,
                       FILE_SYNCHRONOUS_IO_NONALERT,
                       NULL,
                       0 );

  if( rVal < 0 )
  {
    printf( "\nFailed to create TCP Driver handle; NT status code = %d.", rVal );
    *pTCPDriverHandle = INVALID_HANDLE_VALUE;
    return( FALSE );
  }
  return( TRUE );
}


/*  Function:              GetEntityList
    Description:
      Allocates a buffer for and retrieves an array of TDIEntityID 
    structures that identifies the entities supported by 
    the TCP/IP device driver.
    Parameters:
      TCPDriverHandle  --  An open handle to the TCP Driver; if 
            no such handle is available, 
            may be INVALID_HANDLE_VALUE.
      lplpEntities     --  Pointer to a buffer that contains 
            the array of TDIEntityID structures. 
            Must be freed by the calling process 
            using LocalFree( ).
    Return Value:
      DWORD  --  the number of entity structures in the returned array
*/
DWORD GetEntityArray( IN HANDLE TCPDriverHandle, 
    OUT TDIEntityID **lplpEntities )
{
  TCP_REQUEST_QUERY_INFORMATION_EX  req;
  DWORD arrayLen = sizeof(TDIEntityID) * MAX_TDI_ENTITIES;
  DWORD bufferLen = arrayLen;
  TDIEntityID * pEntity = NULL;
  NTSTATUS status = TDI_SUCCESS;
  DWORD temporaryHandle = 0;
  int i;


// First, if the handle passed in is not valid, try to obtain one.
  if( TCPDriverHandle == INVALID_HANDLE_VALUE )
  {
    if( GetTCPHandle( &TCPDriverHandle ) == FALSE )
    {
      *lplpEntities = NULL;
      return( 0 );
    }
    temporaryHandle = TRUE;
  }

// Next, set up the input structure for the IOCTL operation.
  req.ID.toi_entity.tei_entity    = GENERIC_ENTITY;
  req.ID.toi_entity.tei_instance  = 0;
  req.ID.toi_class                = INFO_CLASS_GENERIC;
  req.ID.toi_type                 = INFO_TYPE_PROVIDER;
  req.ID.toi_id                   = ENTITY_LIST_ID;


// The loop below is defensively engineered:
// (1)  In the first place, it is unlikely that more 
//     than MAX_TDI_ENTITIES of TCP/IP entities exist, 
//     so the loop should execute only once.
// (2)  Execution is limited to 4 iterations to rule out 
//     infinite looping in case of parameter corruption. Only 2
//     iterations should ever be necessary unless entities are 
//     being added while the loop is running.
  for( i = 0; i < 4; ++i )
  {
    if( pEntity != NULL )
    {
      LocalFree( pEntity );
      pEntity = NULL;
      bufferLen = arrayLen;
    }

    if( arrayLen == 0 )
      break;

    pEntity = (TDIEntityID *) LocalAlloc( LMEM_FIXED, bufferLen );
    if( pEntity == NULL )
    {
      arrayLen = 0;
      break;
    }

    if( !DeviceIoControl( TCPDriverHandle, // Handle to TCP driver
                          IOCTL_TCP_QUERY_INFORMATION_EX, // Cmd code
                          &req,            // Pointer to input buffer
                          sizeof(req),     // Size of ipt buffer
                          pEntity,         // Ptr to output buffer
                          bufferLen,       // Size of output buffer
                          &arrayLen,       // Actual size of array
                          NULL ) )
      status = GetLastError( );

    // Even if the output buffer is too small, the TCP driver 
    // returns a status of TDI_SUCCESS; it is the value returned in
    // arrayLen that indicates whether the entire array was 
    // successfully copied to the output buffer.
    if( status == TDI_SUCCESS )
    {
      if( arrayLen && ( arrayLen <= bufferLen ) )
        break;
    }
    else
      arrayLen = 0;
  }
  if( temporaryHandle )
    CloseHandle( TCPDriverHandle );

  *lplpEntities = pEntity;
  return( (DWORD)( arrayLen / sizeof(TDIEntityID) ) );
}

int main( )
{
  DWORD i;
  DWORD entityCount;
  TDIEntityID
    *entityArray,
    *entityPtr;

  if( !( entityCount = GetEntityArray( INVALID_HANDLE_VALUE, 
    &entityArray ) ) )
    return( 1 );

  entityPtr = entityArray;
  printf( "\n\nList of %d Transport Driver Interface Entities on this machine:\n", entityCount );

  for( i = 0; i < entityCount; ++i )
  {
    printf( "\n  Entity #%d:\n    Category (tei_entity) is ", i );
    switch( entityPtr->tei_entity )
    {
      case GENERIC_ENTITY:
        printf( "Generic." );
        break;
      case CL_NL_ENTITY:
        printf( "Connectionless Network-Layer (CL_NL)" );
        break;
      case CO_NL_ENTITY:
        printf( "Connected Network-Layer (CO_NL)" );
        break;
      case CL_TL_ENTITY:
        printf( "Connectionless Transport-Layer (CL_TL)" );
        break;
      case CO_TL_ENTITY:
        printf( "Connected Transport-Layer (CO_TL)" );
        break;
      case AT_ENTITY:
        printf( "Address Translation (AT)" );
        break;
      case IF_ENTITY:
        printf( "Interface (IF)" );
        break;
      case ER_ENTITY:
        printf( "Echo Request/Response (ER)" );
        break;
      default:
        printf( "[Unidentified Entity Type] = 0x%x", 
        entityPtr->tei_entity );
    }
    printf( "\n Instance (tei_instance) = %d\n", 
        entityPtr->tei_instance );

    ++entityPtr;
  }

//  Free the entity-array buffer before quitting.
    LocalFree( entityArray );

  return( 0 );
}

Требования

Требование	Ценность
заголовка	tcpioctl.h

См. также

DeviceIoControl

вспомогательный API протокола Интернета

Справочник базы сведений об управлении