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.

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>

Schema Definition

Input



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

Output



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

Sample Code

Applies To