Função DsGetSpnA (ntdsapi.h)

A função DsGetSpn constrói uma matriz de um ou mais SPNs (nomes de entidade de serviço). Cada nome na matriz identifica uma instância de um serviço. Esses SPNs podem ser registrados com o DS (serviço de diretório) usando a função DsWriteAccountSpn.

Sintaxe

NTDSAPI DWORD DsGetSpnA(
  [in]           DS_SPN_NAME_TYPE ServiceType,
  [in]           LPCSTR           ServiceClass,
  [in, optional] LPCSTR           ServiceName,
  [in]           USHORT           InstancePort,
  [in]           USHORT           cInstanceNames,
  [in, optional] LPCSTR           *pInstanceNames,
  [in, optional] const USHORT     *pInstancePorts,
  [out]          DWORD            *pcSpn,
  [out]          LPSTR            **prpszSpn
);

Parâmetros

[in] ServiceType

Identifica o formato dos SPNs a serem redigidos. O parâmetro ServiceType pode ter um dos valores a seguir.

DS_SPN_DNS_HOST, DS_SPN_DN_HOST, DS_SPN_NB_HOST

Os SPNs têm o seguinte formato.

ServiceClass/ InstanceName: InstancePort

O parâmetro ServiceName deve ser NULL. Esse é o formato SPN para um serviço baseado em host, que fornece serviços identificados com seu computador host. O componente InstancePort é opcional.

DS_SPN_DOMAIN, DS_SPN_NB_DOMAIN

Os SPNs têm o seguinte formato.

ServiceClass/ InstanceName: InstancePort/ ServiceName

O parâmetro ServiceName deve ser o nome DNS ou DN de um domínio. Esse formato é usado para um serviço replicável que fornece serviços para o domínio especificado.

DS_SPN_SERVICE

Os SPNs têm o seguinte formato.

ServiceClass/ InstanceName: InstancePort/ ServiceName

O parâmetro ServiceName deve ser um nome DN ou DNS canônico que identifique uma instância do serviço. Por exemplo, pode ser um nome DNS de um registro SRV ou o nome diferenciado do ponto de conexão de serviço para essa instância de serviço.

[in] ServiceClass

Ponteiro para uma cadeia de caracteres terminada em nulo constante que especifica a classe do serviço; por exemplo, http. Em geral, essa pode ser qualquer cadeia de caracteres exclusiva para o serviço.

[in, optional] ServiceName

Ponteiro para uma cadeia de caracteres terminada em nulo constante que especifica o nome DNS ou o DN (nome diferenciado) do serviço. ServiceName não é necessário para um serviço baseado em host. Para obter mais informações, consulte a descrição do parâmetro ServiceType para obter os valores possíveis de ServiceName.

[in] InstancePort

Especifica o número da porta da instância de serviço. Se esse valor for zero, o SPN não inclui um número de porta.

[in] cInstanceNames

Especifica o número de elementos nas matrizes pInstanceNames e pInstancePorts. Se esse valor não for zero, pInstanceNames deverá apontar para uma matriz de cadeias de caracteres cInstanceNames e pInstancePorts podem ser NULL ou um ponteiro para uma matriz de números de porta cInstanceNames . Se esse valor for zero, DsGetSpn retornará apenas um SPN na matriz de prpszSpn e pInstanceNames e pInstancePorts serão ignorados.

[in, optional] pInstanceNames

Ponteiro para uma matriz de cadeias de caracteres terminadas em nulo que especificam nomes de instância extras (não usados para nomes de host). Esse parâmetro será ignorado se cInstanceNames for zero. Nesse caso, o componente InstanceName do SPN usa como padrão o nome DNS totalmente qualificado do computador local ou o nome NetBIOS se DS_SPN_NB_HOST ou DS_SPN_NB_DOMAIN for especificado.

[in, optional] pInstancePorts

Ponteiro para uma matriz de portas de instância extra. Se esse valor não forNULL, ele deverá apontar para uma matriz de cInstanceNames números de porta. Se esse valor for NULL, os SPNs não incluirão um número de porta. Esse parâmetro será ignorado se cInstanceNames for zero.

[out] pcSpn

Ponteiro para uma variável que recebe o número de SPNs contidos em prpszSpn.

[out] prpszSpn

Ponteiro para uma variável que recebe um ponteiro para uma matriz de SPNs. Essa matriz deve ser liberada com DsFreeSpnArray.

Valor de retorno

Se a função retornar uma matriz de SPNs, o valor retornado será ERROR_SUCCESS.

Se a função falhar, o valor retornado poderá ser um dos seguintes códigos de erro.

Observações

Criar SPNs para várias instâncias de um serviço replicado em execução em vários computadores host

1. Defina cInstanceNames com o número de instâncias.
2. Especifique os nomes dos computadores host na matriz de pInstanceNames .

Criar SPNs para várias instâncias de um serviço em execução no mesmo computador host

1. Defina o cInstanceNames com o número de instâncias.
2. Defina cada entrada na matriz pInstanceNames com o nome DNS do computador host.
3. Use o parâmetro pInstancePorts para especificar uma matriz de números de porta exclusivos para cada instância para desambiguar os SPNs.

Os parâmetros de cadeia de caracteres não podem incluir a barra (/), que é usada para separar os componentes do SPN.

Um aplicativo com os privilégios apropriados, que geralmente são os de um administrador de domínio, pode chamar a função DsWriteAccountSpn para registrar um ou mais SPNs na conta de usuário ou computador em que o serviço está sendo executado. Os clientes podem usar os SPNs para autenticar o serviço.

Nota

O cabeçalho ntdsapi.h define DsGetSpn 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 Vista
servidor com suporte mínimo	Windows Server 2008
da Plataforma de Destino	Windows
cabeçalho	ntdsapi.h
biblioteca	Ntdsapi.lib
de DLL	Ntdsapi.dll

Consulte também

Funções de gerenciamento de replicação e controlador de domínio

DsFreeSpnArray

DsWriteAccountSpn