Type a page name and press Enter. You'll jump to the page if it exists, or you can create it if it doesn't.
To create a page in a module other than ntdsapi, prefix the name with the module name and a period.
<DllImport("ntdsapi.dll")> _
Public Shared Function DsCrackNames(ByVal hDS As IntPtr, _
ByVal flags As DS_NAME_FLAGS, _
ByVal formatOffered As DS_NAME_FORMAT, _
ByVal formatDesired As DS_NAME_FORMAT, _
ByVal cNames As UInt32, _
<MarshalAs(UnmanagedType.LPArray, ArraySubType:=UnmanagedType.LPTStr, SizeParamIndex:=4)> ByVal rpNames As String(), _
ByRef ppResult As IntPtr) As Object
End Function
<DllImport("ntdsapi.dll")> _
Public Shared Function DsCrackNames(ByVal hDS As IntPtr, _
ByVal flags As DS_NAME_FLAGS, _
ByVal formatOffered As DS_NAME_FORMAT, _
ByVal formatDesired As DS_NAME_FORMAT, _
ByVal cNames As UInt32, _
<MarshalAs(UnmanagedType.LPArray, ArraySubType:=UnmanagedType.LPWStr, SizeParamIndex:=4)> ByVal rpNames As String(), _
ByRef ppResult As IntPtr) As Object
End Function
User-Defined Types:
None.
Notes:
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.
Tips & Tricks:
Please add some!
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.
Tips & Tricks:
Please add some!
Sample Code:
using System;
using System.Runtime.ConstrainedExecution;
using System.Runtime.InteropServices;
using System.Security;
namespace Microsoft.Win32
using System.Text;
namespace test
{
internal static partial class NativeMethods
class Class1
{
const uint NO_ERROR = 0;
[DllImport("ntdsapi.dll", CharSet=CharSet.Auto)]
static public extern uint DsCrackNames(
IntPtr hDS,
DS_NAME_FLAGS flags,
DS_NAME_FORMAT formatOffered,
DS_NAME_FORMAT formatDesired,
uint cNames,
string[] rpNames,
out IntPtr ppResult // PDS_NAME_RESULT
);
// Couldn't find the name at all - or perhaps caller doesn't have
// rights to see it.
DS_NAME_ERROR_NOT_FOUND = 2,
// Input name mapped to more than one output name.
DS_NAME_ERROR_NOT_UNIQUE = 3,
// Input name found, but not the associated output format.
// Can happen if object doesn't have all the required attributes.
DS_NAME_ERROR_NO_MAPPING = 4,
// Unable to resolve entire name, but was able to determine which
// domain object resides in. Thus DS_NAME_RESULT_ITEM?.pDomain
// is valid on return.
DS_NAME_ERROR_DOMAIN_ONLY = 5,
// Unable to perform a purely syntactical mapping at the client
// without going out on the wire.
DS_NAME_ERROR_NO_SYNTACTICAL_MAPPING = 6,
// The name is from an external trusted forest.
DS_NAME_ERROR_TRUST_REFERRAL = 7
}
[Flags]
public enum DS_NAME_FLAGS
{
DS_NAME_NO_FLAGS = 0x0,
// Perform a syntactical mapping at the client (if possible) without
// going out on the wire. Returns DS_NAME_ERROR_NO_SYNTACTICAL_MAPPING
// if a purely syntactical mapping is not possible.
DS_NAME_FLAG_SYNTACTICAL_ONLY = 0x1,
// Force a trip to the DC for evaluation, even if this could be
// locally cracked syntactically.
DS_NAME_FLAG_EVAL_AT_DC = 0x2,
// The call fails if the DC is not a GC
DS_NAME_FLAG_GCVERIFY = 0x4,
// Same as DS_CANONICAL_NAME except that rightmost '/' is
// replaced with '\n' - even in domain-only case.
// eg: example.microsoft.com/software\nuser name
DS_CANONICAL_NAME_EX = 9,
// eg: www/www.microsoft.com@example.com - generalized service principal
// names.
DS_SERVICE_PRINCIPAL_NAME = 10,
// This is the string representation of a SID. Invalid for formatDesired.
// See sddl.h for SID binary <--> text conversion routines.
// eg: S-1-5-21-397955417-626881126-188441444-501
DS_SID_OR_SID_HISTORY_NAME = 11,
// Pseudo-name format so GetUserNameEx can return the DNS domain name to
// a caller. This level is not supported by the DS APIs.
DS_DNS_DOMAIN_NAME = 12
}
[SuppressUnmanagedCodeSecurity, ReliabilityContract(Consistency.WillNotCorruptState, Cer.Success)]
public class DsHandle : IDisposable
{
IntPtr handle = IntPtr.Zero;
public DsHandle(string domainControllerName = null, string dnsDomainName = null)
{
uint res = DsBind(domainControllerName, dnsDomainName, out handle);
if (res != NO_ERROR)
throw new System.ComponentModel.Win32Exception((int)res);
}
public string CrackName(string name)
{
var res = CrackNames(new string[] { name });
if (res == null || res.Length == 0 || res[0].status != NativeMethods.DS_NAME_ERROR.DS_NAME_NO_ERROR)
throw new System.Security.SecurityException("Unable to resolve user name.");
return res[0].pName;
}
/// <summary>
/// A wrapper function for the DsCrackNames OS call
/// </summary>
/// <param name="names">The names to crack</param>
/// <param name="flags">Flags controlling the process</param>
/// <param name="formatOffered">Format of the names</param>
/// <param name="formatDesired">Desired format for the names</param>
/// <returns>The crack result</returns>
public DS_NAME_RESULT_ITEM[] CrackNames(string[] names = null, DS_NAME_FLAGS flags = DS_NAME_FLAGS.DS_NAME_NO_FLAGS,
DS_NAME_FORMAT formatOffered = DS_NAME_FORMAT.DS_NT4_ACCOUNT_NAME, DS_NAME_FORMAT formatDesired = DS_NAME_FORMAT.DS_USER_PRINCIPAL_NAME)
{
IntPtr pResult;
uint err = DsCrackNames(handle, flags, formatOffered, formatDesired, (uint)((names == null) ? 0 : names.Length), names, out pResult);
if (err != NO_ERROR)
throw new System.ComponentModel.Win32Exception((int)err);
try
{
// Next convert the returned structure to managed environment
DS_NAME_RESULT Result = (DS_NAME_RESULT)Marshal.PtrToStructure(pResult, typeof(DS_NAME_RESULT));
return Result.Items;
}
finally
{
DsFreeNameResult(pResult);
}
}
public void Dispose()
{
uint ret = DsUnBind(ref handle);
System.Diagnostics.Debug.WriteLineIf(ret != 0, "Error unbinding :\t" + ret.ToString());
}
}
[DllImport(NTDSAPI, CharSet = CharSet.Auto)]
public static extern uint DsBind(
string DomainControllerName, // in, optional
string DnsDomainName, // in, optional
out IntPtr phDS);
[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Auto)]
public struct DS_NAME_RESULT
{
public uint cItems;
internal IntPtr rItems; // PDS_NAME_RESULT_ITEM
public DS_NAME_RESULT_ITEM[] Items
{
get
{
if (rItems == IntPtr.Zero)
return new DS_NAME_RESULT_ITEM[0];
var ResultArray = new DS_NAME_RESULT_ITEM[cItems];
Type strType = typeof(DS_NAME_RESULT_ITEM);
int stSize = Marshal.SizeOf(strType);
IntPtr curptr;
for (uint i = 0; i < cItems; i++)
{
curptr = new IntPtr(rItems.ToInt64() + (i * stSize));
ResultArray[i] = (DS_NAME_RESULT_ITEM)Marshal.PtrToStructure(curptr, strType);
}
return ResultArray;
}
}
}
[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Auto)]
public struct DS_NAME_RESULT_ITEM
{
public DS_NAME_ERROR status;
public string pDomain;
public string pName;
public override string ToString()
{
if (status == DS_NAME_ERROR.DS_NAME_NO_ERROR)
return pName;
return null;
}
}
}
}
DS_NAME_NO_ERROR = 0,
// Couldn't find the name at all - or perhaps caller doesn't have
// rights to see it.
DS_NAME_ERROR_NOT_FOUND = 2,
// Input name mapped to more than one output name.
DS_NAME_ERROR_NOT_UNIQUE = 3,
// Input name found, but not the associated output format.
// Can happen if object doesn't have all the required attributes.
DS_NAME_ERROR_NO_MAPPING = 4,
// Unable to resolve entire name, but was able to determine which
// domain object resides in. Thus DS_NAME_RESULT_ITEM?.pDomain
// is valid on return.
DS_NAME_ERROR_DOMAIN_ONLY = 5,
// Unable to perform a purely syntactical mapping at the client
// without going out on the wire.
DS_NAME_ERROR_NO_SYNTACTICAL_MAPPING = 6,
// The name is from an external trusted forest.
DS_NAME_ERROR_TRUST_REFERRAL = 7
}
[Flags]
public enum DS_NAME_FLAGS
{
DS_NAME_NO_FLAGS = 0x0,
// Perform a syntactical mapping at the client (if possible) without
// going out on the wire. Returns DS_NAME_ERROR_NO_SYNTACTICAL_MAPPING
// if a purely syntactical mapping is not possible.
DS_NAME_FLAG_SYNTACTICAL_ONLY = 0x1,
// Force a trip to the DC for evaluation, even if this could be
// locally cracked syntactically.
DS_NAME_FLAG_EVAL_AT_DC = 0x2,
// The call fails if the DC is not a GC
DS_NAME_FLAG_GCVERIFY = 0x4,
// Same as DS_CANONICAL_NAME except that rightmost '/' is
// replaced with '\n' - even in domain-only case.
// eg: example.microsoft.com/software\nuser name
DS_CANONICAL_NAME_EX = 9,
// eg: www/www.microsoft.com@example.com - generalized service principal
// names.
DS_SERVICE_PRINCIPAL_NAME = 10,
// This is the string representation of a SID. Invalid for formatDesired.
// See sddl.h for SID binary <--> text conversion routines.
// eg: S-1-5-21-397955417-626881126-188441444-501
DS_SID_OR_SID_HISTORY_NAME = 11,
// Pseudo-name format so GetUserNameEx can return the DNS domain name to
// a caller. This level is not supported by the DS APIs.
DS_DNS_DOMAIN_NAME = 12
}
[ StructLayout( LayoutKind.Sequential, CharSet=CharSet.Auto )]
public struct DS_NAME_RESULT_ITEM
{
public DS_NAME_ERROR status;
public string pDomain;
public string pName;
}
[DllImport("ntdsapi.dll", CharSet=CharSet.Auto)]
static public extern uint DsBind(
string DomainControllerName, // in, optional
string DnsDomainName, // in, optional
out IntPtr phDS);
[DllImport("ntdsapi.dll", CharSet=CharSet.Auto)]
static public extern uint DsUnBind(ref IntPtr phDS);
[ StructLayout( LayoutKind.Sequential, CharSet=CharSet.Auto )]
public struct DS_NAME_RESULT
{
public uint cItems;
public IntPtr rItems; // PDS_NAME_RESULT_ITEM
}
[STAThread]
static void Main(string[] args)
{
// Bind to default global catalog
IntPtr hDS;
uint err = DsBind(null,null,out hDS);
if (err != NO_ERROR)
{
Console.WriteLine("Error on DsBind : {0}",err);
return;
}
// Crack the currently logged on name
try
{
string[] names = new string[]{System.Security.Principal.WindowsIdentity.GetCurrent().Name};
DS_NAME_RESULT_ITEM[] results =
HandleDsCrackNames(hDS,DS_NAME_FLAGS.DS_NAME_NO_FLAGS,DS_NAME_FORMAT.DS_NT4_ACCOUNT_NAME,DS_NAME_FORMAT.DS_FQDN_1779_NAME,names);
foreach (DS_NAME_RESULT_ITEM result in results)
{
Console.WriteLine("Result : {0}\r\nDomain : {1}\r\nName : {2}",result.status,result.pDomain,result.pName);
}
}
finally
{
DsUnBind(ref hDS);
}
}
/// <summary>
/// A wrapper function for the DsCrackNames OS call
/// </summary>
/// <param name="hDS">DsBind handle</param>
/// <param name="flags">Flags controlling the process</param>
/// <param name="formatOffered">Format of the names</param>
/// <param name="formatDesired">Desired format for the names</param>
/// <param name="names">The names to crack</param>
/// <returns>The crack result</returns>
public static DS_NAME_RESULT_ITEM[] HandleDsCrackNames(IntPtr hDS,DS_NAME_FLAGS flags,DS_NAME_FORMAT formatOffered,DS_NAME_FORMAT formatDesired,string[] names)
{
IntPtr pResult;
DS_NAME_RESULT_ITEM[] ResultArray;
uint err = DsCrackNames(
hDS,
flags,
formatOffered,
formatDesired,
(uint)((names == null) ? 0 : names.Length),
names,
out pResult);
if (err != NO_ERROR)
throw new System.ComponentModel.Win32Exception((int)err);
try
{
// Next convert the returned structure to managed environment
DS_NAME_RESULT Result = new DS_NAME_RESULT();
Result.cItems = (uint)Marshal.ReadInt32(pResult);
Result.rItems = Marshal.ReadIntPtr(pCrackNamesResult, Marshal.OffsetOf(typeof(DS_NAME_RESULT), "rItems").ToInt32());
IntPtr curptr = Result.rItems;
ResultArray = new DS_NAME_RESULT_ITEM[Result.cItems];
for (int index = 0; index < (int)Result.cItems; index++)
{
ResultArray[index] = (DS_NAME_RESULT_ITEM)Marshal.PtrToStructure(curptr,typeof(DS_NAME_RESULT_ITEM));
curptr = (IntPtr)((int)curptr + Marshal.SizeOf(ResultArray[index]));
}
}
finally
{
DsFreeNameResult(pResult);
}
return ResultArray;
}
}
}
Alternative Managed API:
Do you know one? Please contribute it!
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.
9/21/2015 5:53:24 PM - -131.107.0.80
The DsBindWithCred function binds to a domain controller using the specified credentials.
4/19/2016 7:39:45 AM - stefan.cuypers@pandora.be-213.118.174.16
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.
9/21/2015 5:53:24 PM - -131.107.0.80
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.
9/21/2015 5:53:24 PM - -131.107.0.80
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.
9/21/2015 5:53:24 PM - -131.107.0.80
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.
9/21/2015 5:53:24 PM - -131.107.0.80
Please edit this page!
Do you have...
helpful tips or sample code to share for using this API in managed code?
corrections to the existing content?
variations of the signature you want to share?
additional languages you want to include?
Select "Edit This Page" on the right hand toolbar and edit it! Or add new pages containing supporting types needed for this API (structures, delegates, and more).
Revisions