Pre-Updates and Post-Updates

Some callback methods are called twice for each server event, once to inquire if the extension will allow the event to complete, and again to notify the extension that the event has completed. These callback methods include a PostUpdate parameter.

If the PostUpdate parameter is False (zero), it is a "pre-update" notification of intent to perform the action. If the notification is for a property change, the property value is still in its unaltered state. If it is for a protocol message, the associated action has not taken place. During the pre-update notification, the extension can modify the property value or cancel the event. It can also perform other relevant operations, such as updating its internal state.

Some server events do not produce pre-update notifications. In addition, pre-update notifications are not sent by remote servers. (For more information, see Multiple Server Event Distribution.)

The second invocation is a "post-update" confirmation that the server event has finished. During this call, the PostUpdate parameter is True (not zero). If the notification is for a property change, the new value is passed in, but changes to the property value are ignored. Since a lower priority extension could cancel the intent of any pre-update notification, it is possible that some server events will start but not complete. Therefore, extensions should only create event bindings during post-update calls.

The following C++ example binds to the channel's OnChannelText event during the post-update call:

// Notification of new channel
STDMETHODIMP CMessageFilter::OnNewChannel(
    IChatChannel *pChannel, VARIANT_BOOL varbPostUpdate,
    long *pCancel) 
{
    if( varbPostUpdate == VARIANT_TRUE ) {
        // if post-update, bind to OnChannelText event
        m_pRegistrar->AddChannelEvent(
            (_bstr_t)L"OnChannelText",
            pChannel, pCancel);
    }

    *pCancel = 0;    // don't cancel the event
    return S_OK;
}

The Cancel parameter is ignored during post-update callbacks.

© 1998 Microsoft Corporation. All rights reserved.