Função DsCrackNamesA (ntdsapi.h)

Artigo
02/29/2024

A função DsCrackNames converte uma matriz de nomes de objeto de serviço de diretório de um formato para outro. A conversão de nome permite que os aplicativos cliente mapeiem entre os vários nomes usados para identificar vários objetos de serviço de diretório. Por exemplo, os objetos de usuário podem ser identificados por nomes de conta SAM (Nome de Usuário de Domínio\), nome principal do usuário (Domínio de Nome de Usuário@.com) ou nome diferenciado.

Sintaxe

NTDSAPI DWORD DsCrackNamesA(
  [in]  HANDLE           hDS,
  [in]  DS_NAME_FLAGS    flags,
  [in]  DS_NAME_FORMAT   formatOffered,
  [in]  DS_NAME_FORMAT   formatDesired,
  [in]  DWORD            cNames,
  [in]  const LPCSTR     *rpNames,
  [out] PDS_NAME_RESULTA *ppResult
);

Parâmetros

[in] hDS

Contém um identificador de serviço de diretório obtido da função DSBind ou DSBindWithCred . Se flags contiver DS_NAME_FLAG_SYNTACTICAL_ONLY, hDS poderá ser NULL.

[in] flags

Contém um ou mais dos valores de DS_NAME_FLAGS usados para determinar como a sintaxe do nome será rachada.

[in] formatOffered

Contém um dos valores de DS_NAME_FORMAT que identifica o formato dos nomes de entrada.

O valor DS_LIST_NCS também pode ser passado para esse parâmetro. Isso faz com que DsCrackNames retorne os nomes diferenciados de todos os contextos de nomenclatura na floresta atual. O parâmetro formatDesired é ignorado. cNames devem ser pelo menos uma e todas as cadeias de caracteres em rpNames devem ter um comprimento maior que zero caracteres. O conteúdo das cadeias de caracteres rpNames é ignorado.

ObserveDS_LIST_NCS não está definido em um arquivo de cabeçalho publicado. Para usar esse valor, defina-o no formato exato mostrado abaixo.

#ifndef DS_LIST_NCS
    #define DS_LIST_NCS 0xfffffff6
#endif

[in] formatDesired

Contém um dos valores DS_NAME_FORMAT que identifica o formato dos nomes de saída. Não há suporte para o valor de DS_SID_OR_SID_HISTORY_NAME .

[in] cNames

Contém o número de elementos na matriz rpNames .

[in] rpNames

Ponteiro para uma matriz de ponteiros para cadeias de caracteres terminadas em nulo que contêm nomes a serem convertidos.

[out] ppResult

Ponteiro para um valor PDS_NAME_RESULT que recebe uma estrutura DS_NAME_RESULT que contém os nomes convertidos. O chamador deve liberar essa memória, quando não for mais necessária, chamando DsFreeNameResult.

Retornar valor

Retorna um valor de erro Win32, um valor de erro RPC ou um dos seguintes.

Comentários

O sucesso da solicitação de conversão de nome depende de onde o cliente está associado. Os clientes se associam a instâncias específicas do serviço de diretório usando alguma variante de DsBind. Se estiver associado a um catálogo global, o escopo do mapeamento de nome será toda a floresta. Se não estiver associado a um catálogo global, o escopo do mapeamento de nomes será o domínio não coberto por um catálogo global para esse controlador de domínio. Se não estiver associado a um catálogo global e um nome não for encontrado, mas o nome de entrada identificar sem ambiguidade seu domínio e esse domínio estiver na floresta, os dados de retorno identificarão o nome de domínio DNS para o domínio de interesse. Espera-se que os clientes usem esses dados para associar ao controlador de domínio correto ou ao catálogo global e chamar DsCrackNames novamente com o novo identificador de associação.

O valor retornado de DsCrackNames indica erros como parâmetros inválidos ou memória insuficiente. No entanto, problemas na conversão de nomes individuais são relatados no membro status da estrutura DS_NAME_RESULT_ITEM retornada para cada nome de entrada.

Nota Não confunda os valores dos elementos de formato do parâmetro formatOffered usado pela função DsCrackNames com os elementos de formato nomeados da mesma forma, conforme definido na enumeração ADS_NAME_TYPE_ENUM usada pela interface IADsNameTranslate . Os dois conjuntos de formatos de elemento não são equivalentes e não são intercambiáveis.

Observação

O cabeçalho ntdsapi.h define DsCrackNames 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