Active Directory Provider::Translate Name

Converts names between different Microsoft® Win32® naming conventions. Used by Microsoft® Provisioning Framework (MPF).

Wrapper for the Win32 API function Translate Name.

XML Input Schema

The following code fragment shows the format for sending data to this procedure. For more information on individual elements and attributes, see the Elements and Attributes table.


<executeData>1..1 <outputFormat>1..1</outputFormat> <inputName>0..1</inputName> <inputFormat>0..1</inputFormat> </executeData>

XML Output Schema

The following code fragment shows the format for data this procedure returns. For more information on individual elements and attributes, see the Elements and Attributes table.


<executeData>1..1 <outputName></outputName>1..1 </executeData>

Elements and Attributes

The following table describes the XML schema elements and attributes. Unless otherwise indicated, the data type is string.

Element Description, relationships, and attributes
executeData Description:
Encapsulates the procedure's input and output data.

Children:
inputFormat (minOccurs="0" maxOccurs="1", input only)
inputName (minOccurs="0" maxOccurs="1", input only)
outputFormat (minOccurs="1" maxOccurs="1", input only)
outputName (minOccurs="1" maxOccurs="1", output only)

inputFormat Description:
Format of the input name to convert. The inputFormat value can be an EXTENDED_NAME_FORMAT string or decimal number. Defaults to NameUnknown. For more information, see the Win32 API TranslateName documentation in MSDN®.

Table of EXTENDED_NAME_FORMAT strings and values:

NameUnknown 0 Unknown name type.
NameFullyQualifiedDN 1 Fully qualified distinguished name (for example, CN=John Smith,OU=Users,DC=Engineering,DC=Microsoft,DC=Com).
NameSamCompatible 2 Microsoft® Windows NT® 4.0 account name (for example, Engineering\JSmith). The domain-only version includes trailing backslashes (\\).
NameDisplay 3 A "friendly" display name (for example, John Smith). The display name is not necessarily the defining relative distinguished name (RDN).
NameUniqueId 6 Globally unique identifier (GUID) string that the IIDFromString function returns (for example, {4fa050f0-f561-11cf-bdd9-00aa003a77b6}).
NameCanonical 7 Complete canonical name (for example, sales.tailspintoys.com/software/someone). The domain-only version includes a trailing forward slash (/).
NameUserPrincipal 8 User principal name (for example, someone@engineering.microsoft.com).
NameCanonicalEx 9 Same as NameCanonical 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).
NameServicePrincipal 10 Generalized service principal name (for example, www/www.microsoft.com@microsoft.com).

Parent:
executeData

inputName Description:
Name to convert. If inputName is empty or the element is not included, the provider uses the Win32 API function GetUserNameEx to get the name of the calling user.

Parent:
executeData

outputFormat Description:
The output format that the input name will be converted to and returned as outputName. The outputFormat value can be an EXTENDED_NAME_FORMAT string or decimal number. For more information, see the MSDN Win32 API TranslateName documentation.

Table of EXTENDED_NAME_FORMAT strings and values:

NameUnknown 0 Unknown name type.
NameFullyQualifiedDN 1 Fully qualified distinguished name (for example, CN=John Smith,OU=Users,DC=Engineering,DC=Microsoft,DC=Com).
NameSamCompatible 2 Windows NT 4.0 account name (for example, Engineering\JSmith). The domain-only version includes trailing backslashes (\\).
NameDisplay 3 A "friendly" display name (for example, John Smith). The display name is not necessarily the defining relative distinguished name (RDN).
NameUniqueId 6 GUID string that the IIDFromString function returns (for example, {4fa050f0-f561-11cf-bdd9-00aa003a77b6}).
NameCanonical 7 Complete canonical name (for example, engineering.microsoft.com/software/someone). The domain-only version includes a trailing forward slash (/).
NameUserPrincipal 8 User principal name (for example, someone@engineering.microsoft.com).
NameCanonicalEx 9 Same as NameCanonical 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).
NameServicePrincipal 10 Generalized service principal name (for example, www/www.microsoft.com@microsoft.com).

Parent:
executeData

outputName Description:
Converted name.

Parent:
executeData

Remarks

For example, to obtain the "otherHomePhone" property of "user@domain.com", you would use Translate Name to convert the name from NameUserPrincipal to NameFullyQualifiedDN, then Path From DN to convert the DN to a lightweight directory access protocol (LDAP) path, and finally Get Properties to get the value of "otherHomePhone".

Sample request:


<request> <data> <inputName>user@domain.com</inputName> <referencePath>LDAP://domain.com/dc=domain,dc=com</referencePath> </data> <procedure> <!-- Convert from "user@domain.com" to "cn=user,cn=users,dc=domain,dc=com" --> <execute namespace='Active Directory Provider' procedure='Translate Name'> <executeData> <inputFormat>NameUserPrincipal</inputFormat> <outputFormat>NameFullyQualifiedDN</outputFormat> </executeData> <before source='data' sourcePath='inputName' destination='executeData'/> <after source='executeData' sourcePath='outputName' destination='data'/> </execute> <!-- Convert the DN from above to an LDAP path --> <execute namespace='Active Directory Provider' procedure='Path From DN'> <executeData> <distinguishedName/> </executeData> <before source='data' sourcePath='outputName' destination='executeData' destinationPath='distinguishedName' mode='merge'/> <before source='data' sourcePath='referencePath' destination='executeData'/> <after source='executeData' sourcePath='path' destination='data'/> </execute> <!-- Get the user's "otherHomePhone" property from Active Directory --> <execute namespace='Active Directory Provider' procedure='Get Properties'> <executeData> <propertyList> <otherHomePhone> </propertyList> </executeData> <before source='data' sourcePath='path' destination='executeData'/> <after source='executeData' sourcePath='properties' destination='data'/> </execute> </procedure> </request>

Sample response:

<response>
  <data>
	<inputName>user@domain.com</inputName>
	<referencePath>LDAP://domain.com/dc=domain,dc=com</referencePath>
	<outputName>cn=user,cn=users,dc=domain,dc=com</outputName>
	<path>LDAP://domain.com/cn=user,cn=users,dc=domain,dc=com</path>
	<properties>
	 <property name='otherHomePhone'><value>555-1212</value></property>
	</properties>
  </data>
</response>
 Applies To
See Also

Active Directory Provider