Função DsCrackNamesA (ntdsapi.h)

Artigo
11/20/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 nomes 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, objetos de usuário podem ser identificados por nomes de conta SAM (Domínio\nome de usuário), nome de entidade de usuário (Nome de Usuário@Domínio.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 sinalizadores 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 retornem os nomes diferenciados de todos os contextos de nomenclatura na floresta atual. O parâmetro formatDesired é ignorado. cNames deve ser pelo menos uma e todas as cadeias de caracteres em rpNames devem ter um comprimento maior que zero caracteres. O conteúdo do rpNames cadeias de caracteres é ignorado.

ObservaçãoDS_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 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 ela não for mais necessária, chamando DsFreeNameResult.

Valor de retorno

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

Observações

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 associado a um catálogo global, o escopo do mapeamento de nomes 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 de forma inequívoca 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 ou ao catálogo global correto 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 status membro da estrutura de DS_NAME_RESULT_ITEM retornada para cada nome de entrada.

Observação Não confunda os valores dos elementos de formato do parâmetro formatOffered usado pela função DsCrackNames com os elementos de formato de nome semelhante, 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.

Nota

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