LPNSPV2SETSERVICEEX função de retorno de chamada (ws2spi.h)

Artigo
08/28/2023

A função NSPv2SetServiceEx registra ou desregistra um nome ou instância de serviço em um namespace de um provedor de serviços de namespace versão 2 (NSPv2).

Sintaxe

LPNSPV2SETSERVICEEX Lpnspv2setserviceex;

void Lpnspv2setserviceex(
  [in] HANDLE hAsyncCall,
  [in] LPGUID lpProviderId,
  [in] LPWSAQUERYSET2W lpqsRegInfo,
  [in] WSAESETSERVICEOP essOperation,
  [in] DWORD dwControlFlags,
  [in] LPVOID lpvClientSessionArg
)
{...}

Parâmetros

[in] hAsyncCall

Um identificador retornado da chamada anterior para NSPv2LookupServiceBegin usado para chamadas assíncronas.

[in] lpProviderId

Um ponteiro para o GUID do provedor de namespace específico no qual o nome ou serviço está registrado.

[in] lpqsRegInfo

As informações de propriedade a serem atualizadas após o registro.

[in] essOperation

O tipo de 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 0	Registre o serviço. Para o namespace sap (Service Advertising Protocol) usado em um ambiente NetWare, isso significa enviar uma difusão periódica. Este é um NOP para o namespace DNS (Sistema de Nomes de Domínio). Para armazenamentos de dados persistentes, isso significa atualizar as informações de endereço.
RNRSERVICE_DEREGISTER 1	Desregistrar o serviço. Para o namespace 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 2	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 fornecido será excluído e isso deve corresponder exatamente à estrutura CSADDR_INFO correspondente fornecida quando o serviço foi registrado.

[in] dwControlFlags

Um conjunto de sinalizadores que controla a operação solicitada.

Os valores possíveis para esse parâmetro são definidos no arquivo de cabeçalho Winsock2.h .

Valor	Significado
SERVICE_MULTIPLE 0x00000001	Controlar o escopo da operação. Quando esse valor é definido, a ação só é executada no conjunto de endereços fornecido. Uma operação de registro não invalida endereços existentes e uma operação de cancelamento de registro invalida apenas o conjunto de endereços especificado. Quando esse valor está ausente, os endereços de serviço são gerenciados como um grupo. Um registro ou cancelamento de registro invalida todos os endereços existentes antes de adicionar o conjunto de endereços especificado.

Valor

Significado

SERVICE_MULTIPLE

0x00000001

Controlar o escopo da operação.

Quando esse valor é definido, a ação só é executada no conjunto de endereços fornecido. Uma operação de registro não invalida endereços existentes e uma operação de cancelamento de registro invalida apenas o conjunto de endereços especificado.

Quando esse valor está ausente, os endereços de serviço são gerenciados como um grupo. Um registro ou cancelamento de registro invalida todos os endereços existentes antes de adicionar o conjunto de endereços especificado.

[in] lpvClientSessionArg

Um ponteiro para a sessão do cliente.

Retornar valor

A função deverá retornar NO_ERROR (zero) se a rotina for bem-sucedida. Ele deverá retornar SOCKET_ERROR (ou seja, 1) se a rotina falhar e precisar definir o código de erro apropriado usando WSASetLastError.

Código do erro	Significado
WSA_NOT_ENOUGH_MEMORY	Não há memória suficiente disponível para executar essa operação.
WSAEACCES	A rotina de chamada não tem privilégios suficientes para instalar o serviço.
WSAEINVAL	Um ou mais parâmetros eram inválidos ou ausentes para esse provedor.
WSAEOPNOTSUPP	A operação não tem suporte. Esse erro será retornado se o provedor de namespace não implementar essa função. Esse erro também poderá ser retornado se o dwControlCode especificado for um comando não reconhecido.
WSASERVICE_NOT_FOUND	O serviço é desconhecido. O serviço não pode ser encontrado no namespace especificado.

Comentários

A função NSPv2SetServiceEx é usada como parte da arquitetura do provedor de serviços de namespace versão 2 (NSPv2) disponível no Windows Vista e posterior.

No Windows Vista e no Windows Server 2008, a função NSPv2SetServiceEx só pode ser usada para operações em provedores de namespace NS_EMAIL.

A função NSPv2Startup é chamada sempre que um novo processo de cliente começa a usar o provedor de namespace. Os provedores podem usar o argumento de sessão do cliente apontado pelo parâmetro ppvClientSessionArg para armazenar informações sobre essa sessão. Esse argumento de sessão do cliente pode ser passado para a função NSPv2SetServiceEx no parâmetro lpvClientSessionArg .

A função NSPv2SetServiceEx é opcional, dependendo dos requisitos do provedor NSPv2. Se a função NSPv2SetServiceEx não for implementada, o ponteiro da função NSPv2 poderá ser para uma função stub que sempre retorna NO_ERROR.

A tabela a seguir lista a possível combinação de valores para os parâmetros essOperation e dwControlFlags .

essOperation	Dwcontrolflags	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ções 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 é DEREGISTERED.	WSASERVICE_NOT_FOUND
RNRSERVICE_DEREGISTER	SERVICE_MULTIPLE	Atualizações objeto . Remove somente os endereços especificados. Marque apenas o objeto como DEREGISTERED se nenhum endereço estiver presente. Não remove do namespace.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	Nenhum	Remove o objeto do namespace.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	SERVICE_MULTIPLE	Remove apenas os endereços especificados. Só removerá o objeto do namespace se nenhum endereço permanecer.	WSASERVICE_NOT_FOUND

Quando o parâmetro dwControlFlags é definido como SERVICE_MULTIPLE, isso permite que um aplicativo gerencie seus endereços de forma independente. Isso é útil quando o aplicativo deve 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, um soquete de escuta pode anular, mas os outros soquetes permanecem operacionais. Neste exemplo, o serviço pode desregistrar o endereço anulado sem afetar os outros endereços.

Ao usar SERVICE_MULTIPLE, um aplicativo não deve permitir que endereços antigos permaneçam no objeto . Isso pode acontecer se o aplicativo for anulado sem emitir uma solicitação de RNRSERVICE_DEREGISTER . Quando um serviço se registra, ele deve armazenar seus endereços. Em sua próxima chamada, o serviço deve desregistrar explicitamente esses endereços antigos antes de registrar novos endereços.

Se a função NSPv2SetServiceEx não for implementada, as chamadas para essa função deverão ser interceptadas por uma função stub que retorna WSAEOPNOTSUPP. O ponteiro da função NSPv2 para a função NSPv2SetServiceEx não simplificada na estrutura NSPV2_ROUTINE deve apontar para a função stub.

Propriedades do Serviço

A tabela a seguir lista WSAQUERYSET2 nomes de membro e descreve como os dados da propriedade de serviço são representados. Os membros rotulados como opcionais e dependentes dos requisitos do provedor NSPv2 podem ser fornecidos como um ponteiro **NULL** quando não utilizados pelo provedor de namespace.

WSAQUERYSET2 nome do membro	Descrição da propriedade de serviço
Dwsize	Defina como sizeof(WSAQUERYSET2). Esse é um mecanismo de controle de versão.
Lpszserviceinstancename	Uma cadeia de caracteres que contém o nome da instância de serviço.
lpVersion	O número de versão da instância de serviço. Esse membro é opcional, dependendo dos requisitos do provedor de serviços NSPv2.
lpszComment	Uma cadeia de caracteres de comentário. Esse membro é opcional, dependendo dos requisitos do provedor de serviços NSPv2.
Dwnamespace	O identificador de namespace. Esse membro é opcional, dependendo dos requisitos do provedor de serviços NSPv2.
lpNSProviderId	O identificador do provedor. Observe que o identificador do provedor de namespace também é passado no parâmetro lpProviderId . Esse membro é opcional, dependendo dos requisitos do provedor de serviços NSPv2.
lpszContext	O ponto de partida da consulta em um namespace hierárquico. Esse membro é opcional, dependendo dos requisitos do provedor de serviços NSPv2.
dwNumberOfProtocols	O tamanho, em bytes, do número de entradas na matriz de restrição de protocolo. Esse membro pode ser zero. Esse membro é opcional, dependendo dos requisitos do provedor de serviços NSPv2.
lpafpProtocols	Uma matriz de estruturas AFPROTOCOLS . Esse membro é opcional, dependendo dos requisitos do provedor de serviços NSPv2.
lpszQueryString	Alguns namespaces (como whois++) dão suporte a consultas avançadas semelhantes a SQL contidas em uma cadeia de caracteres de texto simples. Esse parâmetro é usado para especificar essa cadeia de caracteres. Esse membro é opcional, dependendo dos requisitos do provedor de serviços NSPv2.
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 o endereço ou endereços em que o serviço está escutando.
dwOutputFlags	Esse membro é opcional, dependendo dos requisitos do provedor de serviços NSPv2.
Lpblob	Um ponteiro para uma entidade específica do provedor. Esse membro é necessário para o namespace NS_EMAIL. Esse membro é opcional, dependendo dos requisitos para outros provedores de serviço NSPv2.

**Observação** É aceitável que o membro **iProtocol** da estrutura CSADDR_INFO contenha a constante de manifesto **IPROTOCOL_ANY**, indicando um valor curinga. O provedor de namespace deve substituir um valor aceitável para a família de endereços e o tipo de soquete fornecidos.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	ws2spi.h