Função WSASetServiceW (winsock2.h)

Artigo
08/27/2023

A função WSASetService registra ou remove do registro uma instância de serviço em um ou mais namespaces.

Sintaxe

INT WSAAPI WSASetServiceW(
  [in] LPWSAQUERYSETW   lpqsRegInfo,
  [in] WSAESETSERVICEOP essoperation,
  [in] DWORD            dwControlFlags
);

Parâmetros

[in] lpqsRegInfo

Um ponteiro para as informações de serviço para registro ou desregistração.

[in] essoperation

Um valor que determina essa operação solicitada. Esse parâmetro pode ser um dos valores do tipo de enumeração WSAESETSERVICEOP definido no arquivo de cabeçalho Winsock2.h.

Valor	Significado
RNRSERVICE_REGISTER	Registre o serviço. Para SAP, isso significa enviar uma transmissão periódica. Este é um NOP para o namespace DNS. Para armazenamentos de dados persistentes, isso significa atualizar as informações de endereço.
RNRSERVICE_DEREGISTER	Remova o serviço do Registro. Para SAP, isso significa parar de enviar a transmissão periódica. Este é um NOP para o namespace DNS. Para armazenamentos de dados persistentes, isso significa excluir informações de endereço.
RNRSERVICE_DELETE	Exclua o serviço do nome dinâmico e dos espaços persistentes. Para serviços representados por várias estruturas de CSADDR_INFO (usando o sinalizador SERVICE_MULTIPLE), somente o endereço especificado será excluído e isso deve corresponder exatamente à estrutura de CSADDR_INFO correspondente especificada quando o serviço foi registrado.

[in] dwControlFlags

Valor de sinalizadores de instalação de serviço que controla ainda mais a operação executada da função WSASetService . Os valores possíveis para esse parâmetro são definidos no arquivo de cabeçalho Winsock2.h.

Bandeira	Significado
SERVICE_MULTIPLE	Controla o escopo da operação. Quando esse sinalizador não está definido, os endereços de serviço são gerenciados como um grupo. Um registro ou remoção do Registro invalida todos os endereços existentes antes de adicionar o conjunto de endereços especificado. Quando definida, a ação só é executada no conjunto de endereços especificado. Um registro não invalida endereços existentes e uma remoção do Registro invalida apenas o conjunto de endereços especificado.

Bandeira

Significado

SERVICE_MULTIPLE

Controla o escopo da operação. Quando esse sinalizador não está definido, os endereços de serviço são gerenciados como um grupo. Um registro ou remoção do Registro invalida todos os endereços existentes antes de adicionar o conjunto de endereços especificado. Quando definida, a ação só é executada no conjunto de endereços especificado. Um registro não invalida endereços existentes e uma remoção do Registro invalida apenas o conjunto de endereços especificado.

Valor de retorno

O valor retornado para WSASetService será zero se a operação tiver sido bem-sucedida. Caso contrário, o valor SOCKET_ERROR será retornado e um número de erro específico poderá ser recuperado chamando WSAGetLastError.

Código de erro	Significado
WSAEACCES	A rotina de chamada não tem privilégios suficientes para instalar o Serviço.
WSAEINVAL	Um ou mais parâmetros necessários eram inválidos ou ausentes.
WSANOTINITIALISED	O Ws2_32.dll não foi inicializado. O aplicativo deve primeiro chamar WSAStartup antes de chamar as funções do Windows Sockets.
WSA_NOT_ENOUGH_MEMORY	Não havia memória suficiente para executar a operação.

Observações

A função WSASetService pode ser usada para afetar um provedor de namespace específico, todos os provedores associados a um namespace específico ou todos os provedores em todos os namespaces.

Os valores disponíveis para de essOperation e dwControlFlags combinar para controlar a operação da função WSASetService, conforme mostrado na tabela a seguir.

Operação	Sinalizadores	O serviço já existe	O serviço não existe
RNRSERVICE_REGISTER	Nenhum	Substitui o objeto. Usa apenas os endereços especificados. O objeto é REGISTERED.	Cria um novo objeto. Usa apenas os endereços especificados. O objeto é REGISTERED.
RNRSERVICE_REGISTER	SERVICE_MULTIPLE	Atualiza o objeto. Adiciona novos endereços ao conjunto existente. O objeto é REGISTERED.	Cria um novo objeto. Usa todos os endereços especificados. O objeto é REGISTERED.
RNRSERVICE_DEREGISTER	Nenhum	Remove todos os endereços, mas não remove o objeto do namespace. O objeto é removido do registro.	WSASERVICE_NOT_FOUND
RNRSERVICE_DEREGISTER	SERVICE_MULTIPLE	Atualiza o objeto. Remove somente os endereços especificados. Só marcará o objeto como DESREGISTERED se nenhum endereço estiver presente. Não remove o objeto do namespace.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	Nenhum	Remove o objeto do namespace.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	SERVICE_MULTIPLE	Remove somente os endereços especificados. Só removerá o objeto do namespace se nenhum endereço permanecer.	WSASERVICE_NOT_FOUND

A publicação de serviços em diretórios, como os Serviços do Active Directory, é restrita com base em ACLs (listas de controle de acesso). Para obter mais informações, consulte problemas de segurança parade publicação de serviço.

Quando o parâmetro dwControlFlags é definido como SERVICE_MULTIPLE, um aplicativo pode gerenciar seus endereços de forma independente. Isso é útil quando o aplicativo deseja gerenciar seus protocolos individualmente ou quando o serviço reside em mais de um computador. Por exemplo, quando um serviço usa mais de um protocolo, pode achar que um soquete de escuta anula, mas os outros soquetes permanecem operacionais. Nesse caso, o serviço pode remover o endereço anulado do registro sem afetar os outros endereços.

Quando o parâmetro dwControlFlags é definido como SERVICE_MULTIPLE, um aplicativo não deve permitir que endereços obsoletos permaneçam no objeto. Isso pode acontecer se o aplicativo anular sem emitir uma solicitação DEREGISTER. Quando um serviço é registrado, ele deve armazenar seus endereços. Em sua próxima invocação, o serviço deve remover explicitamente esses endereços antigos obsoletos do registro antes de registrar novos endereços.

Observação Se cadeias de caracteres ANSI forem usadas, há uma chance de que o WSAQUERYSET dados em lpqsRegInfo pode não conter resultados depois que essa função retornar. Isso ocorre porque a versão ANSI desse método, WSASetServiceA, converte os dados ANSI em WSAQUERYSET para Unicode internamente, mas não converte os resultados em ANSI. Isso afeta principalmente os transportes que retornam um "identificador de registro de serviço" usado para identificar exclusivamente um registro. Para contornar esse problema, os aplicativos devem usar dados de cadeia de caracteres Unicode no WSAQUERYSET ao chamar essa função.

Propriedades do serviço

A tabela a seguir descreve como os dados da propriedade de serviço são representados em uma estrutura de WSAQUERYSET . Campos rotulados como (Opcional) podem conter um ponteiro nulo.

Membro WSAQUERYSET	Descrição da propriedade de serviço
dwSize	Deve ser definido como sizeof (WSAQUERYSET). Esse é um mecanismo de controle de versão.
dwOutputFlags	Não aplicável e ignorado.
lpszServiceInstanceName	A cadeia de caracteres referenciada contém o nome da instância de serviço.
lpServiceClassId	O GUID correspondente a essa classe de serviço.
lpVersion	(Opcional) Fornece o número de versão da instância de serviço.
lpszComment	(Opcional) Uma cadeia de caracteres de comentário opcional.
dwNameSpace	Veja a tabela a seguir.
lpNSProviderId	Veja a tabela a seguir.
lpszContext	(Opcional) Especifica o ponto inicial da consulta em um namespace hierárquico.
dwNumberOfProtocols	Ignorado.
lpafpProtocols	Ignorado.
lpszQueryString	Ignorado.
dwNumberOfCsAddrs	O número de elementos na matriz de estruturas de CSADDR_INFO referenciadas por lpcsaBuffer.
lpcsaBuffer	Um ponteiro para uma matriz de estruturas de CSADDR_INFO que contêm o endereço(es) em que o serviço está escutando.
lpBlob	(Opcional) Esse é um ponteiro para uma entidade específica do provedor.

Conforme ilustrado a seguir, a combinação dos membros dwNameSpace e lpNSProviderId determinam que os provedores de namespace são afetados por essa função.

dwNameSpace	lpNSProviderId	Escopo do impacto
Ignorado	Não nulo	O provedor de espaço de nome especificado.
Um identificador de espaço de nome válido	Zero	Todos os provedores de espaço de nome que dão suporte ao namespace indicado.
NS_ALL	Zero	Todos os provedores de espaço de nome.

Windows Phone 8: a função WSASetServiceW 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 WSASetServiceW tem suporte para aplicativos da Windows Store no Windows 8.1, Windows Server 2012 R2 e posterior.

Nota

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

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 8.1, Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
servidor com suporte mínimo	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
da Plataforma de Destino	Windows
cabeçalho	winsock2.h
biblioteca	Ws2_32.lib
de DLL	Ws2_32.dll

Consulte também

Bluetooth e WSASetService

WSAGetLastError

WSAStartup

do Winsock Functions

referência Winsock

Compartilhar via