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

Artigo
08/08/2023

A função WskControlSocket executa operações de controle em um soquete.

Sintaxe

PFN_WSK_CONTROL_SOCKET PfnWskControlSocket;

NTSTATUS PfnWskControlSocket(
  [in]            PWSK_SOCKET Socket,
  [in]            WSK_CONTROL_SOCKET_TYPE RequestType,
  [in]            ULONG ControlCode,
  [in]            ULONG Level,
  [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] Socket

Um ponteiro para uma estrutura WSK_SOCKET que especifica o objeto de soquete para o soquete no qual a operação de controle está sendo executada.

[in] RequestType

Um valor que especifica o tipo de operação de controle que está sendo executada. Um aplicativo WSK define esse parâmetro como um dos seguintes valores:

WskSetOption

Defina o estado ou o valor de uma opção de soquete.

WskGetOption

Obtenha o estado ou o valor de uma opção de soquete.

WskIoctl

Executar uma operação de controle de E/S.

[in] ControlCode

Se o parâmetro RequestType for definido como WskSetOption ou WskGetOption, o parâmetro ControlCode especificará a opção de soquete específica cujo valor está sendo definido ou recuperado. Para obter mais informações sobre as opções de soquete compatíveis com o subsistema WSK, consulte Opções de soquete do WSK. O protocolo de rede subjacente pode dar suporte a opções de soquete adicionais.

Se o parâmetro RequestType estiver definido como WskIoctl, o parâmetro ControlCode especificará a operação de controle de E/S específica que está sendo executada. Para obter mais informações sobre operações de controle de E/S compatíveis com o subsistema WSK, consulte Operações IOCTL do soquete WSK. O protocolo de rede subjacente pode dar suporte a operações de controle de E/S de soquete adicionais.

[in] Level

O nível na pilha de rede no qual o valor de uma opção de soquete está sendo definido ou recuperado. Para opções de soquete no nível do subsistema do WSK, o aplicativo WSK deve definir esse parâmetro como SOL_SOCKET. Para opções de protocolo de transporte ou soquete de nível de protocolo de rede, o aplicativo WSK deve definir esse parâmetro para o nível apropriado para o transporte subjacente.

Se o parâmetro RequestType for definido como WskIoctl, o parâmetro Level será ignorado.

[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 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 o parâmetro OutputSizeReturned como NULL , exceto quando todos os itens a seguir forem verdadeiros:

O parâmetro Irp é definido como 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.

Se o parâmetro RequestType for definido como WskSetOption ou WskGetOption, o parâmetro Irp será necessário, será opcional ou deverá ser NULL dependendo da opção de soquete específica que está sendo definida ou recuperada. Para obter mais informações sobre os requisitos do parâmetro Irp para cada uma das opções de soquete com suporte, consulte Opções de soquete do WSK.

Se o parâmetro RequestType for definido como WskIoctl, o parâmetro Irp será necessário, será opcional ou deverá ser NULL dependendo da operação de controle de E/S específica que está sendo executada. Para obter mais informações sobre os requisitos para o parâmetro Irp para cada uma das operações de controle de E/S com suporte, consulte Operações ioctl de soquete WSK.

Retornar valor

WskControlSocket 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 e o número de bytes retornados no buffer apontado pelo parâmetro OutputBuffer será retornado no campo IoStatus.Information do IRP.
STATUS_PENDING	O subsistema 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. Se a operação for bem-sucedida, o número de bytes retornados no buffer apontado pelo parâmetro OutputBuffer será retornado no campo IoStatus.Information do IRP.
STATUS_EVENT_PENDING	O subsistema WSK não pôde concluir a operação de controle imediatamente. Esse valor é retornado somente quando um aplicativo WSK está desabilitando uma função de retorno de chamada de evento em um soquete quando há chamadas em andamento para essa função de retorno de chamada de evento e quando o parâmetro Irp é NULL. Para obter mais informações sobre como desabilitar funções de retorno de chamada de evento, consulte SO_WSK_EVENT_CALLBACK.
STATUS_FILE_FORCED_CLOSED	O soquete não é mais funcional. O IRP será concluído com status de falha. O aplicativo WSK deve chamar a função WskCloseSocket para fechar o soquete o mais rápido possível.
Outros códigos de status	Ocorreu um erro. O IRP será concluído com status de falha.

Comentários

Se um aplicativo WSK especificar WskSetOption ou WskGetOption no parâmetro RequestType , consulte Opções de soquete do WSK para obter mais informações sobre como os buffers de entrada e saída são usados para cada opção de soquete.

Se um aplicativo WSK especificar WskIoctl no parâmetro RequestType , consulte WSK Socket IOCTL Operations para obter mais informações sobre como os buffers de entrada e saída são usados para cada operação de controle de E/S.

Se a função WskControlSocket 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 WskControlSocket até que o IRP seja concluído.

Os chamadores da função WskControlSocket devem estar em execução em IRQL <= DISPATCH_LEVEL exceto quando o parâmetro RequestType estiver definido como WskIoctl e o parâmetro ControlCode estiver definido como SIO_ADDRESS_LIST_QUERY, SIO_ADDRESS_LIST_CHANGE ou SIO_ADDRESS_LIST_SORT. Nessa situação, os chamadores devem estar em execução em IRQL = PASSIVE_LEVEL.

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 (consulte a seção Comentários)