Función DsCrackNamesA (ntdsapi.h)

Artículo
03/08/2023

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 (Nombre de usuario de dominio\), nombre principal de usuario (@dominio de nombre de usuario.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 DSBind o DSBindWithCred . Si las marcas contienen DS_NAME_FLAG_SYNTACTICAL_ONLY, hDS puede ser NULL.

[in] flags

Contiene uno o varios de los valores de DS_NAME_FLAGS usados para determinar cómo se descifrará la sintaxis del 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 devuelva los nombres distintivos de todos los contextos de nomenclatura del bosque actual. Se omite el parámetro formatDesired . cNames debe tener al menos una y todas las cadenas de rpNames deben tener una longitud mayor que cero caracteres. Se omite el contenido de las cadenas rpNames .

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 .

[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 es necesaria, llamando a DsFreeNameResult.

Valor devuelto

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

Comentarios

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 está enlazado 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 miembro de estado 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, tal como se define en la enumeración de 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 neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista
Servidor mínimo compatible	Windows Server 2008
Plataforma de destino	Windows
Encabezado	ntdsapi.h
Library	Ntdsapi.lib
Archivo DLL	Ntdsapi.dll