Export (0) Print
Expand All

DsCrackNames 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\UserName), user principal name (UserName@Domain.com), or distinguished name.

Syntax


DWORD DsCrackNames(
  _In_   HANDLE hDS,
  _In_   DS_NAME_FLAGS flags,
  _In_   DS_NAME_FORMAT formatOffered,
  _In_   DS_NAME_FORMAT formatDesired,
  _In_   DWORD cNames,
  _In_   LPCTSTR *rpNames,
  _Out_  PDS_NAME_RESULT *ppResult
);

Parameters

hDS [in]

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.

flags [in]

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

formatOffered [in]

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

formatDesired [in]

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.

cNames [in]

Contains the number of elements in the rpNames array.

rpNames [in]

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

ppResult [out]

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.

Return codeDescription
NO_ERROR

The function was successful. Individual name conversion errors are reported in the status member of the DS_NAME_RESULT_ITEM structure.

ERROR_INVALID_PARAMETER

One or more of the parameters are invalid.

ERROR_NOT_ENOUGH_MEMORY

A memory allocation failure occurred.

DS_NAME_ERROR_NO_SYNTACTICAL_MAPPING

A syntactical mapping is not possible.

 

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

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Redistributable

Active Directory Client Extension on Windows NT 4.0 and Windows Me/98/95

Header

Ntdsapi.h

Library

Ntdsapi.lib

DLL

Ntdsapi.dll

Unicode and ANSI names

DsCrackNamesW (Unicode) and DsCrackNamesA (ANSI)

See also

Domain Controller and Replication Management Functions
ADS_NAME_TYPE_ENUM
DS_NAME_FLAGS
DS_NAME_FORMAT
DS_NAME_RESULT
DS_NAME_RESULT_ITEM
DsFreeNameResult
IADsNameTranslate

 

 

Show:
© 2014 Microsoft