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

Artigo
08/08/2023

A função WskSocket cria um novo soquete e retorna um ponteiro para o objeto de soquete associado.

Sintaxe

PFN_WSK_SOCKET PfnWskSocket;

NTSTATUS PfnWskSocket(
  [in]           PWSK_CLIENT Client,
  [in]           ADDRESS_FAMILY AddressFamily,
  [in]           USHORT SocketType,
  [in]           ULONG Protocol,
  [in]           ULONG Flags,
  [in, optional] PVOID SocketContext,
  [in, optional] const VOID *Dispatch,
  [in, optional] PEPROCESS OwningProcess,
  [in, optional] PETHREAD OwningThread,
  [in, optional] PSECURITY_DESCRIPTOR SecurityDescriptor,
  [in, out]      PIRP Irp
)
{...}

Parâmetros

[in] Client

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

[in] AddressFamily

A família de endereços para o soquete que está sendo criado. Para obter mais informações sobre famílias de endereços com suporte, consulte Famílias de Endereços do WSK.

[in] SocketType

O tipo de soquete que está sendo criado. Há suporte para os seguintes tipos de soquete:

SOCK_STREAM

Dá suporte à comunicação de fluxo de bytes orientada a conexão confiável.

SOCK_DGRAM

Dá suporte à comunicação de datagrama sem conexão não confiável.

SOCK_RAW

Dá suporte ao acesso bruto ao protocolo de transporte.

Para obter mais informações sobre os tipos de soquete com suporte para cada família de endereços com suporte, consulte
Famílias de endereços WSK.

[in] Protocol

O protocolo de transporte para o soquete que está sendo criado. Para obter mais informações sobre os protocolos com suporte para cada família de endereços com suporte, consulte Famílias de endereços do WSK.

[in] Flags

Um sinalizador que especifica a categoria de soquete WSK para o soquete que está sendo criado. Esse parâmetro pode ser um dos seguintes sinalizadores:

WSK_FLAG_BASIC_SOCKET

Um soquete básico será criado que só pode ser usado para obter e definir opções de soquete de pilha de transporte ou para executar operações de controle de E/S de soquete.

WSK_FLAG_LISTEN_SOCKET

Será criado um soquete de escuta que pode ser usado para escutar conexões de entrada de endereços de transporte remoto.

WSK_FLAG_DATAGRAM_SOCKET

Será criado um soquete de datagrama que pode ser usado para enviar e receber datagramas.

WSK_FLAG_CONNECTION_SOCKET

Um soquete orientado à conexão será criado que pode ser usado para enviar e receber dados de rede por meio de uma conexão.

WSK_FLAG_STREAM_SOCKET

Será criado um soquete de fluxo que pode ser usado para escutar conexões de entrada de endereços de transporte remoto ou enviar e receber dados de rede por meio de uma conexão.

Se um aplicativo WSK não especificar nenhum dos sinalizadores anteriores, o WskSocket criará um soquete básico.

[in, optional] SocketContext

Um ponteiro para um contexto fornecido pelo chamador para o soquete que está sendo criado. O subsistema WSK passa esse ponteiro para as funções de retorno de chamada de evento do soquete. As informações de contexto são opacas para o subsistema do WSK e devem ser armazenadas na memória não paginada. Se o aplicativo WSK não estiver habilitando nenhuma função de retorno de chamada de evento no novo soquete, ele deverá definir esse ponteiro como NULL. Para um soquete básico, esse ponteiro sempre deve ser NULL.

[in, optional] Dispatch

Um ponteiro para uma estrutura de expedição de cliente constante. Essa estrutura é uma tabela de expedição que contém ponteiros para as funções de retorno de chamada de evento para o novo soquete. Dependendo da categoria de soquete WSK do soquete (conforme especificado pelo parâmetro Flags ), esse parâmetro é um ponteiro para uma das estruturas a seguir.

Sinalizador	Estrutura de tabela de expedição
WSK_FLAG_LISTEN_SOCKET	WSK_CLIENT_LISTEN_DISPATCH
WSK_FLAG_DATAGRAM_SOCKET	WSK_CLIENT_DATAGRAM_DISPATCH
WSK_FLAG_CONNECTION_SOCKET	WSK_CLIENT_CONNECTION_DISPATCH
WSK_FLAG_STREAM_SOCKET	WSK_CLIENT_STREAM_DISPATCH

Se o aplicativo WSK não estiver habilitando todas as funções de retorno de chamada de evento para o novo soquete, ele deverá definir os ponteiros na tabela de expedição como NULL para as funções de retorno de chamada de evento que ele não habilita. Se o aplicativo WSK não estiver habilitando nenhuma função de retorno de chamada de evento no novo soquete, ele deverá definir o ponteiro Dispatch como NULL. Para um soquete básico, esse ponteiro sempre deve ser NULL.

[in, optional] OwningProcess

Um ponteiro para o processo do qual o subsistema do WSK recuperará o contexto de segurança a ser usado quando associar o soquete. O subsistema WSK usa o contexto de segurança para determinar se o endereço de transporte local pode ser compartilhado se esse endereço já estiver em uso. Para especificar o processo atual, um aplicativo WSK define esse ponteiro como NULL.

[in, optional] OwningThread

Um ponteiro para um thread específico do qual o subsistema do WSK recuperará o contexto de segurança a ser usado quando associar o soquete. O subsistema WSK usa o contexto de segurança para determinar se o endereço de transporte local pode ser compartilhado se esse endereço já estiver em uso. Se um aplicativo WSK não precisar especificar um thread específico, ele definirá esse ponteiro como NULL.

[in, optional] SecurityDescriptor

Um ponteiro para uma estrutura SECURITY_DESCRIPTOR que especifica o descritor de segurança a ser aplicado ao soquete que está sendo criado. O descritor de segurança controla o compartilhamento do endereço de transporte local ao qual o soquete está associado. Se um aplicativo WSK especificar um ponteiro não NULL , ele deverá especificar um ponteiro para uma cópia armazenada em cache de um descritor de segurança obtido chamando a função WskControlClient com o código de controle WSK_CACHE_SD . Para especificar um descritor de segurança padrão que não permite o compartilhamento do endereço de transporte local, um aplicativo WSK define SecurityDescriptor como NULL.

Para obter mais informações sobre a estrutura de SECURITY_DESCRIPTOR, consulte a página de referência para SECURITY_DESCRIPTOR na documentação do SDK do Microsoft Windows.

[in, out] Irp

Um ponteiro para um IRP alocado pelo chamador que o subsistema WSK usa para concluir a criação do novo soquete 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

O WskSocket retorna um dos seguintes códigos NTSTATUS:

Código de retorno	Descrição
STATUS_SUCCESS	O novo soquete foi criado com êxito. O IRP será concluído com êxito status.
STATUS_PENDING	O subsistema do WSK não pôde criar o soquete imediatamente. O subsistema WSK concluirá o IRP depois de criar o novo soquete. O status da criação do soquete será retornado no campo IoStatus.Status do IRP.
Outros códigos status	Ocorreu um erro. O IRP será concluído com falha status.

Comentários

Se o IRP for concluído com êxito status, o campo IoStatus.Information do IRP conterá um ponteiro para uma estrutura de objeto de soquete (WSK_SOCKET) para o novo soquete.

Um aplicativo WSK pode obter uma lista de protocolos de transporte disponíveis chamando a função WskControlClient com o código de controle WSK_TRANSPORT_LIST_QUERY . WskControlClient retorna uma lista de estruturas WSK_TRANSPORT que contém todas as combinações válidas dos parâmetros AddressFamily, SocketType e Protocol .

Quando um aplicativo WSK cria com êxito um novo soquete, todas as funções de retorno de chamada de evento no novo soquete são desabilitadas por padrão. Para obter mais informações sobre como habilitar qualquer uma das funções de retorno de chamada de evento do novo soquete, consulte Habilitando e desabilitando funções de retorno de chamada de evento.

Se um aplicativo WSK especificar um ponteiro não NULL para o parâmetro SecurityDescriptor , ele não deverá liberar o descritor de segurança armazenado em cache até que o IRP seja concluído.

O subsistema WSK aloca a memória para a estrutura do objeto de soquete (WSK_SOCKET) para o novo soquete em nome do aplicativo WSK. O subsistema WSK desaloca essa memória quando o soquete é fechado.

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