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

Artigo
03/01/2024

A função WskGetLocalAddress recupera o endereço de transporte local de um soquete.

Sintaxe

PFN_WSK_GET_LOCAL_ADDRESS PfnWskGetLocalAddress;

NTSTATUS PfnWskGetLocalAddress(
  [in]      PWSK_SOCKET Socket,
  [out]     PSOCKADDR LocalAddress,
  [in, out] PIRP Irp
)
{...}

Parâmetros

[in] Socket

Um ponteiro para uma estrutura WSK_SOCKET que especifica o objeto de soquete para o soquete que está sendo consultado.

[out] LocalAddress

Um ponteiro para um buffer alocado pelo chamador que recebe o endereço de transporte local do soquete. O buffer deve estar localizado na memória não paginada. O buffer também deve ser grande o suficiente para conter o tipo de estrutura SOCKADDR específico que corresponde à família de endereços especificada pelo aplicativo WSK ao criar o soquete.

Para um soquete orientado à conexão que o aplicativo WSK aceitou em um soquete de escuta, a família de endereços é igual à família de endereços especificada pelo aplicativo WSK ao criar o soquete de escuta.

[in, out] Irp

Um ponteiro para um IRP alocado pelo chamador que o subsistema WSK usa para concluir a operação de recuperação de forma assíncrona. Para obter mais informações sobre como usar IRPs com funções WSK, consulte Usando IRPs com funções de kernel Winsock.

Retornar valor

WskGetLocalAddress retorna um dos seguintes códigos NTSTATUS:

Código de retorno	Descrição
STATUS_SUCCESS	O endereço de transporte local do soquete foi recuperado com êxito. O IRP será concluído com êxito status.
STATUS_PENDING	O subsistema WSK não pôde recuperar o endereço de transporte local para o soquete imediatamente. O subsistema WSK concluirá o IRP depois de recuperar o endereço de transporte local do soquete. O status da operação de recuperação será retornado no campo IoStatus.Status do IRP.
STATUS_INVALID_DEVICE_STATE	O soquete não está associado a um endereço de transporte local. O IRP será concluído com falha status.
STATUS_FILE_FORCED_CLOSED	O soquete não está mais funcional. O IRP será concluído com falha status. O aplicativo WSK deve chamar a função WskCloseSocket para fechar o soquete o mais rápido possível.
Outros códigos status	Ocorreu um erro. O IRP será concluído com falha status.

Comentários

Um aplicativo WSK pode chamar a função WskGetLocalAddress somente em um soquete associado a um endereço de transporte local.

Um soquete de escuta, datagrama ou fluxo é associado a um endereço de transporte local quando o aplicativo WSK chama a função WskBind .

Um soquete orientado para conexão está associado a um endereço de transporte local de uma das seguintes maneiras:

O aplicativo WSK chama a função WskBind .
O aplicativo WSK cria, associa e conecta o soquete chamando a função WskSocketConnect .
O subsistema WSK associa o soquete quando o aplicativo WSK aceita uma solicitação de conexão de entrada em um soquete de escuta.

A função WskGetLocalAddress é particularmente útil para determinar o endereço de transporte local específico que foi atribuído a um soquete pelo protocolo de transporte quando o soquete foi associado ao endereço curinga local. Para um soquete orientado à conexão associado ao endereço curinga local, o endereço de transporte local pode não ser atribuído ao soquete pelo protocolo de transporte até que o soquete esteja conectado a um endereço de transporte remoto. A etapa em que o endereço de transporte local é atribuído ao soquete depende do protocolo de transporte. Para TCP, o número da porta é atribuído quando um soquete orientado à conexão é associado, mas o endereço IP não é atribuído até que o soquete esteja conectado.

Se a função WskGetLocalAddress retornar STATUS_PENDING, o buffer apontado pelo parâmetro LocalAddress deverá permanecer válido até que o IRP seja concluído. Se o aplicativo WSK alocou o buffer com uma das funções ExAllocateXxx, ele não poderá liberar a memória com a função ExFree Xxx correspondente até que o IRP seja concluído. Se o aplicativo WSK alocou o buffer na pilha, ele não poderá retornar da função que chama a função WskGetLocalAddress até que o IRP seja concluído.

Requisitos

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