PFN_WSK_SOCKET função de retorno de chamada (wsk.h)
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_FLAG_DATAGRAM_SOCKET | WSK_CLIENT_DATAGRAM_DISPATCH |
| WSK_FLAG_CONNECTION_SOCKET | WSK_CLIENT_CONNECTION_DISPATCH |
| WSK_FLAG_STREAM_SOCKET |
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 |
|---|---|
|
O novo soquete foi criado com êxito. O IRP será concluído com êxito status. |
|
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. |
|
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 |