Interfaces Implemented by the Provider

  • Article

The interfaces on the provider should be implemented within the provider's data source object. This object will need to be created in-process because the property sheet interfaces expect in-process operation.

Only the methods used by the Data Link core component are listed below. It is left to the provider whether to implement any of the other methods of the interface, but the Data Link core component will not use them.

IServiceProvider

IServiceProvider::QueryService

QueryService is used by the Data Link core component to determine whether the provider supports extensible user interface. Since it is possible that a provider has already implemented property pages for another container, the Data Link core component also uses QueryService to determine whether the provider's pages were implemented for the Data Link core component in particular.

HRESULT QueryService(
   _Guid      guidService,
   _Guid      riid,
   Object[]   ppvObject);

Parameters

  • guidService
    [in] The constant OLEDB_SVC_DSLPropertyPages will be passed to the QueryService method, guidService parameter. This is the GUID for the Data Source Locator property pages.

  • riid
    [in] The unique identifier of the interface the caller wishes to receive for the service.

  • ppvObject
    [out] Address of pointer variable that receives the interface pointer requested in riid. Upon successful return, *ppvObject contains a pointer to the requested interface.

ISpecifyPropertyPages

ISpecifyPropertyPages::GetPages

Fills a counted array of GUID values, where each GUID specifies the CLSID of each property page that can be displayed in the property sheet for this object.

GetPages is called by the Data Link core component to get an array of exactly two CLSIDs that represent the extensible property pages: the first to replace the Connection tab, and the second to replace the Advanced tab. These pages must be registered properly so that they can be cocreated by the Data Link core component in-process. If an entry in the array is set to GUID_NULL, that page is not overloaded and the corresponding default Data Link page is used.

HRESULT GetPages(
   CAUUID *   pPages);

Parameters

  • pPages
    [out] Pointer to a caller-allocated CAUUID structure that must be initialized and filled before returning. The pElems field in the CAUUID structure is allocated by the callee with CoTaskMemAlloc and freed by the caller with CoTaskMemFree.

IPropertyPage

IPropertyPage::SetPageSite

Initializes a property page and provides the page with a pointer to the IPropertyPageSite interface through which the property page communicates with the property frame.

The SetPageSite method is used by the Data Link core component to give the property page a reference to the Data Link core component IPropertyPageSite implementation.

To unload the provider's user interface, the Data Link core component calls SetPageSite with a null pointer.

HRESULT SetPageSite(
   IPropertyPageSite *   pPageSite);

Parameters

  • pPageSite
    [in] Pointer to the IPropertyPageSite interface of the page site that manages and provides services to this property page within the entire property sheet.

IPropertyPage::Activate

Creates the dialog box window for the property page.

Activate is used by the Data Link core component to request that the provider page is displayed (including window creation, and so forth). All provider pages will be requested as modal dialogs.

HRESULT Activate(
   HWND      hWndParent,
   LPCRECT   prc,
   BOOL      bModal);

Parameters

  • hWndParent
    [in] Window handle of the parent of the dialog box that is being created.

  • prc
    [in] Pointer to the RECT structure containing the positioning information for the dialog box. This method must create its dialog box with the placement and dimensions described by this rectangle ? that is, origin point at (prc->left, prc->top) and dimensions of (prc->right-prc->Left, prc->bottom-prc->top).

  • bModal
    [in] Indicates whether the dialog box frame is modal (TRUE) or modeless (FALSE).

IPropertyPage::Deactivate

Destroys the window created with Activate.

Deactivate is used by the Data Link core component to request that the provider page be destroyed. Property sheets are supposed to destroy property pages that are not in use, so whenever the user changes providers via the Providers tab, the Data Link core component will request that the provider destroy its page.

HRESULT Deactivate(void);

IPropertyPage::IsPageDirty

Indicates whether the property page has changed since activated or since the most recent call to Apply.

IsPageDirty is used by the Data Link core component to determine whether the user has made any changes to the provider property sheet. If so, the Data Link core component will make a second request to the provider to have the changes applied to the sheet.

HRESULT IsPageDirty(void);

IPropertyPage::Apply

Applies current property page values to underlying objects.

When the Data Link user interface has received an Apply button hit message or when the user changes pages in the property sheet, the Data Link core component will ask the active page whether there are pending changes. If so, it will call the Apply method. The provider should then write only the changes using the Data Link core component IPropertyBag implementation.

HRESULT Apply(void);

IPropertyPage::TranslateAccelerator

Provides a pointer to an MSG structure that specifies a keystroke to process.

This method is consumed by the Data Link user interface so that the Data Link core component, upon receiving a keystroke it doesn't handle, can pass the keystroke on to the active property page for processing.

HRESULT TranslateAccelerator(
   LPMSG   pMsg);

Parameters

  • pMsg
    [in] Pointer to the MSG structure describing the keystroke to process.

IPropertyPage::Help

Invokes help in response to end-user request.

This is a notification to the provider that a user has requested help for the current tab page. The provider is responsible for invoking context-sensitive help for its own pages.

HRESULT Help(
   LPCOLESTR *   pszHelpDir);

Parameters

  • pszHelpDir
    [in] Pointer to the string under the HelpDir key in the property page's CLSID information in the registry. If HelpDir does not exist, this will be the path found in the InProcServer32 entry minus the server file name. (LocalServer32 is not checked in the current implementation because local property pages are not currently supported.)

IPersistPropertyBag

IPersistPropertyBag::Load

Called by the container to load the control's properties.

After activating a provider page to be displayed, the Data Link core component will subsequently call the provider's Load method, passing in the Data Link core component implementation of IPropertyBag. This is to be used by the provider to populate the controls on the page being activated.

HRESULT Load(
   IPropertyBag *   pPropBag,
   IErrorLog *      pErrorLog);

Parameters

  • pPropBag
    [in] Pointer to the caller's IPropertyBag interface bag that the control uses to read its properties. Cannot be NULL.

  • pErrorLog
    [in] Currently unused. Will always be set to NULL.

IPersistPropertyBag::Save

Called by the container to save the object's properties.

If the Data Link core component determines that the page is dirty from the IsPageDirty call, it will subsequently call the provider's Save method. The provider is then to use the IPropertyBag passed in to save changes. The Data Link core component will always pass in True for the fClearDirty flag and False for the fSaveAllProperties flag.

HRESULT Save(
   IPropertyBag *   pPropBag,
   BOOL            fClearDirty,
   BOOL            fSaveAllProperties);

  • pPropBag
    [in] Pointer to the caller's IPropertyBag interface through which the object can write properties. Cannot be NULL.

  • fClearDirty
    [in] A flag indicating whether the object should clear its dirty flag when saving is complete. TRUE means clear the flag, and FALSE means leave the flag unaffected. FALSE is used when the caller wishes to do a Save Copy As type of operation.

  • fSaveAllProperties
    [in] A flag indicating whether the object should save all its properties (TRUE) or only those that have changed since the last save or initialization (FALSE).