ADS_ESCAPE_MODE_ENUM

The ADS_ESCAPE_MODE_ENUM enumeration specifies how escape characters are displayed in a directory pathname.

typedef enum {
  ADS_ESCAPEDMODE_DEFAULT  = 1,
  ADS_ESCAPEDMODE_ON       = 2,
  ADS_ESCAPEDMODE_OFF      = 3,
  ADS_ESCAPEDMODE_OFF_EX   = 4
  } ADS_ESCAPE_MODE_ENUM;

Elements

ADS_ESCAPEDMODE_DEFAULT

The default escape mode provides a convenient option for specifying the escaping mode. It gives rise to a bare minimal escaping appropriate for a chosen format. Thus, the default behavior depends on the value that ADS_FORMAT_ENUM uses to retrieve the directory paths.

Retrieved Path Format	Default Escaped Mode
ADS_FORMAT_X500	ADS_ESCAPEDMODE_ON
ADS_FORMAT_X500_NO_SERVER	ADS_ESCAPEDMODE_ON
ADS_FORMAT_WINDOWS	ADS_ESCAPEDMODE_ON
ADS_FORMAT_WINDOWS_NO_SERVER	ADS_ESCAPEDMODE_ON
ADS_FORMAT_X500_DN	ADS_ESCAPEDMODE_OFF
ADS_FORMAT_X500_PARENT	ADS_ESCAPEDMODE_OFF
ADS_FORMAT_WINDOWS_DN	ADS_ESCAPEDMODE_OFF
ADS_FORMAT_WINDOWS_PARENT	ADS_ESCAPEDMODE_OFF
ADS_FORMAT_LEAF	ADS_ESCAPEDMODE_ON

ADS_ESCAPEDMODE_ON

All special characters will be displayed as escaped, for example, "CN=date\=yy\/mm\/dd\,weekday" will be shown as is.

ADS_ESCAPEDMODE_OFF

ADSI special characters will be displayed as unescaped, for example, "CN=date\=yy\/mm\/dd\,weekday" will be displayed as "CN=date\=yy/mm/dd\,weekday".

ADS_ESCAPEDMODE_OFF_EX

ADSI and LDAP special characters will be displayed as unescaped, for example, "CN=date\=yy\/mm\/dd\,weekday" will be displayed as "CN=date=yy/mm/dd,weekday".

Remarks

Special characters must be escaped when they are used for any unintended purposes. For example, LDAP special characters, "," and "=", are intended as field separators in a distinguished name, "CN=user, CN=users, DC=Microsoft, DC=com". When an attribute value uses such special characters, for example, "CN=users\,last name\=Smith", these special characters must be escaped as shown. This ensures that an LDAP-compliant directory, such as Active Directory, will parse the path properly. However, an escaped path string may not appear to be user-friendly on a display. In this case, you can set the ADS_ESCAPE_MODE in such way that shows the path as an unescaped string, "CN=users,last name=Smith".

Similarly, the ADSI special character, "/", is used to separate ADSI-specific elements, "LDAP://server/CN=James Smith, CN=Users, DC=Microsoft, DC=com". Although it must be escaped when used for any other purposes, for example, "LDAP://server/CN=James Smith\/California, CN=Users, DC=Microsoft, DC=com". You can choose an ADS_ESCAPE_MODE option to display this escaped string in a more humanly readable fashion: "LDAP://server/CN=James Smith/California, CN=Users, DC=Microsoft, DC=com".

Presently, "/" is the only ADSI special character. LDAP special characters are defined in the LDAP specifications. ADSI escaping/unescaping applies to ADSI special characters only. The operation will not affect any LDAP special characters, that is, they are neither escaped nor unescaped.

To show unescaped path string, you must use IADsPathname interface and its methods. All other ADSI APIs return the escaped path string.

Note  Because VBSript cannot read information from a type library, VBScript applications do not understand the symbolic constants as defined above. You should use the numerical constants instead to set the appropriate flags in your VBScript applications. If you want to use the symbolic constants as a good programming practice, you should make explicit declarations of such constants, as done here, in your VBScript applications.

Requirements

  Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with DSClient).
  Windows 95/98: Requires Windows 95 or later (with DSClient).
  Header: Declared in Iads.h.

See Also

ADSI Enumerations, ADS_FORMAT_ENUM, IADsPathname