Función DsCrackNamesA (ntdsapi.h)

Artículo
11/20/2024

La función DsCrackNames convierte una matriz de nombres de objeto de servicio de directorio de un formato a otro. La conversión de nombres permite a las aplicaciones cliente asignar entre los varios nombres usados para identificar varios objetos de servicio de directorio. Por ejemplo, los objetos de usuario se pueden identificar mediante nombres de cuenta SAM (Dominio\NombreDeUsuario), nombre principal de usuario (NombreDeUsuario@Dominio.com) o nombre distintivo.

Sintaxis

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

Contiene un identificador de servicio de directorio obtenido de la función de DSBind o DSBindWithCred. Si marcas contiene DS_NAME_FLAG_SYNTACTICAL_ONLY, hDS se puede null.

[in] flags

Contiene uno o varios de los valores de DS_NAME_FLAGS usados para determinar cómo se descifrará la sintaxis de nombre.

[in] formatOffered

Contiene uno de los valores de DS_NAME_FORMAT que identifica el formato de los nombres de entrada.

El valor de DS_LIST_NCS también se puede pasar para este parámetro. Esto hace que DsCrackNames devuelvan los nombres distintivos de todos los contextos de nomenclatura del bosque actual. El parámetro formatDesired se omite. cNames debe ser al menos una y todas las cadenas de rpNames deben tener una longitud mayor que cero caracteres. Se omite el contenido del rpNames cadenas.

NotaDS_LIST_NCS no se define en un archivo de encabezado publicado. Para usar este valor, definalo en el formato exacto que se muestra a continuación.

#ifndef DS_LIST_NCS
    #define DS_LIST_NCS 0xfffffff6
#endif

[in] formatDesired

Contiene uno de los valores de DS_NAME_FORMAT que identifica el formato de los nombres de salida. No se admite el valor de DS_SID_OR_SID_HISTORY_NAME.

[in] cNames

Contiene el número de elementos de la matriz rpNames de .

[in] rpNames

Puntero a una matriz de punteros a cadenas terminadas en null que contienen nombres que se van a convertir.

[out] ppResult

Puntero a un valor de PDS_NAME_RESULT que recibe una estructura DS_NAME_RESULT que contiene los nombres convertidos. El autor de la llamada debe liberar esta memoria, cuando ya no sea necesario, llamando a DsFreeNameResult.

Valor devuelto

Devuelve un valor de error Win32, un valor de error RPC o uno de los siguientes.

Observaciones

El éxito de la solicitud de conversión de nombres depende de dónde está enlazado el cliente. Los clientes se enlazan a instancias específicas del servicio de directorio mediante alguna variante de DsBind. Si se enlaza a un catálogo global, el ámbito de la asignación de nombres es todo el bosque. Si no está enlazado a un catálogo global, el ámbito de la asignación de nombres es el dominio no cubierto por un catálogo global para ese controlador de dominio. Si no está enlazado a un catálogo global y no se encuentra un nombre, pero el nombre de entrada identifica inequívocamente su dominio y este dominio está en el bosque, los datos devueltos identifican el nombre de dominio DNS para el dominio de interés. Se espera que los clientes usen estos datos para enlazar al controlador de dominio correcto o al catálogo global y llamar a DsCrackNames de nuevo con el nuevo identificador de enlace.

El valor devuelto de DsCrackNames indica errores como parámetros no válidos o memoria insuficiente. Sin embargo, los problemas de conversión de nombres individuales se notifican en el estado miembro de la estructura DS_NAME_RESULT_ITEM devuelta para cada nombre de entrada.

Nota No confunda los valores de los elementos de formato del parámetro formatOffered usado por la función DsCrackNames con los elementos de formato con nombre similar definidos en la enumeración ADS_NAME_TYPE_ENUM usada por la interfaz IADsNameTranslate. Los dos conjuntos de formatos de elemento no son equivalentes y no son intercambiables.

Nota

El encabezado ntdsapi.h define DsCrackNames como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows Vista
servidor mínimo admitido	Windows Server 2008
de la plataforma de destino de	Windows
encabezado de	ntdsapi.h
biblioteca de	Ntdsapi.lib
DLL de	Ntdsapi.dll