DsCrackNamesA function

The DsCrackNames function converts an array of directory service object names from one format to another. Name conversion enables client applications to map between the multiple names used to identify various directory service objects. For example, user objects can be identified by SAM account names (Domain<i>UserName), user principal name (UserName@Domain.com), or distinguished name.


  HANDLE           hDS,
  DS_NAME_FLAGS    flags,
  DS_NAME_FORMAT   formatOffered,
  DS_NAME_FORMAT   formatDesired,
  DWORD            cNames,
  const LPCSTR     *rpNames,



Contains a directory service handle obtained from either the DSBind or DSBindWithCred function. If flags contains DS_NAME_FLAG_SYNTACTICAL_ONLY, hDS can be NULL.


Contains one or more of the DS_NAME_FLAGS values used to determine how the name syntax will be cracked.


Contains one of the DS_NAME_FORMAT values that identifies the format of the input names.

The DS_LIST_NCS value can also be passed for this parameter. This causes DsCrackNames to return the distinguished names of all naming contexts in the current forest. The formatDesired parameter is ignored. cNames must be at least one and all strings in rpNames must have a length greater than zero characters. The contents of the rpNames strings is ignored.

Note  DS_LIST_NCS is not defined in a published header file. To use this value, define it in the exact format shown below.
#ifndef DS_LIST_NCS
    #define DS_LIST_NCS 0xfffffff6


Contains one of the DS_NAME_FORMAT values that identifies the format of the output names. The DS_SID_OR_SID_HISTORY_NAME value is not supported.


Contains the number of elements in the rpNames array.


Pointer to an array of pointers to null-terminated strings that contain names to be converted.


Pointer to a PDS_NAME_RESULT value that receives a DS_NAME_RESULT structure that contains the converted names. The caller must free this memory, when it is no longer required, by calling DsFreeNameResult.

Return value

Returns a Win32 error value, an RPC error value, or one of the following.


The success of the name conversion request depends on where the client is bound. Clients bind to specific instances of the directory service using some variant of DsBind. If bound to a global catalog, the scope of the name mapping is the entire forest. If not bound to a global catalog, the scope of the name mapping is the domain not covered by a global catalog for that domain controller. If not bound to a global catalog and a name is not found, but the input name unambiguously identifies its domain and this domain is in the forest, then the return data identifies the DNS domain name for the domain of interest. Clients are expected to use this data to bind to the correct domain controller or global catalog and call DsCrackNames again with the new bind handle.

The return value from DsCrackNames indicates errors such as invalid parameters or insufficient memory. However, problems in converting individual names are reported in the status member of the DS_NAME_RESULT_ITEM structure returned for each input name.

Note  Do not confuse the values of the format elements of the formatOffered parameter used by the DsCrackNames function with the similarly named format elements as defined in the ADS_NAME_TYPE_ENUM enumeration used by the IADsNameTranslate interface. The two sets of element formats are not equivalent and are not interchangeable.


Minimum supported client Windows Vista
Minimum supported server Windows Server 2008
Target Platform Windows
Header ntdsapi.h
Library Ntdsapi.lib
DLL Ntdsapi.dll

See also






Domain Controller and Replication Management Functions