IPimSrcContactNew::Create

Artigo
09/09/2008

Windows Mobile Supported Windows Embedded CE Not Supported

9/8/2008

The Criar método altera o fluxo de controle no apontar onde os usuários criar um novo contato item. Em vez de supondo que o contato para Outlook, os usuários recebem a opção para criar um novo contato que está associado com um determinado Source Provider, que pode ser associado com um externo serviço such as Windows Messenger ou o cartão SIM.

Essa personalização é exibida quando os usuários tocar Novo No aplicativo de contatos. Na apontar, o Escolher tipo de contato Tela for exibida, que apresenta aos usuários com uma lista das opções Contact Type para escolher a partir — cada um para um serviço diferente (e cada associado com um Source Provider diferentes). O serviço usar como padrão é Outlook.

Syntax

HRESULT Create (
  HWND hwndParent,
  IItem * pitem
)

Parameters

hwndParent
[no] Identificador (HWND) para o janela pai. Para informações sobre o HWND tipo, consulte GetParent.

pitem
[In/Out] Referência a um IItem contato item. As in parâmetro de entrada: Se pitem não é NULL, em seguida, ele contém dados para serem salvos no novo contato. As in parâmetro de saída: Se pitem não é NULL, em seguida, o OID do contato item é considerado um parâmetro de saída. Para obter mais informações sobre Item OIDS, consulte IItem::get_Oid.

Return Value

Esse método retorna o seguinte valores:

S_OK
The method completed successfully.

S_FALSE
O provedor não requer um comportamento especial. Você deve apenas exibir o Contact Edit Card, usar como padrão e salvar o novo contato sem um Source ID e definir o PIMPR_DO_NOT_SYNC flag. For more information, see Shared Property ID's.

S_AUTO_CLOSED
O método foi concluída com êxito, mas o cartão de resumo não devem ser exibido. Provedores retornam este valor quando a caixa diálogo criar sai por um motivo Other Than o usuário descartando-lo. Nessas situações, o re-aparência do Summary Card seria inadequado e confusa.

E_INVALIDARG
Um dos argumentos era inválido.

E_ABORT
O usuário cancelou a criação do novo item.

Remarks

Quando Criar é chamado com uma referência para um IItem contato item, ele indica que há dados para salvar o contato Novo item.

Desde que os dados são fornecidos na pItem referência, você deve garantir que o Contact OID é preenchido para o chamador pode link de contato para os dados. Por exemplo, considere a possibilidade salvando um contato item com informações histórico chamar. Este maiúsculas e minúsculas, o OID retornado na pItem é usado para link o CALLLOGENTRY item para o contato Novo item. Se não houver nenhuma OID, e o histórico chamar não pode ser vinculado, e o nome exibir não será atualizado para esse histórico específico chamar item in a Discagem ou ISpTTSEngine::Speak. Chamada de histórico interface usuário.

Fonte provedores e seus associado fazem do Source ID parte de um mecanismo que ofereça suporte por-provedor personalização da experiência do gerenciador de informações pessoais em dispositivos Windows Mobile powered.

Um provedor de origem é um personalizado função que personaliza experiência do usuário Gerenciador de informações pessoais. Normalmente, um provedor de fonte tem uma correspondente associar função que é responsável Sincronizando dados gerenciador de informações pessoais com o dispositivo Windows Mobile powered. Dados sincronizado com o dispositivo Windows Mobile powered por este associar função é marcada com uma marca de identificação de fonte (Source ID). Quando Outlook Mobile exibe um PIM item, ele verifica se o item tem um ID. de origem Se encontrar um, ele chama o provedor de fonte, que personaliza a interface usuário para o gerenciador de informações pessoais item.

Quando os usuários inserem novos contatos e compromissos, pode selecionar um provedor de fonte para associar com eles.

Um válido Source ID é um DWORD com somente conjunto 1 bit (isto é, há identificações de origem possíveis 32).

Embora sejam itens de contatos e compromissos, regardless of Source ID, sincronizado com Microsoft Exchange — as identificações de origem não são.

As identificações de origem não são com suporte para itens de tarefas.

Como contatos e compromissos podem ser associado com apenas uma Source Provider, sua implementação instalação Source Provider deve selecionar um Source ID that is exclusivo no domínio de todos os Source Providers instalado o dispositivo Windows Mobile powered (ele é considerado um erro para determinar as identificações de fonte prior to instalar). A implementação deve escolher um exclusivo Source ID por Iterando primeiro sobre o Source Providers instalado registrado na chave \HKLM\PIMSources\ e, em seguida, escolhendo o próximo disponível ID. de origem

O valor Source ID usar como padrão é zero (0). Itens de contato e compromisso com um valor Source ID do zero não são associado com um Source Provider e apenas use a interface usuário usar como padrão.

Sua implementação desinstalar Source Provider deve redefinir o campo Source ID de tudo associado itens de contatos e compromissos voltar para zero.

Example

Este exemplo de código é uma função encapsulada que demonstra como usar IPimSrcContactNew::Create Para criar um contato item. Ele cria um personalizado caixa de mensagem com usar como padrão entre em contato com os detalhes e, em seguida, permite que os usuários salvar o item para o armazenamento de dados.

Observação

Para tornar este exemplo de código mais fácil para ler, verificação de segurança e manipulação de erro não estão incluídos.Portanto, não use este exemplo de código " como está" Na sua versão Configuration–you precisa modificar a codificar incluí-los.

STDMETHODIMP CSampleProvider::Create(HWND hwndParent, IItem *pItemIn)
{
    HRESULT            hr = S_OK;
    IDispatch * pDispatch = NULL;
    IItem         * pItem = NULL;
    DWORD      dwSourceID;
    int   idMessageResult;

    CEPROPVAL rgpvals[] = {{PIMPR_SOURCE_ID,   0, 0, 0}, 
                           {PIMPR_FIRST_NAME,  0, 0, 0}, 
                           {PIMPR_DO_NOT_SYNC, 0, 0, 1}};

    // Display a user confirmation message box.
    idMessageResult = MessageBox(hwndParent, 
                                 _T("Would you like to create a new Contact item?"), 
                                 _T("New Contact"), MB_YESNO);

    if (idMessageResult != IDYES)
        goto Exit;                 // The user decided to not create a Contact item.

    // Create a new Contact item with default details.
    hr = m_polApp->CreateItem(olContactItem, &pDispatch);
    hr = pDispatch->QueryInterface(IID_IItem, (void**)&pItem);

    // Configure the Source Provider by reading its Source ID (REG_DWORD) registry value.
    hr = RegistryGetDWORD(PIMSRC_REGHKEY, g_wszOurKey, g_wszOurValueName, &dwSourceID);

    // Set the default properties for the new Contact item.
    rgpvals[0].val.ulVal  = dwSourceID;
    rgpvals[1].val.lpwstr = _T("TestCreateProvider");

    hr = pItem->SetProps(0, ARRAYSIZE(rgpvals), rgpvals);

    // Save the new Contact item.
    hr = pItem->Save();

Exit:
    if (pDispatch)
        pDispatch->Release();

    if (pItem)
        pItem->Release();

    return hr;
}

Se você estiver criando novo provedor origem baseia este codificar, você pode localizá-la útil para fazer o seguinte referências e declarações em seu arquivo cabeçalho.

// Include ATL headers.
#define _CE_ALLOW_SINGLE_THREADED_OBJECTS_IN_MTA 
#define MAX_BUFFER 1024

extern CComModule _Module;

#include <atlbase.h>
#include <atlcom.h>
#include <windows.h>
#include <RegExt.h>         // For registry helper functions.
#include <pimstore.h>       // For POOM and PIM APIs.

// SDK macros (for example CBR, and CHR, RELEASE_OBJ).
#include "Macros.h"

Definir um personalizado código de erro para identificador a maiúsculas e minúsculas quando uma personalização não está disponível.

#define E_PIMSRC_NO_AVAILABLE_ID    MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, 0x00)

Define o conjunto de personalizações que estiver implementando neste provedor de fonte.

#define PIM_CUSTOMIZATIONS PIMSRC_CUSTOM_CONTACTS_SUMMARY_CARD | \
                           PIMSRC_CUSTOM_CONTACTS_PAINT_LIST_ICON | \
                           PIMSRC_CUSTOM_CONTACTS_NEW | \
                           PIMSRC_CUSTOM_APPOINTMENTS_COLORS

Define os tipos item Outlook a aplicar as personalizações para.

#define PIM_CUSTOMIZED_TYPES PIMSRC_TYPE_CONTACTS | PIMSRC_TYPE_APPOINTMENTS

Constantes (consulte Const.cpp para valores definidos).

extern const GUID     CLSID_SampleProvider;
extern HANDLE         g_currentInstance;
extern const LPTSTR   g_szCLSID_SampleProvider;
extern const LPWSTR   g_szDllName;
extern const COLORREF g_crCalendarBackground;
extern const WCHAR    g_wszOurKey[];
extern const WCHAR    g_wszOurValueName[];
extern const WCHAR    g_wszDisplayName[];

Encaminhar Declarações função.

// Functions to Init and UnInit POOM.
HRESULT InitPOOM(IPOutlookApp2 **ppolApp);
HRESULT UnInitPOOM(IPOutlookApp2 *polApp);

// Functions to register and unregister this Source Provider.
HRESULT LookupSourceId(DWORD *pdwSourceId);
HRESULT RegisterPIMSource();
HRESULT UnregisterPIMSource();

// Function to handle any additional setup for the Source Provider.
HRESULT ItemSetup(IPOutlookApp2 *polApp, int olItemType, BOOL bInstall);

// Function to get HMITMAP from IStream.
HBITMAP LoadImageStream(IStream *pStream);

O seguinte exemplo de código demonstra uma típica definição de classe Source Provider.

class CSampleProvider :
    public CComObjectRootEx<CComMultiThreadModel>,
    public CComCoClass<CSampleProvider, &CLSID_SampleProvider>,
    public IPimSrcContactListIcon,
    public IPimSrcContactNew,
    public IPimSrcContactSummaryCard
{
public:
    // Miscillaneous ATL declarations.
    DECLARE_NO_REGISTRY();
    DECLARE_PROTECT_FINAL_CONSTRUCT()
    BEGIN_COM_MAP(CSampleProvider)
        COM_INTERFACE_ENTRY(IPimSrcContactListIcon)
        COM_INTERFACE_ENTRY(IPimSrcContactSummaryCard)
        COM_INTERFACE_ENTRY(IPimSrcContactNew)
    END_COM_MAP()

protected:
    // The lifetime of Source Provider is managed by CComObject<>, which derives from our class, 
    // therefore our constructor and destructor should be protected, 
    // to ensure that no other objects can create or destroy objects of this type.
    CSampleProvider();
    virtual ~CSampleProvider();

    HRESULT EnsurePOOM();

    // Access to methods of the Source Provider class should be through interface pointers ohly.

    // IPimSrcContactSummaryCard
    STDMETHOD(Display)(HWND hwndParent, IItem *pitem);

    // IPimSrcContactListIcon
    STDMETHOD(Paint)(const SRCCUSTOMDRAW *pscd, CEOID oid);

    // IPimSrcContactNew
    STDMETHOD(Create)(HWND hwndParent, IItem *pItem);

private:
    IPOutlookApp2   *m_polApp;

Requirements

Header	pimstore.h
Library	Pimstore.lib
Windows Mobile	Windows Mobile 6 Classic and later, Windows Mobile 6 Professional and later, Windows Mobile 6 Standard and later

Compartilhar via

IPimSrcContactNew::Create

Syntax

Parameters

Return Value

Remarks

Example

Requirements

See Also

Reference

Concepts

Other Resources

Recursos adicionais