LazyMAPI

unit: MAPITable.pas
file path: ..\Library\Helpers\
version: 2014.хх


uses Classes, Windows, ExtendedMAPI, Types, SysUtils, IMIEMTypes, MAPIRestriction;

The TMAPITable object represents a single MAPI Table.
Delphi wrapper object for MAPI IMAPITable.
Provides a read-only view of a table (IMAPITable itself is read-only).

type
   TFastFilterRelation
= (rLess, rLessEqual, rGreater, rGreaterEqual, rEqual, rNotEqual, rLike, rPrefix);

Value

Meaning

pLess

The comparison is made based on a lesser first value.

pLessEqual

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

pGreater

The comparison is made based on a greater first value.

pGreaterEqual

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

pEqual

The comparison is made based on equal values.

pNotEqual

The comparison is made based on unequal values.

pLike

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

rPrefix

The comparison is made based on start substring.

TTableType = (tblTypeSnapshot, tblTypeKeyset, tblTypeDynamic);

Value

Meaning

tblTypeSnapshot

The table is static, and its contents do not change when the underlying data changes.

tblTypeKeyset

The rows within the table are fixed, but the values of the columns within these rows are dynamic and can change as the underlying data changes.

tblTypeDynamic

The table's contents are dynamic and the rows and column values can change as the underlying data changes.

TTableStatus = (tblStatUnknown, tblStatComplete, tblStatQChanged, tblStatSorting, tblStatSortError, tblStatSettingCols, tblStatSetcolError,
tblStatRestricting, tblStatRestrictError);

Value

Meaning

tblStatUnknown

Unknown State.

tblStatComplete

No operations are in progress.

tblStatQChanged

The contents of the table have expectantly changed

tblStatSorting

An Sort operation is in progress.

tblStatSortError

An error occurred during Sort operation.

tblStatSettingCols

A ColumnsTags (IMAPITable.SetColumns) operation is in progress.

tblStatSetcolError

An error occurred during an ColumnsTags (IMAPITable.SetColumns) operation.

tblStatRestricting

A Filter (IMAPITable.Restrict) operation is in progress.

tblStatRestrictError

An error occurred during a Filter (IMAPITable.Restrict) operation.

 TSortOrder = record
     PropTag: ULONG; { Column to sort on }
     OrderDescend: BOOL; { Ascending, descending}
end;

TSortOrders = array of TSortOrder;

 
 
TTableEventType = (tbleChanged, tbleReload, tbleRestrictDone, tbleSetColDone, tbleSortDone, tbleErrorEvent, tbleRowAdd, tbleRowModified, tbleRowDeleted);
TTableBasicEvent = procedure(Sender: TObject; EventType: TTableEventType) of object;
TTableErrorEvent = procedure(Sender: TObject; Error: HRESULT) of object;
TTableRowAddOrModifiedEvent = procedure(Sender: TObject; EventType: TTableEventType; PriorRowID: TBytes; RowID: TBytes; Fields: TMAPITableFields; var AllowUpdate: Boolean) of object;
TTableRowDeletedEvent = procedure(Sender: TObject; RowID: TBytes; Fields: TMAPITableFields; var AllowUpdate: Boolean) of object;
 
 
 
 
TMAPITable = class(TMAPIBase)
  protected
   ...
   ...
   ...
  public
    constructor Create(const Table: IMAPITable); virtual;
    destructor Destroy; override;
    property Count: Integer Read GetCount;
    property Row[const Index: Integer]: TMAPITableFields read GetMAPITableFields;
    property ColumnsTags: TCardinalDynArray read GetFieldDefs write SetFieldDefs;
    property BatchLoad: word read GetCacheCount write SetCacheCount default 20;
    property WaitForOnBusy: Cardinal read FWaitForOnBusy write FWaitForOnBusy default 2000;
    property RawTable: IMAPITable read GetMAPITable;
    property IsFiltered: Boolean read FIsFiltered;
    property TableType: TTableType read GetTableType;
    property TableStatus: TTableStatus read GetTableStatus;
    property AllowEvents: Boolean read FAllowDynamicUpdates write SetAllowDynamicUpdates;
 
    procedure FastFilter(const PropTag: ULONG; const Relation: TFastFilterRelation; Value: Variant);
    procedure FastSort(const PropTag: ULONG; const Ascending: Boolean = True);
    procedure Refresh(const KeepSortOrder: Boolean = True); virtual;
 
    function GetFirst: TMAPITableFields;
    function GetNext: TMAPITableFields;
    function GetLast: TMAPITableFields;
 
    function CreateBookmark: TBOOKMARK;
    procedure FreeBookmark(Position: TBOOKMARK);
    function GetBookmarked(Position: TBOOKMARK): TMAPITableFields;
 
    function GetSortOder: TSortOrders;
    procedure Sort(const SortOrders: TSortOrders);
    procedure Filter(const Restriction: TRestriction);

    function GetRowByID(const RowID: TBytes): TMAPITableFields;
    function GetRowPosition(const RowID: TBytes): Integer;
 
    function GetRowData(const RowID: TBytes; out RowSet: PSRowSet): Boolean;
    procedure Reload(const Table: IMAPITable; const KeepSortOrder: Boolean = True);
    function GetFilter: TRestriction;
 
    property OnChanged: TTableBasicEvent read FOnChanged write FOnChanged;
    property OnError: TTableErrorEvent read FOnError write FOnError;
    property OnReload: TTableBasicEvent read FOnReload write FOnReload;
    property OnRestrictDone: TTableBasicEvent read FOnRestrictDone write FOnRestrictDone;
    property OnSetColDone: TTableBasicEvent read FOnSetColDone write FOnSetColDone;
    property OnSortDone: TTableBasicEvent read FOnSortDone write FOnSortDone;
    property OnRowAdd: TTableRowAddOrModifiedEvent read FOnRowAdd write FOnRowAdd;
    property OnRowModified: TTableRowAddOrModifiedEvent read FOnRowModified write FOnRowModified;
    property OnRowDeleted: TTableRowDeletedEvent read FOnRowDeleted write FOnRowDeleted;
  end;


Properties

Name Access Type Description
Count RO Integer Returns the total number of rows in the table
Row RO TMAPITableFields Returns a singe row
ColumnsTags RW TCardinalDynArray Returns/Defines a list of columns for the table.
BatchLoad RW word Specifies the size of the cache for the table. Default value of BatchLoad is 20
WaitForOnBusy RW Cardinal Maximum number of milliseconds to wait for the asynchronous operation or operations to complete.  Default value of WaitForOnBusyis 2000  (2 sec.)
RawTable RO IMAPITable Wrapped IMAPITable  
IsFiltered RO Boolean Specifies whether a restriction, or filter, id applied on a table.
TableType RO TTableType Returns a table type as keyset, dynamic, or snapshot.
TableStatus RO TTableStatus Returns a table status.
AllowEvents RW Boolean Specifies whether the processing of events to be enabled. If they are allowed, then they can be captured by the processing of events such as OnSortDone, OnRowModified, etc..

Methods

Name Description
FastFilter Applies a filter to a table, reducing the row set to only those rows matching the specified criteria.

procedure FastFilter(const PropTag: ULONG; const Relation: TFastFilterRelation; Value: Variant);
FastSort Orders the rows of the table, depending on sort criteria.

procedure FastSort(const PropTag: ULONG; const Ascending: Boolean = True);
Refresh Delete rows that are loaded into memory. It is possible to keep the sorting.

procedure Refresh(const KeepSortOrder: Boolean = True); virtual;
GetFirst Returns the first row of the table.

function GetFirst: TMAPITableFields;
GetNext Returns the next row of the table.

function GetNext: TMAPITableFields;
GetLast Returns the last row of the table.

function GetLast: TMAPITableFields;
CreateBookmark Creates a bookmark at the table's current position.

function CreateBookmark: TBOOKMARK;
FreeBookmark Releases the memory associated with a bookmark.

procedure FreeBookmark(Position: TBOOKMARK);
GetBookmarked Moves the cursor to a bookmarked position in the table.

function GetBookmarked(Position: TBOOKMARK): TMAPITableFields;
GetSortOder Retrieves the current sort order for a table.

function GetSortOder: TSortOrders;
Sort Orders the rows of the table, depending on sort criteria.

procedure Sort(const SortOrders: TSortOrders);
GetFilter Retrieves the current restriction for a table.

function GetFilter: TRestriction;
Filter Applies a filter to a table, reducing the row set to only those rows matching the specified criteria. Passing nil in the Restriction parameter removes the current filter.

procedure Filter(const Restriction: TRestriction);
GetRowByID Returns a singe row by RowID. RowID is PR_INSTANCE_KEY value as TBytes.

function GetRowByID(const RowID: TBytes): TMAPITableFields;
GetRowPosition Retrieves the current table row position of the cursor.
RowID is PR_INSTANCE_KEY value as TBytes.

function GetRowPosition(const RowID: TBytes): Integer;
GetRowData Returns the raw row of the table. RowID is PR_INSTANCE_KEY value as TBytes.

function GetRowData(const RowID: TBytes; out RowSet: PSRowSet): Boolean;
Reload Deletes all table data loaded into memory, resets restrictions, and load fresh copy of table in memory.

procedure Reload(const Table: IMAPITable; const KeepSortOrder: Boolean = True);

Events

Name Type Description
OnChanged TTableBasicEvent Indicates at a high level that something about the table has changed.
OnError TTableErrorEvent An error has occurred, usually during the processing of an asynchronous operation. Errors during the processing of the following methods can generate this event: FastSort, Sort, Set ColumnsTags, FastFilter, Filter
OnReload TTableBasicEvent The data in the table should be reloaded.
OnRestrictDone TTableBasicEvent A restriction operation initiated with an FastFilter/Filter method call has completed.
OnSetColDone TTableBasicEvent A column setting operation initiated with an Set ColumnsTags method call has completed.
OnSortDone TTableBasicEvent A table sorting operation initiated with an FastSort/Sort method call has completed.
OnRowAdd TTableRowAddOrModifiedEvent A new row has been added to the table.
OnRowModified TTableRowAddOrModifiedEvent A row has been changed. The row member contains the affected properties for the row.
OnRowDeleted TTableRowDeletedEvent A row has been removed from the table. The propPrior member is set to nil.


usage

Please see Lazy MAPI # 6 - Test TMAPITable wrapper, FastFilter and FastSort

Top


Copyright 2017 IMIBO
Privacy Statement