IMAPIFormAdviseSink::OnActivateNext

The IMAPIFormAdviseSink::OnActivateNext method indicates whether or not the form can handle the message class of the next message to display.

Quick Info

See IMAPIFormAdviseSink : IUnknown.

HRESULT OnActivateNext(
  LPCSTR lpszMessageClass,                 
  ULONG ulMessageStatus,                   
  ULONG ulMessageFlags,                    
  LPPERSISTMESSAGE FAR * ppPersistMessage  
);
 

Parameters

lpszMessageClass

[in] Pointer to the message class of the next message.

ulMessageStatus

[in] Bitmask of client-defined or provider-defined flags — copied from the PR_MSG_STATUS property of the next message to display — that provides status information relating to the contents table in which it is included.

ulMessageFlags

[in] Pointer to a bitmask of flags — copied from the PR_MESSAGE_FLAGS property of the next message to display — that indicates the current state of the message.

ppPersistMessage

[out] Pointer to a pointer to the IPersistMessage implementation for the form object used for the new form, if a new form is required. A pointer to NULL can be returned if the current form object can be used to display and save the next message.

Return Values

S_OK

The notification was successful and the form can handle the next message.

S_FALSE

The form does not handle the message class of the next message.

Remarks

Form viewers call the IMAPIFormAdviseSink::OnActivateNext method to help the form determine whether it is capable of displaying the next message in a folder. The next message could be a message of any class, but typically it is of the same class or a related class. This makes the process of reading multiple messages of the same class more efficient by allowing client applications to reuse form objects whenever possible.

Most form objects will use the message class pointed to by lpszMessageClass to determine whether or not they can handle the next message. Usually a form can handle messages that belong to classes of which the form's default class is a subclass as well as messages that belong to the default class. However, a form can use other factors to determine without question whether or not a message can be handled, such as the sent or unsent status of the next message.

Notes to Implementers

Return S_OK and NULL in the ppPersistMessage parameter if your form can handle the message class. If your form can create a new form that can handle the message that your form is unable to handle, perform the following tasks:

1. Call your form's class factory to create an instance of a new form object.
2. Store that instance in the contents of the ppPersistMessage pointer parameter.
3. Return S_OK.

The message will be loaded by the form viewer using the IPersistMessage::Load method belonging to the object pointed to by ppPersistMessage.

If neither your form nor a form that you can create can handle the next message, return S_FALSE. MAPI discourages forms from returning this value because it results in degraded performance in the form viewer.

See Also

IPersistMessage::Load