Initializing the Store

When a connection event occurs, the service manager calls IReplStore::Initialize to ensure that the data file for the application exists and is open. The service manager:

To accomplish these tasks, the service manager places a series of calls to the desktop provider module, prompting the desktop provider module to respond with the necessary information.

The following illustration shows the order in which the service manager calls the desktop provider module.

In order for the service manager to initialize the desktop provider module, you must store the name of the file that needs to be synchronized in the registry. The registry location for this file name depends on whether you are initializing the desktop provider module for a connected device or a selected device.

A selected device is a disconnected device that a user selects from the list of profiles stored in the Windows CE Services Mobile Device folder. A user selects a profile to change synchronization options. When a user selects a device, the service manager passes the bit flag ISF_SELECTED_DEVICE into IReplStore::Initialize.

To access the profile information for a device:

If a device is remotely connected to the desktop, the service manager passes the ISF_REMOTE_CONNECTED bit flag into IReplStore::Initialize. Whenever this flag is set, the desktop provider module should not display any blocking UI, such as a message box or a dialog box, because the user may not be able to respond to the UI. Instead, the desktop provider module should accept all default actions, without prompting the user on the desktop.

If the service provider returns an error in IReplStore::Initialize, the service manager automatically displays an error message. If you want the desktop provider module rather than the service manager to display an error message that you create, return RERR_NO_ERR_PROMPT.

The service manager typically calls IReplStore::Initialize immediately after a connection event occurs. However, the service manager can call other methods first, such as when a user changes the synchronization options for a disconnected device.

The following table shows the methods that can be called before IReplStore::Initialize.

IReplStore method
Description
IReplStore::GetStoreInfo Gets information about a store, which is displayed in the ActiveSync option dialog box.
IReplStore::GetObjTypeUIData Gets information about an object type, which is displayed in the ActiveSync option dialog box under Status.
IReplStore::GetFolderInfo Gives the folder handle, HREPLFLD, to the desktop provider module.
IReplStore::ActivateDialog Allows a user to change options for an ActiveSync service.
IReplStore::BytesToObject Converts a series of bytes to a HREPLITEM handle or a HREPLFLD handle.
IReplStore::ObjectToBytes Converts a HREPLITEM handle or a HREPLFLD handle to a series of bytes.
IReplStore::ReportStatus Informs the desktop provider module about events that are taking place. This method is optional.

The following code example shows how to implement IReplStore::Initialize.

STDMETHODIMP CStore::Initialize
(
    IReplNotify *pNotify,    // Pointer to the IReplNotify interface
    UINT uFlags              // Either ISF_SELECTED_DEVICE or 
                            // ISF_REMOTE_CONNECTED
)
{
    m_pNotify = pNotify;
    m_uFlags = uFlags;

    // Get the correct registry for the synchronization options.
    HKEY hKey;
    HRESULT hr;
    hr = m_pNotify->QueryDevice( ( uFlags & ISF_SELECTED_DEVICE )? 
            QDC_SEL_DEVICE_KEY : QDC_CON_DEVICE_KEY, (LPVOID *)&hKey );

 // Read the registry for the type of files to synchronize.
 // ...


    // The service provider should suppress all UI that requires 
    // user input 
    // if ISF_REMOTE_CONNECTED is set in uFlags.
    // ...

    return NOERROR;
}

CStore is a COM class whose base is IReplStore. The following code example shows the CStore definition.

class CStore: public IReplStore
{
private:
    LONG                m_cRef;
    LPUNKNOWN        m_pUnkOuter;

public:
    CStore( LPUNKNOWN );
    ~CStore();

    // ******** IUnknown methods **************
    // QueryInterface, AddRef, and Release

    // ******** IReplStore methods **************
    // Store manipulation routines
     // Initialize, GetStoreInfo, ReportStatus, CompareStoreIDs

    // Object-related routines
     // CompareItem, IsItemChanged, IsItemReplicated, UpdateItem

    // Folder-related routines
    // GetFolderInfo, IsFolderChanged

    // Enumeration of folder objects
    // FindFirstItem, FindNextItem, FindItemClose

    // STD management routines
     // ObjectToBytes, BytesToObject, FreeObject, CopyObject,         
    // IsValidObject

    // UI-related routines
    // ActivateDialog, GetObjTypeUIData, GetConflictInfo, 
    // RemoveDuplicates

private:
    IreplNotify        *m_pNotify;
    CDataHandler    *m_pObjHandler;
    UINT                m_uFlags;
};