PFN_WSK_CONTROL_SOCKET função de retorno de chamada (wsk.h)
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 socket 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 especifica 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 WSK. O protocolo de rede subjacente pode dar suporte a opções de soquete adicionais.
Se o parâmetro RequestType for definido como WskIoctl, o parâmetro ControlCode especifica 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 soquete de protocolo de transporte ou 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 de Nível será ignorado.
[in] InputSize
O número de bytes de dados no buffer apontado pelo parâmetro InputBuffer.
[in, optional] InputBuffer
Um buffer alocado por 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 para 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 para 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 que é apontado pelo parâmetro OutputBuffer. Um aplicativo WSK deve definir o parâmetro OutputSizeReturned para NULL, exceto quando todos os seguintes forem verdadeiros:
- O parâmetro irp é definido como NULL.
- A operação que está sendo executada retorna dados de saída no buffer que é 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 por 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 do WSK, consulte Usando IRPs com funções de kernel winsock.
Se o parâmetro RequestType estiver definido como WskSetOption ou WskGetOption, o parâmetro Irp será necessário 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 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 do parâmetro Irp para cada uma das operações de controle de E/S com suporte, consulte operações ioctl do soquete WSK.
Valor de retorno
WskControlSocket retorna um dos seguintes códigos NTSTATUS:
| Código de retorno | Descrição |
|---|---|
|
A operação de controle 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 o status de êxito e o número de bytes retornados no buffer apontado pelo parâmetro OutputBuffer será retornado no campo IoStatus.Information do IRP. |
|
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. 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. |
|
O subsistema do 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. |
|
O soquete não está mais funcional. O IRP será concluído com o status de falha. O aplicativo WSK deve chamar a função WskCloseSocket para fechar o soquete o mais rápido possível. |
|
Ocorreu um erro. O IRP será concluído com o status de falha. |
Observações
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 operações IOCTL do soquete WSK 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 o parâmetro OutputBuffer deverão permanecer válidos até que o IRP seja concluído. Se o aplicativo WSK alocar 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 alocar 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 no IRQL <= DISPATCH_LEVEL exceto quando o parâmetro RequestType é definido como WskIoctl e o parâmetro do ControlCode é definido como SIO_ADDRESS_LIST_QUERY, SIO_ADDRESS_LIST_CHANGEou SIO_ADDRESS_LIST_SORT. Nessa situação, os chamadores devem estar em execução no IRQL = PASSIVE_LEVEL.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Disponível no Windows Vista e versões posteriores dos sistemas operacionais Windows. |
| da Plataforma de Destino | Universal |
| cabeçalho | wsk.h (inclua Wsk.h) |
| IRQL | <= DISPATCH_LEVEL (consulte a seção Comentários) |
Consulte também
operações IOCTL do soquete WSK
WSK_PROVIDER_CONNECTION_DISPATCH WSK_PROVIDER_DATAGRAM_DISPATCH