API Reference | developer.brewmp.com API Reference | developer.brewmp.com

Developer

API Reference

ISETTINGS_ONCHANGE()

Brew Release
Brew MP 1.0.2
See Also
Description
This method provides allows the caller to register for notifications when settings are added, removed, or changed. The caller provides an ISignal object they create to ISettings which is set when the associated setting or settings subtree is changed.
This method returns a registration object the caller must keep track of for the lifetime of the ISignal object that it creates to be notified. To stop a particular notification, the application need only release the associated registration object.
Params
_me
[]:
[in] A pointer to the ISettings object.
key
[]:
[in] The NULL-terminated name of the setting or settings subtree that the caller wishes to observe.
signal
[]:
[in] The ISignal object used to notifiy the caller when the setting or subtree identified by key is modified.
reg
[]:
[out] On successful setup, a registration object is returned to the caller in this parameter. The notification will be removed when all references to this object have been released.
Interface
Prototype
  •    int ISettings_OnChange(ISettings *_me, 
                              const char *key, 
                              ISignal *signal,
                              IQI **reg);
    
Return
  • AEE_SUCCESS : On success. AEE_EBADITEM : The requested setting or settings subtree does not exist. AEE_EUNSUPPORTED : The operation isn't supported by the implementation. AEE_EPRIVLEVEL : The caller does not have sufficient privileges for this operation. Error code : Otherwise.
Side Effect
  • None
Comments
Components that wish to be notified when a particular setting or settings subtree changes must first create an ISignal object and pass it to ISettings_OnChange() to set up the notification. For example: nErr = ISHELL_CreateInstance(piShell, AEECLSID_SignalCBFactory, (void **)&piSignalCBFactory); if (AEE_SUCCESS == nErr) { nErr = ISignalCBFactory_CreateSignal(piSignalCBFactory, MySignalCB, (void *)me, &piSignal, &me->pISignalCtl); if (AEE_SUCCESS == nErr) { nErr = ISettings_OnChange((ISettings *)piSettings, pszKey, piSignal, &me->piReg); } } // don't need these anymore if (piSignal != NULL) { ISignal_Release(piSignal); piSignal = NULL; } if (piSignalCBFactory != NULL) { ISignalCBFactory_Release(piSignalCBFactory); piSignalCBFactory = NULL; } Note that the application needs to keep track of the ISignalCtl that it created as well as the registration object returned from the call. The application must then implement the callback routine that is to be invoked when ISettings changes the specified setting: // Callback fired when a setting changes static void MySignalCB(void *pCx) { MyApp *me = (MyApp *)pCx; // Do my thing ... // re-enable the Signal I gave to ISettings to hear if this // setting changes again ... ISignalCtl_Enable(pCtx->piSignalCtl); } To clean up after registering for change notifications, or to stop listening for a particular change notification, the application must release the ISignalCtl and the registration object used in the initial setup of the notification: ISignalCtl_Detach(me->piSignalCtl); ISignalCtl_Release(me->piSignalCtl); IQI_Release(me->piReg);