Compartilhar via


Função WSASocketA (winsock2.h)

A função WSASocket cria um soquete associado a um provedor de serviços de transporte específico.

Sintaxe

SOCKET WSAAPI WSASocketA(
  [in] int                 af,
  [in] int                 type,
  [in] int                 protocol,
  [in] LPWSAPROTOCOL_INFOA lpProtocolInfo,
  [in] GROUP               g,
  [in] DWORD               dwFlags
);

Parâmetros

[in] af

A especificação da família de endereços. Os valores possíveis para a família de endereços são definidos no arquivo de cabeçalho Winsock2.h .

Na SDK do Windows lançada para Windows Vista e posterior, a organização dos arquivos de cabeçalho foi alterada e os valores possíveis para a família de endereços são definidos no arquivo de cabeçalho Ws2def.h. Observe que o arquivo de cabeçalho Ws2def.h é incluído automaticamente no Winsock2.h e nunca deve ser usado diretamente.

Os valores com suporte no momento são AF_INET ou AF_INET6, que são os formatos de família de endereços da Internet para IPv4 e IPv6. Outras opções para família de endereços (AF_NETBIOS para uso com NetBIOS, por exemplo) têm suporte se um provedor de serviços do Windows Sockets para a família de endereços estiver instalado. Observe que os valores para a família de endereços AF_ e PF_ constantes da família de protocolos são idênticos (por exemplo, AF_INET e PF_INET), portanto, qualquer constante pode ser usada.

A tabela a seguir lista valores comuns para a família de endereços, embora muitos outros valores sejam possíveis.

Af Significado
AF_UNSPEC
0
A família de endereços não é especificada.
AF_INET
2
A família de endereços IPv4 (Protocolo de Internet versão 4).
AF_IPX
6
A família de endereços IPX/SPX. Essa família de endereços só terá suporte se o protocolo NWLink IPX/SPX NetBIOS Compatible Transport estiver instalado.

Não há suporte para essa família de endereços no Windows Vista e posterior.

AF_APPLETALK
16
A família de endereços do AppleTalk. Essa família de endereços só terá suporte se o protocolo AppleTalk estiver instalado.

Não há suporte para essa família de endereços no Windows Vista e posterior.

AF_NETBIOS
17
A família de endereços NetBIOS. Essa família de endereços só terá suporte se o provedor do Windows Sockets para NetBIOS estiver instalado.

O provedor do Windows Sockets para NetBIOS tem suporte em versões de 32 bits do Windows. Esse provedor é instalado por padrão em versões de 32 bits do Windows.

O provedor do Windows Sockets para NetBIOS não tem suporte em versões de 64 bits do Windows, incluindo Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 ou Windows XP.

O provedor do Windows Sockets para NetBIOS dá suporte apenas a soquetes em que o parâmetro de tipo é definido como SOCK_DGRAM.

O provedor do Windows Sockets para NetBIOS não está diretamente relacionado à interface de programação NetBIOS . Não há suporte para a interface de programação NetBIOS no Windows Vista, no Windows Server 2008 e posterior.

AF_INET6
23
A família de endereços IPv6 (Internet Protocol versão 6).
AF_IRDA
26
A família de endereços da IrDA (Associação de Dados Infravermelhos).

Essa família de endereços só terá suporte se o computador tiver uma porta infravermelha e um driver instalados.

AF_BTH
32
A família de endereços Bluetooth.

Essa família de endereços terá suporte no Windows XP com SP2 ou posterior se o computador tiver um adaptador Bluetooth e um driver instalados.

[in] type

A especificação de tipo para o novo soquete.

Os valores possíveis para o tipo de soquete são definidos no arquivo de cabeçalho Winsock2.h .

A tabela a seguir lista os valores possíveis para o parâmetro de tipo com suporte para Windows Sockets 2:

Type Significado
SOCK_STREAM
1
Um tipo de soquete que fornece fluxos de bytes sequenciados, confiáveis, bidirecionais e baseados em conexão com um mecanismo de transmissão de dados OOB. Esse tipo de soquete usa o protocolo TCP para a família de endereços da Internet (AF_INET ou AF_INET6).
SOCK_DGRAM
2
Um tipo de soquete que dá suporte a datagramas, que são buffers sem conexão e não confiáveis de um comprimento máximo fixo (normalmente pequeno). Esse tipo de soquete usa o UDP (Protocolo de Datagrama do Usuário) para a família de endereços da Internet (AF_INET ou AF_INET6).
SOCK_RAW
3
Um tipo de soquete que fornece um soquete bruto que permite que um aplicativo manipule o próximo cabeçalho de protocolo de camada superior. Para manipular o cabeçalho IPv4, a opção de soquete IP_HDRINCL deve ser definida no soquete. Para manipular o cabeçalho IPv6, a opção de soquete IPV6_HDRINCL deve ser definida no soquete.
SOCK_RDM
4
Um tipo de soquete que fornece um datagrama de mensagem confiável. Um exemplo desse tipo é a implementação de protocolo multicast PGM (Pragmática Geral Multicast) no Windows, geralmente conhecida como programação multicast confiável.

Esse valor de tipo só terá suporte se o Protocolo Multicast Confiável estiver instalado.

SOCK_SEQPACKET
5
Um tipo de soquete que fornece um pacote pseudo stream com base em datagramas.
 

No Windows Sockets 2, novos tipos de soquete foram introduzidos. Um aplicativo pode descobrir dinamicamente os atributos de cada protocolo de transporte disponível por meio da função WSAEnumProtocols . Portanto, um aplicativo pode determinar as possíveis opções de tipo de soquete e protocolo para uma família de endereços e usar essas informações ao especificar esse parâmetro. As definições de tipo de soquete nos arquivos de cabeçalho Winsock2.h e Ws2def.h serão atualizadas periodicamente conforme novos tipos de soquete, famílias de endereços e protocolos forem definidos.

No Windows Sockets 1.1, os únicos tipos de soquete possíveis são SOCK_DGRAM e SOCK_STREAM.

[in] protocol

O protocolo a ser usado. As opções possíveis para o parâmetro de protocolo são específicas para a família de endereços e o tipo de soquete especificados. Os valores possíveis para o protocolo são definidos nos arquivos de cabeçalho Winsock2.h e Wsrm.h .

Na SDK do Windows lançada para Windows Vista e posterior, a organização dos arquivos de cabeçalho foi alterada e esse parâmetro pode ser um dos valores do tipo de enumeração IPPROTO definido no arquivo de cabeçalho Ws2def.h. Observe que o arquivo de cabeçalho Ws2def.h é incluído automaticamente no Winsock2.h e nunca deve ser usado diretamente.

Se um valor de 0 for especificado, o chamador não deseja especificar um protocolo e o provedor de serviços escolherá o protocolo a ser usado.

Quando o parâmetro af é AF_INET ou AF_INET6 e o tipo é SOCK_RAW, o valor especificado para o protocolo é definido no campo de protocolo do cabeçalho de pacote IPv6 ou IPv4.

A tabela a seguir lista valores comuns para o protocolo , embora muitos outros valores sejam possíveis.

protocolo Significado
IPPROTO_ICMP
1
O protocolo ICMP. Esse é um valor possível quando o parâmetro af é AF_UNSPEC, AF_INET ou AF_INET6 e o parâmetro de tipo é SOCK_RAW ou não especificado.

Esse valor de protocolo tem suporte no Windows XP e posterior.

IPPROTO_IGMP
2
O Protocolo de Gerenciamento de Grupos da Internet (IGMP). Esse é um valor possível quando o parâmetro af é AF_UNSPEC, AF_INET ou AF_INET6 e o parâmetro de tipo é SOCK_RAW ou não especificado.

Esse valor de protocolo tem suporte no Windows XP e posterior.

BTHPROTO_RFCOMM
3
O protocolo Bluetooth RADIO FREQUENCY Communications (Bluetooth RFCOMM). Esse é um valor possível quando o parâmetro af é AF_BTH e o parâmetro de tipo é SOCK_STREAM.

Esse valor de protocolo tem suporte no Windows XP com SP2 ou posterior.

IPPROTO_TCP
6
O Protocolo de Controle de Transmissão (TCP). Esse é um valor possível quando o parâmetro af é AF_INET ou AF_INET6 e o parâmetro de tipo é SOCK_STREAM.
IPPROTO_UDP
17
O UDP (Protocolo de Datagrama do Usuário). Esse é um valor possível quando o parâmetro af é AF_INET ou AF_INET6 e o parâmetro de tipo é SOCK_DGRAM.
IPPROTO_ICMPV6
58
O Protocolo de Mensagem de Controle da Internet versão 6 (ICMPv6). Esse é um valor possível quando o parâmetro af é AF_UNSPEC, AF_INET ou AF_INET6 e o parâmetro de tipo é SOCK_RAW ou não especificado.

Esse valor de protocolo tem suporte no Windows XP e posterior.

IPPROTO_RM
113
O protocolo PGM para multicast confiável. Esse é um valor possível quando o parâmetro af é AF_INET e o parâmetro de tipo é SOCK_RDM. No SDK do Windows lançado para o Windows Vista e posterior, esse protocolo também é chamado de IPPROTO_PGM.

Esse valor de protocolo só terá suporte se o Reliable Multicast Protocol estiver instalado.

[in] lpProtocolInfo

Um ponteiro para uma estrutura WSAPROTOCOL_INFO que define as características do soquete a ser criado. Se esse parâmetro não for NULL, o soquete será associado ao provedor associado à estrutura de WSAPROTOCOL_INFO indicada.

[in] g

Uma ID de grupo de soquete existente ou uma ação apropriada a ser tomada ao criar um soquete e um novo grupo de soquetes.

Se g for uma ID de grupo de soquete existente, ingresse o novo soquete nesse grupo de soquetes, desde que todos os requisitos definidos por esse grupo sejam atendidos.

Se g não for uma ID de grupo de soquete existente, os valores a seguir serão possíveis.

g Significado
0
Nenhuma operação de grupo é executada.
SG_UNCONSTRAINED_GROUP
0x01
Crie um grupo de soquete não treinado e tenha o novo soquete como o primeiro membro. Para um grupo não treinado, Winsock não restringe todos os soquetes no grupo de soquetes a terem sido criados com o mesmo valor para os parâmetros de tipo e protocolo .
SG_CONSTRAINED_GROUP
0x02
Crie um grupo de soquetes restrito e tenha o novo soquete como o primeiro membro. Para um grupo de soquetes restrito, Winsock restringe todos os soquetes no grupo de soquetes a terem sido criados com o mesmo valor para os parâmetros de tipo e protocolo . Um grupo de soquetes restrito pode consistir apenas em soquetes orientados à conexão e requer que as conexões em todos os soquetes agrupados sejam para o mesmo endereço no mesmo host.
 
Nota As constantes SG_UNCONSTRAINED_GROUP e SG_CONSTRAINED_GROUP não são definidas atualmente em um arquivo de cabeçalho público.
 

[in] dwFlags

Um conjunto de sinalizadores usados para especificar atributos de soquete adicionais.

Uma combinação desses sinalizadores pode ser definida, embora algumas combinações não sejam permitidas.

Valor Significado
WSA_FLAG_OVERLAPPED
0x01
Crie um soquete que dê suporte a operações de E/S sobrepostas.

A maioria dos soquetes deve ser criada com esse conjunto de sinalizadores. Soquetes sobrepostos podem utilizar WSASend, WSASendTo, WSARecv, WSARecvFrom e WSAIoctl para operações de E/S sobrepostas, que permitem que várias operações sejam iniciadas e em andamento simultaneamente.

Todas as funções que permitem a operação sobreposta (WSASend, WSARecv, WSASendTo, WSARecvFrom, WSAIoctl) também dão suporte ao uso não sobreposto em um soquete sobreposto se os valores para parâmetros relacionados a operações sobrepostas forem NULL.

WSA_FLAG_MULTIPOINT_C_ROOT
0x02
Crie um soquete que será um c_root em uma sessão de vários pontos.

Esse atributo só será permitido se a estrutura WSAPROTOCOL_INFO para o provedor de transporte que cria o soquete der suporte a um mecanismo multiponto ou multicast e o plano de controle de uma sessão de vários pontos estiver com raiz. Isso seria indicado pelo membro dwServiceFlags1 da estrutura WSAPROTOCOL_INFO com os sinalizadores XP1_SUPPORT_MULTIPOINT e XP1_MULTIPOINT_CONTROL_PLANE definidos.

Quando o parâmetro lpProtocolInfo não é NULL, a estrutura WSAPROTOCOL_INFO para o provedor de transporte é apontada pelo parâmetro lpProtocolInfo . Quando o parâmetro lpProtocolInfo é NULL, a estrutura WSAPROTOCOL_INFO é baseada no provedor de transporte selecionado pelos valores especificados para os parâmetros af, type e protocol .

Consulte Multipoint e Multicast Semântica para obter informações adicionais sobre uma sessão de vários pontos.

WSA_FLAG_MULTIPOINT_C_LEAF
0x04
Crie um soquete que será um c_leaf em uma sessão de vários pontos.

Esse atributo só será permitido se o WSAPROTOCOL_INFO estrutura para o provedor de transporte que cria o soquete der suporte a um mecanismo multiponto ou multicast e o plano de controle de uma sessão de vários pontos não tiver raiz. Isso seria indicado pelo membro dwServiceFlags1 da estrutura WSAPROTOCOL_INFO com o sinalizador XP1_SUPPORT_MULTIPOINT definido e o sinalizador XP1_MULTIPOINT_CONTROL_PLANE não definido.

Quando o parâmetro lpProtocolInfo não é NULL, a estrutura WSAPROTOCOL_INFO para o provedor de transporte é apontada pelo parâmetro lpProtocolInfo . Quando o parâmetro lpProtocolInfo é NULL, a estrutura WSAPROTOCOL_INFO é baseada no provedor de transporte selecionado pelos valores especificados para os parâmetros af, type e protocol .

Consulte Multipoint e Multicast Semântica para obter informações adicionais sobre uma sessão de vários pontos.

WSA_FLAG_MULTIPOINT_D_ROOT
0x08
Crie um soquete que será um d_root em uma sessão de vários pontos.

Esse atributo só será permitido se o WSAPROTOCOL_INFO estrutura para o provedor de transporte que cria o soquete der suporte a um mecanismo multiponto ou multicast e o plano de dados de uma sessão de vários pontos estiver com raiz. Isso seria indicado pelo membro dwServiceFlags1 da estrutura WSAPROTOCOL_INFO com os sinalizadores XP1_SUPPORT_MULTIPOINT e XP1_MULTIPOINT_DATA_PLANE definidos.

Quando o parâmetro lpProtocolInfo não é NULL, a estrutura WSAPROTOCOL_INFO para o provedor de transporte é apontada pelo parâmetro lpProtocolInfo . Quando o parâmetro lpProtocolInfo é NULL, a estrutura WSAPROTOCOL_INFO é baseada no provedor de transporte selecionado pelos valores especificados para os parâmetros af, type e protocol .

Consulte Multipoint e Multicast Semântica para obter informações adicionais sobre uma sessão de vários pontos.

WSA_FLAG_MULTIPOINT_D_LEAF
0x10
Crie um soquete que será um d_leaf em uma sessão de vários pontos.

Esse atributo só será permitido se o WSAPROTOCOL_INFO estrutura para o provedor de transporte que cria o soquete der suporte a um mecanismo multiponto ou multicast e o plano de dados de uma sessão de vários pontos não tiver raiz. Isso seria indicado pelo membro dwServiceFlags1 da estrutura WSAPROTOCOL_INFO com o sinalizador XP1_SUPPORT_MULTIPOINT definido e o sinalizador XP1_MULTIPOINT_DATA_PLANE não definido.

Quando o parâmetro lpProtocolInfo não é NULL, a estrutura WSAPROTOCOL_INFO para o provedor de transporte é apontada pelo parâmetro lpProtocolInfo . Quando o parâmetro lpProtocolInfo é NULL, a estrutura WSAPROTOCOL_INFO é baseada no provedor de transporte selecionado pelos valores especificados para os parâmetros af, type e protocol .

Consulte Multipoint e Multicast Semântica para obter informações adicionais sobre uma sessão de vários pontos.

WSA_FLAG_ACCESS_SYSTEM_SECURITY
0x40
Crie um soquete que permita a capacidade de definir um descritor de segurança no soquete que contém uma SACL (lista de controle de acesso de segurança) em vez de apenas uma DACL (lista de controle de acesso discricionário).

AS SACLs são usadas para gerar auditorias e alarmes quando ocorre uma marcar de acesso no objeto . Para um soquete, ocorre uma marcar de acesso para determinar se o soquete deve ter permissão para associar a um endereço específico especificado à função de associação.

O ACCESS_SYSTEM_SECURITY direito de acesso controla a capacidade de obter ou definir o SACL no descritor de segurança de um objeto. O sistema concede esse direito de acesso somente se o privilégio SE_SECURITY_NAME estiver habilitado no token de acesso do thread solicitante.

WSA_FLAG_NO_HANDLE_INHERIT
0x80
Crie um soquete que não seja herdável.

Um identificador de soquete criado pelo WSASocket ou pela função de soquete é herdável por padrão. Quando esse sinalizador é definido, o identificador de soquete não é herdável.

A função GetHandleInformation pode ser usada para determinar se um identificador de soquete foi criado com o sinalizador WSA_FLAG_NO_HANDLE_INHERIT definido. A função GetHandleInformation retornará que o valor de HANDLE_FLAG_INHERIT está definido.

Esse sinalizador tem suporte no Windows 7 com SP1, Windows Server 2008 R2 com SP1 e posterior

 
Importante Para soquetes de vários pontos, apenas um dos sinalizadores de WSA_FLAG_MULTIPOINT_C_ROOT ou WSA_FLAG_MULTIPOINT_C_LEAF pode ser especificado e apenas um dos sinalizadores de WSA_FLAG_MULTIPOINT_D_ROOT ou WSA_FLAG_MULTIPOINT_D_LEAF pode ser especificado. Consulte Multipoint e Multicast Semântica para obter informações adicionais.
 

Retornar valor

Se nenhum erro ocorrer, WSASocket retornará um descritor referenciando o novo soquete. Caso contrário, um valor de INVALID_SOCKET é retornado e um código de erro específico pode ser recuperado chamando WSAGetLastError.

Nota Esta descrição do código de erro é específica da Microsoft.
 
Código do erro Significado
WSANOTINITIALISED
Uma chamada WSAStartup bem-sucedida deve ocorrer antes de usar essa função.
WSAENETDOWN
O subsistema de rede falhou.
WSAEAFNOSUPPORT
A família de endereços especificada não tem suporte.
WSAEFAULT
O parâmetro lpProtocolInfo não está em uma parte válida do espaço de endereço do processo.
WSAEINPROGRESS
Uma chamada do Windows Sockets 1.1 de bloqueio está em andamento ou o provedor de serviços ainda está processando uma função de retorno de chamada.
WSAEINVAL
Esse valor é verdadeiro para qualquer uma das condições a seguir.
  • O parâmetro g especificado não é válido.
  • A estrutura WSAPROTOCOL_INFO para a qual lpProtocolInfo aponta está incompleta, o conteúdo é inválido ou a estrutura WSAPROTOCOL_INFO já foi usada em uma operação de soquete duplicada anterior.
  • Os valores especificados para membros do soquete triplo <af, tipo e protocolo> têm suporte individual, mas a combinação fornecida não é.
WSAEINVALIDPROVIDER
O provedor de serviços retornou uma versão diferente da 2.2.
WSAEINVALIDPROCTABLE
O provedor de serviços retornou uma tabela de procedimento inválida ou incompleta para o WSPStartup.
WSAEMFILE
Nenhum descritor de soquete disponível.
WSAENOBUFS
Nenhum espaço de buffer disponível. O soquete não pode ser criado.
WSAEPROTONOSUPPORT
Não há suporte para o protocolo especificado.
WSAEPROTOTYPE
O protocolo especificado é o tipo errado para esse soquete.
WSAEPROVIDERFAILEDINIT
Falha ao inicializar o provedor de serviços. Esse erro será retornado se um provedor de serviços em camadas (LSP) ou um provedor de namespace tiver sido instalado incorretamente ou o provedor não funcionar corretamente.
WSAESOCKTNOSUPPORT
O suporte para o tipo de soquete especificado não tem suporte nessa família de endereços.

Comentários

A função WSASocket faz com que um descritor de soquete e todos os recursos relacionados sejam alocados e associados a um provedor de serviços de transporte. A maioria dos soquetes deve ser criada com o atributo WSA_FLAG_OVERLAPPED definido no parâmetro dwFlags . Um soquete criado com esse atributo dá suporte ao uso de operações de E/S sobrepostas que fornecem maior desempenho. Por padrão, um soquete criado com a função WSASocket não terá esse atributo sobreposto definido. Por outro lado, a função de soquete cria um soquete que dá suporte a operações de E/S sobrepostas como o comportamento padrão.

Se o parâmetro lpProtocolInfo for NULL, Winsock utilizará o primeiro provedor de serviço de transporte disponível que dá suporte à combinação solicitada de família de endereços, tipo de soquete e protocolo especificados nos parâmetros af, type e protocol .

Se o parâmetro lpProtocolInfo não for NULL, o soquete será associado ao provedor associado à estrutura de WSAPROTOCOL_INFO indicada. Nessa instância, o aplicativo pode fornecer a constante de manifesto FROM_PROTOCOL_INFO como o valor de qualquer um dos parâmetros af, type ou protocol . Isso indica que os valores correspondentes da estrutura de WSAPROTOCOL_INFO indicada (iAddressFamily, iSocketType, iProtocol) devem ser assumidos. De qualquer forma, os valores especificados para af, tipo e protocolo são passados sem modificação para o provedor de serviços de transporte.

Ao selecionar um protocolo e seu provedor de serviços de suporte com base em af, tipo e protocolo, esse procedimento escolherá apenas um protocolo base ou uma cadeia de protocolos, não uma camada de protocolo por si só. As camadas de protocolo não armazenadas não são consideradas com correspondências parciais no tipo ou af. Ou seja, eles não levam a um código de erro de WSAEAFNOSUPPORT ou WSAEPROTONOSUPPORT, se nenhum protocolo adequado for encontrado.

Nota A constante de manifesto AF_UNSPEC continua a ser definida no arquivo de cabeçalho, mas seu uso é fortemente desencorajado, pois isso pode causar ambiguidade na interpretação do valor do parâmetro de protocolo .
 
Os aplicativos são incentivados a usar AF_INET6 para o parâmetro af e criar um soquete de modo duplo que pode ser usado com IPv4 e IPv6.

Se um soquete for criado usando a função WSASocket , o parâmetro dwFlags deverá ter o atributo WSA_FLAG_OVERLAPPED definido para que as opções de soquete SO_RCVTIMEO ou SO_SNDTIMEO funcionem corretamente. Caso contrário, o tempo limite nunca entrará em vigor no soquete.

Soquetes orientados à conexão, como SOCK_STREAM fornecem conexões completas duplex e devem estar em um estado conectado antes que qualquer dado possa ser enviado ou recebido neles. Uma conexão com um soquete especificado é estabelecida com uma chamada de função connect ou WSAConnect . Depois de conectados, os dados podem ser transferidos usando as chamadasWSASend/ e recv/WSARecv. Quando uma sessão for concluída, a função closesocket deverá ser chamada para liberar os recursos associados ao soquete. Para soquetes orientados à conexão, a função de desligamento deve ser chamada para interromper a transferência de dados no soquete antes de chamar a função closesocket .

Os protocolos de comunicação usados para implementar um soquete confiável orientado à conexão garantem que os dados não sejam perdidos ou duplicados. Se os dados para os quais o protocolo par tiver espaço de buffer não puderem ser transmitidos com êxito em um período razoável de tempo, a conexão será considerada interrompida e as chamadas subsequentes falharão com o código de erro definido como WSAETIMEDOUT.

Soquetes orientados a mensagens sem conexão permitem o envio e o recebimento de datagramas de e para pares arbitrários usando sendto/WSASendTo e revfrom/WSARecvFrom. Se esse soquete estiver conectado a um par específico, os datagramas poderão ser enviados para esse par usando send/WSASend e poderão ser recebidos desse par (somente) usando o recv/WSARecv.

O suporte para soquetes com tipo SOCK_RAW não é necessário, mas os provedores de serviços são incentivados a dar suporte a soquetes brutos sempre que possível.

A função WSASocket pode ser usada para criar um soquete a ser usado por um serviço para que, se outro soquete tentar associar à mesma porta usada pelo serviço, um registro de auditoria seja gerado. Para habilitar essa opção, um aplicativo precisaria fazer o seguinte:

  • Chame a função AdjustTokenPrivileges para habilitar o privilégio SE_SECURITY_NAME no token de acesso para o processo. Esse privilégio é necessário para definir os direitos de acesso ACCESS_SYSTEM_SECURITY no descritor de segurança para um objeto .
  • Chame a função WSASocket para criar um soquete com dwFlag com a opção WSA_FLAG_ACCESS_SYSTEM_SECURITY definida. A função WSASocket falhará se a função AdjustTokenPrivileges não for chamada primeiro para habilitar o privilégio SE_SECURITY_NAME necessário para essa operação.
  • Chame a função SetSecurityInfo para definir um descritor de segurança com uma SACL (Lista de Controle de Acesso do Sistema) no soquete. O identificador de soquete retornado pela função WSASocket é passado no parâmetro handle . Se a função for bem-sucedida, isso definirá o acesso ACCESS_SYSTEM_SECURITY diretamente no descritor de segurança para o soquete.
  • Chame a função bind para associar o soquete a uma porta específica. Se a função de associação for bem-sucedida, uma entrada de auditoria será gerada se outro soquete tentar associar à mesma porta.
  • Chame a função AdjustTokenPrivileges para remover o privilégio SE_SECURITY_NAME no token de acesso para o processo, pois isso não é mais necessário.

Para obter mais informações sobre ACCESS_SYSTEM_SECURITY, consulte Geraçãode acesso e auditoria do SACL na documentação de autorização.

Grupos de soquetes

O WinSock 2 introduziu a noção de um grupo de soquetes como um meio para um aplicativo ou conjunto de aplicativos de cooperação, para indicar a um provedor de serviços subjacente que um determinado conjunto de soquetes está relacionado e que o grupo, portanto, formado tem determinados atributos. Os atributos de grupo incluem prioridades relativas dos soquetes individuais dentro do grupo e uma qualidade de grupo de especificação de serviço.

Aplicativos que precisam trocar fluxos multimídia pela rede são um exemplo em que ser capaz de estabelecer uma relação específica entre um conjunto de soquetes pode ser benéfico. Cabe ao transporte sobre como tratar grupos de soquetes.

As funções WSASocket e WSAAccept podem ser usadas para criar e ingressar explicitamente em um grupo de soquetes ao criar um novo soquete. A ID do grupo de soquetes para um soquete pode ser recuperada usando a função getsockopt com o parâmetro de nível definido como SOL_SOCKET e o parâmetro optname definido como SO_GROUP_ID. Um grupo de soquetes e sua ID de grupo de soquete associado permanecem válidos até que o último soquete pertencente a esse grupo de soquetes seja fechado. As IDs de grupo de soquete são exclusivas em todos os processos para um determinado provedor de serviços. Um grupo de soquetes de zero indica que o soquete não é membro de um grupo de soquetes.

A prioridade de grupo relativo de um grupo de soquetes pode ser acessada usando a função getsockopt com o parâmetro de nível definido como SOL_SOCKET e o parâmetro optname definido como SO_GROUP_PRIORITY. A prioridade de grupo relativo de um grupo de soquetes pode ser definida usando setsockopt com o parâmetro de nível definido como SOL_SOCKET e o parâmetro optname definido como SO_GROUP_PRIORITY.

O provedor Winsock incluído no Windows permite a criação de grupos de soquetes e impõe o SG_CONSTRAINED_GROUP. Todos os soquetes em um grupo de soquetes restritos devem ser criados com o mesmo valor para os parâmetros de tipo e protocolo . Um grupo de soquetes restrito pode consistir apenas em soquetes orientados à conexão e requer que as conexões em todos os soquetes agrupados sejam para o mesmo endereço no mesmo host. Essa é a única restrição aplicada a um grupo de soquetes pelo provedor Winsock incluído no Windows. A prioridade do grupo de soquetes não é usada atualmente pelo provedor Winsock ou pela pilha TCP/IP incluída no Windows.

Código de exemplo

O exemplo a seguir demonstra o uso da função WSASocket .
#ifndef UNICODE
#define UNICODE 1
#endif

// link with Ws2_32.lib
#pragma comment(lib,"Ws2_32.lib")

#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>
#include <stdlib.h>   // Needed for _wtoi


int __cdecl wmain(int argc, wchar_t **argv)
{

    //-----------------------------------------
    // Declare and initialize variables
    WSADATA wsaData = {0};
    int iResult = 0;

//    int i = 1;

    SOCKET sock = INVALID_SOCKET;
    int iFamily = AF_UNSPEC;
    int iType = 0;
    int iProtocol = 0;
    DWORD dwFlags = 0;

    // Validate the parameters
    if (argc != 5) {
        wprintf(L"usage: %s <addressfamily> <type> <protocol> <flags>\n", argv[0]);
        wprintf(L"       opens a socket for the specified family, type, protocol, and flags\n");
        wprintf(L"       flags value must be in decimal, not hex\n");
        wprintf(L"%ws example usage\n", argv[0]);
        wprintf(L"   %ws 0 2 17 1\n", argv[0]);
        wprintf(L"   where AF_UNSPEC=0 SOCK_DGRAM=2 IPPROTO_UDP=17 OVERLAPPED\n", argv[0]);
        return 1;
    }

    iFamily = _wtoi(argv[1]);
    iType = _wtoi(argv[2]);
    iProtocol = _wtoi(argv[3]);
    dwFlags = _wtoi(argv[4]);
    
    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != 0) {
        wprintf(L"WSAStartup failed: %d\n", iResult);
        return 1;
    }

    wprintf(L"Calling socket with following parameters:\n");
    wprintf(L"  Address Family = ");
    switch (iFamily) {
    case AF_UNSPEC:
        wprintf(L"Unspecified");
        break;
    case AF_INET:
        wprintf(L"AF_INET (IPv4)");
        break;
    case AF_INET6:
        wprintf(L"AF_INET6 (IPv6)");
        break;
    case AF_NETBIOS:
        wprintf(L"AF_NETBIOS (NetBIOS)");
        break;
    case AF_BTH:
        wprintf(L"AF_BTH (Bluetooth)");
        break;
    default:
        wprintf(L"Other");
        break;
    }
    wprintf(L" (%d)\n", iFamily);
    
    wprintf(L"  Socket type = ");
    switch (iType) {
    case 0:
        wprintf(L"Unspecified");
        break;
    case SOCK_STREAM:
        wprintf(L"SOCK_STREAM (stream)");
        break;
    case SOCK_DGRAM:
        wprintf(L"SOCK_DGRAM (datagram)");
        break;
    case SOCK_RAW:
        wprintf(L"SOCK_RAW (raw)");
        break;
    case SOCK_RDM:
        wprintf(L"SOCK_RDM (reliable message datagram)");
        break;
    case SOCK_SEQPACKET:
        wprintf(L"SOCK_SEQPACKET (pseudo-stream packet)");
        break;
    default:
        wprintf(L"Other");
        break;
    }
    wprintf(L" (%d)\n", iType);

    wprintf(L"  Protocol = %d = ", iProtocol);
    switch (iProtocol) {
    case 0:
        wprintf(L"Unspecified");
        break;
    case IPPROTO_ICMP:
        wprintf(L"IPPROTO_ICMP (ICMP)");
        break;
    case IPPROTO_IGMP:
        wprintf(L"IPPROTO_IGMP (IGMP)");
        break;
    case IPPROTO_TCP:
        wprintf(L"IPPROTO_TCP (TCP)");
        break;
    case IPPROTO_UDP:
        wprintf(L"IPPROTO_UDP (UDP)");
        break;
    case IPPROTO_ICMPV6:
        wprintf(L"IPPROTO_ICMPV6 (ICMP Version 6)");
        break;
    default:
        wprintf(L"Other");
        break;
    }
    wprintf(L" (%d)\n", iProtocol);

    wprintf(L"  Flags = ");
    if (dwFlags & WSA_FLAG_OVERLAPPED)
        wprintf(L"  WSA_FLAG_OVERLAPPED");
    if (dwFlags & WSA_FLAG_MULTIPOINT_C_ROOT)
        wprintf(L"  WSA_FLAG_MULTIPOINT_C_ROOT");
    if (dwFlags & WSA_FLAG_MULTIPOINT_C_LEAF)
        wprintf(L"  WSA_FLAG_MULTIPOINT_C_LEAF");
    if (dwFlags & WSA_FLAG_MULTIPOINT_D_ROOT)
        wprintf(L"  WSA_FLAG_MULTIPOINT_D_ROOT");
    if (dwFlags & WSA_FLAG_MULTIPOINT_D_LEAF)
        wprintf(L"  WSA_FLAG_MULTIPOINT_D_LEAF");
    if (dwFlags & WSA_FLAG_ACCESS_SYSTEM_SECURITY)
        wprintf(L"  WSA_FLAG_ACCESS_SYSTEM_SECURITY");
#ifdef WSA_FLAG_NO_HANDLE_INHERIT 
    if (dwFlags & WSA_FLAG_NO_HANDLE_INHERIT)
        wprintf(L"  WSA_FLAG_NO_HANDLE_INHERIT");
#endif
    wprintf(L" (0x%x)\n" , dwFlags);

    sock = WSASocket(iFamily, iType, iProtocol, NULL, 0, dwFlags);
    if (sock == INVALID_SOCKET) 
        wprintf(L"WSASocket function failed with error = %d\n", WSAGetLastError() );
    else {
        wprintf(L"WSASocket function succeeded\n");

        // Close the socket to release the resources associated
        // Normally an application calls shutdown() before closesocket 
        //   to  disables sends or receives on a socket first
        // This isn't needed in this simple sample
        iResult = closesocket(sock);
        if (iResult == SOCKET_ERROR) {
            wprintf(L"closesocket function zfailed with error = %d\n", WSAGetLastError() );
            WSACleanup();
            return 1;
        }    
    }
    WSACleanup();

    return 0;
}


Windows Phone 8: a função WSASocketW tem suporte para aplicativos da Windows Phone Store no Windows Phone 8 e posterior.

Windows 8.1 e Windows Server 2012 R2: a função WSASocketW tem suporte para aplicativos da Windows Store em Windows 8.1, Windows Server 2012 R2 e posteriores.

Observação

O cabeçalho winsock2.h define WSASocket como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 8.1, Windows Vista [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho winsock2.h
Biblioteca Ws2_32.lib
DLL Ws2_32.dll

Confira também

WSAPROTOCOL_INFO

Funções Winsock

Referência de Winsock

accept

bind

Closesocket

connect

Getsockname

Getsockopt

Ioctlsocket

listen

Recv

Recvfrom

select

send

Sendto

Setsockopt

shutdown

socket