Platform SDK: Active Directory, ADSI, and Directory Services

IADsPathname

The IADsPathname interface is designed for parsing the X.500 and Windows® paths in ADSI. You can use this interface to:

Set and retrieve paths of ADSI objects in different formats
Extract or add each element for a given ADsPath
Construct ADsPaths to be used in queries of directory objects

The IADsPathname interface is implemented on a Pathname object. You need to instantiate the Pathname object in order to use the methods defined in the IADsPathname interface. This requirement amounts to calling the CoCreateInstance() function in C++

IADsPathname *pPathname=NULL;
HRESULT hr;
 
hr = CoCreateInstance(CLSID_Pathname,
                      NULL,
                      CLSCTX_INPROC_SERVER,
                      IID_IADsPathname,
                      (void**)&pPathname);

You can also invoke the New operator in Visual Basic®:

Dim path as New Pathname

Or you can use the CreateObject function in VBScript, supplying "Pathname" as the ProgID.

Dim path
Set path = CreateObject("Pathname")

The IADsPathname interface exposes the following methods and uses two enumeration types: ADS_SETTYPE_ENUM, and ADS_FORMAT_ENUM.

Methods in Vtable Order

IUnknown methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.

IDispatch methods	Description
GetTypeInfoCount	Gets the number of type descriptions.
GetTypeInfo	Gets a description of object's programmable interface.
GetIDsOfNames	Maps name of method or property to DISPID.
Invoke	Calls one of the object's methods or gets and sets one of its properties.

IADsPathname methods	Description
get_EscapedMode	Retrieves the mode for escaping a path.
put_EscapedMode	Specifies the mode for escaping a path.
Set	Sets an object path with an ADS_SETTYPE_ENUM option.
SetDisplayType	Specifies how a path is to be displayed.
Retrieve	Retrieves an object path with an ADS_FORMAT_ENUM type.
GetNumElements	Gets the number of elements in the path.
GetElement	Gets elements stored in the object with its index.
GetEscapedElement	Escapes an RDN string and returns the output.
AddLeafElement	Adds an element to the end of the path.
RemoveLeafElement	Removes the last element from the object.
CopyPath	Generates an object with the same path.

Example Code [Visual Basic]

The following Visual Basic® code snippets shows how to create an ADsPathname object.

Dim x as New Pathname
x.Set "LDAP", ADS_SETTYPE_PROVIDER

x.Set "LDAP://server/dc=domain1,dc=Microsoft,dc=com", ADS_SETTYPE_FULL
MsgBox "Path in Windows Format: " & x.Retrieve(ADS_FORMAT_WINDOWS)

Example Code [VBScript]

The following VBScript/ASP code snippet shows how to create an ADsPathname object.

<%
Dim x 
Set x = CreateObject("Pathname")
x.Set "LDAP://server/dc=domain1,dc=Microsoft,dc=com", ADS_SETTYPE_FULL
winPath = x.Retrieve(ADS_FORMAT_WINDOWS)
Response.Write "Path in Windows Format: " & winPath
%>

Example Code [C++]

The following C++ code snippet shows how to create an ADsPathname object.

IADsPathname *GetPathnameObject(LPWSTR adsPath)
{
   if(!adsPath) return NULL;
 
   IADsPathname *pPathname=NULL;
   HRESULT hr;
 
   hr = CoCreateInstance(CLSID_Pathname,
                         NULL,
                         CLSCTX_INPROC_SERVER,
                         IID_IADsPathname,
                         (void**)&pPathname);
 
   if(FAILED(hr)) {
       if(pPathname) pPathname->Release();
       return NULL;
   }
 
   pPathname->AddRef();
   hr = pPathname->Set(adsPath,ADS_SETTYPE_FULL); 
 
   return pPathname;
}

Requirements