LazyMAPI

unit: MAPIRestriction.pas
file path: ..\Library\Helpers
version: 2014.хх
uses Windows, ExtendedMAPI, Contnrs;

 

A restriction is a way to limit the number of rows in a view to only those rows with values for columns that match specific criteria. There are many different opportunities for using restrictions with tables. Client applications can use restrictions, for example, to filter a contents table for messages sent by a particular person, to search for rows that either do not support a property or have set a property to a specific value, or to look for duplicate recipients within a message.

Type
   TRestrictionType = (resAND, resOR, resNOT, resCONTENT, resPROPERTY, resCOMPAREPROPS, resBITMASK, resSIZE, resEXIST, resSUBRESTRICTION);

Value

Type of restriction

MAPI structure

TRestriction subclass

resAND

AND

_SAndRestriction

TRestrictionAnd

resAND  - Performs a logical AND operation on two or more restrictions.

resOR

OR

_SOrRestriction

TRestrictionOr

  - Performs a logical OR operation on two or more restrictions.

resNOT

NOT

_SNotRestriction

TRestrictionNot

resNOT  - Performs a logical NOT operation on two or more restrictions.

resCONTENT

Content

_SContentRestriction

TRestrictionContent

resCONTENT  - Locates specified data.

resPROPERTY

Property

_SPropertyRestriction

TRestrictionProperty

resPROPERTY - Specifies a particular property value as criteria for matching. Can be used, for example, to search for a particular type of attachment.

resCOMPAREPROPS

Compare MAPI property

_SComparePropsRestriction

TRestrictionCompare

resCOMPAREPROPS  - Compares two properties of the same type.

resBITMASK

Bitmask

_SBitMaskRestriction

TRestrictionBitMask

resBITMASK  - Applies a bitmask to a PT_LONG property, typically to determine if particular flags are set.

reSize

Size

_SSizeRestriction

TRestrictionSize

reSize - Tests the size of a property using standard relational operators.

resEXIST

Exist

_SExistRestriction

TRestrictionExist

resEXIST - Tests whether or not an object has a value for a property.

resSUBRESTRICTION

SubObject

 

_SSubRestriction

TRestrictionSub

resSUBRESTRICTION - Used for searching through subobjects, or objects that cannot be accessed with an entry identifier (recipients and attachments). Can be used, for example, to look for messages for a particular recipient.


TRestrictionRelation = (prLess, prLessEqual, prGreater, prGreaterEqual, prEqual, prNotEqual, prLike);

Value

Meaning

prLess

The comparison is made based on a lesser first value.

prLessEqual

The comparison is made based on a lesser or equal first value.

prGreater

The comparison is made based on a greater first value.

prGreaterEqual

The comparison is made based on a greater or equal first value.

prEqual

The comparison is made based on equal values.

prNotEqual

The comparison is made based on unequal values.

prLike

The comparison is made based on LIKE (regular expression) values. Not supported.



TSubjRestriction = (rsRecipient, rsAttachment);

Value

Meaning

rsRecipient

Apply the restriction to a message's recipient table.

rsAttachment

Apply the restriction to a message's attachment table.

Procedures

function GetMAPIRestriction(const Restriction: TRestriction; BasePoint: Pointer): PSRestriction;

Converts Delphi TRestriction class to native MAPI _SRestriction pointer

TRestriction - the base class for restriction objects.

Do not create instances of TRestriction. Use a descendant of TRestriction, such as TRestrictionContent.

Unit: MAPIRestriction.pas
Type: Class
Inherited from: TObject

Properties

Name Access Type Description
ResType RO TRestrictionType Type of restriction

Methods

Name Description
Apply Applies a filter to a table, reducing the row set to only those rows matching the specified criteria
ResetTable Discard the current table restriction without creating a new one.

Top


TRestrictionAnd = class(TRestriction)

Description – TRestrictionAnd implements an AND restriction, which is used to join a group of restrictions using a logical AND operation.

Unit: MAPIRestriction.pas
Type: Class
Inherited from: TRestriction

Properties

Name Access Type Description
Count RO Integer Count of joined restrictions

Methods

Name Description
Add Add a new TRestriction.

function Add(const ResType: TRestrictionType): TRestriction; overload;
function Add(const Restriction: TRestriction): Integer; overload;
Remove Delete an existing TRestriction.

function Remove(const Restriction: TRestriction): Integer;

usage


Example: Restrict Folder Content Table to messages where Message Subject exists and Message Subject contains phrase “test me”

 

Restriction:= TRestrictionAnd.Create(FContentTable);

try

  With Restriction.Add(resEXIST) do

PropTag:= PR_SUBJECT;

 

 

  With Restriction.Add(resCONTENT) do

  begin

PropTag:= PR_SUBJECT;

SubString:=True;

IgnoreCase:=True;

Value:=’test me’;

  end;


  Restriction.Apply;

 

finally

FreeAndNil(Restriction);

End;

Top


TRestrictionOr = class(TRestriction)

Description – TRestrictionOr implements an OR restriction, which is used to join a group of restrictions using a logical OR operation.

Unit: MAPIRestriction.pas
Type: Class
Inherited from: TRestriction

Properties

Name Access Type Description
Count RO Integer Count of joined restrictions

Methods

Name Description
Add Add a new TRestriction.

function Add(const ResType: TRestrictionType): TRestriction; overload;
function Add(const Restriction: TRestriction): Integer; overload;
Remove Delete an existing TRestriction.

function Remove(const Restriction: TRestriction): Integer;

usage


Example: Restrict Folder Content Table to messages where Message is Unread OR Message Size is => 2048 bytes.

 

Restriction:= TRestrictionOr.Create(FContentTable);

Try

      With Restriction.Add(resBITMASK) do

      Begin

            PropTag:= PR_MESSAGE_FLAGS;

            EqualToZero:=True;

            Mask:= MSGFLAG_READ;   

      End;

 

With Restriction.Add(resPROPERTY) do

      Begin

            PropTag:= PR_MESSAGE_SIZE;

            Relation:= prGreaterEqual;

            Value:= 2048;   

      End;

 

Restriction.Apply;

 

Finally

      FreeAndNil(Restriction);

           End;

 

Top


TRestrictionNot = class(TRestriction)

Description – TRestrictionNot implements a NOT restriction, which is used to apply a logical NOT operation to a restriction.

Unit: MAPIRestriction.pas
Type: Class
Inherited from: TRestriction

Properties

Name Access Type Description
Restriction RO TRestriction TRestriction, which is used to apply a logical NOT operation.

Methods

Name Description
Add Add a new TRestriction.

function Add(const ResType: TRestrictionType): TRestriction; overload;
procedure Add(const Restriction: TRestriction); overload;

usage


Example: Restrict Folder Content Table to messages where Message do NOT have a PR_TRANSPORT_MESSAGE_HEADERS.


Restriction:= TRestrictionNot.Create(FContentTable);

Try

      With Restriction.Add(resEXIST) do

        PropTag:= PR_TRANSPORT_MESSAGE_HEADERS;

        

 Restriction.Apply;

 

Finally

      FreeAndNil(Restriction);

End;

Top


TRestrictionContent = class(TRestriction)

Description – TRestrictionContent implements a content restriction, which is used to limit a table view to only those rows that include a column with contents matching a search string.

Unit: MAPIRestriction.pas
Type: Class
Inherited from: TRestriction

Properties

Name Access Type Description
PropTag RW ULONG Property tag identifying the string property to be checked for occurrence of the search string.
FullString RW Boolean The search string must be completely contained in the property identified by PropTag.
SubString RW Boolean To match, the search string can be contained anywhere within the property identified by PropTag.
Prefix RW Boolean To match, the search string must appear at the beginning of the property identified by PropTag. The two strings should be compared only up to the length of the search string indicated by Value.
IgnoreCase RW Boolean The comparison should be made without considering case.
IgnoreNonSpace RW Boolean The comparison should ignore Unicode-defined nonspacing characters such as diacritical marks.
Loose RW Boolean The comparison should result in a match whenever possible, ignoring case and nonspacing characters.
Value RW Variant The string value to use as the search string.
Note: FullString, SubString and Prefix are mutually exclusive. Only one of them can be set, and one of them must be set.

Methods

Name Description
none none

usage


Example: Restrict Folder Content Table to messages where Message Subject exists and Message Subject contains phrase “test me”  

Top

TRestrictionProperty = class(TRestriction)

Description – TRestrictionProperty implements a property restriction which is used to match a constant with the value of a property.

Unit: MAPIRestriction.pas
Type: Class
Inherited from: TRestriction

Properties

Name Access Type Description
PropTag RW ULONG Property tag identifying the string property to be checked for occurrence of the search string.
Relation RW TRestrictionRelation Relational operator to be used in the search.
Value RW string The value to use as the search.

Methods

Name Description
none none

usage


Example: Restrict Folder Content Table to messages where Message is Unread OR Message Size is => 2048 bytes.  

Top

TRestrictionCompare = class(TRestriction)

Description – TRestrictionCompare implements compare property restriction, which tests two properties using a relational operator.

Unit: MAPIRestriction.pas
Type: Class
Inherited from: TRestriction

Properties

Name Access Type Description
Relation RW TRestrictionRelation Relational operator to be used in the search.
PropTag1 RW ULONG Property tag of the first property to be compared.
PropTag2 RW ULONG Property tag of the second property to be compared.

Methods

Name Description
none none

usage


Example: Restrict Folder Content Table to messages where Sender (PR_SENDER_NAME) is not equal to PR_SENT_REPRESENTING_NAME. This would mean that the e-mal was sent by someone else (on behalf of).


 

Restriction:= TRestrictionCompare.Create(FContentTable);

Try

  Restriction.Relation:= prNotEqual;

  Restriction.PropTag1:= PR_SENDER_NAME;

  Restriction.PropTag2:= PR_SENT_REPRESENTING_NAME;

  Restriction.Apply;

Finally

  FreeAndNil(Restriction);

End;

Top

TRestrictionBitMask = class(TRestriction)

Description – TRestrictionBitMask implements a bitmask restriction, which is used to perform a bitwise AND operation and test the result.

Unit: MAPIRestriction.pas
Type: Class
Inherited from: TRestriction

Properties

Name Access Type Description
PropTag RW ULONG Property tag of the property to which the bitmask is applied.
Mask RW ULONG Bitmask to apply to the property identified by PropTag.
EqualToZero RW Boolean True - Perform a bitwise AND operation of the mask in the Mask member with the property represented by the PropTag member and test for being equal to zero.
False - Perform a bitwise AND operation of the mask in the Mask member with the property represented by the PropTag member and test for being not equal to zero.

Methods

Name Description
none none

usage


Example: Restrict Folder Content Table to messages where Message is Unread OR Message Size is => 2048 bytes.  

Top

TRestrictionSize = class(TRestriction)

Description – TRestrictionSize implements a size restriction which is used to test the size of a property value.

Unit: MAPIRestriction.pas
Type: Class
Inherited from: TRestriction

Properties

Name Access Type Description
PropTag RW ULONG Property tag identifying the property to test.
Relation RW TRestrictionRelation Relational operator used in the size comparison.
Size RW ULONG Count of bytes in the property value.

Methods

Name Description
none none

usage

Example: Restrict Folder Content Table to messages where Message body is => 2048 bytes.


Restriction:= TRestrictionSize.Create(FContentTable);

Try

Restriction.PropTag:= PR_BODY;

     Restriction.Relation:= prGreaterEqual;

Restriction.Size:= 2048;

 

Restriction.Apply;

 

Finally

      FreeAndNil(Restriction);

            End;

Top

TRestrictionExist = class(TRestriction)

Description – TRestrictionExist implements an exist restriction which is used to test whether or not a particular property exists as a column in the table.

Unit: MAPIRestriction.pas
Type: Class
Inherited from: TRestriction

Properties

Name Access Type Description
PropTag RW ULONG Property tag identifying the column to be tested for existence in each row.

Methods

Name Description
none none

usage

Example: Restrict Folder Content Table to messages where Message do NOT have a PR_TRANSPORT_MESSAGE_HEADERS.

Top

TRestrictionSub = class(TRestriction)

Description – TRestrictionSub implements a subObject restriction which is used to filter the rows of a message's attachment or recipient table.

Unit: MAPIRestriction.pas
Type: Class
Inherited from: TRestriction

Properties

Name Access Type Description
SubObject RW TSubjRestriction Type of subobject to serve as the target for the restriction.
Restriction RO TRestriction TRestriction, which is used to apply a search.

Methods

Name Description
Add Add a new TRestriction.

function Add(const ResType: TRestrictionType): TRestriction; overload;
function Add(const Restriction: TRestriction): Integer; overload;

usage

Example: Restrict Folder Content Table to messages where recipient e-mail address like “@test.com”.

Restriction:= TRestrictionSub.Create(FContentTable);

Restriction.SubObject:= rsRecipient;

Try

  With Restriction.Add(resCONTENT) do

  begin

PropTag:= PR_EMAIL_ADDRESS;

     SubString:=True;

     IgnoreCase:=True;

     Loose:=True;

     Value:=’@test.com’;

   end;

   Restriction.Apply;

Finally

   FreeAndNil(Restriction);

End;

Top

Copyright © 2021 IMIBO
Privacy Statement