DsCrackNamesA function (ntdsapi.h)
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\UserName), user principal name (UserName@Domain.com), or distinguished name.
Syntax
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
);
Parameters
[in] hDS
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.
[in] flags
Contains one or more of the DS_NAME_FLAGS values used to determine how the name syntax will be cracked.
[in] formatOffered
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.
#ifndef DS_LIST_NCS
#define DS_LIST_NCS 0xfffffff6
#endif
[in] formatDesired
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.
[in] cNames
Contains the number of elements in the rpNames array.
[in] rpNames
Pointer to an array of pointers to null-terminated strings that contain names to be converted.
[out] ppResult
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.
Remarks
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
The ntdsapi.h header defines DsCrackNames as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista |
| Minimum supported server | Windows Server 2008 |
| Target Platform | Windows |
| Header | ntdsapi.h |
| Library | Ntdsapi.lib |
| DLL | Ntdsapi.dll |