Development

LazyMAPI
Included Helper Classes & Objects

Restrictions

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 of restriction:

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
resOR – 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.

---

Classes & Objects

TRestriction
The base class for restriction objects.
Delphi wrapper object for _SRestriction.
Note: Do not create instances of TRestriction. Use a descendant of TRestriction, such as TRestrictionContent.

unit: MAPIRestriction.pas
file path: ..\Library\Helpers
version: 2018.хх

uses Windows, Contnrs, ExtendedMAPI;

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

Declaration:

// Base class
  TRestriction = class(TObject)
  protected
    ...
  public
    destructor Destroy; override;
    property ResType: TRestrictionType read GetRestrictionType;
    procedure Apply;
    procedure ResetTable;
  end;

Properties

Name	Access	Type	Description	MAPI Reference
ResType	RO	TRestrictionType	Type of restriction	_SRestriction

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.

---

TRestrictionAnd = class(TRestriction)
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

Declaration:

TRestrictionAnd = class(TRestriction)
protected
  ...
public
  constructor Create(const Table: IMAPITable); reintroduce;
  destructor Destroy; override;
  property Count: Integer read GetCount;
  function Add(const ResType: TRestrictionType): TRestriction; overload;
  function Add(const Restriction: TRestriction): Integer; overload;
  function Remove(const Restriction: TRestriction): Integer;
end;

Properties

Name	Access	Type	Description	MAPI Reference
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;

---

TRestrictionOr = class(TRestriction)
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

Declaration:

TRestrictionOr = class(TRestriction)
  protected
    ...
  public
    constructor Create(const Table: IMAPITable); reintroduce;
    destructor Destroy; override;
    property Count: Integer read GetCount;
    function Add(const ResType: TRestrictionType): TRestriction; overload;
    function Add(const Restriction: TRestriction): Integer; overload;
    function Remove(const Restriction: TRestriction): Integer;
  end;

Properties

Name	Access	Type	Description	MAPI Reference
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;

---

TRestrictionNot = class(TRestriction)
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

Declaration:

TRestrictionNot = class(TRestriction)
protected
...
public
  constructor Create(const Table: IMAPITable); reintroduce;
  destructor Destroy; override;
  function Add(const ResType: TRestrictionType): TRestriction; overload;
  procedure Add(const Restriction: TRestriction); overload;
  property Restriction: TRestriction read FRestriction;
end;

Properties

Name	Access	Type	Description	MAPI Reference
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; function Add(const Restriction: TRestriction): Integer; 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;

---

TRestrictionContent = class(TRestriction)
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

Declaration:

TRestrictionContent = class(TRestriction)
protected
...
public
  constructor Create(const Table: IMAPITable); reintroduce;
  property PropTag: ULONG read FPropTag write FPropTag;
  property FullString: Boolean index 0 read GetFuzzyLevel write SetFuzzyLevel;
  property SubString: Boolean index 1 read GetFuzzyLevel write SetFuzzyLevel;
  property Prefix: Boolean index 2 read GetFuzzyLevel write SetFuzzyLevel;
  property IgnoreCase: Boolean index 3 read GetFuzzyLevel write SetFuzzyLevel;
  property IgnoreNonSpace: Boolean index 4 read GetFuzzyLevel write SetFuzzyLevel;
  property Loose: Boolean index 5 read GetFuzzyLevel write SetFuzzyLevel;
  property Value: WideString read GetPropValue write SetPropValue;
end;

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”

---

TRestrictionProperty = class(TRestriction)
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

Declaration:

TRestrictionProperty = class(TRestriction)
  protected
   ...
  public
    constructor Create(const Table: IMAPITable); reintroduce;
    property PropTag: ULONG read FPropTag write FPropTag;
    property Relation: TRestrictionRelation read GetRelation write SetRelation;
    property Value: Variant read GetPropValue write SetPropValue;
  end;

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.

---

TRestrictionCompare= class(TRestriction)
TRestrictionCompare implements compare property restriction, which tests two properties using a relational operator..

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

Declaration:

TRestrictionCompare = class(TRestriction)
  protected
    ...
  public
    constructor Create(const Table: IMAPITable); reintroduce;
    property Relation: TRestrictionRelation read GetRelation write SetRelation;
    property PropTag1: ULONG read FPropTag write FPropTag;
    property PropTag2: ULONG read FPropTag2 write FPropTag2;
  end;

Properties

Name	Access	Type	Description
Relation	RW	TRestrictionRelation	Relational operator to be used in the comparison.
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;

---

TRestrictionBitMask = class(TRestriction)
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

Declaration:

TRestrictionBitMask = class(TRestriction)
  protected
   ...
  public
    constructor Create(const Table: IMAPITable); reintroduce;
    property PropTag: ULONG read FPropTag write FPropTag;
    property Mask: ULONG read FMask write FMask;
    property EqualToZero: Boolean read GetEqualToZero write SetEqualToZero;
  end;

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.

---

TRestrictionSize = class(TRestriction)
TRestrictionSize implements a size restriction which is used to test the size of a property value.

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

Declaration:

TRestrictionSize = class(TRestriction)
  protected
    ...
  public
    constructor Create(const Table: IMAPITable); reintroduce;
    property PropTag: ULONG read FPropTag write FPropTag;
    property Relation: TRestrictionRelation read GetRelation write SetRelation;
    property Size: ULONG read FSize write FSize;
  end;

Properties

Name	Access	Type	Description
PropTag	RW	ULONG	Property tag of the property to which the bitmask is applied.
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;

---

TRestrictionExist= class(TRestriction)
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

Declaration:

 TRestrictionExist = class(TRestriction)
  protected
    ...
  public
    constructor Create(const Table: IMAPITable); reintroduce;
    property PropTag: ULONG read FPropTag write FPropTag;
  end;

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.

---

TRestrictionBitMask = class(TRestriction)
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

Declaration:

TRestrictionBitMask = class(TRestriction)
  protected
   ...
  public
    constructor Create(const Table: IMAPITable); reintroduce;
    property PropTag: ULONG read FPropTag write FPropTag;
    property Mask: ULONG read FMask write FMask;
    property EqualToZero: Boolean read GetEqualToZero write SetEqualToZero;
  end;

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.

---

TRestrictionSize = class(TRestriction)
TRestrictionSize implements a size restriction which is used to test the size of a property value.

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

Declaration:

TRestrictionSize = class(TRestriction)
  protected
    ...
  public
    constructor Create(const Table: IMAPITable); reintroduce;
    property PropTag: ULONG read FPropTag write FPropTag;
    property Relation: TRestrictionRelation read GetRelation write SetRelation;
    property Size: ULONG read FSize write FSize;
  end;

Properties

Name	Access	Type	Description
PropTag	RW	ULONG	Property tag of the property to which the bitmask is applied.
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;

---

TRestrictionSub= class(TRestriction)
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

Declaration:

   TRestrictionSub = class(TRestriction)
  protected
    ...
  public
    constructor Create(const Table: IMAPITable); reintroduce;
    destructor Destroy; override;
    property SubObject: TSubjRestriction read GetSubObjectRestriction write SetSubObjectRestriction;
    property Restriction: TRestriction read FRestriction;
    function Add(const ResType: TRestrictionType): TRestriction; overload;
    procedure Add(const Restriction: TRestriction); overload;
  end;

Properties

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

Methods

Name	Description
none	none

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;