Share via

3.1.4.1 Creating a New E-Mail Address for a Supported Address Type

  • Article

When the client has to use an e-mail address that does not exist on the address book server, it can create a new e-mail address for a supported address type and use this address to identify a recipient.

When the client creates a new e-mail address, first the address creation table MUST be retrieved by calling the NspiGetSpecialTable function, as specified in [MS-NSPI] and [MS-OXNSPI] section 3.1.4.1.3, where the value of the dwFlags parameter is set to NspiAddressCreationTemplates (0x00000002) and the rest of the input parameters are initialized as specified in[MS-NSPI] and [MS-OXNSPI] section 3.1.4.1.3. The function returns a PropertyRowSet_r structure that contains the data needed to create a list of creation templates for the supported address types. This list is then used to select an address type, possibly by displaying this list to the user or by selecting a type programmatically. When the address type has been selected, the data from the corresponding PropertyRow_r structure, as specified in [MS-NSPI] and [MS-OXNSPI] section 2.2.3, can be used to determine the distinguished name (DN) for the creation template that will be used to create the new e-mail address and its address type. The PidTagAddressType property ([MS-OXPROPS] section 2.576) is the property in the PropertyRow_r structure that indicates the e-mail address type. PidTagEntryId ([MS-OXPROPS] section 2.684) is the property in the PropertyRow_r that can be parsed to get the DN. The PidTagEntryId property is a PermanentEntryID structure, and its format is specified in [MS-NSPI] and [MS-OXNSPI] section 2.2.9.3.

Next, the creation dialog template that will be used to create a new e-mail address MUST be retrieved by using the NspiGetTemplateInfo function call, as specified in [MS-NSPI] and [MS-OXNSPI] section 3.1.4.1.18, passing in the DN (2) value for the creation template as the pDN parameter and 0x00000000 as the ulType parameter. The dwFlags parameter contains a bitwise combination that MUST include the bits for TI_TEMPLATE (0x00000001) set so that the template will be retrieved, and TI_SCRIPT (0x0000004) set so the script to format the e-mail address is retrieved, and MAY contain the bits for TI_HELPFILE_NAME (0x00000020) and TI_HELPFILE_CONTENTS (0x00000040) for a value of 0x00000065. <4>

The function's dwCodePage input parameter is the code page in which the strings in the template are stored, and in which the ppData return parameter is a pointer to a PropertyRow_r structure that contains the data needed to create and display a dialog to create the new e-mail address. When the dialog is completed and dismissed, the data from the dialog MUST be used to run the script and create the e-mail address for this entry. This e-mail address MUST be used to populate the PidTagEmailAddress property ([MS-OXPROPS] section 2.682) and the address type retrieved from the selected PropertyRow_r structure MUST be used to populate the PidTagAddressType property. These two properties comprise the e-mail address that can be used as an e-mail recipient.