IPOlItems3::IncludeSimContacts (Compact 7)

Article
03/14/2014

3/12/2014

The IncludeSimContacts method configures a Contacts collection to include SIM Contacts along with the rest of the Device Contacts. SIM Contact items have a PIMPR_CONTACT_TYPE property value of PIMPR_CONTACTTYPE::PIMPR_CONTACTTYPE_SIM.

Note

For more information about support for SIM Contacts in POOM, see PIMPR_CONTACTTYPE.

Syntax

virtual HRESULT STDMETHODCALLTYPE IncludeSimContacts() = 0;

Parameters

None.

Return Values

This method returns the standard value E_UNEXPECTED, as well as the following:

S_OK
The method completed successfully.

Remarks

Prior to calling IncludeSimContacts, the Contacts collection returns only Device Contacts. After calling IncludeSimContacts, the collection can return SIM Contacts (if they match any restrictions placed on the item collection).

Example

The following code example demonstrates how to use IncludeSimContacts to create and work with both Device Contacts and SIM Contacts.

Note

To make the following code example easier to read, security checking and error handling are not included. This code example should not be used in a release configuration unless it has been modified to include them.

HRESULT DemoSIMContacts(void)
{
    HRESULT                 hr = S_OK;
    IDispatch      * pDispatch = NULL;
    IContact        * pContact = NULL;

    IPOutlookApp      * polApp = NULL;
    IFolder          * pFolder = NULL;

    IPOlItems3  * polItemsBase = NULL,
               * polItemsBase2 = NULL;

    IPOutlookItemCollection * polDefaultCollection        = NULL,
                            * polDefaultCollection2       = NULL,
                            * polRestrictedNotSecondPhone = NULL,
                            * polRestrictedOnlyFirstPhone = NULL,
                            * polRestrictedSimOnly        = NULL,
                            * polRestrictedSecondPhone    = NULL,
                            * polRestrictedNoSim          = NULL;

    // Logon to POOM.
    CoInitializeEx(NULL, COINIT_MULTITHREADED);
    hr = CoCreateInstance(CLSID_Application, NULL, CLSCTX_INPROC_SERVER, IID_IPOutlookApp, (LPVOID *) &polApp);
    hr = polApp->Logon(NULL);

    // Create three Device Contacts.
    hr = polApp->CreateItem(olContactItem, &pDispatch);
    hr = pDispatch->QueryInterface(IID_IContact, (void **)&pContact);
    hr = pContact->put_FirstName(_T("Device Contact 1"));
    hr = pContact->put_BusinessTelephoneNumber(PHONE_FIRST);
    hr = pContact->Save();
    pDispatch = NULL;
    pContact = NULL;

    hr = polApp->CreateItem(olContactItem, &pDispatch);
    hr = pDispatch->QueryInterface(IID_IContact, (void **)&pContact);
    hr = pContact->put_FirstName(_T("Device Contact 2"));
    hr = pContact->put_BusinessTelephoneNumber(PHONE_SECOND);
    hr = pContact->Save();
    pDispatch = NULL;
    pContact = NULL;

    hr = polApp->CreateItem(olContactItem, &pDispatch);
    hr = pDispatch->QueryInterface(IID_IContact, (void **)&pContact);
    hr = pContact->put_FirstName(_T("Device Contact 3"));
    hr = pContact->put_BusinessTelephoneNumber(PHONE_THIRD);
    hr = pContact->Save();
    pDispatch = NULL;
    pContact = NULL;

    // Create two SIM Contacts.
    hr = polApp->CreateItem(olContactItem, &pDispatch);
    hr = pDispatch->QueryInterface(IID_IContact, (void **)&pContact);
    hr = pContact->put_FirstName(_T("Sim Contact 1"));
    hr = pContact->put_BusinessTelephoneNumber(PHONE_FIRST);
    hr = pContact->Save();
    pDispatch = NULL;
    pContact = NULL;

    hr = polApp->CreateItem(olContactItem, &pDispatch);
    hr = pDispatch->QueryInterface(IID_IContact, (void **)&pContact);
    hr = pContact->put_FirstName(_T("Sim Contact 2"));
    hr = pContact->put_BusinessTelephoneNumber(PHONE_SECOND);
    hr = pContact->Save();

    RELEASE(pContact);
    RELEASE(pDispatch);
    pDispatch = NULL;
    pContact = NULL;

    // Get the default Contacts Collection (which contains no SIM Contacts).
    hr = polApp->GetDefaultFolder(olFolderContacts, &pFolder);
    hr = pFolder->get_Items(&polDefaultCollection);

    // Include SIM contacts in the Contacts Collection (both Device and SIM Contacts).
    hr = polDefaultCollection->QueryInterface(IID_IPOlItems3, (void**)&polItemsBase);
    hr = polItemsBase->IncludeSimContacts();

    // Restrict the collection to just the SIM Contacts.
    hr = polItemsBase->Restrict(SIMONLY_RESTRICTION, &polRestrictedSimOnly);

    // Restrict the collection to just the Device Contacts.
    hr = polItemsBase->Restrict(NOSIM_RESTRICTION, &polRestrictedNoSim);
    
    // Restrict the collection to just the 2nd Contacts.
    hr = polItemsBase->Restrict(PHONE_RESTRICTION_SECOND, &polRestrictedSecondPhone);

    // Restriction placed over default SIM restriction - only #1 Device Contact.
    hr = pFolder->get_Items(&polDefaultCollection2);
    hr = polDefaultCollection2->Restrict(PHONE_RESTRICTION_NOTSECOND, &polRestrictedNotSecondPhone);
    hr = polRestrictedNotSecondPhone->Restrict(PHONE_RESTRICTION_NOTTHIRD, &polRestrictedOnlyFirstPhone);

    // Include SIM Contacts in the already restricted set - Only #1 Contacts.
    hr = polRestrictedOnlyFirstPhone->QueryInterface(IID_IPOlItems3, (void**)&polItemsBase2);
    hr = polItemsBase2->IncludeSimContacts();
    hr = ShowCollection(polItemsBase2, _T("All contacts with the first phone number:"));

    RELEASE(polDefaultCollection);
    RELEASE(polDefaultCollection2);
    RELEASE(polRestrictedSimOnly);
    RELEASE(polRestrictedNoSim);
    RELEASE(polRestrictedSecondPhone);
    RELEASE(polItemsBase);
    RELEASE(pFolder);
    RELEASE(polApp);

    return !SUCCEEDED(hr);
}

To Compile the Code Example

The POOM API defines several interface GUIDs that you can use to identify specific Outlook Mobile objects. To use these IIDs, add the following preprocessor directives to your application's source code before any other #include statements.
```
#define INITGUID
#include <stdafx.h>
#include <initguid.h>
#include <pimstore.h>
#include "pimstoreEx.h"
#undef INITGUID
```

Define a set of string constants that you can reference in your code.

#define PHONE_FIRST _T("1111111")
#define PHONE_SECOND _T("2222222")
#define PHONE_THIRD _T("3333333")
#define PHONE_RESTRICTION_SECOND _T("[BusinessTelephoneNumber] = \"2222222\"")
#define PHONE_RESTRICTION_NOTSECOND _T("[BusinessTelephoneNumber] <> \"2222222\"")
#define PHONE_RESTRICTION_NOTTHIRD _T("[BusinessTelephoneNumber] <> \"3333333\"")
#define SIMONLY_RESTRICTION _T("[ContactType] = 1")
#define NOSIM_RESTRICTION _T("[ContactType] <> 1")

Specify a linker dependency to the POOM type library, as a project property.
1. Press Alt+F7, and the Project Property Pages dialog box appears.
2. In the dialog box, navigate to the Input property page for the Linker (navigate to Configuration Properties > Linker > Input).
3. In Additional Dependencies, type pimstore.lib, and then click OK.
Rebuild the Solution (press Ctrl+Alt+F7).

Remarks

Calling IncludeSimContacts more than once has no effect.

To exclude SIM Contacts from a Contacts collection that has been configured to include them, it is better to just get another collection; as opposed to implementing a restriction to filter them out (which incurs a performance hit each time you use the collection).

Requirements

Header	pimstoreex.h
Library	Pimstore.lib

IPOlItems3::IncludeSimContacts (Compact 7)

Syntax

Parameters

Return Values

Remarks

Example

To Compile the Code Example

Remarks

Requirements

See Also

Reference

Other Resources

Additional resources