Função WSASetServiceA (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 WSASetServiceA(
  [in] LPWSAQUERYSETA   lpqsRegInfo,
  [in] WSAESETSERVICEOP essoperation,
  [in] DWORD            dwControlFlags
);

Parâmetros

[in] lpqsRegInfo

Um ponteiro para as informações de serviço para registro ou cancelamento do registro.

[in] essoperation

Um valor que determina a 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 o 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 difusã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

O 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 .

Sinalizador	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 determinado.

Sinalizador

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 determinado.

Retornar valor

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 do 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 qualquer função do Windows Sockets.
WSA_NOT_ENOUGH_MEMORY	Não havia memória suficiente para executar a operação.

Comentários

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 essOperation e dwControlFlags combinam para controlar a operação da função WSASetService , conforme mostrado na tabela a seguir.

Operação	Flags	O serviço já existe	O serviço não existe
RNRSERVICE_REGISTER	Nenhum	Substitui o objeto . Usa apenas endereços especificados. O objeto é REGISTERED.	Cria um novo objeto. Usa apenas 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. Marca apenas o objeto como DEREGISTERED 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 para 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, ele pode descobrir 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 for anulado sem emitir uma solicitação DEREGISTER. Quando um serviço se registra, ele deve armazenar seus endereços. Em sua próxima invocação, o serviço deve remover explicitamente esses endereços obsoletos antigos do registro antes de registrar novos endereços.

Nota Se cadeias de caracteres ANSI forem usadas, há uma chance de que os dados WSAQUERYSET em lpqsRegInfo não possam conter nenhum resultado após o retorno dessa função. Isso ocorre porque a versão ANSI desse método, WSASetServiceA, converte os dados ANSI no WSAQUERYSET em Unicode internamente, mas não converte os resultados de volta para 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 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	Confira a tabela a seguir.
lpNSProviderId	Confira a tabela a seguir.
lpszContext	(Opcional) Especifica o ponto de partida da consulta em um namespace hierárquico.
dwNumberOfProtocols	Ignorado.
lpafpProtocols	Ignorado.
lpszQueryString	Ignorado.
dwNumberOfCsAddrs	O número de elementos na matriz de CSADDR_INFO estruturas referenciadas por lpcsaBuffer.
Lpcsabuffer	Um ponteiro para uma matriz de estruturas de CSADDR_INFO que contêm os endereços 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 determina que os provedores de namespace são afetados por essa função.

Dwnamespace	lpNSProviderId	Escopo do impacto
Ignored	Não nulo	O provedor de espaço de nome especificado.
Um identificador de espaço de nome válido	Null	Todos os provedores de name-space que dão suporte ao namespace indicado.
NS_ALL	Null	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 em Windows 8.1, Windows Server 2012 R2 e posteriores.

Observação

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 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