MDAC 2.5 SDK - OLE DB Programmer's Reference
Chapter 20: OLE DB Core Components
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.
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.
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.
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.
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).
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);
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);
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);
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.
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.)
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.
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).