IMAPIFormAdviseSink::OnActivateNext

Article
05/31/2022

Applies to: Outlook 2013 | Outlook 2016

Indicates whether the form can handle the message class of the next message to display.

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

Parameters

lpszMessageClass

[in] A pointer to the message class of the next message.

ulMessageStatus

[in] A bitmask of client-defined or provider-defined flags, copied from the PR_MSG_STATUS (PidTagMessageStatus) property of the next message to display, that provides status information regarding the contents table that the message is included in.

ulMessageFlags

[in] A pointer to a bitmask of flags copied from the PR_MESSAGE_FLAGS (PidTagMessageFlags) property of the next message to display that indicates the current state of the message.

ppPersistMessage

[out] A 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 value

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 can display 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 enabling client applications to reuse form objects whenever possible.

Most form objects will use the message class pointed to by the lpszMessageClass parameter to determine whether 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, in addition to messages that belong to the default class. However, a form can use other factors to determine without question whether 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 the form can handle the message class. If the form can create a new form that can handle the message that the form is unable to handle, follow these steps:

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

The form viewer will load the message by using the IPersistMessage::Load method that belongs to the object pointed to by ppPersistMessage.

If neither the form nor a form that you can create can handle the next message, return S_FALSE. However, in general, forms should not return this value because it causes decreased performance in the form viewer.

MFCMAPI reference

For MFCMAPI sample code, see the following table.

File	Function	Comment
MAPIFormFunctions.cpp	CMyMAPIFormViewer::ActivateNext	MFCMAPI uses the IMAPIFormAdviseSink::OnActivateNext method to implement the IMAPIViewContext::ActivateNext method.

Share via