DsCrackNames

The DsCrackNames function converts an array of directory service object names from one format to another.

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

Parameters

hDS

[in] Bind handle to the directory service.

flags

[in] Passes additional information to be used to process the request. This parameter can have one of the following values.

Value	Meaning
DS_NAME_FLAG_SYNTACTICAL_ONLY	Performs a purely syntactical mapping at the client without going over the network. The only syntactic mapping supported is from DS_FQDN_1779_NAME to DS_CANONICAL_NAME or DS_CANONICAL_NAME_EX (see the following formatOffered parameter). The DsCrackNames function returns DS_NAME_ERROR_NO_SYNTACTICAL_MAPPING if a purely syntactical mapping is not possible.
DS_NAME_NO_FLAGS	No flags passed.

formatOffered

[in] Identifies the format of the input names. This parameter can have one of the following values.

Value	Meaning
DS_CANONICAL_NAME	Complete canonical name (for example, engineering.microsoft.com/software/someone). The domain-only version includes a trailing forward slash (/).
DS_CANONICAL_NAME_EX	Same as DS_CANONICAL_NAME except that the rightmost forward slash (/) is replaced with a newline character (\n), even in a domain-only case (for example, engineering.microsoft.com/software\nsomeone).
DS_DISPLAY_NAME	A "friendly" display name (for example, John Smith). The display name is not necessarily the defining relative distinguished name (RDN).
DS_FQDN_1779_NAME	Fully qualified distinguished name (for example, CN=John Smith,OU=Users,DC=Engineering,DC=Microsoft,DC=Com).
DS_NT4_ACCOUNT_NAME	Windows NT® 4.0 account name (for example, Engineering\JSmith). The domain-only version includes a trailing backslash (\).
DS_SERVICE_PRINCIPAL_NAME	Generalized service principal name (for example, www/www.microsoft.com@microsoft.com).
DS_SID_OR_SID_HISTORY_NAME	A Security Identifier (SID) for the object. This can be either the current SID or a SID from the object's SID history. The SID string can use either the standard string representation of a SID, or one of the string constants defined in sddl.h. For information on converting a binary SID into a SID string, see SID Strings. This value is not valid for the formatDesired parameter.
DS_UNIQUE_ID_NAME	GUID string that the IIDFromString() function returns (for example, {4fa050f0-f561-11cf-bdd9-00aa003a77b6}).
DS_UNKNOWN_NAME	Unknown name type.
DS_USER_PRINCIPAL_NAME	User principal name (for example, someone@engineering.microsoft.com).

formatDesired

[in] Identifies the format of the output names. This parameter can be one of the values listed for formatOffered, except for DS_SID_OR_SID_HISTORY_NAME.

cNames

[in] Number of names to be converted.

rpNames

[in] Array of pointers to character strings containing the input names.

ppResult

[out] Pointer to a variable that receives a pointer to a DS_NAME_RESULT structure containing the converted names. The returned structure must be deallocated using DsFreeNameResult.

Return Values

If the function returns converted names, the return value is NO_ERROR.

If the function fails, the return value can be one of the following error codes.

ERROR_INVALID_PARAMETER

A parameter is incorrect.

ERROR_NOT_ENOUGH_MEMORY

There is insufficient memory available.

Individual name conversion errors are reported in the returned DS_NAME_RESULT structure.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Ntdsapi.h.
  Library: Included as a resource in Ntdsapi.dll.
  Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

DC and Replication Management Functions, DsFreeNameResult, DS_NAME_RESULT