Extended MAPI in DELPHI
LazyMAPI
Included Helper Classes & Objects
TMAPITable
Represents a single MAPI Table.
Delphi wrapper object for MAPI IMAPITable.
Provides a read-only view of a table (IMAPITable itself is read-only).
unit: MAPITable.pas
file path: ..\Library\Helpers
version: 2018.хх
uses Classes, Windows, ActiveX, Types, SysUtils, ExtendedMAPI, IMIEMTypes, MAPIRestriction;
| Unit: | MAPITable.pas |
| Type: | Class |
| Inherited from: | TMAPIBase |
Declaration:
TMAPITable = class(TMAPIBase)
protected
...
public
constructor Create(const oTable: IMAPITable); virtual;
destructor Destroy; override;
property Count: Integer Read GetCount;
property Row[const Index: Integer]: TMAPITableRow read GetMAPITableRows;
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: TMAPITableRow;
function GetNext: TMAPITableRow;
function GetLast: TMAPITableRow;
function CreateBookmark: TBOOKMARK;
procedure FreeBookmark(Position: TBOOKMARK);
function GetBookmarked(Position: TBOOKMARK): TMAPITableRow;
function GetSortOder: TSortOrders;
procedure Sort(const SortOrders: TSortOrders);
function GetFilter: TRestriction;
procedure Filter(const Restriction: TRestriction);
function GetRowByID(const RowID: TBytes): TMAPITableRow;
function GetRowPosition(const RowID: TBytes): Integer;
function FindPositionByEntryID(const EntryID: TBytes): Integer;
function GetRowData(const RowID: TBytes; out RowSet: PSRowSet): Boolean;
procedure Reload(const Table: IMAPITable; const KeepSortOrder: Boolean = True);
procedure AddColumn(const PropTag: ULONG);
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;
Constructors
| Name | Description |
|---|---|
| constructor Create(const oTable: IMAPITable); virtual; | Creates and initializes object instance from IMAPITable |
Properties
| Name | Access | Type | Description |
|---|---|---|---|
| Count | RO | Integer | Returns the total number of rows in the table |
| Row | RO | TMAPITableRow | 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, is applied to the 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