Synchronization Manager

Purpose

The Synchronization Manager provides a centralized, standard technology for synchronizing files for offline use on either a mobile computer or a computer connected to a local area network that has latency issues. Developers can use the common interface to the Synchronization Manager in their applications to synchronize files between the user's local computer and network storage.

Files are synchronized independent of the protocol. For example, an e-mail program can transfer its messages using SMTP, NMTP, or POP3, while a browser can use HTTP, and a database can use Remote Procedure Call (RPC).

Where Applicable

The Synchronization Manager is intended for applications that run primarily on mobile computers. Applications that run on computers connected to high latency local area networks may also benefit from using the Synchronization Manager.

Developer Audience

This document is intended for software developers who develop applications for mobile computing and high latency local area networks. This document provides a complete reference of all parts of the Synchronization Manager including the methods and interfaces to the Synchronization Manager.

Run-time Requirements

Requires Microsoft® Windows® 2000.

See Also

System Event Notification Service

Overview

General information about Synchronization Manager.

Reference

Documentation of Synchronization Manager interfaces and methods.

Feedback

Make error reports and feature requests directly to Microsoft.

Microsoft Platform SDK, February 2001 Edition.
This content last built on Thursday, February 01, 2001.


Synchronization Manager

To enable applications for mobile computing, the operating system provides a synchronization manager (SyncMgr). Together with the connectivity functions, notifications (System Event Notification Service), and client side caching, the SyncMgr provides an infrastructure to support mobile computing. Instead of each application implementing its own technology to cache and synchronize network resources for local use, the operating system provides an integrated model that all applications can use.

To help you find the information you need, the following list describes each section of Synchronization Manager documentation:

  • About Synchronization Manager offers a broad overview of SyncMgr technology, including a discussion of mobile computing configurations where SyncMgr would be useful.
  • SyncMgr Reference lists methods and interfaces for Synchronization Manager.


About Synchronization Manager

The Synchronization Manager provides a centralized, standard technology for synchronizing files for offline use on a local computer. The user can prepare a computer for offline use by updating the needed files from the network storage. Then, when the computer is brought back online, any offline changes can be copied back to the network. SyncMgr provides a common user interface that all applications can share for synchronizing their files.

Files are transferred independent of the protocol. For example, an e-mail program can transfer its messages using SMTP, NMTP, or POP3, while a browser can use HTTP and a database can use RPC. The protocol is transparent to the SyncMgr.

SyncMgr is also storage independent and can transfer files, e-mail messages, HTML pages, or database information transparently.


Mobile Computing Configurations

The Synchronization Manager is useful for computers configured as follows:

  • Mobile computer used in a docking station on a high bandwidth network but occasionally used via a dial-in connection.
  • Mobile computer used mostly via a dial-in connection
  • Desktop computer used strictly via a dial-in connection, such as a computer used by a telecommuter
  • Desktop computer used strictly via a high bandwidth network.

Although the last case is not a typical mobile scenario, latency issues with network access may make it convenient to cache resources locally. In all these configurations, the application can use the SyncMgr to keep files and other resources cached locally and synchronized between online and offline use.


Application Scenarios

Applications and services that can use the Synchronization Manager include the following:

  • Microsoft® Office applications that need to prepare files for offline use
  • Client side caching that let you cache files locally
  • Browsers that can cache HTML pages locally
  • Mail programs that can cache e-mail messages locally
  • Databases that can store information locally


Synchronization Manager Architecture

The Synchronization Manager includes user interface components, such as the tabbed dialogs in the SyncMgr service, error dialogs, and progress dialogs. With the user interface components the end user can schedule applications for synchronization and set up automatic synchronization to occur in conjunction with specified system events. For example, the SyncMgr can be invoked at user logon or system shutdown. The user can also invoke a manual synchronization.

The user selects an application and specifies the items within the application to be synchronized and sets a trigger event. For example, within an e-mail application, the Inbox, the Outbox, or some other folder containing messages can be a separate item for the application.

SyncMgr also includes a programming interface so that applications can register to use synchronization features, can process errors, and can receive progress information and notifications during the synchronization process.


Using Synchronization Manager from a Program

To enable your application to work with the Sychronization Manager you must implement a COM object to handle synchronization notifications that you receive from SyncMgr. Your application's handler performs the synchronization for the items that you handle. Included in your handler, you must implement the ISyncMgrSynchronize interface. Also, you must provide an enumerator object and ISyncMgrEnumItems for any separate items that your application can synchronize.

SyncMgr implements ISyncMgrSynchronizeCallback and ISyncMgrSynchronizeInvoke.

The SyncMgr calls methods in your ISyncMgrSynchronize to get information on the items that your application handles and information on the handler that you provide for synchronizing these items.

At runtime, the synchronization process follows these steps:

  1. SyncMgr notifies your application that it is time for synchronization to occur for one of the items that your application handles by calling your ISyncMgrSynchronize::Initialize method.
  2. SyncMgr calls ISyncMgrSynchronize::EnumSyncMgrItems to obtain the ISyncMgrEnumItems interface for the items handled by your application.
  3. SyncMgr calls ISyncMgrSynchronize::SetProgressCallback to provide your handler with the interface pointer for the ISyncMgrSynchronizeCallback interface. Your handler uses this interface to call back to the SyncMgr during synchronization.
  4. SyncMgr then calls your ISyncMgrSynchronize::PrepareForSync method to give your handler a chance to display any user interface element that is necessary before synchronization begins. For example, an e-mail application may display a user logon dialog.
  5. Your handler calls ISyncMgrSynchronizeCallback::EnableModeless before and after displaying any user interface elements. Your handler calls ISyncMgrSynchronizeCallback::PrepareForSyncCompleted when you are done.
  6. SyncMgr calls your ISyncMgrSynchronize::Synchronize method to start the synchronization.

During the synchronization process, SyncMgr continues to call methods in your ISyncMgrSynchronize interface. It can send your handler errors, progress, and notifications. It can also enumerate through the items that your application handles or allow your application to show properties for the items.

Your handler calls methods in ISyncMgrSynchronizeCallback to determine if an item should be skipped, to log errors, and to post progress information during the synchronization process.

For further information, see the related reference pages for the interfaces involved.

When the synchronization is completed, your handler calls ISyncMgrSynchronizeCallback::SynchronizeCompleted.


SyncMgr Reference

This section lists the following methods and interfaces for Synchronization Manager:

  • ISyncMgrEnumItems
  • ISyncMgrRegister
  • ISyncMgrSynchronize
  • ISyncMgrSynchronizeCallback
  • ISyncMgrSynchronizeInvoke


ISyncMgrEnumItems

The ISyncMgrEnumItems interface is used to enumerate through an array of SYNCMGRITEM structures. Each of these structures provides information on an item that can be synchronized. ISyncMgrEnumItems has the same methods as all standard enumerator interfaces: Next, Skip, Reset, and Clone. For general information on these methods, refer to IEnumXXXX.

When to Implement

If the registered application works with the Synchronization Manager to synchronize items, it must implement an enumerator object with this interface to enumerate through the items.

When to Use

The SyncMgr obtains a pointer to this interface and calls each method during the synchronization process.

The prototypes of the methods are as follows:

HRESULT Next(
  ULONG celt,           // [in] Number of items in array
  LPSYNCMGRITEM rgelt,  // [out] Address of array containing items
  ULONG* pceltFetched   // [out] Address of variable containing actual number
                        //        of items
);

HRESULT Skip(
  ULONG celt                     // [in] Number of items to skip
);

HRESULT Reset(void);

HRESULT Clone(
  ISyncMgrEnumItems **ppenum     // [out] Address of variable that receives
                                 //   the ISyncMgrEnumItems interface pointer
);

Remarks

ISyncMgrEnumItems::Next
Enumerates the next celt elements in the enumerator's list, returning them in rgelt along with the actual number of enumerated elements in pceltFetched.

E_NOTIMPL is not allowed as a return value. If an error value is returned, no entries in the rgelt array are valid on exit and require no release.

ISyncMgrEnumItems::Skip
Instructs the enumerator to skip the next celt elements in the enumeration so the next call to ISyncMgrEnumItems::Next does not return those elements.
ISyncMgrEnumItems::Reset
Instructs the enumerator to position itself at the beginning of the list of elements.

There is no guarantee that the same set of elements are enumerated on each pass through the list, nor are the elements necessarily be enumerated in the same order. The exact behavior depends on the collection being enumerated. It is too expensive in terms of memory for some collections, such as files in a directory, to maintain a specific state.

ISyncMgrEnumItems::Clone
Creates another items enumerator with the same state as the current enumerator to iterate over the same list. This method makes it possible to record a point in the enumeration sequence in order to return to that point at a later time.

The caller must release this new enumerator separately from the first enumerator.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

SYNCMGRITEM


ISyncMgrRegister

An application can register with the Synchronization Manager either through the ISyncMgrRegister interface or by registering directly in the registry.

The handler must be a standard OLE server. It must register the standard OLE keys for an InProc OLE server in addition to the SyncMgr key.

IUnknown methods | Description
QueryInterface | Returns pointer to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

ISyncMgrRegister methods | Description
RegisterSyncMgrHandler | A handler calls this to register with SyncMgr when it has items to synchronize
UnregisterSyncMgrHandler | A handler calls this to indicate it no longer has an items to synchronize
GetHandlerRegistrationInfo | Called by the handler to obtain registration information.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.


ISyncMgrRegister::GetHandlerRegistrationInfo

The registered application's handler calls the ISyncMgrRegister::GetHandlerRegistrationInfo method to get current registration information.

HRESULT GetHandlerRegistrationInfo(
  REFCLSID rclsidHandler,
  LPDWORD pdwSyncMgrRegisterFlags
);

Parameters

rclsidHandler
[in] CLSID of the handler.
pdwSyncMgrRegisterFlags
[in,out] Returns registration flags.

Return Values

This method supports the standard return values E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY, as well as the following:

S_OK
Call was successful, the handler is registered.
S_FALSE
Call was not successful, the handler is not registered.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.


ISyncMgrRegister::RegisterSyncMgrHandler

A handler should call the ISyncMgrRegister::RegisterSyncMgrHandler method to register with the Synchronization Manager when it has items to synchronize.

HRESULT RegisterSyncMgrHandler(
  REFCLSID rclsid,
  WCHAR const *pwsDescription,
  DWORD dwReserved
);

Parameters

rclsid
[in] CLSID of the handler that should be registered to do synchronizations.
pwsDescription
[in] Text identifying the handler. This parameter may be NULL.
dwReserved
[in] Reserved for future use. Must be zero.

Return Values

This method supports the standard return values E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY, as well as the following:

S_OK
The handler was successfully registered.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.


ISyncMgrRegister::UnregisterSyncMgrHandler

The handler calls the ISyncMgrRegister::UnregisterSyncMgrHandler method to remove its CLSID from the registration. A handler should call this when it no longer has any items to synchronize.

HRESULT UnregisterSyncMgrHandler(
  REFCLSID rclsidHandler,
  DWORD dwReserved
);

Parameters

rclsidHandler
[in] CLSID of the handler that should be unregistered
dwReserved
[in] Reserved for future use. Must be zero.

Return Values

This method supports the standard return values E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY, as well as the following:

S_OK
The handler was successfully removed from the registry with SyncMgr.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.


ISyncMgrSynchronize

The ISyncMgrSynchronize interface enables the registered application or service to receive notifications from the Synchronization Manager.

When to Implement

This interface should be implemented on the registered application's handler to receive notifications from the SyncMgr and to participate in the synchronization process.

When to Use

The SyncMgr calls the methods of this interface to send notifications to the registered application or service during synchronization.

Methods in Vtable Order

IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

ISyncMgrSynchronize methods | Description
Initialize | Determines whether the registered application handles the synchronization event.
GetHandlerInfo | Called by SyncMgr to obtain handler information.
EnumSyncMgrItems | Called by SyncMgr to obtain the enumeration interface for the items maintained by the registered application.
GetItemObject | Called by SyncMgr to obtain an interface on the requested server's Items.
ShowProperties | Called by SyncMgr when the item is selected in the Choice dialog box and the user clicks the Properties button.
SetProgressCallback | Called by SyncMgr to set the ISyncMgrSynchronizeCallback interface.
PrepareForSync | Called by SyncMgr to give the registered application a chance to show any user interface and do any necessary initialization before calling the Synchronize method.
Synchronize | Called by SyncMgr once for each selected group after the user has selected applications for synchronization.
SetItemStatus | Called by SyncMgr to set the status of an item being synchronized.
ShowError | Called by SyncMgr to set an error status for the item being synchronized.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

ISyncMgrEnumItems, ISyncMgrSynchronizeCallback, ISyncMgrSynchronizeInvoke


ISyncMgrSynchronize::EnumSyncMgrItems

This method obtains the ISyncMgrEnumItems interface for the items handled by the registered application.

HRESULT EnumSyncMgrItems(
  ISyncMgrEnumItems **ppSyncMgrEnumItems  // Address of ISyncMgrEnumItems
                                          //  pointer
);

Parameters

ppSyncMgrEnumItems
[out] Address of variable that receives a pointer to a valid ISyncMgrEnumItems interface.

Return Values

This method supports the standard return values, E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY, as well as the following:

S_OK
The enumeration interface was successfully returned.
S_SYNCMGR_MISSINGITEMS
The enumeration interface object is successfully returned but some items are missing. When this success code is returned SyncMgr does not remove any stored preferences for ItemIds that were not returned in the enumerator.

Remarks

The enumeration object created by this method implements the ISyncMgrEnumItems interface, a standard enumeration interfaces that contains the Next, Reset, Clone, and Skip methods.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

ISyncMgrEnumItems


ISyncMgrSynchronize::GetHandlerInfo

The ISyncMgrSynchronize::GetHandlerInfo method obtains handler information.

HRESULT GetHandlerInfo(
  LPSYNCMGRHANDLERINFO *ppSyncMgrHandlerInfo  // SYNCMGRHANDLERINFO structure
);

Parameters

ppSyncMgrHandlerInfo
[out] Returns a pointer to a SYNCMGRHANDLERINFO structure.

Return Values

This method supports the standard return values, E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY, as well as the following:

S_OK
Handler information was returned successfully.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

SYNCMGRHANDLERINFO


ISyncMgrSynchronize::GetItemObject

The ISyncMgrSynchronize::GetItemObject method obtains an interface on a specified item handled by the registered application.

HRESULT GetItemObject(
  REFSYNCMGRITEMID ItemID,  // Identifies the requested item
  REFIID riid,              // Identifies the requested interface
  void **ppv                // Address of variable containing the requested
                            //  interface pointer
);

Parameters

ItemID
[in] Identifier for the requested item.
riid
[in] Identifier for the requested interface.
ppv
[out] Address of a variable that receives a pointer to the requested interface.

Return Values

E_NOTIMPL
The requested interface was not found.

Remarks

This method is for future use. There are currently no interfaces defined on an Item. Application implementers must return E_NOTIMPL from this method.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.


ISyncMgrSynchronize::Initialize

The Synchronization Manager calls the ISyncMgrSynchronize::Initialize method in the registered application's handler to determine whether the handler will process the synchronization event.

HRESULT Initialize(
  DWORD dwReserved,         // Reserved
  DWORD dwSyncMgrFlags,     // SYNCMGRFLAG enumeration
  DWORD cbCookie,           // Size of lpCookie
  BYTE const *lpCookie      // Token identifying application
);

Parameters

dwReserved
[in] Reserved; must be zero.
dwSyncMgrFlags
[in] Specifies the SYNCMGRFLAG enumeration values that describe how the synchronization event was initiated.
cbCookie
[in] Specifies the size in bytes of the lpCookie data.
lpCookie
[in] Points to the token identifying the application. This token was passed when the application programmatically invoked SyncMgr.

Return Values

This method supports the standard return values, E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY, as well as the following:

S_OK
Initialization was successful.
S_FALSE
Application handler will not process the synchronize event.

Remarks

The SYNCMGRFLAG enumeration values apply through the lifetime of the ISyncMgrSynchronize interface and are used by the other ISyncMgrSynchronize methods.

If the application does not recognize the SYNCMGRFLAG event, the application should treat the event as a manual synchronization.

The registered application's handler cannot display a user interface within this call unless it is the very first time the initialize method is called. The application is allowed to display any one-time initialization it needs to set up items and introduce the user to the application's feature. If you need to display a user interface for any other reason as part of the synchronization process, you can do so in the ISyncMgrSynchronize::PrepareForSync method.

lpCookie is NULL unless the handling application invoked the Synchronization Manager programmatically using ISyncMgrSynchronizeInvoke::UpdateItems. In this case the CLSID is that of the handling application and the value of lpCookie is passed in by the handling application and is passed back by SyncMgr during synchronization for context. lpCookie is only meaningful if SYNCMGRFLAG_INVOKE is set

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

ISyncMgrSynchronize::PrepareForSync, ISyncMgrSynchronizeInvoke::UpdateItems, SYNCMGRFLAG


ISyncMgrSynchronize::PrepareForSync

The ISyncMgrSynchronize::PrepareForSync method allows the registered application to display any user interface and perform any necessary initialization before the ISyncMgrSynchronize::Synchronize method is called. For example, an application such as the Microsoft® Outlook® e-mail client may need to display the password dialog box to enable the user to log onto the mail server.

HRESULT PrepareForSync(
  ULONG cbNumItems,           // Number of items in ItemId array
  SYNCMGRITEMID *pItemIDs,    // Array of ItemIds
  HWND hWndParent,            // Parent hWnd for user interface
  DWORD dwReserved            // Reserved
);

Parameters

cbNumItems
[in] Number of items in the ItemId array pointed to by pItemIDs.
pItemIDs
[in] Array of ItemIDs the user has chosen to synchronize.
hWndParent
[in] Handle to the parent hWnd that the registered application should use for any user interface element displayed. This value may be NULL.
dwReserved
[in] Reserved. Registered applications should ignore this value.

Return Values

This method supports the standard return values, E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY, as well as the following:

S_OK
Preparation was successful.

Remarks

The registered application's handler should return from this method as soon as possible and then call the ISyncMgrSynchronizeCallback::PrepareForSyncCompleted method. It is possible for the registered application's handler to call the ISyncMgrSynchronizeCallback::PrepareForSyncCompleted method before returning from this method.

Registered applications should only show a user interface if the SYNCMGRFLAG_MAYBOTHERUSER flag was set in the dwSyncFlags parameter of the ISyncMgrSynchronize::Initialize method. If a registered application cannot prepare for synchronization without showing a user interface when the SYNCMGRFLAG_MAYBOTHERUSER flag is not set it should return S_FALSE from this method.

The array of ItemIDs that are passed into this method are relevant to the ISyncMgrSynchronize::Synchronize method also.

The ISyncMgrSynchronizeCallback methods can be called on any thread in the registered application.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

ISyncMgrSynchronize::Synchronize, ISyncMgrSynchronize::Initialize , ISyncMgrSynchronizeCallback::PrepareForSyncCompleted, ISyncMgrSynchronizeCallback, SYNCMGRFLAG


ISyncMgrSynchronize::SetItemStatus

The Synchronization Manager calls the ISyncMgrSynchronize::SetItemStatus method in a registered application's handler to change the status of an item either between the time the handler has returned from the ISyncMgrSynchronize::PrepareForSync method and called the ISyncMgrSynchronizeCallback::PrepareForSyncCompleted callback method or after the handler has returned from the ISyncMgrSynchronize::Synchronize method but has not yet called the ISyncMgrSynchronizeCallback::SynchronizeCompleted callback method.

HRESULT SetItemStatus(
  REFSYNCMGRITEMID pItemID,    // Identifies the item with changed status
  DWORD dwSyncMgrStatus        // New status for item from SYNCMGRSTATUS
);

Parameters

pItemID
[in] Identifies the item with changed status.
dwSyncMgrStatus
[in] New status for the specified item taken from the SYNCMGRSTATUS enumeration.

Return Values

This method supports the standard return values, E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY, as well as the following:

S_OK
Status was set.

Remarks

Currently, the only SYNCMGRSTATUS status value supported by the SyncMgr is SYNCMGRSTATUS_SKIPPED. The registered application's handler should skip the item specified in pItemID when it receives this status value.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

ISyncMgrSynchronize::PrepareForSync, ISyncMgrSynchronize::SetProgressCallback, ISyncMgrSynchronize::Synchronize, ISyncMgrSynchronizeCallback::PrepareForSyncCompleted, ISyncMgrSynchronizeCallback::SynchronizeCompleted, SYNCMGRSTATUS


ISyncMgrSynchronize::SetProgressCallback

The ISyncMgrSynchronize::SetProgressCallback method sets the ISyncMgrSynchronizeCallback interface. Registered applications use this callback interface to give status information from within the ISyncMgrSynchronize::PrepareForSync and ISyncMgrSynchronize::Synchronize methods.

HRESULT SetProgressCallback(
  ISyncMgrSynchronizeCallback *pSyncCallBack  // Pointer to callback interface
);

Parameters

pSyncCallBack
[in] Pointer to ISyncMgrSynchronizeCallback interface the registered application uses to provide feedback to SyncMgr about the synchronization status and to notify SyncMgr when the synchronization is complete.

Return Values

This method supports the standard return values, E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY, as well as the following:

S_OK
Synchronization callback interface was successfully set.

Remarks

Registered applications must call the AddRef method in the ISyncMgrSynchronizeCallback interface and use it when calling SyncMgr to provide status text and progress indicator feedback.

If the registered application already has an ISyncMgrSynchronizeCallback interface when the method is called, the old interface must be released and the AddRef method of the new interface must be called. The new interface must be maintained by the registered application.

Before the ISyncMgrSynchronize interface is released, SyncMgr calls this method with the pSyncCallBack parameter set to NULL. The registered application should then release the pSyncCallback interface previously passed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

ISyncMgrSynchronizeCallback


ISyncMgrSynchronize::ShowError

The Synchronization Manager calls the ISyncMgrSynchronize::ShowError method in a registered application's handler when the user double-clicks on the associated message in the error tab.

HRESULT ShowError(
  HWND hWndParent,       // Parent hWnd for user interface
  DWORD dwErrorID        // Error identifier
);

Parameters

hWndParent
[in] Handle to the parent hWndt the registered application should use to display the user interface. This value may be NULL.
dwErrorID
[in] Error identifier associated with this error message. The ErrorID value is passed in the ISyncMgrSynchronizeCallback::LogError method.

Return Values

This method supports the standard return values, E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY, as well as the following:

S_OK
Call completed successfully.

Remarks

Handlers should return as soon as possible from this method and call the ISyncMgrSynchronizeCallback::ShowErrorCompleted method. It is acceptable for the handler to make a call to ISyncMgrSynchronizeCallback::ShowErrorCompleted before returning from this method. If a handler returns a failure code from this method, it should not call the ISyncMgrSynchronizeCallback::ShowErrorCompleted method.

Applications may display user interface elements in this method even if the SYNCMGRFLAG_MAYBOTHERUSER was not set in the dwSyncFlags parameter of the ISyncMgrSynchronize::Initialize method. Applications must still call ISyncMgrSynchronizeCallback::EnableModeless and check the return code before showing user interface.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

ISyncMgrSynchronizeCallback::EnableModeless, ISyncMgrSynchronizeCallback::LogError, ISyncMgrSynchronizeCallback::ShowErrorCompleted, ISyncMgrSynchronize::Initialize, SYNCMGRFLAG


ISyncMgrSynchronize::ShowProperties

The ISyncMgrSynchronize::ShowProperties method is called by the Synchronization Manager when the user selects an item in the choice dialog box and clicks the properties button.

HRESULT ShowProperties(
  HWND hWndParent,           // Parent hwnd for any dialog displayed
  REFSYNCMGRITEMID ItemID    // Specifies item requested
);

Parameters

hWndParent
[in] Specifies the parent hWnd for any user interface the registered application displays to set properties. This value may be NULL.
ItemID
[in] Identifies the item for which properties are requested.

Return Values

This method supports the standard return values, E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY, as well as the following:

S_OK
Properties dialog for this item was handled properly.

Remarks

If a registered application provides a properties dialog box for an item, it must set the SYNCMGRITEM_HASPROPERTIES bit in the dwFlags member of the SYNCMGRITEM structure.

If ItemID is GUID_NULL the handler should show the Properties dialog for the overall handler.

The appearance of the displayed dialog box should be consistent with a standard Property Page dialog box.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

SYNCMGRITEM, SYNCMGRITEMFLAGS


ISyncMgrSynchronize::Synchronize

The Synchronization Manager calls the ISyncMgrSynchronize::Synchronize method once for each selected group after the user has chosen the registered applications to be synchronized.

HRESULT Synchronize(
  HWND hWndParent     // Parent hwnd for user interface
);

Parameters

hWndParent
[in] Handle to the parent hWnd the registered application should use for any user interface elements that it displays. This value may be NULL.

Return Values

This method supports the standard return values, E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY, as well as the following:

S_OK
Synchronization was successful.
E_FAIL
Synchronization failed.

Remarks

If the user does not select any item choices for the registered application, the ISyncMgrSynchronize::Synchronize method is not called and the interface is released. If this method is called, the application must synchronize the items that were specified in the ISyncMgrSynchronize::PrepareForSync method.

The registered application's handler should return from the ISyncMgrSynchronize::Synchronize method as soon as possible and then call the ISyncMgrSynchronizeCallback::SynchronizeCompleted method. It is acceptable for the handler to call the ISyncMgrSynchronizeCallback::SynchronizeCompleted call before returning from the ISyncMgrSynchronize::Synchronize method.

The application must give progress feedback and check whether the synchronization should be canceled by using the pSyncCallBack interface pointer that was setup in the ISyncMgrSynchronize::SetProgressCallback method.

Applications must provide progress information even if the SYNCMGRFLAG_MAYBOTHERUSER was not specified in ISyncMgrSynchronize::Initialize.

Applications should attempt not to show user interface elements from within the ISyncMgrSynchronize::Synchronize method. Any user interface elements should be shown in the ISyncMgrSynchronize::PrepareForSync and ISyncMgrSynchronize::ShowError methods so the end user experiences a consistent user interface which is limited to logon and to specifying shares to be synchronized. Subsequently, the synchronization can be performed without any user intervention. After the synchronization is complete, conflicts or other error messages can be shown.

The ISyncMgrSynchronizeCallback methods can be called on any thread in your application.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

ISyncMgrSynchronize::Initialize, ISyncMgrSynchronize::PrepareForSync, ISyncMgrSynchronize::SetProgressCallback, ISyncMgrSynchronize::ShowError, ISyncMgrSynchronizeCallback::SynchronizeCompleted


ISyncMgrSynchronizeCallback

The ISyncMgrSynchronizeCallback interface manages the synchronization process.

When to Implement

This interface is implemented by the Synchronization Manager to receive status, error, and progress information and display the user interface during the synchronization process.

When to Use

Applications should call the methods of this interface as often as possible and must call it before starting each new ItemID to check whether the user has canceled an individual item.

Methods in Vtable Order

IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

ISyncMgrSynchronizeCallback methods | Description
Progress | Updates the progress information and determines if the operation should continue.
ShowPropertiesCompleted | Must by called by the handler before or after its ShowProperties method is complete.
PrepareForSyncCompleted | Must be called by the handler when its PrepareForSync method is complete.
SynchronizeCompleted | Must be called by the application when its Synchronize method is complete.
ShowErrorCompleted | Must be called by the handler before or after its PrepareForSync method is complete.
EnableModeless | Must be called by the application before and after any dialog boxes are displayed from within the PrepareForSync and Synchronize methods.
LogError | Called by the application to log an information, warning, or error message into the Error tab on the SyncMgr status dialog.
DeleteLogError | Called by the handler to delete a previously logged ErrorInformation, warning, or error message in the error tab on the SyncMgr status dialog box.
EstablishConnection | Called by the handler when it requires the system to establish a network connection.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

ISyncMgrSynchronize


ISyncMgrSynchronizeCallback::DeleteLogError

The registered application's handler calls the ISyncMgrSynchronizeCallback::DeleteLogError method to delete a previously logged ErrorInformation, warning, or error message in the error tab on the Synchronization Manager status dialog box.

HRESULT DeleteLogError(
  REFSYNCMGRERRORID ErrorID,
  DWORD dwReserved
);

Parameters

ErrorID
[in] Identifies LogError to be deleted. If ErrorID is GUID_NULL all errors logged by the instance of the registered application's handler will be deleted.
dwReserved
[in] Reserved for future use. Must be set to zero.

Return Values

This method supports the standard return values E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY, as well as the following:

S_OK
The item was successfully deleted from the log.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.


ISyncMgrSynchronizeCallback::EnableModeless

The registered application must call the ISyncMgrSynchronizeCallback::EnableModeless method before and after any dialog boxes are displayed from within the ISyncMgrSynchronize::PrepareForSync and ISyncMgrSynchronize::Synchronize methods.

HRESULT EnableModeless(
  BOOL fEnable
);

Parameters

fEnable
[in] TRUE if the registered application is requesting permission to display a dialog box or FALSE if the registered application has finished displaying a dialog box.

Return Values

S_OK
Continue the synchronization.
S_FALSE
The dialog box should not be displayed.

Remarks

To request permission to display a dialog box, the registered application first calls ISyncMgrSynchronize::EnableModeless with fEnable set to TRUE. If S_OK is returned, the registered application may display the dialog box. Once the dialog box has been displayed, the registered application must call ISyncMgrSynchronize::EnableModeless with fEnable set to FALSE to notify SyncMgr that other items may now display user interface elements.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

ISyncMgrSynchronize::PrepareForSync, ISyncMgrSynchronize::Synchronize


ISyncMgrSynchronizeCallback::EstablishConnection

The registered application's handler calls the ISyncMgrSynchronizeCallback::EstablishConnection method when a network connection is required.

HRESULT EstablishConnection(
  WCHAR const *lpwszConnection,
  DWORD dwReserved
);

Parameters

lpwszConnection
[in] Identifies the name of the connection to dial.
dwReserved
[in] Reserved for future use. Must be set to zero.

Return Values

This method supports the standard return values E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY, as well as the following:

S_OK
The connection was successfully established.

Remarks

SyncMgr should use the default autodial connection if lpwszConnection is NULL.

When an instance of EstablishConnection is called by a handler then SyncMgr tries to establish the connection. If a subsequent EstablishConnection is called then SyncMgr attempts the new connection without hanging up the previous connection. All connections remain until all handlers have finished synchronizing. After all handlers have synchronized, then any opened connections are closed by SyncMgr.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.


ISyncMgrSynchronizeCallback::LogError

The registered application calls the ISyncMgrSynchronizeCallback::LogError method by the to log an information, warning, or error message into the error tab on the Synchronization Manager status dialog box.

HRESULT LogError(
  DWORD dwErrorLevel,                    // Indicates the error level
  const WCHAR *lpcErrorText,             // Error text
  LPSYNCMGRLOGERRORINFO lpSyncLogError   // SYNCMGRLOGERRORINFO structure
);

Parameters

dwErrorLevel
[in] Indicates the error level. Values are taken from the SYNCMGRLOGLEVEL enumeration.
lpcErrorText
[in] Pointer to error text to be displayed in the Error tab.
lpSyncLogError
[in] Pointer to the SYNCMGRLOGERRORINFO structure containing additional error information. Registered applications that do not provide this data can pass NULL.

Return Values

This method supports the standard return values, E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY, as well as the following:

S_OK
The error information was successfully logged.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

SYNCMGRLOGLEVEL, SYNCMGRLOGERRORINFO


ISyncMgrSynchronizeCallback::PrepareForSyncCompleted

The registered application's handler must call the ISyncMgrSynchronizeCallback::PrepareForSyncCompleted method after the ISyncMgrSynchronize::PrepareForSync method has completed execution.

HRESULT PrepareForSyncCompleted(
  HRESULT hr          // HRESULT for the PrepareForSync method.
);

Parameters

hr
[in] Return value of the ISyncMgrSynchronize::PrepareForSync method. If S_OK is returned, SyncMgr calls ISyncMgrSynchronize::Synchronize for the item. If the HRESULT is set to anything other than S_OK, SyncMgr releases the handler without calling the ISyncMgrSynchronize::Synchronize method.

Return Values

S_OK
Call was completed successfully.

Remarks

A registered application's handler should return as soon as possible from the ISyncMgrSynchronize::PrepareForSync method and then call this method to notify the SyncMgr that the registered application is preparing for synchronization.

It is acceptable for the registered application's handler to call this method before returning from the ISyncMgrSynchronize::PrepareForSync method.

The registered application's handler should not call this method if the ISyncMgrSynchronize::PrepareForSync method returns any value other than S_OK.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

ISyncMgrSynchronize::PrepareForSync, ISyncMgrSynchronize::Synchronize


ISyncMgrSynchronizeCallback::Progress

The registered application calls the ISyncMgrSynchronizeCallback::Progress method to update the progress information and determine whether the operation should continue.

HRESULT Progress(
  REFSYNCMGRITEMID pItemID,                 // Item identifier
  LPSYNCMGRPROGRESSITEM lpSyncProgressItem  // SYNCMGRPROGRESSITEM structure
);

Parameters

pItemID
[in] Item identifier for the item being updated.
lpSyncProgressItem
[in] Pointer to a SYNCMGRPROGRESSITEM structure containing the updated progress information.

Return Values

S_OK
Continues the synchronization.
S_SYNCMGR_CANCELITEM
Cancel the synchronization on the specified ItemID as soon as possible.
S_SYNCMGR_CANCELALL
Cancel the synchronization on all items associated with this application as soon as possible.

Remarks

Registered applications should call this to provide normal feedback even when the SYNCMGRFLAG_MAYBOTHERUSER flag has been set.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

SYNCMGRFLAG, SYNCMGRPROGRESSITEM


ISyncMgrSynchronizeCallback::ShowErrorCompleted

The registered application's handler must call the ISyncMgrSynchronizeCallback::ShowErrorCompleted method before or after its ISyncMgrSynchronize::PrepareForSync operation has been completed.

HRESULT ShowErrorCompleted(
  HRESULT hrResult,
  ULONG cbNumItems,
  SYNCMGRITEMID *pItemIDs
);

Parameters

hrResult
[in] Indicates whether ISyncMgrSynchronize::ShowError was successful. This value is S_SYNCMGR_RETRYSYNC if the registered application's handler requires SyncMgr to retry the Synchronization. When this value is returned to SyncMgr both the ISyncMgrSynchronize::PrepareForSync and ISyncMgrSynchronize::Synchronize methods are called again.
cbNumItems
[in] Indicates the number of ItemIds in the pItemIDs parameter. This parameter is ignored unless hrResult is S_SYNCMGR_RETRYSYNC.
pItemIDs
[in] Pointer to array of ItemIds to pass to ISyncMgrSynchronize::PrepareForSync in the event of a retry. This parameter is ignored unless hrResult is S_SYNCMGR_RETRYSYNC.

Return Values

S_OK
The operation completed successfully.

Remarks

The pItemIDs is an [in] parameter and the calling function owns the memory pointed to by pItemIDs. SyncMgr makes a copy of the array before returning.

The registered application's handler should return from the ISyncMgrSynchronize::ShowError method as soon as possible and then call this method to notify SyncMgr that it has completed processing the ISyncMgrSynchronize::ShowError call.

It is acceptable for the registered application's handler to call this method before returning from the ISyncMgrSynchronize::ShowError method.

The registered application's handler should not call this method unless a success code is returned from the ISyncMgrSynchronize::Showerror method.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

ISyncMgrSynchronize::ShowError


ISyncMgrSynchronizeCallback::ShowPropertiesCompleted

The registered application's handler must call the ISyncMgrSynchronizeCallback::ShowPropertiesCompleted method before or after its ShowProperties operation is completed.

HRESULT ShowPropertiesCompleted(
  HRESULT hrResult
);

Parameters

hrResult
[in] indicates whether the ISyncMgrSynchronize::ShowProperties was successful.

Return Values

S_OK
Call was completed successfully.

Remarks

It is acceptable for the registered application's handler to call this method before returning from the ISyncMgrSynchronize::ShowProperties method.

This method should not be called if the registered application's handler does not return a success code from the ISyncMgrSynchronize::ShowProperties method.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

ISyncMgrSynchronize::ShowProperties


ISyncMgrSynchronizeCallback::SynchronizeCompleted

The application must call the ISyncMgrSynchronizeCallback::SynchronizeCompleted method when its ISyncMgrSynchronize::Synchronize method has completed execution.

HRESULT SynchronizeCompleted(
  HRESULT hr           // HRESULT from the ISyncMgrSynchronize::Synchronize method
);

Parameters

hr
[in] Returned result from the ISyncMgrSynchronize::Synchronize method.

Return Values

S_OK
Call was completed successfully.

Remarks

A registered application's handler should return from the ISyncMgrSynchronize::Synchronize method as soon as possible and then call this method to notify the SyncMgr that the synchronization process has completed.

It is acceptable for the registered application's handler to call this method before returning from the ISyncMgrSynchronize::Synchronize method.

The registered application's handler should not call this method if the ISyncMgrSynchronize::Synchronize method returns any value other than S_OK.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

ISyncMgrSynchronize::Synchronize


ISyncMgrSynchronizeInvoke

The ISyncMgrSynchronizeInvoke interface enables a registered application to invoke the Synchronization Manager to update items.

When to Implement

This interface is implemented by SyncMgr.

When to Use

A registered application calls the methods of this interface to update all items or to update specific items.

Methods in Vtable Order

IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

ISyncMgrSynchronizeInvoke methods | Description
UpdateItems | Updates the specified items.
UpdateAll | Updates all items.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.


ISyncMgrSynchronizeInvoke::UpdateAll

The ISyncMgrSynchronizeInvoke::UpdateAll method programmatically starts an update for all items.

HRESULT UpdateAll( );

Return Values

S_OK
Call was completed successfully.

Remarks

This method returns immediately and the Synchronization Manager performs the synchronizations in a separate process from the calling application.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.


ISyncMgrSynchronizeInvoke::UpdateItems

The ISyncMgrSynchronizeInvoke::UpdateItems method programmatically starts an update for the specified items.

HRESULT UpdateItems(
  DWORD dwInvokeFlags,    // Indicates how to invoke the item
  REFCLSID rclsid,        // CLSID of application that handles the update
  DWORD cbCookie,         // Size in bytes of lpCookie
  const BYTE *lpCookie    // Token of calling application
);

Parameters

dwInvokeFlags
[in] Specifies how item should be invoked using the SYNCMGRINVOKEFLAGS enumeration values.
rclsid
[in] CLSID of the registered application that should be invoked to handle the Update.
cbCookie
[in] Size in bytes of lpCookie data.
lpCookie
[in] Pointer to the private token that SyncMgr uses to identify the application. This token is passed in the ISyncMgrSynchronize::Initialize method.

Return Values

This method supports the standard return values, E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY, as well as the following:

S_OK
The synchronization was successfully updated.
E_FAIL
Errors occurred during the synchronization update.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

ISyncMgrSynchronize::Initialize, SYNCMGRINVOKEFLAGS


SYNCMGRFLAG

The SYNCMGRFLAG enumeration values are used in the ISyncMgrSynchronize::Initialize method to indicate how the synchronization event was initiated.

typedef enum _tagSYNCMGRFLAG
   SYNCMGRFLAG_CONNECT                = 0x0001,
   SYNCMGRFLAG_PENDINGDISCONNECT      = 0x0002,
   SYNCMGRFLAG_MANUAL                 = 0x0003,
   SYNCMGRFLAG_IDLE                   = 0x0004,
   SYNCMGRFLAG_INVOKE                 = 0x0005,
   SYNCMGRFLAG_SCHEDULED              = 0x0006,
   SYNCMGRFLAG_EVENTMASK              = 0x00FF,
   SYNCMGRFLAG_SETTINGS               = 0x0100,
   SYNCMGRFLAG_MAYBOTHERUSER          = 0x0200,
} SYNCMGRFLAG;

Elements

SYNCMGRFLAG_CONNECT
Synchronization was initiated by a network connect event.
SYNCMGRFLAG_PENDINGDISCONNECT
Synchronization was initiated by a pending network disconnect event.
SYNCMGRFLAG_MANUAL
Synchronization was initiated manually by the end user.
SYNCMGRFLAG_IDLE
Synchronization was programmatically invoked.
SYNCMGRFLAG_INVOKE
Synchronization was programmatically invoked.
SYNCMGRFLAG_SCHEDULED
Synchronization was initiated by a scheduled update event.
SYNCMGRFLAG_EVENTMASK
Synchronization mask value.
SYNCMGRFLAG_SETTINGS
Synchronization was initiated for configuration purposes only in the System Properties dialog box.
SYNCMGRFLAG_MAYBOTHERUSER
Interaction with the user is permitted. The application is allowed to show user interface elements and interact with the user. If this flag is not set, the application must not display any user interface elements other than using the ISynchronizeCallback interface. If an application cannot complete the synchronization without displaying user interface elements and this flag is not set, the application fails the synchronization.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

ISyncMgrSynchronize::Initialize


SYNCMGRHANDLERFLAGS

The SYNCMGRHANDLERFLAGS enumeration values are used in the SYNCMGRHANDLERINFO structure as flags that apply to the current handler.

typedef enum _tagSYNCMGRHANDLERFLAGS{
   SYNCMGRHANDLER_HASPROPERTIES   = 0x01,
} SYNCMGRHANDLERFLAGS;

Elements

SYNCMGRHANDLER_HASPROPERTIES
The current handler provides a Property Sheet dialog.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

SYNCMGRHANDLERINFO


SYNCMGRHANDLERINFO

The SYNCMGRHANDLERINFO structure provides information about the handler for use in the ISyncMgrSynchronize::GetHandlerInfo method.

typedef struct _tagSYNCMGRHANDLERINFO {
   DWORD    cbSize;
   HICON    hIcon;
   DWORD    SyncMgrHandlerFlags;
   WCHAR    wszHandlerName[MAX_SYNCMGRHANDLERNAME];
} SYNCMGRHANDLERINFO, *LPSYNCMGRHANDLERINFO;

Members

cbSize
Size of the structure in bytes.
hIcon
Icon for the handler
SyncMgrHandlerFlags
Value of the SYNCMGRHANDLERFLAGS enumeration.
wszHandlerName[MAX_SYNCMGRHANDLERNAME]
Name to use for the handler.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

ISyncMgrSynchronize::GetHandlerInfo, SYNCMGRHANDLERFLAGS


SYNCMGRINVOKEFLAGS

The SYNCMGRINVOKEFLAGS enumeration value specifies how the SyncMgr is to be invoked in the ISyncMgrSynchronizeInvoke::UpdateItems method.

typedef enum _tagSYNCMGRINVOKEFLAGS {
   SYNCMGRINVOKE_STARTSYNC    = 0x02,
   SYNCMGRINVOKE_MINIMIZED    = 0x04,
} SYNCMGRINVOKEFLAGS;

Elements

SYNCMGRINVOKE_STARTSYNC
Immediately start the synchronization without displaying the Choice dialog box.
SYNCMGRINVOKE_MINIMIZED
The Choice dialog should be minimized by default.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

ISyncMgrSynchronizeInvoke::UpdateItems


SYNCMGRITEM

The SYNCMGRITEM structure provides information on the next item being enumerated in the ISyncMgrEnumItems interface.

typedef struct _tagSYNCMGRITEM {
   DWORD          cbSize;
   DWORD          dwFlags;
   SYNCMGRITEMID  ItemID;
   DWORD          dwItemState;
   HICON          hIcon;
   WCHAR          wszItemName[MAX_SYNCMGRITEMNAME];
   WCHAR          wszStatus[MAX_SYNCMGRITEMSTATUS];
} SYNCMGRITEM, *LPSYNCMGRITEM;

Members

cbSize
Size of the structure.
dwFlags
Value of the SYNCMGRITEMFLAGS enumeration.
ItemID
Identifier of the next item.
dwItemState
State of the next item.
hIcon
Icon for the handler for the next item.
wszItemName[MAX_SYNCMGRITEMNAME]
Item name.
wszStatus[MAX_SYNCMGRITEMSTATUS]
Item status.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

SYNCMGRITEMFLAGS


SYNCMGRITEMFLAGS

The SYNCMGRITEMFLAGS enumeration value specifies information for the current item in the SYNCMGRITEM structure.

typedef enum _tagSYNCMGRITEMFLAGS {
   SYNCMGRITEM_HASPROPERTIES  = 0x01,
   SYNCMGRITEM_TEMPORARY      = 0x02,
   SYNCMGRITEM_ROAMINGUSER    = 0x04,
} SYNCMGRITEMFLAGS;

Elements

SYNCMGRITEM_HASPROPERTIES
The item has a properties dialog.
SYNCMGRITEM_TEMPORARY
The item is temporary and any stored preferences can be removed.
SYNCMGRITEM_ROAMINGUSER
The item roams with the user and is not specific to a machine.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

SYNCMGRITEM


SYNCMGRLOGERRORINFO

The SYNCMGRLOGERRORINFO structure provides error information for use in the ISyncMgrSynchronizeCallback::LogError method.

typedef struct _tagSYNCMGRLOGERRORINFO {
   DWORD            cbSize;
   DWORD            mask;
   DWORD            dwErrorID;
   SYNCMGRITEMID    ItemID;
} SYNCMGRLOGERRORINFO, *LPSYNCMGRLOGERRORINFO;

Members

cbSize
Size of the structure.
mask
Mask value.
dwErrorID
Error identifier
ItemID
Item in which the error occurred.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

ISyncMgrSynchronizeCallback::LogError


SYNCMGRLOGLEVEL

The SYNCMGRLOGLEVEL enumeration values specifies an error level for use in the ISyncMgrSynchronizeCallback::LogError method.

typedef enum _tagSYNCMGRLOGLEVEL {
   SYNCMGRLOGLEVEL_INFORMATION   = 0x0001,
   SYNCMGRLOGLEVEL_WARNING       = 0x0002,
   SYNCMGRLOGLEVEL_ERROR         = 0x0003,
} SYNCMGRLOGLEVEL;

Elements

SYNCMGRLOGLEVEL_INFORMATION
An information message was logged.
SYNCMGRLOGLEVEL_WARNING
A warning message was logged.
SYNCMGRLOGLEVEL_ERROR
An error message was logged.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

ISyncMgrSynchronizeCallback::LogError


SYNCMGRPROGRESSITEM

The SYNCMGRPROGRESSITEM structure provides status information for the progress dialog for use in the ISyncMgrSynchronizeCallback::Progress method.

typedef struct _tagSYNCMGRPROGRESSITEM {
   DWORD          cbSize;
   UINT           mask;
   const WCHAR*   lpcStatusText;
   DWORD          dwStatusType;
   INT            iProgValue;
   INT            iMaxValue;
} SYNCMGRPROGRESSITEM, *LPSYNCMGRPROGRESSITEM;

Members

cbSize
Size of the structure in bytes.
mask
Mask value.
lpcStatusText
Status text.
dwStatusType
Status type.
iProgValue
Integer indicating the progress value.
iMaxValue
Integer indicating the maximum progress value.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

ISyncMgrSynchronizeCallback::Progress


SYNCMGRSTATUS

The SYNCMGRSTATUS enumeration values are used in the ISyncMgrSynchronize::SetItemStatus method to specify the updated status for the item.

typedef enum _tagSYNCMGRSTATUS {
   SYNCMGRSTATUS_STOPPED     = 0x0000,
   SYNCMGRSTATUS_SKIPPED     = 0x0001,
   SYNCMGRSTATUS_PENDING     = 0x0002,
   SYNCMGRSTATUS_UPDATING    = 0x0003,
   SYNCMGRSTATUS_SUCCEEDED   = 0x0004,
   SYNCMGRSTATUS_FAILED      = 0x0005,
   SYNCMGRSTATUS_PAUSED      = 0x0006,
   SYNCMGRSTATUS_RESUMING    = 0x0007,
} SYNCMGRSTATUS;

Elements

SYNCMGRSTATUS_STOPPED
Synchronization has been stopped.
SYNCMGRSTATUS_SKIPPED
This item should be skipped.
SYNCMGRSTATUS_PENDING
Synchronization for the item is pending.
SYNCMGRSTATUS_UPDATING
The item is currently being synchronized.
SYNCMGRSTATUS_SUCCEEDED
The synchronization for the item succeeded.
SYNCMGRSTATUS_FAILED
The synchronization for the item failed.
SYNCMGRSTATUS_PAUSED
The synchronization for the item paused.
SYNCMGRSTATUS_RESUMING
The synchronization for the item is resuming.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Mobsync.h.

See Also

ISyncMgrSynchronize::SetItemStatus


System Event Notification Service

Purpose

Applications designed for use by mobile users require a unique set of connectivity functions and notifications. In the past these individual applications were required to implement these features internally. The System Event Notification Service (SENS) now provides these capabilities in the operating system, creating a uniform connectivity and notification interface for applications. Using SENS developers can determine connection bandwidth and latency information from within their application and optimize the application's operation based on those conditions.

Where Applicable

The connectivity functions and notifications of SENS are useful for applications written for mobile computers or computers connected to high latency local area networks.

Developer Audience

This document is intended for software developers who develop applications for mobile computing and high latency local area networks. This document provides a complete reference of all parts of the System Event Notification Service including the SENS object and supporting methods.

Run-time Requirements

Requires Microsoft® Windows® 2000.

See Also

IEventSubscription

Synchronization Manager

Overview

General information about System Event Notification Service.

Reference

Documentation of System Event Notification Service methods and interfaces.

Feedback

Make error reports and feature requests directly to Microsoft.


System Event Notification Service

The System Event Notification Service (SENS) creates a uniform connectivity and notification interface for applications designed for mobile use.

For more information, About System Event Notification Service provides an overview, and SENS Reference lists methods and interfaces used for SENS.


About System Event Notification Service

Applications designed for use by mobile users require a unique set of connectivity functions and notifications, and in the past individual applications were required to implement these features internally. The System Event Notification Service (SENS) now provides these capabilities in the operating system, creating a uniform connectivity and notification interface for applications. SENS, the Synchronization Manager, and Client Side Caching combine to provide the infrastructure to fully support mobile computing.

The topics in this section offer an overview about SENS:

  • Mobile Computing Configurations for SENS

    Lists several mobile computer configurations that can benefit from the use of SENS-enabled applications.

  • Application Scenarios for SENS

    Lists several types of applications that can benefit by utilizing SENS functionality.

  • Notifications

    Lists the system events that SENS monitors and dispatches.

  • SENS Architecture

    A description of the internal architecture of SENS.


Mobile Computing Configurations for SENS

Connectivity functions and notifications are useful for computers configured as follows:

  • A mobile computer used in a docking station on a high bandwidth network which may occasionally use a dial-in connection.
  • A mobile computer using a dial-in connection exclusively.
  • A desktop computer using a dial-in connection exclusively.
  • A desktop computer connected to a high bandwidth network with latency issues.

In each of these configurations, the connection bandwidth and latency information can be used by an application to dynamically optimize its operations for network availability.


Application Scenarios for SENS

Several types of applications can utilize the connectivity functions and notification services that the System Event Notification Service offers:

  • An application that requires network connectivity status, such as an application that utilizes directory services.
  • An application that adapts its operations depending on the level of connectivity and the quality of network services, such as an Internet browser application that functions at a reduced level on a low bandwidth connection.
  • An application that can perform deferred operations such as an e-mail program that can queue messages while offline and send them when a connection is established.


Notifications

The System Event Notification Service enables mobile-aware applications to receive notifications from system events that SENS monitors. When the requested event occurs, SENS notifies the application.

SENS can notify applications about three classes of system events:

  • TCP/IP network events, such as the status of a TCP/IP network connection or the quality of the connection.
  • User logon events.
  • Battery and AC power events.

For example, an application can subscribe to any of the following system events:

  • Establishment of network connectivity
  • Notification when a specified destination can be reached within specified Quality of Connection (QOC) parameters
  • The computer has switched to battery power
  • The percentage of remaining battery power is within a specified parameter
  • Scheduled events using Synchronization Manager occur


SENS Architecture

The System Event Notification Service works with the COM+ Event System. SENS is an event publisher for the classes of events that it monitors: network, logon, and power/battery events. The application receiving a notification is called an event subscriber.

When an application subscribes to receive notifications, it can also specify filters associated with the subscribed events. SENS and COM+ Events use the filters to further determine when the application should be notified.

Notifications are asynchronous, so the application receiving the notification does not have to be active when the notification is sent. When an application subscribes to receive notifications, it can specify whether it should be activated when the event occurs or notified later when it is active.

The subscription can be transient and valid only until the application stops running, or it can be persistent and valid until the application is removed from the system.

A COM+ Events data store contains information about the event publisher (SENS), event subscribers, and filters. During setup when you install or upgrade to Microsoft® Windows® 2000, SENS adds itself to the COM+ Events data store and provides information on the classes of events that it monitors using a GUID for each class of events. SENS also predefines an outgoing interface for each event class in a type library.

Event Class | GUID | Interface
Network events | SENSGUID_EVENTCLASS_NETWORK | ISensNetwork
Logon events | SENSGUID_EVENTCLASS_LOGON | ISensLogon
Power events | SENSGUID_EVENTCLASS_ONNOW | ISensOnNow

To receive notifications for any of these events, your application must do two things:

  • Subscribe to the SENS events that interest you. To subscribe to an event, use the IEventSubscription and IEventSystem interfaces in COM+ Events. You need to supply an identifier for the event classes and the SENS publisher identifier, SENSGUID_PUBLISHER. Subscriptions are on a per event level so the subscribing application must also specify which events within the class are of interest. Each event corresponds to a method in the interface corresponding to its event class.

    Note Programmers using SENS on the Internet Explorer 5 platform should use only the IEventSubscription and IEventSystem COM+ Events interfaces.

  • Create a sink object with an implementation for each interface that you handle. See ISensNetwork, ISensLogon, and ISensOnNow for more information about these interfaces and the events supported in each one.

When one of the monitored events occurs, SENS processes each subscription with any associated filters and notifies the subscribers through the COM+ Event system.


SENS Reference

This section lists the following methods for the System Event Notification Service (SENS):

  • IsDestinationReachable
  • IsNetworkAlive

The following interfaces are supported by the SENS object:

  • ISensLogon
  • ISensNetwork
  • ISensOnNow


IsDestinationReachable

Determines if the specified destination can be reached and provides Quality of Connection (QOC) information for the destination.

BOOL IsDestinationReachable(
  LPCSTR lpszDestination,    // Pointer to string specifying destination
  LPQOCINFO lpQOCInfo        // Pointer to Quality of Connection information
);

Parameters

lpszDestination
Pointer to a string that specifies the destination. The destination can be an IP address, a UNC name, or an URL.
lpQOCInfo
Pointer to the QOCINFO structure that receives the Quality of Connection (QOC) information. You can supply a NULL pointer if the QOC information is not desired.

Return Values

TRUE
The destination can be reached.
FALSE
Call GetLastError to determine the reason why the destination cannot be reached.

Remarks

This function is used by client applications to determine the QOC information before proceeding with network operations. For standalone computers that are directly connected to the network through a network card or remote access server (RAS), this function generates minimal network traffic with RPC calls to the nearest router. For computers that are part of a network where the destination can be reached using RAS or a network gateway, this function pings to the destination to generate accurate QOC information.

Notes This function is only available for TCP/IP connections.

The caller supplies the buffer for the QOCINFO structure and must release this memory when it is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Sensapi.h.
Library: Use Sensapi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

IsNetworkAlive, QOCINFO, About System Event Notification Service


QOCINFO

The QOCINFO structure is returned by the IsDestinationReachable function and provides Quality of Connection information to the caller.

typedef struct tagQOCINFO {
   DWORD     dwSize;
   DWORD     dwFlags;
   DWORD     dwInSpeed;
   DWORD     dwOutSpeed;
} QOCINFO, *LPQOCINFO;

Members

dwSize
Upon calling the IsDestinationReachable function, the caller supplies the size of the QOC structure in this member. On return from the function, this member contains the actual size of the structure that was filled in.
dwFlags
Provides information on the type of network connection available. The flags can be:
Flag | Hexadecimal | Description
NETWORK_ALIVE_LAN | 0x00000001 | The computer has one or more active LAN cards.
NETWORK_ALIVE_WAN | 0x00000002 | The computer has one or more active RAS connections.
NETWORK_ALIVE_AOL | 0x00000004 | This flag is only valid in Windows 95 and Windows 98. The computer is connected to the America Online network.

dwInSpeed
Speed of data coming in from the destination in bytes per second.
dwOutSpeed
Speed of data sent to the destination in bytes per second.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).

See Also

IsDestinationReachable


IsNetworkAlive

Determines whether the local system is connected to a network and the type of network connection, for example, LAN, WAN, or both.

Bool IsNetworkAlive(
  LPDWORD lpdwFlags     // Specifies the type of network connection
);

Parameters

lpdwFlags
Provides information on the type of network connection available when the return value is TRUE. The flags can be:
NETWORK_ALIVE_LAN
The computer has one or more LAN cards that are active.
NETWORK_ALIVE_WAN
The computer has one or more active RAS connections.
NETWORK_ALIVE_AOL
This flag is only valid in Windows 95 and Windows 98. Indicates the computer is connected to the America Online network.

Return Values

TRUE
The local system is connected to a network.
FALSE
Call GetLastError to determine the reason for no connectivity.

Remarks

This function can be used by applications to determine whether there is network connectivity before proceeding with network operations. Applications such as directory service applications, e-mail clients, or Internet browsers can adapt to various types of network connectivity. For example, a printing operation can be deferred until the network connection is available.

Note This function is only available for TCP/IP connections.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Sensapi.h.
Library: Use Sensapi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

IsDestinationReachable, About System Event Notification Service


SENS Object

The System Event Notification Service (SENS) defines the SENS coclass as part of the SENS type library.

Implementation

The SENS object implementation is provided by the operating system.

Creation/Access Functions

Function | Description
CoCreateInstance | Creates an instance of the SENS object using its CLSID.

Interfaces

Inteface | Description
IsensNetwork | Default. Outgoing interface implemented by sink object in subscriber application.
IsensOnNow | Outgoing interface implemented by sink object in subscriber application.
IsensLogon | Outgoing interface implemented by sink object in subscriber application.

See Also

ISensLogon, ISensNetwork, ISensOnNow, About System Event Notification Service


ISensLogon

The ISensLogon interface handles logon events fired by SENS.

When to Implement

Implement this interface on your sink object if you subscribe to any of the SENS logon events. Each event corresponds to a method in this interface. This interface is an outgoing interface defined by SENS and implemented by the subscriber application as a dispatch interface.

When to Use

SENS and the COM Event System call the ISensLogon methods on your sink object to fire the corresponding event.

Methods in Vtable Order

Iunknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

Idispatch methods | Description
GetTypeInfoCount | Retrieves the number of type descriptions.
GetTypeInfo | Retrieves a description of the object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

ISenslLogon methods | Description
Logon | A user has logged on.
Logoff | A user has logged off.
StartShell | Shell has been started.
DisplayLock | Screen display has been locked.
DisplayUnlock | Screen display has been unlocked.
StartScreenSaver | Screen saver has been started.
StopScreenSaver | Screen saver has been stopped.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Sensevts.h.
Library: Use Sensevts.tlb.

See Also

ISensNetwork, ISensOnNow, About System Event Notification Service


ISensLogon::Logon

A user has logged on.

HRESULT Logon(
  BSTR bstrUserName    // User name
);

Parameters

bstrUserName
[in] Name of the user who logged on.

Dispatch Identifier

[id(0x00000001)]

Return Values

S_OK
Method returned successfully.

Remarks

SENS calls this method to notify your application that a user has now logged on.

Filtering

Filtering is not currently supported for this event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Sensevts.h.
Library: Use Sensevts.tlb.

See Also

ISensLogon::Logoff, About System Event Notification Service, IEventSubscription, IEventSubscription::PutPublisherProperty


ISensLogon::Logoff

A user has logged off.

HRESULT Logoff(
  BSTR bstrUserName    // User name
);

Parameters

bstrUserName
[in] Name of the user who logged off.

Dispatch Identifier

[id(0x00000002)]

Return Values

S_OK
Method returned successfully.

Remarks

SENS calls this method to notify your application that a user has logged off.

Filtering

Filtering is not currently supported for this event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Sensevts.h.
Library: Use Sensevts.tlb.

See Also

ISensLogon::Logon, About System Event Notification Service, IEventSubscription, IEventSubscription::PutPublisherProperty


ISensLogon::StartShell

Shell has been started.

HRESULT StartShell(
  BSTR bstrUserName    // User name
);

Parameters

bstrUserName
[in] Name of the current user.

Dispatch Identifier

[id(0x00000004)]

Return Values

S_OK
Method returned successfully.

Remarks

SENS calls this method to notify your application that the shell has been started.

Filtering

Filtering is not currently supported for this event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Sensevts.h.
Library: Use Sensevts.tlb.

See Also

About System Event Notification Service, IEventSubscription, IEventSubscription::PutPublisherProperty


ISensLogon::DisplayLock

Screen display has been locked.

HRESULT DisplayLock(
  BSTR bstrUserName    // User name
);

Parameters

bstrUserName
[in] Name of the current user.

Dispatch Identifier

[id(0x00000006)]

Return Values

S_OK
Method returned successfully.

Remarks

SENS calls this method to notify your application that the screen display has been locked.

Filtering

Filtering is not currently supported for this event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Sensevts.h.
Library: Use Sensevts.tlb.

See Also

ISensLogon::DisplayUnLock, ISensLogon::StartScreenSaver, ISensLogon::StopScreenSaver, About System Event Notification Service, IEventSubscription, IEventSubscription::PutPublisherProperty


ISensLogon::DisplayUnLock

Screen display has been unlocked.

HRESULT DisplayUnLock(
  BSTR bstrUserName    // User name
);

Parameters

bstrUserName
[in] Name of the current user.

Dispatch Identifier

[id(0x00000007)]

Return Values

S_OK
Method returned successfully.

Remarks

SENS calls this method to notify your application that the screen display has been unlocked.

Filtering

Filtering is not currently supported for this event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Sensevts.h.
Library: Use Sensevts.tlb.

See Also

ISensLogon::DisplayLock, ISensLogon::StartScreenSaver, ISensLogon::StopScreenSaver, About System Event Notification Service, IEventSubscription, IEventSubscription::PutPublisherProperty


ISensLogon::StartScreenSaver

Screen saver has been started.

HRESULT StartScreenSaver(
  BSTR bstrUserName    // User name
);

Parameters

bstrUserName
[in] Name of the current user.

Dispatch Identifier

[id(0x00000008)]

Return Values

S_OK
Method returned successfully.

Remarks

SENS calls this method to notify your application that the screen saver has been started.

Filtering

Filtering is not currently supported for this event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Sensevts.h.
Library: Use Sensevts.tlb.

See Also

ISensLogon::DisplayLock, ISensLogon::DisplayUnLock, ISensLogon::StopScreenSaver, About System Event Notification Service, IEventSubscription, IEventSubscription::PutPublisherProperty


ISensLogon::StopScreenSaver

Screen saver has been stopped.

HRESULT StopScreenSaver(
  BSTR bstrUserName    // User name
);

Parameters

bstrUserName
[in] Name of the current user.

Dispatch Identifier

[id(0x00000009)]

Return Values

S_OK
Method returned successfully.

Remarks

SENS calls this method to notify your application that the screen saver has been stopped.

Filtering

Filtering is not currently supported for this event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Sensevts.h.
Library: Use Sensevts.tlb.

See Also

ISensLogon::DisplayLock, ISensLogon::DisplayUnLock, ISensLogon::StartScreenSaver, About System Event Notification Service, IEventSubscription, IEventSubscription::PutPublisherProperty


ISensNetwork

The ISensNetwork interface handles network events fired by the System Event Notification Service (SENS).

When to Implement

Implement this interface on your sink object if you subscribe to any of the SENS network events. Each event corresponds to a method in this interface. This interface is an outgoing interface defined by SENS and implemented by the subscriber application as a dispatch interface.

When to Use

SENS and the COM Event System call the ISensNetwork methods on your sink object to fire the corresponding event.

Methods in Vtable Order

IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch methods | Description
GetTypeInfoCount | Retrieves the number of type descriptions.
GetTypeInfo | Retrieves a description of the object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

ISensNetwork methods | Description
ConnectionMade | Specified connection has been established.
ConnectionMadeNoQOCInfo | Specified connection has been established with no Quality of Connection information available.
ConnectionLost | Specified connection has been dropped.
DestinationReachable | Specified connection can be reached.
DestinationReachableNoQOCInfo | Specified connection can be reached with no Quality of Connection information.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Sensevts.h.
Library: Use Sensevts.tlb.

See Also

ISensLogon, ISensOnNow, About System Event Notification Service


ISensNetwork::ConnectionMade

Specified connection has been established.

HRESULT ConnectionMade(
  BSTR bstrConnection,       // Connection name
  ULONG ulType,              // Connection type
  LPSENS_QOCINFO lpQOCInfo   // Pointer to Quality of Connection information
);

Parameters

bstrConnection
[in] Name of the connection. For WAN connections, the connection name is the name of the phone book entry; for LAN connections, it is the name of the network card.
ulType
[in] Connection type. This value can be CONNECTION_LAN or CONNECTION_WAN.
lpQOCInfo
[out] Pointer to the SENS_QOCINFO structure which contains Quality of Connection information.

Dispatch Identifier

[id(0x00000001)]

Return Values

S_OK
Method returned successfully.

Remarks

SENS calls this method to notify your application that the specified connection has been established. SENS also provides a pointer to a structure containing Quality of Connection information.

type
Connection type. Use 0 for LAN or 1 for WAN.

Note This function is only available for TCP/IP connections.

Filtering

Filtering can be performed on the publisher property ulConnectionMadeType by setting it to either CONNECTION_LAN or CONNECTION_WAN or both. Use IEventSubscription::PutPublisherProperty to set the publisher property.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Sensevts.h.
Library: Use Sensevts.tlb.

See Also

ISensNetwork::ConnectionMadeNoQOCInfo, SENS_QOCINFO, About System Event Notification Service, IEventSubscription, IEventSubscription::PutPublisherProperty


ISensNetwork::ConnectionMadeNoQOCInfo

Specified connection has been established with no Quality of Connection information available.

HRESULT ConnectionMadeNoQOCInfo(
  BSTR bstrConnection,     // Connection name
  ULONG ulType             // Connection type
);

Parameters

bstrConnection
[in] Name of the connection. For WAN connections, the connection name is the name of the phone book entry; for LAN connections, it is the name of the network card.
ulType
[in] Connection type. This value can be CONNECTION_LAN or CONNECTION_WAN.

Dispatch Identifier

[id(0x00000002)]

Return Values

S_OK
Method returned successfully.

Remarks

SENS calls this method to notify your application that the specified connection has been established when Quality of Connection information is not available.

type
Connection type. Use 0 for LAN or 1 for WAN.

Note This function is only available for TCP/IP connections.

Filtering

Filtering can be performed on the publisher property ulConnectionMadeTypeNoQOC by setting it to either CONNECTION_LAN or CONNECTION_WAN or both. Use IEventSubscription::PutPublisherProperty to set the publisher property.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Sensevts.h.
Library: Use Sensevts.tlb.

See Also

ISensNetwork::ConnectionMade, About System Event Notification Service, IEventSubscription, IEventSubscription::PutPublisherProperty


ISensNetwork::ConnectionLost

Specified connection has been dropped.

HRESULT ConnectionLost(
  BSTR bstrConnection,    // Connection name
  ULONG ulType            // Connection type
);

Parameters

bstrConnection
[in] Name of the connection. For WAN connections, the connection name is the name of the phone book entry; for LAN connections, it is the name of the network card.
ulType
[in] Connection type. This value can be CONNECTION_LAN or CONNECTION_WAN.

Dispatch Identifier

[id(0x00000003)]

Return Values

S_OK
Method returned successfully.

Remarks

SENS calls this method to notify your application that the specified connection has been dropped.

type
Connection type. Use 0 for LAN or 1 for WAN.

Note This function is only available for TCP/IP connections.

Filtering

Filtering can be performed on the publisher property ulConnectionLostType by setting it to either CONNECTION_LAN or CONNECTION_WAN or both. Use IEventSubscription::PutPublisherProperty to set the publisher property.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Sensevts.h.
Library: Use Sensevts.tlb.

See Also

About System Event Notification Service, IEventSubscription, IEventSubscription::PutPublisherProperty


ISensNetwork::DestinationReachable

Specified connection can be reached.

HRESULT DestinationReachable(
  BSTR bstrDestination,        // Destination name
  BSTR bstrConnection,         // Connection name
  ULONG ulType,                // Connection type
  LPSENS_QOCINFO lpQOCInfo     // Quality of Connection information
);

Parameters

bstrDestination
[in] Name of the destination. Can be an IP address, a URL, a UNC, or a NetBIOS name.
bstrConnection
[in] Name of the connection. For WAN connections, the connection name is the name of the phone book entry; for LAN connections, it is the name of the network card.
ulType
[in] Connection type. This value can be CONNECTION_LAN or CONNECTION_WAN.
lpQOCInfo
[out] Pointer to the SENS_QOCINFO structure which contains Quality of Connection information.

Dispatch Identifier

[id(0x00000004)]

Return Values

S_OK
Method returned successfully.

Remarks

SENS calls this method to notify your application that the specified destination can be reached. A pointer to a structure containing Quality of Connection information is also provided.

Note This function is only available for TCP/IP connections.

Filtering

Filtering can be performed on the publisher property bstrDestination. To determine reachability, set bstrDestination to the name of desired destination. Filtering can also be performed on the property ulType by setting it to either CONNECTION_LAN or CONNECTION_WAN, or both. Use IEventSubscription::PutPublisherProperty to set the publisher property. Note: if a bstrDestination property is not specified, the DestinationReachable event is returned for all destinations.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Sensevts.h.
Library: Use Sensevts.tlb.

See Also

ISensNetwork::DestinationReachableNoQOCInfo, SENS_QOCINFO, About System Event Notification Service, IEventSubscription, IEventSubscription::PutPublisherProperty


ISensNetwork::DestinationReachableNoQOCInfo

Specified connection can be reached with no Quality of Connection information.

HRESULT DestinationReachableNoQOCInfo(
  BSTR bstrDestination,    // Destination name
  BSTR bstrConnection,     // Connection name
  ULONG ulType             // Connection type
);

Parameters

bstrDestination
[in] Name of the destination. Can be an IP address, a URL, a UNC, or a NetBIOS name.
bstrConnection
[in] Name of the connection. For WAN connections, the connection name is the name of the phone book entry; for LAN connections, it is the name of the network card.
ulType
[in] Connection type. This value can be CONNECTION_LAN or CONNECTION_WAN.

Dispatch Identifier

[id(0x00000005)]

Return Values

S_OK
Method returned successfully.

Remarks

SENS calls this method to notify your application that the specified destination can be reached when Quality of Connection information is not available.

Note This function is only available for TCP/IP connections.

Filtering

Filtering can be performed on the publisher property bstrDestinationNoQOC. To determine reachability, set bstrDestinationNoQOC to the name of desired destination. Filtering can also be performed on the property ulDestinationTypeNoQOC by setting it to either CONNECTION_LAN or CONNECTION_WAN, or both. Use IEventSubscription::PutPublisherProperty to set the publisher property. Note: if a bstrDestinationNoQOC property is not specified, the DestinationReachableNoQOC() event is returned for all destinations.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).
Header: Declared in Sensevts.h.
Library: Use Sensevts.tlb.

See Also

ISensNetwork::DestinationReachable, About System Event Notification Service, IEventSubscription, IEventSubscription::PutPublisherProperty


SENS_QOCINFO

The SENS_QOCINFO structure is provided by the ISensNetwork::ConnectionMade method and the ISensNetwork::DestinationReachable method. This structure contains Quality of Connection information to the sink object in an application that subscribes to SENS.

typedef struct _SENS_QOCINFO {
  DWORD dwSize;
  DWORD dwFlags;
  DWORD dwOutSpeed;
  DWORD dwInSpeed;
} SENS_QOCINFO;

Members

dwSize
This member contains the actual size of the structure that was filled in.
dwFlags
Speed of connection. Flag bits indicate whether the connection is slow, medium, fast.
dwOutSpeed
Speed of data sent to the destination in bits per second.
dwInSpeed
Speed of data coming in from the destination in bits per second.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later (or Windows NT 4.0 with Internet Explorer 5 or later).
Windows 95/98/Me: Requires Windows 95 or later (with Internet Explorer 5 or later).

See Also

ISensNetwork::ConnectionMade, ISensNetwork::DestinationReachable, About System Event Notification Service, IEventSubscription, IEventSubscription::PutPublisherProperty


ISensOnNow

The ISensOnNow interface handles AC and battery power events fired by the System Event Notification Service (SENS).

When to Implement

Implement this interface on your sink object if you subscribe to any of the SENS power events. Each event corresponds to a method in this interface. This interface is an outgoing interface defined by SENS and implemented by the subscriber application as a dispatch interface.

When to Use

SENS and the COM Event System call the ISensOnNow methods on your sink object to fire the corresponding event.

Methods in Vtable Order

IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch methods | Description
GetTypeInfoCount | Retrieves the number of type descriptions.
GetTypeInfo | Retrieves a description of the object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

ISensOnNow methods | Description
OnACPower | Switched to AC power.
OnBatteryPower | Switched to Battery power.
BatteryLow | Battery power is low.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Sensevts.h.
Library: Use Sensevts.tlb.

See Also

ISensLogon, ISensNetwork, About System Event Notification Service


ISensOnNow::OnACPower

SENS calls this method to notify your application that the computer is using AC power.

HRESULT OnACPower(void);

Dispatch Identifier

[id(0x00000001)]

Return Values

S_OK
Method returned successfully.

Remarks

SENS calls this method to notify your application that AC power has been activated.

Filtering

Filtering is not currently supported for this event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Sensevts.h.
Library: Use Sensevts.tlb.

See Also

ISensOnNow::OnBatteryPower, About System Event Notification Service, IEventSubscription, IEventSubscription::PutPublisherProperty


ISensOnNow::OnBatteryPower

SENS calls this method to notify your application that the computer is using battery power.

HRESULT OnBatteryPower(
  DWORD dwBatteryLifePercent    // Percent of battery power remaining
);

Parameters

dwBatteryLifePercent
[in] Specifies the percent of battery power remaining.

Dispatch Identifier

[id(0x00000002)]

Return Values

S_OK
Method returned successfully.

Remarks

SENS calls this method to notify your application that the computer is using battery power. The remaining percentage of battery power is specified.

Filtering

Filtering is not currently supported for this event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Sensevts.h.
Library: Use Sensevts.tlb.

See Also

ISensOnNow::BatteryLow, ISensOnNow::OnACPower, About System Event Notification Service, IEventSubscription, IEventSubscription::PutPublisherProperty


ISensOnNow::BatteryLow

Battery power is low.

HRESULT BatteryLow(
  DWORD dwBatteryLifePercent    // Percent of battery power remaining
);

Parameters

dwBatteryLifePercent
[in] Specifies the percent of battery power remaining.

Dispatch Identifier

[id(0x00000003)]

Return Values

S_OK
Method returned successfully.

Remarks

SENS calls this method to notify your application that the computer is using battery power. The remaining percentage of battery power is specified.

Filtering

Filtering is not currently supported for this event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Sensevts.h.
Library: Use Sensevts.tlb.

See Also

ISensOnNow::OnBatteryPower, About System Event Notification Service, IEventSubscription, IEventSubscription::PutPublisherProperty


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.