PFN_WSK_GET_NAME_INFO função de retorno de chamada (wsk.h)

Artigo
08/08/2023

A função WskGetNameInfo fornece tradução independente de protocolo de um endereço de transporte para um nome de host.

Sintaxe

PFN_WSK_GET_NAME_INFO PfnWskGetNameInfo;

NTSTATUS PfnWskGetNameInfo(
  [in]            PWSK_CLIENT Client,
  [in]            PSOCKADDR SockAddr,
  [in]            ULONG SockAddrLength,
  [out, optional] PUNICODE_STRING NodeName,
  [out, optional] PUNICODE_STRING ServiceName,
  [in]            ULONG Flags,
  [in, optional]  PEPROCESS OwningProcess,
  [in, optional]  PETHREAD OwningThread,
  [in, out]       PIRP Irp
)
{...}

Parâmetros

[in] Client

[in] Um ponteiro para uma estrutura WSK_CLIENT que foi retornada por meio do parâmetro WskProviderNpi do Função WskCaptureProviderNPI .

[in] SockAddr

[in] Um ponteiro para uma estrutura SOCKADDR que contém o endereço IP e o número da porta do soquete.

[in] SockAddrLength

[in] Especifica o comprimento, em bytes, do buffer apontado pelo parâmetro SockAddr . O valor de SockAddrLength não deve exceder o tamanho da estrutura SOCKADDR_STORAGE .

[out, optional] NodeName

[out] Um ponteiro opcional para uma estrutura UNICODE_STRING que contém uma cadeia de caracteres Unicode que representa um nome de host (nó). Em caso de êxito, o nome do host Unicode é escrito como um FQDN (Nome de Domínio Totalmente Qualificado) por padrão. O chamador deve fornecer um buffer UNICODE_STRING grande o suficiente para manter o nome do host Unicode, que inclui o caractere NULL de terminação. Se o parâmetro NodeBuffer for NULL, o chamador não desejará receber uma cadeia de caracteres de nome de host. NodeBuffer e ServiceBuffer não devem ser NULL.

[out, optional] ServiceName

[out] Um ponteiro opcional para uma estrutura UNICODE_STRING que contém uma cadeia de caracteres Unicode que representa um nome de serviço associado ao número da porta. O chamador deve fornecer um buffer de UNICODE_STRING grande o suficiente para manter o nome do serviço Unicode, que inclui o caractere NULL de terminação. Se o parâmetro NodeBuffer for NULL, o chamador não desejará receber uma cadeia de caracteres de nome de serviço. NodeBuffer e ServiceBuffer não devem ser NULL.

[in] Flags

[in] Um valor ULONG usado para personalizar o processamento dessa função.

Os seguintes sinalizadores estão disponíveis:

NI_DGRAM

Indica que o serviço é um serviço de datagrama. Esse sinalizador é necessário para os poucos serviços que fornecem números de porta diferentes para o serviço UDP e TCP.

NI_NAMEREQD

Indica que um nome de host que não pode ser resolvido pelo DNS resulta em um erro.

NI_NOFQDN

Resulta em um host local tendo apenas seu RDN (Nome Distinto Relativo) retornado no parâmetro NodeName .

NI_NUMERICHOST

Indica que a função retorna a forma numérica do nome do host em vez de seu nome, uma pesquisa DNS inversa. A forma numérica do nome do host também será retornada se o nome do host não puder ser resolvido pelo DNS.

NI_NUMERICSERV

Indica que a função retorna o número da porta do serviço em vez de seu nome. Além disso, se um nome de host não for encontrado para um endereço IP (127.0.0.2, por exemplo), o nome do host será retornado como o endereço IP.

[in, optional] OwningProcess

[in] Um ponteiro opcional para o processo do qual a função recupera o contexto de segurança. Esse contexto de segurança indica o contexto da conta de usuário no qual a função processa a solicitação de resolução de nomes.

Se esse parâmetro for NULL, a função processará a solicitação de resolução de nomes no contexto de uma conta local predefinida com privilégios mínimos.

Se esse parâmetro não for NULL e um token de representação estiver em vigor para o thread de chamada, essa função falhará e retornará STATUS_INVALID_PARAMETER.

[in, optional] OwningThread

[in] Um ponteiro opcional para o thread do qual a função recupera o contexto de segurança. Esse parâmetro só poderá ser não NULL se OwningProcess não for NULL. Caso contrário, essa função falhará e retornará STATUS_INVALID_PARAMETER.

Se esse parâmetro não for NULL e um token de representação estiver em vigor para o thread de chamada, essa função falhará e retornará STATUS_INVALID_PARAMETER.

[in, out] Irp

[entrada/saída] Um ponteiro para um IRP (pacote de solicitação de E/S) a ser usado para concluir a solicitação de forma assíncrona. Após a conclusão da solicitação, Irp ->Iostatus.Information manterá o código de status retornado.

Retornar valor

WskGetNameInfo retorna um dos seguintes códigos NTSTATUS:

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi especificado.
STATUS_NO_MATCH	O nome do host não pode ser resolvido.
STATUS_SUCCESS	A função foi concluída com êxito. Se o aplicativo WSK especificou um ponteiro para um IRP no Parâmetro irp, o IRP será concluído com um status de êxito.
STATUS_PENDING	O subsistema WSK não pôde concluir a função imediatamente. O subsistema WSK concluirá o IRP depois de concluir a operação de controle. O status da operação de controle será retornado no campo IoStatus.Status do IRP.
Outros códigos de status	Ocorreu um erro. O IRP será concluído com status de falha.

Comentários

O processo para o qual o parâmetro OwningProcess aponta ou o thread para o qual o processo OwningThread aponta indica o contexto de segurança para essa função. A conta de usuário indicada pelo contexto de segurança indica o contexto para a solicitação de resolução de nomes da função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível no Windows 7 e versões posteriores dos sistemas operacionais Windows.
Plataforma de Destino	Universal
Cabeçalho	wsk.h (inclua Wsk.h)
IRQL	PASSIVE_LEVEL