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

Artigo
03/01/2024

A função WskControlClient executa operações de controle em um objeto cliente WSK.

Sintaxe

PFN_WSK_CONTROL_CLIENT PfnWskControlClient;

NTSTATUS PfnWskControlClient(
  [in]            PWSK_CLIENT Client,
  [in]            ULONG ControlCode,
  [in]            SIZE_T InputSize,
  [in, optional]  PVOID InputBuffer,
  [in]            SIZE_T OutputSize,
  [out, optional] PVOID OutputBuffer,
  [out, optional] SIZE_T *OutputSizeReturned,
  [in, out]       PIRP Irp
)
{...}

Parâmetros

[in] Client

Um ponteiro para uma estrutura WSK_CLIENT que foi retornada por meio do parâmetro WskProviderNpi da função WskCaptureProviderNPI .

[in] ControlCode

A operação de controle que está sendo executada. Um aplicativo WSK pode especificar um dos seguintes códigos de controle:

WSK_TRANSPORT_LIST_QUERY

Recupere uma lista de transportes de rede disponíveis.

WSK_TRANSPORT_LIST_CHANGE

Receber notificação de uma alteração na lista de transportes de rede disponíveis.

WSK_CACHE_SD

Obtenha uma cópia armazenada em cache de um descritor de segurança.

WSK_RELEASE_SD

Libere uma cópia armazenada em cache de um descritor de segurança.

WSK_SET_STATIC_EVENT_CALLBACKS

Habilite as funções de retorno de chamada de evento especificadas automaticamente em todos os soquetes.

WSK_TDI_DEVICENAME_MAPPING

Mapeie combinações de família de endereços, tipo de soquete e protocolo para nomes de dispositivo de transportes TDI .

WSK_TDI_BEHAVIOR

Controlar se o subsistema do WSK desviará a E/S da rede para os transportes TDI .

[in] InputSize

O número de bytes de dados no buffer apontado pelo parâmetro InputBuffer .

[in, optional] InputBuffer

Um buffer alocado pelo chamador que fornece todos os dados de entrada necessários para executar a operação de controle especificada. Se nenhum dado de entrada for necessário para a operação de controle especificada, o aplicativo WSK deverá definir esse parâmetro como NULL e definir o parâmetro InputSize como zero.

[in] OutputSize

O tamanho, em bytes, do buffer apontado pelo parâmetro OutputBuffer .

[out, optional] OutputBuffer

Um buffer alocado pelo chamador que recebe todos os dados de saída retornados pela operação de controle especificada. Se nenhum dado de saída for retornado pela operação de controle especificada, o aplicativo WSK deverá definir esse parâmetro como NULL e definir o parâmetro OutputSize como zero.

[out, optional] OutputSizeReturned

Um ponteiro para uma variável do tipo ULONG que recebe o número de bytes de dados retornados no buffer apontado pelo parâmetro OutputBuffer . Um aplicativo WSK deve definir esse ponteiro como NULL , exceto quando todas as seguintes opções forem verdadeiras:

O parâmetro Irp é NULL.
A operação que está sendo executada retorna dados de saída no buffer apontado pelo parâmetro OutputBuffer .
O número de bytes de dados de saída retornados pela operação que está sendo executada é desconhecido.

[in, out] Irp

Um ponteiro para um IRP alocado pelo chamador que o subsistema WSK usa para concluir a operação de controle 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.

Esse parâmetro é necessário, é opcional ou deve ser NULL, dependendo da operação de controle de cliente específica que está sendo executada. Para obter mais informações sobre os requisitos para esse parâmetro para cada uma das operações de controle de cliente com suporte, consulte Operações de controle de cliente do WSK.

Retornar valor

WskControlClient retorna um dos seguintes códigos NTSTATUS:

Código de retorno	Descrição
STATUS_SUCCESS	A operação de controle foi concluída com êxito. Se o aplicativo WSK tiver especificado um ponteiro para um IRP no parâmetro Irp, o IRP será concluído com êxito status.
STATUS_PENDING	O subsistema do WSK não pôde concluir a operação de controle 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.
STATUS_BUFFER_OVERFLOW	O buffer de saída não é grande o suficiente para conter os dados retornados. A variável apontada pelo parâmetro OutputSizeReturned contém o tamanho do buffer necessário.
Outros códigos status	Ocorreu um erro. O IRP será concluído com falha status.

Comentários

Para obter mais informações sobre como os buffers de entrada e saída são usados para cada operação de controle do cliente, consulte Operações de controle de cliente do WSK.

Se a função WskControlClient retornar STATUS_PENDING, todos os buffers apontados pelo parâmetro InputBuffer ou pelo parâmetro OutputBuffer deverão permanecer válidos até que o IRP seja concluído. Se o aplicativo WSK alocou os buffers com uma das funções ExAllocateXxx , ele não poderá liberar a memória com a função ExFreeXxx correspondente até que o IRP seja concluído. Se o aplicativo WSK alocou os buffers na pilha, ele não poderá retornar da função que chama a função WskControlClient até que o IRP seja concluído.

Nota Não haverá suporte para TDI nas versões do Microsoft Windows após o Windows Vista. Em vez disso, use a Plataforma de Filtragem do Windows ou o Kernel winsock .

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