Platform SDK: MAPI

Properties

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. MAPI defines many properties, some to describe many objects and some that are appropriate only for an object of a particular type. Clients and service providers can extend MAPI's set of predefined properties by creating new, custom properties. Clients can define properties to describe new message classes, and service providers can define properties to expose the unique features of their messaging system.

Properties can be persistent or temporary. Properties that persist from session to session can be stored with their objects' data or in the profile. Temporary properties exist only for the duration of the current session.

Clients and service providers can show properties to users with either of the following components:

The IMAPIProp interface is the primary interface for working with properties. All objects that support properties implement IMAPIProp. IMAPIProp includes methods for retrieving property values, copying properties, making changes and saving those changes, mapping between property names and their identifiers, and retrieving information about a prior error.

There are several data structures for describing properties and information about properties. The most commonly used structures are the SPropValue structure and the SPropTagArray structure. The SPropValue structure contains the three pieces of information that describe a property:

The property type and identifier are combined into a single component called the property tag. Property tags are constants that can be used to easily refer to the property. Property tags for properties defined by MAPI are included in the MAPITAGS.H header file and in the ulPropTag member of an SPropValue structure. Clients and service providers use property tags to identify, retrieve, and update the corresponding properties.

The SPropTagArray structure is a counted array of property tags. Many of the methods in IMAPIProp and other interfaces use an SPropTagArray structure for describing properties.