Entry identifiers are constructed with the ENTRYID structure. The ENTRYID structure is made up of a flag that describes the attributes of the entry identifier and the actual entry identifier. The ENTRYID structure is defined as follows:
typedef struct
{
BYTE abFlags[4];
BYTE ab[MAPI_DIM];
} ENTRYID, FAR *LPENTRYID;
MAPI_DIM is a constant that is defined in the MAPIDEFS.H header file.
The first byte of the 4-byte abFlags member describes the type and use of the entry identifier and can have the following values:
MAPI_NOTRECIP
MAPI_NOTRESERVED
MAPI_NOW
MAPI_SHORTTERM
MAPI_THISSESSION
MAPI_NOTRESERVED, when set, indicates that the entry identifier can be used by other service providers for other objects. The MAPI_NOTRECIP value indicates whether or not the entry identifier can be applied to a message recipient. When MAPI_NOW is set, the entry identifier can only be used at the present time, and when MAPI_THIS_SESSION is set, the entry identifier can only be used for the current session. MAPI_SHORTTERM identifies the entry identifier as a short-term identifier.
Clients expect to be able to check this first abFlags byte to determine the entry identifier's longevity. A zero in abFlags[0] indicates a long-term identifier and a nonzero indicates a short-term identifier. The last three bytes of the abFlags member must be zero.
The ab member of entry identifiers created by address book and message store providers is made up of two pieces: a 16-byte MAPIUID that identifies the service provider and a piece to identify the object. MAPIUID is a structure that contains a globally unique identifier, or GUID. A GUID is a byte order independent identifier which can be created using the Microsoft utility UUIDGEN.EXE.
A service provider registers its MAPIUID structure with MAPI during the logon process in a call to IMAPISupport::SetProviderUID. When a client calls an OpenEntry method to access an object, MAPI uses the MAPIUID structure to determine which service provider can provide that access. Service providers should use the same MAPIUID structure for all versions of their DLL. This enables clients with the newer version to respond to messages sent and saved with the older version. Service providers that are using a profile that must work on two different processors, each with a different byte order, use a MAPIUID structure to differentiate between objects.
The rest of the ab member after the 16-byte MAPIUID contains service provider-specific binary data for identifying particular objects. There is no fixed size for this portion of the entry identifier. It can be any size, within reason.
A service provider typically includes the following in this part of its entry identifiers:
Because it is common for a service provider to change the format of its entry identifiers from version to version, storing version information makes it possible to quickly determine how to decipher any entry identifier.
Location information is data that gives a service provider an indicator of how to locate the object represented by the entry identifier. For example, a service provider can store the disk offset for the last place in a data file that the object was stored. Because this type of information can change over time, service providers should provide multiple ways for locating objects in their entry identifiers.
Service providers are encouraged not to recycle their entry identifiers, but they can. If it is necessary to reuse an entry identifier, service providers should make the time period that elapses between the initial use and the reuse as long as possible. Also, the entry identifier should be reassigned to another object of the same type. That is, a particular entry identifier should not be associated first with a message and then with a folder.