"Light" Lazy MAPI Glossary

Term

Explanation

A property is an attribute of a MAPI object. Properties describe something about the object, such as the subject line of a message or the address type of a messaging user. Property tags are used to identify MAPI properties and every property must have one.

PropTag

Property tag for the property. Property tags are codes expressed as 32-bit unsigned integers, that contain the property's unique identifier (PropID) in the high-order 16 bits, and the property's type (PropType) in the low-order 16 bits.
For example, consider the "Importance" message envelope property. Its Property ID (PropID) is $0017, and its Data Type (PropType) is PT_LONG (which maps to a hexadecimal value of $0003). Its Property Tag (PropTag) is a combination of these two: $00170003. This hexadecimal value is defined as the constant PR_IMPORTANCE.

PropID

A property identifier (PropID) is a number that is used to indicate what a property is used for and who is responsible for it. The range of property identifiers runs from $0001 through $FFFF. Property identifiers $0001 and $FFFF are reserved. PropID is high 16 bits from PropTag.

The following table shows the Property ID ranges in which properties in similar categories are grouped.

From	To	Category
$0000	$0000	Reserved by MAPI for the special value PR_NULL.
$0001	$0BFF	Message envelope properties defined by MAPI.
$0C00	$0DFF	Recipient properties defined by MAPI.
$0E00	$0FFF	Non-transmittable message properties defined by MAPI.
$1000	$2FFF	Message content properties defined by MAPI.
$3000	$3FFF	Properties for objects other than messages and recipients defined by MAPI. See the table below for more details.
$4000	$57FF	Message envelope properties defined by Transport Providers.
$5800	$5FFF	Recipient properties defined by Transport and Address Book Providers.
$6000	$65FF	Non-transmittable message properties defined by Clients.
$6600	$67FF	Non-transmittable properties defined by a Service Provider. These properties can be visible or invisible to users.
$6800	$7BFF	Message content properties for custom message classes defined by creators of those classes.
$7C00	$7FFF	Non-transmittable properties for custom message classes defined by creators of those classes.
$8000	$FFFE	Properties defined by clients, and occasionally service providers that are identified by name through the IMAPIProp.GetIDsFromNames method.

The following table shows how this particular range is further subdivided into smaller ranges, to make assigning new Property IDs easier.

From	To	Category
$3000	$32FF	Common properties that appear on multiple objects, such as PR_DISPLAY_NAME and PR_ENTRYID.
$3200	$33FF	Form properties.
$3400	$35FF	Message Store properties.
$3600	$36FF	Folder and Address Book Container properties.
$3700	$38FF	Attachment properties.
$3900	$39FF	Address Book properties.
$3A00	$3BFF	Messaging User properties.
$3C00	$3CFF	Distribution List properties.
$3D00	$3DFF	Profile properties.
$3E00	$3FFF	Status object properties.

The MAPI uses the _A and _W additives to signify if the property is an ASCII (single byte character, AnsiString) or a Wide (multiple byte character, WideString) string. This document does not bother with this distinction. The additive _O is used for some types, it refers to the direct use of embedded object instead of data types.

PropType

Property types (PropType) are constants defined by MAPI that indicate the underlying data type of a property value. All properties, whether they are defined by MAPI, by client applications, or by service providers, use one of these types. PropType is low 16 bits from PropTag.
All defined from MAPI property types are listed here.

PropNamed

Property identifiers are a set of hexadecimal values that range from $0001 to $FFFF. This allows for 65,534 properties. These properties are divided into the following groups, known as ranges:

Transmittable properties - This range is made up of properties that Exchange Server can send with a message.
Internal properties - This range is made up of properties that may be set only by Exchange Server.
Non-transmittable properties - This range represents properties that are not delivered outside the organization when Exchange delivers a message.

In addition to these ranges, there is one other range. This range is the largest and represents all properties that are at $8000 and above. The properties in this range are known as named properties. Named properties provide a way for vendors to extend the standard MAPI property set by adding their own properties. Named properties are made up of the following two main types:

Properties that have numbers for names. These are properties that programs such as Microsoft Outlook use. These property names are generally defined in a source file.
Properties that have string values for names. These properties are known as "String Named Properties".

In addition to a name, each of these properties has an associated GUID. This allows developers to divide named properties into property sets.
Commonly Used Named Property Sets are listed here.

Because the named properties do not have specific IDs assigned, MAPI provides a facility to dynamically create unique IDs for named properties and to maintain a persistent mapping between a named property and its unique ID. However, the dynamic creation of these IDs means that the property IDs for named properties can vary from computer to computer.

To support named properties, MAPI implements two methods thru IMAPIProp interface — IMAPIProp::GetIDsFromNames and IMAPIProp::GetNamesFromIDs — to translate between names and identifiers and to allow its IMAPIProp::GetProps and IMAPIProp::SetProps methods to retrieve and modify properties with identifiers in the named property range. The range for named property identifiers (PropID) is between $8000 and $FFFE.

To define a named property, a client or service provider makes up a name and stores it in a MAPINAMEID structure.

MAPINAMEID

To define a named property, a client or service provider makes up a name and stores it in a MAPINAMEID structure.

type

PMAPINAMEID = ^TMAPINAMEID;

_MAPINAMEID = record
     lpguid: PGUID; // Pointer to a GUID structure defining a particular property set; this member cannot be NULL.
     ulKind: ULONG; // Value describing the type of value in the Kind member. Valid values are: MNID_ID or MNID_STRING.
     Kind: record
       case Integer of
        1: (lID: Longint; ); // The name is an integer value, stored in lID. ulKind = MNID_ID
        2: (lpwstrName: LPWSTR; ); // The name is an Unicode string (PWideChar), stored in lpwstrName. ulKind = MNID_STRING
      end;
end;

TMAPINAMEID = _MAPINAMEID;

SPropValue

Describes a RAW MAPI property.

=======================
type
PSPropValue = ^TSPropValue;

_SPropValue = record
    ulPropTag: ULONG; // Property tag (PropTag) for the property.
     dwAlignPad: ULONG; // Reserved for MAPI. Used as padding to make sure proper alignment on computers that require 8-byte alignment for 8-byte values.
    Value: _PV;            // Union of data values, the specific value dictated by the property type (PropType).
end;

TSPropValue = _SPropValue;
=======================

Value member:

Property type	Value field	Data type of Value
PT_I2 or PT_SHORT	i	short
PT_I4 or PT_LONG (signed)	l	Longint
PT_I4 or PT_LONG (unsigned)	ul	ULONG
PT_R4 or PT_FLOAT	flt	single
PT_R8 or PT_DOUBLE	dbl	double
PT_BOOLEAN	b	WordBool
PT_CURRENCY	cur	Currency
PT_APPTIME	at	double
PT_SYSTIME	ft	TFILETIME
PT_STRING8	lpszA	LPSTR (PAnsiChar)
PT_BINARY	bin	Pointer to BYTE array
PT_UNICODE	lpszW	LPWSTR (PWideChar)
PT_CLSID	lpguid	PGUID
PT_I8 or PT_LONGLONG	li	TLargeInteger (int64)
PT_MV_I2	MVi	array of short values
PT_MV_LONG	MVI	array of Longint values
PT_MV_R4	MVflt	array of single values
PT_MV_DOUBLE	MVdbl	array of double values
PT_MV_CURRENCY	MVcur	array of Currency values
PT_MV_APPTIME	MVat	array of double values
PT_MV_SYSTIME	MVft	array of TFILETIME values
PT_MV_BINARY	MVbin	array of BYTE array values
PT_MV_STRING8	MVszA	array of PAnsiChar values
PT_MV_UNICODE	MVszW	array of PWideChar values
PT_MV_CLSID	MVguid	array of GUID values
PT_MV_I8	MVli	array of TLargeInteger (int64) values
PT_ERROR	err	SCODE (Integer)
PT_NULL or PT_OBJECT	x	LONG (Integer)

PT_MV_XXXXX means MultiValued property. MultiValued member is constructed as record of:

_XXXXXXXArray = record
     cValues: ULONG; // Count of values in the array pointed to by the lpXXX member.
     lpXXX: YYYY;     // Pointer to an array of YYYY type
end;

Example: for PT_MV_DOUBLE, value member MVdbl is defined as TSDoubleArray

type
_SDoubleArray = record
     cValues: ULONG; // Count of values in the array pointed to by the lpdbl member.
     lpdbl: PDouble;   // Pointer to an array of Double type
end;

SDoubleArray = _SDoubleArray;
TSDoubleArray = SDoubleArray;

Demo code:

CountOfValues:=MyMVDouble.MVdbl.cValues; // MyMVDouble is TSPropValue of property type PT_MV_DOUBLE
Index:=1;
SecondDoubleValueInArray:=_PDoubleArray(MyMVDouble.MVdbl.lpdbl)[Index];

Demo code:

MessageSubject := StrPas(MyAnsiStringValue.lpszA); // MyAnsiValue is TSPropValue of property type PT_STRING8

SRowSet

Contains an array of SRow structures. Each SRow structure describes a row from a table.

type
   PSRowSet = ^TSRowSet;

   _SRowSet = record
       cRows: ULONG; { Count of rows }
       aRow: array [0 .. 0] of TSRow; { Array of rows }
    end;

   TSRowSet = _SRowSet;

SRow

Describes a row from a table that contains selected properties for a specific object.

type
   PSRow = ^TSRow;

   _SRow = record
      ulAdrEntryPad: ULONG; { Pad so SRow's can map to ADRENTRY's }
      cValues: ULONG; { Count of property values }
      lpProps: PSPropValue; { Property value array }
   end;

   TSRow = _SRow;

MAPIUID

A byte-order independent version of a GUID structure that is used to uniquely identify a service provider.

type
PMAPIUID = ^TMAPIUID;

_MAPIUID = record
ab: array [0 .. 15] of byte;
end;

TMAPIUID = _MAPIUID;

One-Off Addresses

One-off addresses are used to send messages to one-off recipients, recipients that do not have a corresponding entry in any of the session's address book containers.
The one-off address format is defined by MAPI as follows:

Display name[Address type:E-mail address]

Component	Usage	Description
Display name	Optional	If not present, uses the visible part of the e-mail address as the display name. May include blanks.
[	Required	Delineates the start of the type and address information.
]	Required	Delineates the end of the type and address information. If anything other than white space follows this character, the entry is not treated as a custom recipient.
Address type	Required	Type of address; maps to a specific address format.
:	Required	Separates the address type from the e-mail address.
E-mail address	Required	Address of the recipient. May include blanks.

IMAPISession

Manages objects associated with a MAPI logon session.
Interface identifier: IID_IMAPISession: TGUID = '{00020300-0000-0000-C000-000000000046}'

IMAPIProp

Enables MAPI to work with properties. All objects that support properties implement this interface.
Interface identifier: IID_IMAPIProp: TGUID = '{00020303-0000-0000-C000-000000000046}'

IMsgStore

Provides access to message store information and to messages and folders.
Interface identifier: IID_IMsgStore: TGUID = '{00020306-0000-0000-C000-000000000046}'

IMessage

Manages messages, attachments, and recipients. Inherited from IMAPIProp.
Interface identifier: IID_IMessage: TGUID = '{00020307-0000-0000-C000-000000000046}'

IMAPIFolder

Performs operations on the messages and subfolders in a folder. Inherits IMAPIProp, IMAPIContainer.
Interface identifier: IID_IMAPIFolder: TGUID = '{0002030C-0000-0000-C000-000000000046}'

IMAPIContainer

Manages high-level operations on container objects such as address books, distribution lists, and folders. Inherited from IMAPIProp.
Interface identifier: IID_IMAPIContainer: TGUID = '{0002030B-0000-0000-C000-000000000046}'

IMAPITable

Provides a read-only view of a table.
Interface identifier: IID_IMAPITable: TGUID = '{00020301-0000-0000-C000-000000000046}'

IAttach

Maintains and provides access to the properties of attachments in messages.
Interface identifier: IID_IAttachment: TGUID = '{00020308-0000-0000-C000-000000000046}'

Top