ENTRYID

  • Article

4/8/2010

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

Syntax

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. These flags must not be set for permanent entry identifiers; they are set only for short-term entry identifiers. To clients, this structure is read-only.

    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.
  • ab
    Indicates an array of binary data used by service providers. The client application cannot use this array.

Remarks

The ENTRYID structure is used by message store and address book providers to construct unique identifiers for their objects. Entry identifiers are used to identify the following object types:

  • Message store
  • Folder
  • Message
  • Address book container
  • Distribution list
  • Messaging user
  • Status
  • Profile section

Each provider uses a format for the ENTRYID structure that makes sense for that provider.

Entry identifiers cannot be compared directly because one object can be represented by two different binary values. To determine whether two entry identifiers represent the same object, call the IMAPISession::CompareEntryIDs method.

When a client calls an object's IMAPIProp::GetProps method to retrieve its entry identifier, the object returns the most permanent form of the entry identifier. A client can verify that an entry identifier is long-term by checking that none of the flags are set in the first byte of the abFlags member.

When a client accesses an entry identifier through a column in a table, most likely this entry identifier is short-term rather than long-term. Short-term entry identifiers can be used to open their corresponding objects only in the current MAPI session. A client can verify that an entry identifier is short-term by checking that all of the flags are set in the first byte of abFlags.

Some entry identifiers are short-term but have long-term use. Such entry identifiers have one or more of the appropriate flags set in the first byte of abFlags.

An ENTRYID structure has the following characteristics:

Clients should always pass in naturally aligned entry identifiers. Although providers should handle arbitrarily aligned entry identifiers, clients should not expect this behavior. Failure to pass a suitable aligned entry identifier to a method can result in an alignment fault on RISC processors.

The natural alignment factor, typically 8 bytes, is the largest data type supported by the CPU and is 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.

Usage

The following APIs take parameters, or include as members, that are pointers of type LPENTRYID (pointers to ENTRYID variables).

Term Definition

ERROR_NOTIFICATION

The ERROR_NOTIFICATION structure describes information relating to a critical error, causing an error notification to be generated.

ICEMAPISession::DeleteMsgStore

The DeleteMsgStore method deletes the message store from the MAPI store.

IFormProvider::GetMsgStatusIconIndex

The GetMsgStatusIconIndex method returns the index to the appropriate icon in the symbol bitmap for the form library.

IFormProviderEx::GetMsgStatusIconIndex

The GetMsgStatusIconIndex method returns the index to the appropriate icon in the symbol bitmap for the form library.

IMailRuleClient::ProcessMessage

The ProcessMessage method processes incoming messages, which can be moved, modified, or deleted.

IMAPIContainer::OpenEntry

The OpenEntry method opens an object within the container, returning an interface pointer for further access.

IMAPIFolder::CopyFolder

The CopyFolder method moves a subfolder. Copying a subfolder is not supported in Windows Mobile Messaging.

IMAPIFolder::DeleteFolder

The DeleteFolder method removes a subfolder from the current folder.

IMAPISession::Advise

The Advise method registers to receive notification of specified events affecting the session.

IMAPISession::CompareEntryIDs

The CompareEntryIDs method compares two entry identifiers to determine whether they refer to the same object.

IMAPISession::OpenEntry

The OpenEntry method opens an object and returns an interface pointer for further access.

IMAPISession::OpenMsgStore

The OpenMsgStore method opens a message store and returns a reference to the IMsgStore object for further access.

IMessageFormEx::OnMessageModified

The OnMessageModified method notifies the message form when a message object changes.

IMsgStore::Advise

The Advise method registers to receive notification of specified events affecting the message store.

IMsgStore::GetReceiveFolder

The GetReceiveFolder method obtains the folder that was established as the destination for incoming messages of a specified message class or the default receive folder for the message store.

IMsgStore::OpenEntry

The OpenEntry method opens a message store object and returns an interface pointer for further access.

MailDisplayMessage

The MailDisplayMessage function displays an existing message.

MailSwitchToFolder

The MailSwitchToFolder function switches to a folder, and displays its contents in a List View.

MAILSYNCREQUEST

The MAILSYNCREQUEST structure describes the synchronize request made by the e-mail application to the transport.

NEWMAIL_NOTIFICATION

The NEWMAIL_NOTIFICATION structure describes information relating to the arrival of a new message.

OBJECT_NOTIFICATION

The OBJECT_NOTIFICATION structure contains information about an object that has undergone a change, such as being copied or modified.

SizedENTRYID

The SizedENTRYID macro creates a named ENTRYID structure that contains an AB member of a specified size.

STATUS_OBJECT_NOTIFICATION

The STATUS_OBJECT_NOTIFICATION structure describes a status object that has been affected by a change.

SYNCPROGRESSITEM

The SYNCPROGRESSITEM structure describes the progress information reported by the transport to Messaging.

Requirements

Header mapidefs.h
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Pocket PC 2002 and later, Smartphone 2002 and later

CbNewENTRYID | SizedENTRYID

See Also

Reference

MAPI Structures

Other Resources

Messaging