IExchExtAdvancedCriteria::QueryRestriction

Returns a restriction object and a text version of the restriction.

Quick Info

See IExchExtAdvancedCriteria : IUnknown.

HRESULT QueryRestriction(
  LPVOID lpvAllocBase,                 
  LPSRestriction FAR * lppres,         
  LPSPropTagArray FAR * lppPropTags,   
  LPMAPINAMEID FAR * FAR * lppPropNames,   
  BOOL * lpfNot,                       
  LPTSTR lpszDesc,                     
  ULONG cchDesc,                       
  ULONG ulFlags                        
);
 

Parameters

lpvAllocBase

[in] Pointer to the memory allocation base to be used when allocating memory for the restriction data. For more information on allocating memory, see Managing Memory in the MAPI Programmer's Reference.

lppres

[out] Pointer to where to return a pointer to the advanced criteria restriction.

lppPropTags

[out] Pointer to where to return a pointer to a MAPI property tag array containing the property tags of any named properties involved in the restriction. This parameter is used by Microsoft Exchange to find property tags which need to be remapped should the restriction be applied to a different store.

lppPropNames

[out] Pointer to where to return an array of MAPI property NAMEID structures that define the properties whose tags are given in the lppPropTags parameter. This value is used by Microsoft Exchange to obtain the appropriate new property tags should the restriction be applied to a different store.

lpfNot

[out] Pointer to a variable that returns TRUE if the user only wants messages that do not meet the criteria specified in the structure pointed to by the lpres parameter.

lpszDesc

[out] Pointer to a buffer which the extension should fill with a string containing a text description of the restriction.

cchDesc

[in] Maximum length of the lpszDesc parameter.

ulFlags

[in] Bitmask of flags. The following flag can be set:

EXCHEXT_UNICODE

Microsoft Exchange sets the ulFlags parameter to this value if it wants the extension to fill the lpszDesc parameter with a Unicode string.

Remarks

Microsoft Exchange calls the IExchExtAdvancedCriteria::QueryRestriction method when the criteria which the user has specified must be instantiated as a restriction. For example, when the user closes the Advanced dialog box, Microsoft Exchange prompts the extension object to return the current restriction. The restriction is a MAPI construct specifying a query. Memory for the returned restriction object must be allocated with the MAPIAllocateMore function using the pvAllocBase parameter as the base. QueryRestriction can be called zero, one, or multiple times depending on the context and the user's choices.

The text version this method returns is a user-readable representation of the query that the user composed in the Advanced dialog box. The format of the text version depends on the complexity of the criteria. For example, it could be a description in plain text English or in SQL language.

If no restriction is defined, the function should return S_OK with a null restriction in lppres. If EXCHEXT_S_NOCRITERIA is returned, the operation will be stopped. Extensions can selectively install themselves in different contexts in the Exchange client, such as: EECONTEXT_TASK, EECONTEXT_VIEWER, etc. By installing in a particular context, the extension needs to instantiate a new set of interface objects, such as IExchExtCommands, to handle the methods in that particular object. For example, if an extension is installed into EECONTEXT_VIEWER and EECONTEXT_SENDNOTEMESSAGE, it needs to remember which commands it has installed into which context so that it can respond to the IExchExtCommands::DoCommand method.