3.1.4.3 Obtaining Properties on an Address Book Object

  • Article

To obtain properties for an Address Book object from an OAB, the messaging client needs to have either a DN for the object or the object's Simple Mail Transfer Protocol (SMTP) address. This means that the messaging client will need to keep track of the DN after any lookup in the OAB, and it will need to make sure that the DN or SMTP address is maintained for the addressee of a message when messages are sent or received through a messaging server. Incoming messages can contain either the SMTP address or the DN of message addressees. The messaging server provides the SMTP address or the DN of the addressee. The OAB Format and Schema Protocol, as specified in [MS-OXOAB], describes how this information is organized and structured. After the information for the Address Book object is located, it is possible for the client to retrieve the value of any property in that record. For example, to obtain properties such as the business telephone number and SMTP address, the client looks up the PidTagBusinessTelephoneNumber property (section 2.2.4.21) and the PidTagSmtpAddress property (section 2.2.3.21) in the record.

To obtain properties for an Address Book object on an address book server, the messaging client needs to either have a DN, a Minimal Entry ID, or the object's SMTP address. Specific NSPI calls and corresponding Messaging Application Programming Interface (MAPI) Extensions for HTTP request types that return Address Book object information — including but not limited to:

  • The NspiQueryRows method, as specified in [MS-NSPI] and [MS-OXNSPI] section 3.1.4.1.8<64>

  • The QueryRows request type, as specified in [MS-OXCMAPIHTTP] section 2.2.5.12<65>

  • The NspiSeekEntries method, as specified in [MS-NSPI] and [MS-OXNSPI] section 3.1.4.1.9

  • The SeekEntries request type, as specified in [MS-OXCMAPIHTTP] section 2.2.5.16<66>

  • The NspiGetMatches method, as specified in [MS-NSPI] and [MS-OXNSPI] section 3.1.4.1.10

  • The GetMatches request type, as specified in [MS-OXCMAPIHTTP] section 2.2.5.5<67>

— include the DN or Minimal Entry ID in their calls for the PidTagEntryId property, or as a return value of the calls. Clients use the NspiDNToMId method, as specified in [MS-NSPI] and [MS-OXNSPI] section 3.1.4.1.13, or the DnToMinId request type, as specified in [MS-OXCMAPIHTTP] section 2.2.5.4, to obtain the Minimal Entry ID from a DN.<68> To obtain a DN from an SMTP address, messaging clients construct a string that starts with "=SMTP: " followed by the SMTP address as the paStr or paWStr parameter to either the NspiResolveNames method, as specified in [MS-NSPI] and [MS-OXNSPI] section 3.1.4.1.16, or the NspiResolveNamesW method, as specified in [MS-NSPI] and [MS-OXNSPI] section 3.1.4.1.17, or the ResolveNames request type, as specified in [MS-OXCMAPIHTTP] section 2.2.5.14, and extract the DN from the PidTagEntryId property (section 2.2.3.2) that is returned, as specified in the PermanentEntryID structure, as specified in [MS-NSPI] and [MS-OXNSPI] section 2.2.9.3.<69><70>

After the Minimal Entry ID is known, clients use it as the CurrentRec member of the STAT structure passed to the NspiGetProps method, as specified in [MS-NSPI] and [MS-OXNSPI] section 3.1.4.1.7, or to the GetProps request type, as specified in [MS-OXCMAPIHTTP] section 2.2.5.7.<71> It is possible for clients to specify any number of properties (either in the pPropTags parameter of the NspiGetProps method or in the PropertyTags structure of the GetProps request type) that the client wants to request. For example, to request properties such as the business phone number and SMTP address, the client includes the property IDs for the PidTagBusinessTelephoneNumber (section 2.2.4.21) and PidTagSmtpAddress (section 2.2.3.21) properties in the pPropTags parameter.

To retrieve a property value from the NSPI server for the following properties, use the NspiGetMatches method or the GetMatches request type, as specified in [MS-OXCMAPIHTTP] section 2.2.5.5:<72>

  • PidTagAddressBookHomeMessageDatabase (section 2.2.4.37)

  • PidTagAddressBookMember property (section 2.2.6.1)

  • PidTagAddressBookManager property (section 2.2.5.1)

  • PidTagAddressBookReports property (section 2.2.5.2)

  • PidTagAddressBookIsMemberOfDistributionList property (section 2.2.5.3)

  • PidTagAddressBookOwnerBackLink property (section 2.2.5.4)

  • PidTagAddressBookOwner property (section 2.2.6.2)

    To retrieve these properties, set the CurrentRec field of the pStat input parameter to the EphemeralEntryID of the object and the ContainerId field to the property tag of the property to retrieve. The EphemeralEntryId structure is specified in [MS-OXNSPI] section 2.2.9.2.