Active Directory Provider::Translate Name

  • Article

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

Wrapper for the Win32 API function Translate Name.

Arguments

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:

NameUnknown0Unknown name type.
NameFullyQualifiedDN1Fully qualified distinguished name (for example, CN=John Smith,OU=Users,DC=Engineering,DC=Microsoft,DC=Com).
NameSamCompatible2Microsoft Windows NT 4.0 account name (for example, Engineering\JSmith). The domain-only version includes trailing backslashes (\\).
NameDisplay3A "friendly" display name (for example, John Smith). The display name is not necessarily the defining relative distinguished name (RDN).
NameUniqueId6Globally unique identifier (GUID) string that the IIDFromString function returns (for example, {4fa050f0-f561-11cf-bdd9-00aa003a77b6}).
NameCanonical7Complete canonical name (for example, sales.tailspintoys.com/software/someone). The domain-only version includes a trailing forward slash (/).
NameUserPrincipal8User principal name (for example, someone@engineering.microsoft.com).
NameCanonicalEx9Same 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).
NameServicePrincipal10Generalized 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:

NameUnknown0Unknown name type.
NameFullyQualifiedDN1Fully qualified distinguished name (for example, CN=John Smith,OU=Users,DC=Engineering,DC=Microsoft,DC=Com).
NameSamCompatible2Windows NT 4.0 account name (for example, Engineering\JSmith). The domain-only version includes trailing backslashes (\\).
NameDisplay3A "friendly" display name (for example, John Smith). The display name is not necessarily the defining relative distinguished name (RDN).
NameUniqueId6GUID string that the IIDFromString function returns (for example, {4fa050f0-f561-11cf-bdd9-00aa003a77b6}).
NameCanonical7Complete canonical name (for example, engineering.microsoft.com/software/someone). The domain-only version includes a trailing forward slash (/).
NameUserPrincipal8User principal name (for example, someone@engineering.microsoft.com).
NameCanonicalEx9Same 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).
NameServicePrincipal10Generalized 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

Example XML Request

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.

Example XML Response

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.

Applies To

Active Directory Provider for:

  • Hosted Messaging and Collaboration version 4.5

  • Hosted Messaging and Collaboration version 4.0

  • Hosted Messaging and Collaboration version 3.5

  • Hosted Messaging and Collaboration version 3.0

  • Windows-based Hosting version 4.5

  • Windows-based Hosting version 4.0

  • Windows-based Hosting version 3.5

  • Windows-based Hosting for Applications version 1.0

See also

Tasks

Active Directory Provider::Rename Object