PFN_WSK_SOCKET_CONNECT função de retorno de chamada (wsk.h)
A função WskSocketConnect cria um novo soquete orientado à conexão, associa-o a um endereço de transporte local, conecta-o a um determinado endereço de transporte remoto e retorna um ponteiro para o objeto de soquete associado.
Sintaxe
PFN_WSK_SOCKET_CONNECT PfnWskSocketConnect;
NTSTATUS PfnWskSocketConnect(
[in] PWSK_CLIENT Client,
[in] USHORT SocketType,
[in] ULONG Protocol,
[in] PSOCKADDR LocalAddress,
[in] PSOCKADDR RemoteAddress,
ULONG Flags,
[in, optional] PVOID SocketContext,
[in, optional] const WSK_CLIENT_CONNECTION_DISPATCH *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] SocketType
O tipo do 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] LocalAddress
Um ponteiro para uma estrutura que especifica o endereço de transporte local ao qual associar o soquete. O aplicativo WSK deve especificar um ponteiro para o tipo de estrutura SOCKADDR específico que corresponde à família de endereços para o soquete que está sendo criado.
[in] RemoteAddress
Um ponteiro para uma estrutura que especifica o endereço de transporte remoto ao qual conectar o soquete. O aplicativo WSK deve especificar um ponteiro para o tipo de estrutura SOCKADDR específico que corresponde à família de endereços para o soquete que está sendo criado.
Flags
Esse parâmetro é reservado para uso do sistema. Os aplicativos WSK devem definir esse parâmetro como zero.
[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.
[in, optional] Dispatch
Um ponteiro para uma constante WSK_CLIENT_CONNECTION_DISPATCH estrutura. 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. 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 esse ponteiro como 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
WskSocketConnect 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 SocketType e Protocol .
O subsistema WSK determina a família de endereços para o novo soquete da família de endereços especificada na estrutura SOCKADDR apontada pelo parâmetro LocalAddress .
Se o aplicativo WSK precisar definir uma opção de soquete ou emitir uma operação de controle de E/S no soquete antes de associar ou conectar o soquete, o aplicativo WSK deverá chamar as funções WskSocket, WskBind e WskConnect em vez de chamar a função WskSocketConnect .
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 |