Platform SDK: MAPI

Creating a Distribution List

Clients can create a distribution list directly into a modifiable container such as the personal address book (PAB).

To create a distribution list in the PAB

  1. Create a sized property tag array with one property tag, PR_DEF_CREATE_DL, as follows:
SizedPropTagArray(1, tagaDefaultDL) = 
{
    1,
    {
        PR_DEF_CREATE_DL
    }
};
  1. Call IAddrBook::GetPAB to retrieve the entry identifier of the PAB. If there is an error or GetPAB returns zero or NULL, do not continue.
LPENTRYID peidPAB = NULL;
ULONG cbeidPAB = 0;
lpIAddrBook->GetPAB(&cbeidPAB, &peidPAB);
  1. Call IAddrBook::OpenEntry to open the PAB. The ulObjType output parameter should be set to MAPI_ABCONT.
ULONG ulObjType = 0;
LPABCONT lpPABCont = NULL;
lpIAddrBook->OpenEntry(cbeidPAB, peidPAB,
                NULL,
                MAPI_MODIFY,
                &ulObjType,
                &lpPABCont);
  1. Call the PAB's IMAPIProp::GetProps method to retrieve the PR_DEF_CREATE_DL property, the template that it uses to create a distribution list.
lpPABCont->GetProps(0,
            tagaDefaultDL,
            &lpspvDefDLTpl);
  1. If GetProps fails:
    1. Call the PAB's IMAPIProp::OpenProperty method to open the PR_CREATE_TEMPLATES property with the IMAPITable interface.
    2. Create a property restriction to search for the row with the PR_ADDRTYPE column equal to "MAPIPDL."
    3. Call IMAPITable::FindRow to locate this row.
  2. Save the entry identifier returned by either GetProps or FindRow.
peidDefDLTpl = lpspvDefDLTpl->Value.bin.pb;
cbeidDefDLTpl = lpspvDefDLTpl->Value.bin.cb;
  1. Call the PAB's IABContainer::CreateEntry method to create a new entry using the template represented by the saved entry identifier. Do not assume that the object returned will be a distribution list rather than a messaging user when this call is remoted. Notice that the CREATE_CHECK_DUP flag is passed in the ulFlags parameter to prevent the entry from being added twice.
lpPABCont->CreateEntry(cbeidDefDLTpl,
                peidDefDLTPL,
                CREATE_CHECK_DUP_STRICT,
                &lpNewPABEntry);
  1. Call the new entry's IUnknown::QueryInterface method, passing IID_IDistList as the interface identifier, to determine if the entry is a distribution list and supports the IDistList interface. Because CreateEntry returns an IMAPIProp pointer rather than the more specific IMailUser or IDistList pointer, check that a distribution list object was created. If QueryInterface succeeds, you can be sure that you have created a distribution list rather than a messaging user.
  2. Call the distribution list's IMAPIProp::SetProps method to set its display name and other properties.
  3. Call the distribution list's IABContainer::CreateEntry method to add one or more messaging users.
  4. Call the distribution list's IMAPIProp::SaveChanges method when you're ready to save it. To retrieve the entry identifier of the saved distribution list, set the KEEP_OPEN_READWRITE flag and then call IMAPIProp::GetProps asking for the PR_ENTRYID property.
  5. Release the new distribution list and the PAB by calling their IUnknown::Release methods.
  6. Call MAPIFreeBuffer to release the memory for the entry identifier of the PAB and the sized property tag array.