ENTRYID 

The ENTRYID structure contains an entry identifier for a MAPI object.

Quick Info

typedef struct

{ 

     BYTE        abFlags[4];

     BYTE        ab[MAPI_DIM];

} ENTRYID, FAR *LPENTRYID;

Members

abFlags

Bitmask of flags that provide information describing the object. Only the first byte of the flags, abFlags[0], may be set by the provider; the other three are reserved. The client should never change anything in the structure.

The following flags can be set in abFlags[0]:

MAPI_NOTRECIP

The entry identifier cannot be used as a recipient on a message.

MAPI_NOTRESERVED

Other users cannot access the entry identifier.

MAPI_NOW

The entry identifier cannot be used at other times.

MAPI_SHORTTERM

The entry identifier is short-term. All other values in this byte must be set unless other uses of the entry identifier are allowed.

MAPI_THISSESSION

The entry identifier cannot be used on other sessions.

The flags must not be set for permanent entry identifiers and set for short-term entry identifiers.

ab

Array of binary data used by service providers. The client application cannot use this array.

Remarks

A message store or address book provider fills an entry identifier with information that makes sense for that provider. For a message store, entry identifiers identify folders or messages but not attachments. For an address book, entry identifiers identify address book containers, individual messaging users, and distribution lists. Entry identifiers also identify message store, status, profile, and session objects. An entry identifier is a unique number that distinguishes one object from all other objects of the same type. For example, a message entry identifier uniquely identifies a message in the message store.

Directly comparing the binary data in two entry identifiers does not provide much information to the application because MAPI can use different binary values in ENTRYID structures to refer to the same object. To determine if two entry identifiers refer to the same object, the client application can use the IMAPISession::CompareEntryIDsZ9F4JH method for the appropriate object.

The following rules apply for using the abFlags[0] byte in entry identifiers.

    Each object, if queried for its entry identifier through its IMAPIProp interface, generates and provides the most permanent form of its entry identifier. To indicate an entry identifier is the most permanent one available for a given object, clear all the bits in the abFlags array.

    Entry identifiers found in most MAPI tables can be short-term instead of permanent. The use of short-term entry identifiers is usually restricted. In general, a client can use a short-term entry identifier to open an object only in the current MAPI session. Use the short-term entry identifier with the message store only for the current session and only while the address book remains open. To indicate a short-term entry identifier, set all the values in the abFlags array. The next rule slightly modifies these limitations.

    In some cases, your short-term entry identifier might be just as good as a permanent entry identifier. In such cases, clear individual bits in the abFlags array as appropriate.

Although providers should handle arbitrarily aligned entry identifiers, clients cannot expect providers to handle arbitrarily aligned entry identifiers. Failure to pass in a suitable aligned entry identifier can result in an alignment fault on RISC CPUs. To allow for those providers that do not handle arbitrarily aligned identifiers, clients should always pass in naturally aligned entry identifiers. The natural alignment factor, typically 8 bytes, is the largest data type supported by the CPU, and usually the same alignment factor used by the system memory allocator. A naturally aligned memory address allows the CPU to access any data type it supports at that address without generating an alignment fault. For RISC CPUs, a data type of size N bytes must usually be aligned on an even multiple of N bytes, with the address being an even multiple of N.

See Also