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 serviço de diretório (DS) 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 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 incluirá 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 poderá 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 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 extras. Se esse valor não for NULL, ele deverá apontar para uma matriz de números de porta cInstanceNames . 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.
Retornar valor
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.
Comentários
Para criar SPNs para várias instâncias de um serviço replicado em execução em vários computadores host
- Defina cInstanceNames como o número de instâncias.
- Especifique os nomes dos computadores host na matriz pInstanceNames .
Para criar SPNs para várias instâncias de um serviço em execução no mesmo computador host
- Defina cInstanceNames como o número de instâncias.
- Defina cada entrada na matriz pInstanceNames como o nome DNS do computador host.
- Use o parâmetro pInstancePorts para especificar uma matriz de números de porta exclusivos para cada instância para desambiguar os SPNs.
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á em execução. Em seguida, os clientes podem usar os SPNs para autenticar o serviço.
Observação
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 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 Vista |
| Servidor mínimo com suporte | Windows Server 2008 |
| Plataforma de Destino | Windows |
| Cabeçalho | ntdsapi.h |
| Biblioteca | Ntdsapi.lib |
| DLL | Ntdsapi.dll |
Confira também
Funções de gerenciamento de replicação e controlador de domínio
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de