IPropertyPage::SetObjects

Provides the IUnknown pointers of the objects affected by the property sheet in which this property page is displayed. When the property page receives a call to IPropertyPage::Apply, it must send value changes to these objects through whatever interfaces are appropriate. The property page must query for those interfaces. This method can fail if the objects do not support the interfaces expected by the property page.

HRESULT SetObjects(
  ULONG cObjects ,  //Number of IUnknown pointers in the ppUnk array
  IUnknown **ppUnk  //Pointer to array
);

Parameters

cObjects: [in] Number of IUnknown pointers in the array pointed to by ppUnk. If zero, the property page must release any pointers previously passed to this method.
ppUnk: [in] Pointer to an array of IUnknown interface pointers where each pointer identifies a unique object affected by the property sheet in which this (and possibly other) property pages are displayed. The property page must cache these pointers calling IUnknown::AddRef for each pointer at that time. This array of pointers is the same one that was passed to OleCreatePropertyFrame or OleCreatePropertyFrameIndirect to invoke the property sheet.

Return Values

This method supports the standard return values E_FAIL, E_INVALIDARG,

E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK: The property page successfully saved the pointers it needed.
E_NOINTERFACE: One of the objects in ppUnk did not support the interface expected by this property page, and so this property page cannot communicate with it.
E_POINTER: The address in ppUnk is not valid. For example, it may be NULL.

Remarks

The property page is required to keep the pointers returned by this method or others queried through them. If these specific IUnknown pointers are held, the property page must call IUnknown::AddRef through each when caching them, until the time when IPropertyPage::SetObjects is called with cObjects equal to zero. At that time, the property page must call IUnknown::Release through each pointer, releasing any objects that it held.

The caller must provide the property page with these objects before calling IPropertyPage::Activate, and should call IPropertyPage::SetObjects with zero as the parameter when deactivating the page or when releasing the object entirely. Each call to SetObjects with a non-NULL ppUnk parameter must be matched with a later call to SetObjects with zero in the cObjects parameter.

Notes to Implementers

E_NOTIMPL is not a valid return value.

QuickInfo

  Windows NT: Use version 4.0 or later.
  Windows: Use Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in ocidl.h.