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、Windows SDK 中發布的頭檔，可與 IOCTL_TCP_QUERY_INFORMATION_EX搭配使用，以及 Tdiinfo.h 和 Tdistat.h，以及 WDK for 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 作業會根據 lpInBuffer 參數所指向的 TCP_REQUEST_QUERY_INFORMATION_EX 結構，擷取不同類型的資訊，如下列段落和範例程式代碼所述。

1. 列舉 TDI 實體。

若要擷取識別電腦上所有 TCP 實體的 TDIEntityID 結構陣列，請將輸入結構的 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錯誤碼。 要求清單時，會忽略輸入結構的 Context 成員。 在此情況下，輸出是 TDIEntityID 結構的陣列。 下列第一個程式代碼範例中的 GetEntityArray 函式示範如何擷取這類數位。

2. 取得特定 TDI 實體的類型資訊。

如果輸入結構的 ID.toi_entity 成員識別特定實體（如上述列舉要求傳回的 TDIEntityID 結構），則將 ID.toi_class 設定為 INFO_CLASS_GENERIC、ID.toi_typeINFO_TYPE_PROVIDER，而 ID.toi_idENTITY_TYPE_ID 會導致一或多個旗標值傳回至 lpOutBuffer 參數所指向 不帶正負號的長。 這些旗標值會識別指定實體的類型。 再次忽略輸入結構的 Context 成員。

下表顯示可傳回的可能型別旗標值。

旗	意義
AT_ARP	實體會實作ARP（位址解析通訊協定）。
AT_NULL	實體不會轉譯位址。
CL_NL_IP	實體會在網路層上實作IP（因特網通訊協定），無連線。
CL_NL_IPX	實體會在網路層上實作IPX （Internetwork Packet Exchange 通訊協定），無連線。
CL_TL_NBF	實體會實作 NBF （NetBEUI Frame 通訊協定），在傳輸層上無連線。
CL_TL_UDP	實體會在傳輸層上實作無連線的 UDP（用戶數據報通訊協定）。
CO_TL_NBF	實體會實作 NBF （NetBEUI Frame 通訊協定），在傳輸層上導向封包。
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 成員設定為識別實體、要 INFO_CLASS_PROTOCOL的 ID.toi_class、要 INFO_TYPE_PROVIDERID.toi_type，並將 ID.toi_id 設定為 IF_MIB_STATS_ID。

請注意，由於 IFEntry 是可變長度的結構，因此輸出緩衝區應該不只配置為 “sizeof（IFEntry）”，而應該配置為 “sizeof（IFEntry） + MAX_ADAPTER_DESCRIPTION_LENGTH + 1”。

4. 取得特定IP實體的 MIB-II 資訊。

MIB 資訊也可以透過將 ID.toi_entity 成員設定為識別實體 CL_NL_ENTITY、將 ID.toi_classINFO_CLASS_PROTOCOL、ID.toi_typeINFO_TYPE_PROVIDER，以及要 IP_MIB_STATS_ID的 ID.toi_id，從 IP 實體擷取 MIB 資訊。 在此情況下，會傳回 IPSNMPInfo 結構，而且輸出緩衝區可以配置為 “sizeof（IPSNMPInfo）”。

5. 取得特定IP實體的地址資訊。

如果為特定IP實體傳回 IPSNMPInfo 結構的 ipsi_numaddr 成員不是零，則可以藉由將 ID.toi_entity 成員設定為識別實體，以擷取 ipAddrEntry 結構的 陣列，方法是將 ID.toi_entity 成員設定為識別實體、ID.toi_class INFO_CLASS_PROTOCOL、ID.toi_type INFO_TYPE_PROVIDER、 和 要 IP_MIB_ADDRTABLE_ENTRY_ID的 ID.toi_id。 在此情況下，應該設定輸出緩衝區來保存大小陣列：

sizeof(IPAddrEntry) * pIpSnmpInfoReturned->ipsi_numaddr

6. 取得特定IP位址的介面資訊。

若要擷取在上方 IPAddrEntry 陣列中傳回的指定IP位址，可以擷取更多介面資訊，方法是讓 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

管理資訊基底參考