Função GetExtendedTcpTable (iphlpapi.h)

Artigo
08/24/2023

A função GetExtendedTcpTable recupera uma tabela que contém uma lista de pontos de extremidade TCP disponíveis para o aplicativo.

Sintaxe

IPHLPAPI_DLL_LINKAGE DWORD GetExtendedTcpTable(
  [out]     PVOID           pTcpTable,
  [in, out] PDWORD          pdwSize,
  [in]      BOOL            bOrder,
  [in]      ULONG           ulAf,
  [in]      TCP_TABLE_CLASS TableClass,
  [in]      ULONG           Reserved
);

Parâmetros

[out] pTcpTable

Um ponteiro para a estrutura da tabela que contém os pontos de extremidade TCP filtrados disponíveis para o aplicativo. Para obter informações sobre como determinar o tipo de tabela retornado com base em combinações de parâmetros de entrada específicas, consulte a seção Comentários mais adiante neste documento.

[in, out] pdwSize

O tamanho estimado da estrutura retornada em pTcpTable, em bytes. Se esse valor for definido muito pequeno, ERROR_INSUFFICIENT_BUFFER será retornado por essa função e esse campo conterá o tamanho correto da estrutura.

[in] bOrder

Um valor que especifica se a tabela de conexão TCP deve ser classificada. Se esse parâmetro for definido como TRUE, os pontos de extremidade TCP na tabela serão classificados em ordem crescente, começando com o endereço IP local mais baixo. Se esse parâmetro for definido como FALSE, os pontos de extremidade TCP na tabela aparecerão na ordem em que foram recuperados.

Os seguintes valores são comparados (conforme listado) ao ordenar os pontos de extremidade TCP:

Endereço IP local
ID do escopo local (aplicável quando o parâmetro ulAf é definido como AF_INET6)
Porta TCP local
Endereço IP remoto
ID de escopo remoto (aplicável quando o parâmetro ulAf é definido como AF_INET6)
Porta TCP remota

[in] ulAf

A versão do IP usada pelos pontos de extremidade TCP.

Valor	Significado
AF_INET	O IPv4 é usado.
AF_INET6	IPv6 é usado.

[in] TableClass

O tipo da estrutura da tabela TCP a ser recuperada. Esse parâmetro pode ser um dos valores da enumeração TCP_TABLE_CLASS .

Na SDK do Windows lançada para o Windows Vista e posteriores, a organização dos arquivos de cabeçalho foi alterada e a enumeração TCP_TABLE_CLASS é definida no arquivo de cabeçalho Iprtrmib.h, não no arquivo de cabeçalho Iphlpapi.h.

O valor de enumeração TCP_TABLE_CLASS é combinado com o valor do parâmetro ulAf para determinar as informações de TCP estendidas a serem recuperadas.

[in] Reserved

Reservado. Esse valor precisa ser zero.

Retornar valor

Se a chamada for bem-sucedida, o valor NO_ERROR será retornado.

Se a função falhar, o valor retornado será um dos seguintes códigos de erro.

Código de retorno	Descrição
ERROR_INSUFFICIENT_BUFFER	Uma quantidade insuficiente de espaço foi alocada para a tabela. O tamanho da tabela é retornado no parâmetro pdwSize e deve ser usado em uma chamada subsequente para essa função para recuperar a tabela com êxito. Esse erro também será retornado se o parâmetro pTcpTable for NULL.
ERROR_INVALID_PARAMETER	Um parâmetro inválido foi passado para a função. Esse erro será retornado se o parâmetro TableClass contiver um valor que não está definido na enumeração TCP_TABLE_CLASS .

Comentários

O tipo de tabela retornado por essa função depende da combinação específica do parâmetro ulAf e do parâmetro TableClass .

Quando o parâmetro ulAf é definido como AF_INET, a tabela a seguir indica o tipo de tabela TCP a ser recuperado na estrutura apontada pelo parâmetro pTcpTable para cada valor TableClass possível.

Valor de TableClass	Estrutura pTcpTable
TCP_TABLE_BASIC_ALL	MIB_TCPTABLE
TCP_TABLE_BASIC_CONNECTIONS	MIB_TCPTABLE
TCP_TABLE_BASIC_LISTENER	MIB_TCPTABLE
TCP_TABLE_OWNER_MODULE_ALL	MIB_TCPTABLE_OWNER_MODULE
TCP_TABLE_OWNER_MODULE_CONNECTIONS	MIB_TCPTABLE_OWNER_MODULE
TCP_TABLE_OWNER_MODULE_LISTENER	MIB_TCPTABLE_OWNER_MODULE
TCP_TABLE_OWNER_PID_ALL	MIB_TCPTABLE_OWNER_PID
TCP_TABLE_OWNER_PID_CONNECTIONS	MIB_TCPTABLE_OWNER_PID
TCP_TABLE_OWNER_PID_LISTENER	MIB_TCPTABLE_OWNER_PID

Quando o parâmetro ulAf é definido como AF_INET6, a tabela a seguir indica o tipo de tabela TCP a ser recuperado na estrutura apontada pelo parâmetro pTcpTable para cada valor TableClass possível.

Valor de TableClass	Estrutura pTcpTable
TCP_TABLE_OWNER_MODULE_ALL	MIB_TCP6TABLE_OWNER_MODULE
TCP_TABLE_OWNER_MODULE_CONNECTIONS	MIB_TCP6TABLE_OWNER_MODULE
TCP_TABLE_OWNER_MODULE_LISTENER	MIB_TCP6TABLE_OWNER_MODULE
TCP_TABLE_OWNER_PID_ALL	MIB_TCP6TABLE_OWNER_PID
TCP_TABLE_OWNER_PID_CONNECTIONS	MIB_TCP6TABLE_OWNER_PID
TCP_TABLE_OWNER_PID_LISTENER	MIB_TCP6TABLE_OWNER_PID

A função GetExtendedTcpTable chamada com o parâmetro ulAf definido como AF_INET6 e o TableClass definido como TCP_TABLE_BASIC_LISTENER, TCP_TABLE_BASIC_CONNECTIONS ou TCP_TABLE_BASIC_ALL não tem suporte e retorna ERROR_NOT_SUPPORTED.

No SDK do Windows lançado para o Windows Vista e posterior, a organização dos arquivos de cabeçalho foi alterada. As várias estruturas MIB_TCPTABLE são definidas no arquivo de cabeçalho Tcpmib.h , não no arquivo de cabeçalho Iprtrmib.h . Observe que o arquivo de cabeçalho Tcpmib.h é incluído automaticamente em Iprtrmib.h, que é incluído automaticamente no arquivo de cabeçalho Iphlpapi.h . Os arquivos de cabeçalho Tcpmib.h e Iprtrmib.h nunca devem ser usados diretamente.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista, Windows XP com SP2 [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2008, Windows Server 2003 com SP1 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	iphlpapi.h
Biblioteca	Iphlpapi.lib
DLL	Iphlpapi.dll