DsCrackNames

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.

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

Parameters

hDS

[in] Contains the bind handle to the directory service. To obtain this handle, call DsBind 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.

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 Values

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

Client: Included in Windows XP and Windows 2000 Professional.
Server: Included in Windows Server 2003 and Windows 2000 Server.
Redistributable: Requires Active Directory Client Extension on Windows NT 4.0 SP6a and Windows 95/98/Me.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000/XP.
Header: Declared in Ntdsapi.h.
Library: Use Ntdsapi.lib.

See Also

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