TMAPITable

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

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

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

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

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;

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.

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.

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.

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

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);

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.

Value

Meaning

Value

Meaning

Value

Meaning